The tech-writer’s journal #10 — Leveraging Postman Collections

This post explains why you need postman collections and how to leverage them to provide a smooth developer experience. A postman collection is simply a group of API requests that can be saved, arranged into folders, and shared amongst the team in a workspace. Developers can fork the collection and use it to validate the APIs with minimal effort.

This post is for developer evangelists and advocates who aim to provide a seamless experience for their API users. The article assumes that you are familiar with APIs and the Postman tool.

Why you need a postman collection?

Having a postman collection saves the time and effort of your developers. They need not go through the strenuous process of building stand-alone applications to test their APIs. It is particularly helpful when a developer is just dipping their toes in the water to see if your APIs are the right solution.

Also, just like GitHub, your developers can pull and merge changes made to your collection to stay up to date with the changes made to your APIs. It is less time-consuming than reading over release notes or change-logs.

Leveraging postman collections

Once you have built a postman collection, make sure you’ve ironed out all the wrinkles before publishing it. Here are a few hacks that help you polish your collection and make it more pleasant for your developers.

1. Naming your requests

Choosing appropriate request names for APIs in your collection goes a long way in helping developers understand the purpose of an API. The postman, by default, sets the request URL as the request name. Even if your API endpoints are clear, it might look clumsy when you store an entire URL as a request name.

Naming your API requests

Here are a few things to keep in mind while naming your requests:

1. Use nouns. For example: Get Users, Delete Users, and so on.
2. Make it as intuitive as possible. Choose plain language while naming your requests, avoiding the need for developers to sift through documentation.
3. Be consistent about the noun form throughout the collection. You can either choose to name your requests with either singular or plural noun forms.
4. Be consistent about the case throughout the collection. It can be Get Users or Get users or any other case.

2. Grouping requests into folders

Organise the API calls into folders to boost discoverability.

Grouping requests into folders

Additionally, add specific descriptions to API calls, examples, folders, and parameters. Ensure that your descriptions are crisp and to the point. You can add them using Markdown.

Adding descriptions

You can include descriptions at three different parts of a Postman collection.

1. API requests: In the above illustration, This endpoint returns the details about the Tweet specified by the requested ID is an endpoint level description. You can additionally include descriptions of Request Parameters and Path variables as well.
2. Request folders: You can add descriptions to folders as a whole.

Adding folder descriptions

3. Collection: You can add a summary to the Postman collection, which is similar to the readme.md file in GitHub. You may provide general information about the collection, how to load or fork the collection, how to configure environment variables, and authorization details.

Adding collection description

3. Adding examples

Add unique examples illustrating different parameters and status codes including all the possible error cases. Using relevant samples helps users to get a complete understanding of how the API can be used.

Adding examples

To conclude, I’d love to hear if this post helped you use Postman collections more efficiently, and I am certain that there are several other tips that might be useful; please share them in the comments section. Let’s connect :)