Some Developer Tips on building API Documentation with Postman

this week, I wrapped up an API documentation project using Postman. Some quick notes for my first-time code learning students.

First up, obviously, you want to have a Postman account and use it on your desktop. I am not a big fan of the cloud version of Postman and prefer the speed and convenience of a local installation. However, logging in to the desktop version ensures that,

Next, use workspaces. This is very useful when you are working on different projects, and helps keep things separate.

Next, use collections within workspaces. This is again, useful, because, even in a simple project, you will have at least one authentication API server, one payment API server, and one app API server. So, don’t mix them up.

Make sure you use variables for commonly used values like baseURLs, and current tokens, refresh tokens. These will save you a lot of time and hassle. Also, it will make it easy for your team members to change these things as they use it for front end development or load testing or production testing or any other automations they want to do.

Export your collection as it grows, and keep a copy in your github repository. Now, yes, Postman has cloud backups, but, still, having a second backup never hurt anybody.

watch out for spaces. Yes. a lot of times you might unusual HTTP errors, but that’s because there are extra spaces in the URL.

watch out for forgotten ‘/’ symbols or extra ‘/’ symbols. It’ easy to not see them because Postman font is so small by default.

When testing File Upload endpoints, make sure you are sharing the test files used, either through github or another way with your team members.

Query Parameters look like this, “/someendpoint?queryparameter=”queryparametervalue” (and they will be visible in the Parameter section of the Postman call)

API keys are usually put in Headers section.

usually, you will be using JSON in your body. If you are see red lines, it’s usually a bracket mismatch. There is a nice “beautify” option in Postman, use that to make things look nice and also catch formatting errors and brackets mismatch.

If you keep getting errors, check the ‘Postman Console’, which will always give you more details.

And, don’t forget to use the duplicate option as much as possible. This will save you time. And also, you will get less errors and all the variables will easily carry over.

an example of postman collection, is available on my github.

https://github.com/Jay-study-nildana/FrontEndForStudents/tree/main/PostmanCollections

And, finally, don’t forget to have fun while coding.

this a copy of my post from my mediumb blog.