Neatly organise your Postman collections to navigate your micro-services maze

While implementing a distributed system, I find that I’m working across dozens of apps and services. Moreover, these services typically expose their functionality over REST APIs, protected in different ways. It would be nice if there was some way to keep track of all APIs, preferably in a neatly organised fashion…

Several challenges arise when we work on systems that are sufficiently large:

• It is difficult to maintain an understanding of all the functionality exposed by different subsystems
• The codebase for each service can be split across dozens of repositories making it difficult to perform global searches and find code samples, sample data, etc
• Even if there is swagger documentation, they will be scattered and the functionality offered is very limited

This article describes how these issues can be addressed using Postman. Though many developers have used Postman, they are likely not leveraging all its organisational and scripting functionality. By the end of the setup, you will be able to see at a glance all the endpoints exposed by your Micro-services solution, their respective sample requests and ultimately be able to test and execute different parts of your systems.

Organisational features

Postman offers three tools for organising requests into a hierarchy:

• Workspaces are at the root of the organisational hierarchy of postman. They are shared contexts which allow team members to collaborate, setup different environments and attach variables to these environments.
• Collections sit inside a workspace and have the functionality to be executed by firing all its child requests, hold variables as well as pre- and post-request scripts.
• Folders sit inside collections and can also have their own pre/post-request scripts.

Using these tools, we can organise our micro-services requests like this:

• Workspace: A single workspace is setup for your micro-services solution; this has a `development`, `staging` and `production` environments attached to it. The host names and credentials for each environment are saved as environment specific variables.
• Collections: Each micro-service has its own collection. This can look like ‘identity service’, ‘orders’, ‘pricing’, etc. This is setup so we can associate specific variables and scripts to each micro-services to handle their unique quirks and features. Scripting is described in detail below.
• Folders: When a service has APIs that can be neatly grouped by their response or request format, these request should be organised into folders. This has the benefits of allowing scripts with related input or output formats.

A visualisation of the proposed organisation of requests as explained above. Note that the request path of a request can also be parameterised.

Scripting in postman

Postman allows execution of arbitrary javascript before and after your API requests. In Postman parlance, these are named “Pre-request scripts” and “Tests”.

The most common usecase for a pre-request script is setting up the necessary data for API authorisation. A different pre-request script can be configured per collection. For example the orders service could have an openid connect pre-request script to attach a bearer token; while a separate collection for Azure Service Bus can have its own pre-request script to generate and cache a SAS token.

Scripts can also run after the requests have been executed. If an service has a set of APIs that returns large amounts of data, we can place them into a folder and attach scripts that format this data nicely as demonstrated below. For example you may have a set of endpoints that return CSV data, by placing these requests, in the same folder they can automatically inherit the same script to format the data in a searchable and sortable table.

Demonstration of using the “Tests” to display large json output as a table that is sortable and searchable.

Conclusion

With your micro-service’s solution API requests neatly organised and scripted many aspects of working REST APIs becomes more convenient:

• You can see at glance all the functionality exposed by all your micro-services
• Authentication is straightforward since this is scripted and executed automatically
• Large API responses can be visualised in graphs or tables
• Posting a schematised message to a messaging queue becomes easier since you have an example request ready
• You can share variables across requests between micro-service like a product id or user id which is impossible with scattered swagger docs