Basic API questions, to get started on a Postman Collections documentation portal

meta
1

Hello, all. Volunteer technical writer here. I’m hoping through this project to get hands-on experience that elevates me in the minds of employers. Long story short, @jmiranda and I agreed on needing a comprehensive docs site for the API; beyond the site’s API guide, that is. Right now, I’m reading through bug reports on the community site, wiki, and GitHub repository. I have lots of questions, but let’s start with some basic ones so I have hints on where to begin documenting. (Some say the technical writer job is 10% or so writing and the other % information harvesting and organizing.)

Please help if you can! I will need input from more than just @jmiranda. At least one more developer and someone from a different department should suffice. (In a big company full-time, I’d interview developers, marketing, support, project management, stakeholders, localization, and legal.)

Some questions are easy, others hard. Here we go! :shopping_cart:

  • (from my academic notes) “The overview provides a high-level description of the main use cases or business objectives of the product.” What are the most common use cases and business objectives of OpenBoxes, in your words?

  • What are some less common, but still important, use cases? As in, desired by at least a few people?

  • In addition to cURL, should I incorporate requests done in other programming languages? If so, which languages? (This is easy to do in Postman.)

  • What version of Java are you currently running? (I’ve seen this topic come up in multiple GitHub Issues.)

  • Do you know of any hard-coded error codes in any file? //something that looks like this /*or this*/

  • I’ll need to document any limitations and thresholds (for example: max number of API calls, max file sizes, max string lengths, max/min parameter values, max server load, free vs. upper tier, max item numbers, etc.). This also involves me deliberately breaking the API to be able to document what happens, why, and how to fix it. That’ll be the future. But for now, what are the limitations and thresholds?

  • Any platform/OS-based limitations?

  • Any geographical limitations?

  • Any user/role-based limitations or differences?

  • I will need to know any security vulnerabilities so that I can NOT document them (bad guys often look for these in the docs). That also means that any we type here or elsewhere will have to be erased later.

Thank you for your help! :slightly_smiling_face:

2

While I would love to see this discussion take off, I’m seeing a lot of heavy topics and it’s difficult for me to distill a response into something less than a multi-volume treatise. I’ve asked our development team to provide their thoughts. But it might take some time to get the ball rolling to the point where it leads to actual next steps. I know you’re looking at this project the same way I would (lots of discovery regarding philosophical topics before getting started). Still, it would be good to get the technical questions answered in a more immediate way.

Therefore … let’s get you into Slack so you can ask some narrowly scoped questions to the development team (including me) to help move you forward with the immediate project of creating a public Postman collection or updating the Swagger docs.

Here’s a link to join Slack

https://join.slack.com/t/openboxes/shared_invite/zt-2f1l7i8xd-mXqSTulptYpZp1wbFqNKfA

(I believe this link is set to expire 30 days from now, so if anyone is trying to join past the expiry date, please email and I’ll send you a personal invite).

As an aside, the larger project I mentioned that was consuming all of my energy at the moment, is an API Design Guide for our internal developers. It’s the other side of the API documentation coin i.e. how do we build an intuitive and secure API following REST principles, with an emphasis on implementation using Grails and Spring.

Perhaps you could jump into that initiative once I have something worth sharing. It’s currently in “draft” draft form and resembles the chaos of neurons firing inside my brain. But soon (probably later in April, after a family vacation) it’ll be a comprehensive guide that will help us to develop better APIs. This guide will eventually start to leak its way into our consumer-side API documentation (the ones for external devs), so it’ll hopefully be a good resource for the project you want to work on.

3

Hi @micshar92 sorry for the long wait. I’ll try to answer your questions.

What are the most common use cases and business objectives of OpenBoxes, in your words?

Warehouse management system and stock management. Stock monitoring in various facilities and stock movements monitoring between various facilities (or inside a facility).

What are some less common, but still important, use cases? As in, desired by at least a few people?

Assets management system (?)

In addition to cURL, should I incorporate requests done in other programming languages? If so, which languages? (This is easy to do in Postman.)

IMHO, for now, cURL should be enough, you could also think about JS, but it is not a must right now.

What version of Java are you currently running? (I’ve seen this topic come up in multiple GitHub Issues.)

On the current develop and master branches ( = legacy 0.8.x version of the project) - we have Java 1.7 and Grails 1.3.10
On the currently actively developed part of the app - mainly branch feature/upgrade-to-grails-3.3.10 ( = 0.9.x version of the project) - we have Java 1.8 and Grails 3.3.17. So I think this one should be your point of focus.

Do you know of any hard-coded error codes in any file? //something that looks like this /*or this*/

I am not sure if I understand this question. Could you be more specific about what you mean? Do you mean any hard-coded error codes that are commented out?

But for now, what are the limitations and thresholds?

Good question. I am not sure if there are any types of thresholds right now in terms of request count limitations. The only limit that comes to my mind is a size limit → 2MB for the request size and 2MB for the file upload size. Would be good to get @jmiranda’s confirmation here in terms of max number of requests.

Any platform/OS-based limitations?

None, or nothing that I know about (or anything that I can think of from the top of my head).

Any geographical limitations?

None, or nothing that I know about (or anything that I can think of from the top of my head).

Any user/role-based limitations or differences?

Technically right now our API is using a current user from the session and configurable RBAC.

I will need to know any security vulnerabilities so that I can NOT document them (bad guys often look for these in the docs). That also means that any we type here or elsewhere will have to be erased later.

Well, then I cannot tell you anything about this here :sweat_smile:

If any answer is too vague, let me know and I’ll try to elaborate a bit more or if you have more questions let me know too.

4

@jmiranda I spent a few months learning a moderate amount of REST API best practices & Swagger, but I got discouraged what with the tech sector layoffs, invention of GenAI, and saturated technical writer market, so I’ll go back through my notes. Heck, if I study Grails and Spring Boot… and Java… I may have ideas to add to the API. So I look forward to April.

@Artur By “hard-coded” I mean something like this, as an example:

// throw error if string > 30 characters
[code here]
...

Companies sometimes “document” errors in this way and never mention it outside the code. Meaning I’d have to look through code to find these errors so that I can say how to avoid them while performing some task, i.e. “This field does not support strings over 30 characters.” Just an example.

… And as for the last question, while I’m certainly no expert on cybersec, I’m studying an initial bit of it right now. I’ll get back to you on that. I watched this video on “what not to document and why” recently, and that’s the extent of my knowledge. It just makes me think about things.