Postman Collections enable you to link your API elements and facilitate documenting, sharing, and testing APIs. You can also fork existing collections into another workspace. When you do so, Postman creates another collection you can use for testing or reference.
But what happens if the original collection changes? Just pull changes from the original collection and keep your forked collection up-to-date with its parent collection. It’s that simple!
Postman displays a detailed view of the changes, which you can then pull into your forked collection.
To ensure your forked collection is always up-to-date, you need to run this manual process periodically, or watch the original collection and pull changes when the collection changes. This can be error-prone and time-consuming.
Are there any alternatives to this manual process? There is, thanks to the Postman API!
The pull source changes endpoints
The Postman API’s Pull collection source changes endpoint can help to reduce the manual process of updating forked collections. When you call this endpoint for the forked collection, the Postman API automatically updates the forked collection with the latest changes from the original collection.
For environments, you can keep them in sync with the original by using the Postman API’s Pull environment source changes endpoint.
Automating forked element updates
How can we automatically run both requests? The answer to this question is with Postman Monitors. To implement our tool to automatically update our forked collection, we’ll do the following:
Step 1
Create a collection with a request to update our forked collections with the Postman API. Optionally, if you’ve also forked an environment, you can update it in the same collection as well.
Note that the Postman API requires a valid API key to authenticate requests. Take into account that rate and usage limits may also apply.
Step 2
Create a monitor that periodically runs the collection, depending on your needs. A daily monitor run should be enough:
The Postman API requires your API key to authenticate the request. It’s a piece of private and sensitive information, so don’t share it publicly.
For the monitor to run properly, the request must send the proper header with your API key. To access this information, the collection can retrieve it from an environment or collection variable, but the value must persist in the Postman Cloud.
If your collection is in a private workspace, only you can access this information; otherwise, other team members can view your private API key. If you are concerned about security, use the Postman Vault (integrated with password managers such as 1password). Note that private workspaces are available on Postman Professional and Enterprise plans, and Postman Vault is available on Postman Enterprise plans with the Advanced Security Administration add-on.
You can also use the Postman CLI, which enables you to run a collection by passing specific variable values from the command line, which can be read from the system environment variables.
Once you create the monitor, your collection will run and the forked collection is updated with the original collection changes. You can add a simple post-response script to validate that the API response is a 200 (the pull operation worked):
If, for whatever reason, the request fails, Postman Monitors will send a notification to you.
Do more with the Postman API
In addition to pulling changes into a forked collection, the Postman API offers other endpoints to work with collection and environment forks:
- Get a collection’s forks
- Get an environment forks
- Create a collection fork
- Create an environment fork
- Merge or pull changes into a collection fork (this endpoint is asynchronous, we provide another endpoint to check the operation status)
- Merge an environment fork
Explore the Postman API and let us know if you discover any other great ways to manage your forks programmatically!