Iacovos Constantinou

Posted on Jan 10, 2022 • Updated on Nov 2, 2023 • Originally published at softius.net

Synchronize Postman collections with the API

#postman #api #webdev

Working with Postman and APIs can be painful when you don't synchronize Postman collections automatically with the API.

A common approach to get started with Postman is to import the API schema. This works absolutely fine until the first update on the API spec happens.

While importing the updated API spec works, it creates a new Collection from scratch. Obviously this doesn't scale well.

Apart from creating a new Collection each time, any customisation done (tests, scripts, etc) are not transferred to the new Collection.

In this post we will be looking on how we can automate this and properly update the existing Collection, so that we don't loose our customisation and keep our Postman collections lean.

Manually synchronize Postman with API

The first option is to manually update the API Schema directly, without importing. This approach is ideal when we have the URL or the actual file for the updated spec.

I found that this feature in Postman, even quite powerful is well hidden and quite difficult to discover.

Here are the steps:

In the left sidebar, click on the APIs tab and then the API that you would like to update.
If you are seeing the same API multiple times, go through the list and find the right one by checking the associated collection under the Develop tab.
Click on the Define tab and paste the updated spec and hit Save
Then move to the Develop tab. Under the Documentation section hit 'Validate'. This will try to sync the API spec with the Collection.
In case there any issues like breaking changes you will need to review the issues (press Issues found). Once you do that, you will be redirected to your browser where the changes will be listed one by one.
You can choose which changes to apply and how to sync with Collection.

Link Postman with an existing repository

Another option is to link the API Spec with an existing repository. This is of course ideal when the API Spec is part of your code-base and you have already access to the right repository.

Here are the steps:

In the left sidebar, click on the APIs tab and then the API that you would like to update.
If you see the same API multiple times, go through the list and find the right one by checking the associated collection under the develop tab.
Click on the Define tab, hit "Connect Repository" and provide the necessary details. You will need to that once.
Every time there is an update, you will need to move to the Develop tab and hit "Validate" under the Documentation section. This will try to sync the API spec with the Collection.
In case there any issues like breaking changes you will need to review the issues (press Issues found). Once you do that, you will be redirected to your browser where the changes will be listed one by one.
You can choose which changes to apply and how to sync with Collection.