Version Control in Postman

Ankit

June 20, 2017

Postman Pro is now used by 1000s of companies around the world to collaboratively build and manage APIs. One of the most requested features from our customers is managing changes to API documentation with version control.

Our goal for a good version control system includes the following:

1. Back up and restore – Data is backed up as it is updated, and you can jump to any state of your data in time.
2. Synchronization – Everyone in the team stays up-to-date with the latest version of the data at all times.
3. Short- and long-term undo – Any gaffe, big or small, is restorable and recoverable.
4. Track changes and ownership – Keep track of how your data is evolving over time and who’s responsible.
5. Sandbox – Try out and test temporary changes in an isolated area, where you can work out the nitty-gritties before distributing to the rest of the world
6. Branch and merge – A larger sandbox for the bigger changes, which when ready, can easily be merged back with the rest of the team.
7. Tag and version – Postman is a UI tool to create and manipulate structured data, like Postman Collections, and traditional source control systems for this use case can be both inefficient and overly complex. Simplicity when dealing with tagging and versioning is in order.

A little while ago, we introduced team-, individual-, and collection-level activity feeds. The activity feed addresses our aforementioned goal to “Track changes and ownership” really well. You can track all recent changes to every collection shared within the team along with your own private collections. Frequently, it’s the main tool used internally to communicate changes to an API. Our customers love it!

Revision History

Today, we’ve made a significant addition to the activity feed. It’s called revision history, and it allows you to restore collections to any point in time.

You can access it by hovering over an activity and clicking the Restore link as shown below

Each restoration is applied on top of the existing activities, retaining all the newer changes. This means you can go back or forward in your collection’s history, as you want.

Let’s explain this using a recipe for one of my favourite desserts, the Panna Cotta.

If only I had this Restore while baking desserts.

With the introduction of revision history, we have nailed down the first 4 points of our ideal version control system.

What’s Next

Sandbox

Session variables, which will allow users to build, edit, and debug collections without worrying about accidentally syncing and publishing the collections before they’re ready.

Branch and Merge

In line with our goal of simplicity, we intend to keep the oft-dreaded “merge misery” as painless and stress-free as possible. We’re experimenting internally with user experiences and hope to have updates out in production builds soon. Our power users, of course, can use the Postman Pro API to manage version control as they wish.

Tag and Version

Tagging will allow you to create snapshots and versions of your collections. You’ll soon be able to publish documentation or set up monitors on a tagged version of the collection. You will also be able to restore your collections to any tagged version.

Integrations

In line with our vision of an open ecosystem, Postman is compatible with many of your existing developer tools. Learn more about integrations.

You can easily integrate with your existing version control systems, like GitHub, GitLab, or Dropbox. You can even use your choice of API description format to back up your Postman Collections in Swagger, RAML, API Blueprint and other API description formats.