Postman Collections API docs?

[micshar92]

In #4235, @jmiranda said:

... we'd also love to create postman collection(s) and improve our swagger docs to help users do their own testing on various APIs.

Since I haven't landed an entry-level technical writer job after 12 months and over three hundred applications, I think I'll tackle this issue like an internship. I'm not a years-of-experience expert, though, so I'll likely need help. With your approval, let's begin this undertaking. I have a lot of questions to ask to set up the project requirements, goals, architecture, and so on.

Approve? Let's discuss.

Eventually, I want to use some collections to allow users for learning manual testing and other collections for performance and penetration testing. But just getting a few API examples out in the world and tying them back to our static API docs would be great.

Unless more API testing needs to be done?

[jmiranda]

Sounds good, @micshar92. I've set up a couple of collections myself, but there are lots of things that seem to escape me at the moment, like proper parameterization and authentication. So this will be a good learning experience for both of us.

[micshar92]

@jmiranda Planning is the first stage of the process and involves a lot of questions for design and writing, like a blueprint for a house. I have so many questions, in fact, that I'll start with these setup concerns:

1. I think it'll be better to have a separate page where I ask these questions and get feedback. GitHub Projects looks to me like an ideal choice, unless you have a different, preferred method. This will prevent this issue page from growing enormously tall and allow me to write a to-do list to keep everyone updated on deliverables and timelines. There, I'll ask questions, get answers from multiple people, and incorporate responses.
2. What is the timeline? (This helps me plan review cycles, editing, and prioritization.)
3. Speaking of prioritization, what are our priorities? That is, which docs are critical and most likely to be needed ASAP? I'll start there, after the reusable overview.
4. Who will review these docs? At least one review per page per person is ideal. At least three reviewers— two developers and one customer support— is ideal. (In a bigger company, a project manager, marketing, QA, and legal would be involved. The more breadth, the better.)
5. Will someone localize these docs? (i.e. French, Spanish, etc.) I always use plain language, but this helps me check translatability of turns of phrase and the like.

And some requirements:

• I'll need to access a sandbox/test server to test calls. It may be good for average users, too; this builds confidence and understanding before committing to use/purchase and can increase trust, although that decision is out of my domain. As part of this, I'll need non-admin credentials to document what regular users see.
• Do you have any test scripts? How about a test suite?
• Do you have a sample app/demo that calls the API and logs responses? (This gives me a starting point.)
• I need to access the Postman Collections you've already started.

I know this looks like a lot, but in a typical company, I'd interview people from various departments and thus cut down on text blocks like these. This is why I suggest a GitHub Project, or a separate page of your choice. I'll populate it with lots more questions to ensure accuracy, usability, findability, and quality of the final docs.

Thanks!

[jmiranda]

Thanks for the thoughtful response and questions, @micshar92. I will respond as soon as I can.

For now, I would recommend setting up a Postman account on your own to use as a playground to explore. You can then use documentation, GitHub issues and/or community forum posts to find content related to the API, including sample requests and questions we probably need to provide answers to at some point in the future.

• Resources
  • API Guide https://docs.openboxes.com/en/latest/api-guide/
  • Blog: https://openboxes.com/blog/2020/05/14/rest-api/
  • Swagger: Docs https://app.swaggerhub.com/apis-docs/openboxes/api/0.8.17
• Spikes to consider / explore
  • https://community.openboxes.com/t/how-to-update-quantityavailable-of-a-product-in-an-inventory-via-api/731/4
  • Add discussion of location handling to API docs #4437
  • https://community.openboxes.com/t/outbound-movement-created-via-api-not-visible/355
  • https://community.openboxes.com/t/configuration-user-roles-and-permissions-via-api/649
  • Wrong behavior of Locations API (version 0.8.21) #3910

[micshar92]

In the meantime, I'll collect bug/error tickets for future documenting.

[micshar92]

@jmiranda Getting the test server set up is vital, yes, but the first step is a GitHub Project. You can make one on this repo, or I can fork a branch, make one there, and give access to the others who I'll need input from throughout the docs creation. Lots of questions, lots of small issues. But to my knowledge, I can't have two forks of the same branch, so I need you to close PR #4235.

By the way, bug collection phase is maybe 3/4. Then I'll organize them into tasks and insert into larger pages.

[jmiranda]

@micshar92 Sounds good. I haven't figured out the best way to move forward with respect to the Github project and I'm in the middle of a large project that I am struggling with so bear with me a bit. We can discuss next steps, but I can't really do a ton of project management right this minute.

As for immediate questions while you're exploring, you can either post to community.openboxes.com or join us on Slack. I'll send you an invite if you're interested. Speaking of which, the "community" forum may have been a better place for our earlier discussion (issue #4235), so we may want to move future discussions over there and use Issues for work we're planning to do. FWIW, there's also a Discussions feature on GitHub that might have been better as well.

But to my knowledge, I can't have two forks of the same branch, so I need you to close PR #4235.

I'm not sure what you meant by this but I've icebox'd (temporarily closed) ticket #4235 and PR #4341. I'll defrost them when I am ready to work on them.

As for "two forks of the same branch", you might be mixing terminology. If you meant that you cannot have two feature/upgrade-to-grails-3.3.10 branches then that is true, but I don't want you to delete that branch anyway.

You can create as many similar branches as you'd like as long as you change the name slightly. With your PR #4341 you seemed to have forked the repo, cloned the repository locally, and checked out the feature/upgrade-to-grails-3.3.10 branch. At the time, feature/upgrade-to-grails-3.3.10 was acting as our active development branch.

Typically, we create new feature branches off the "develop" branch like this.

git clone https://github.com/openboxes/openboxes
git checkout develop
git checkout -b 4235-clean-documentation

In your case, you could / should have create a separate feature branch targeting the Grails 3 branch (feature/upgrade-to-grails-3.3.10)

git clone https://github.com/openboxes/openboxes
git checkout feature/upgrade-to-grails-3.3.10
git checkout -b 4235-clean-documentation

And then you would add your code to that branch, pushed the changes, created a PR, etc. It's not much different from what you did, but I think you're worried that you couldn't create a new feature/upgrade-to-grails-3.3.10 branch. And while that's true, there's nothing special about that branch other than the special meaning we've bestowed upon it.

In other words, once you have our forked repository and you've checked out the feature/upgrade-to-grails-3.3.10, you could have created as many branches off a single ticket as you'd like

git checkout feature/upgrade-to-grails-3.3.10
git branch 4235-fix-this-thing
git branch 4235-build-that-thing
git branch 4235-implement-the-other-thing

Note

The current "develop" branch points to our legacy 0.8.x codebase at the moment. And the current 0.9.x codebase (which is mostly the product of the Grails 3 migration) was done in a separate branch called feature/upgrade-to-grails-3.3.10. We are working on "finalizing" the Grails 3 migration and 0.9.0 release as we speak. Once 0.9.0 has been released to the community, we'll rename develop to 0.8.x and feature/upgrade-to-grails-3.3.10 to develop.

[micshar92]

@jmiranda Thank you for the lesson. Yyyyyeah, I did get the terminology confused. At least I learned that now and not after being hired somewhere. Anyway, I started this topic on the community site. If you don't mind, I will need input from 3 people, ideally 2 devs and another person, so please tell them about my post. Thank you.