Streamline the API Development Lifecycle with Postman Version Control

The API lifecycle involves a plethora of personas—developers, architects, testers, technical writers, and more. These personas come in at different stages and make necessary contributions to develop different facets of an API; a backend developer creates endpoints, a tester writes tests, a technical writer adds user-facing documentation, and so on.

Take a moment to think about how you or your organization perform any of these tasks. You might have a primary repository for code and another one for tests. You might create a wiki to design and document all your APIs. Technical writers might have a different portal where they update API documentation. Your security team might have a separate space for all security tests.

At Postman, we aim to streamline these jobs and provide a simplified mechanism to collaboratively evolve an API using our version control features. Let’s take a look at an example:

Imagine you are a backend developer in a team called the User Management Squad, which creates services to manage customer information for your company. You already have an API deployed that has endpoints to create, update, and get user data. All of this is documented in a Postman Collection you’ve created, called the User API collection. Your team now has a requirement to add a user delete endpoint. Let’s see how you can take advantage of Postman’s version control features and collaborate asynchronously with your team to add this functionality.

Create forks to work in separate context

Forks allow you to create a copy of a collection where you can experiment and work its elements without modifying the original collection. You can also merge your changes to the main collection. Moreover, forks enable you to contribute to collections without having to have edit access.

Back to the job at hand. Let’s create a fork feature/add-user-delete-endpoint from the parent User API collection.

Once a fork is created, you can start designing the endpoint in Postman by adding request URL, parameters, and examples. You can also interact with peers to develop collaboratively. Let’s add a DELETE {{url}}/users/:id endpoint to our collection with relevant params. We’ll also use the inline commenting feature to ask Bob (a fellow developer) if the endpoint satisfies our API design guidelines.

Modify to fit your workflow

Now, let’s say you work with a QA and technical writer who are responsible for writing tests and documents for your API. Once you finish your API design, they will add test scripts and documentation to the collection.

In such scenarios, forks give you the flexibility to create a workflow that suits your needs. If your team prefers to work asynchronously, everyone can have a separate fork for their work. On the other hand, all of you can collaborate in real time on a single fork.

To see all the work happening on a collection, you can view a list of forks in the context bar.

For the sake of discussion, let’s assume all team members work in separate forks.

Review changes using pull requests

So far, we’ve seen how your team will work asynchronously in Postman using forks. But once all your work is done, you’ll want to merge it back into the original collection. This is similar to checking in your code into the main branch.

Postman provides two options to do this: merge and pull requests.

In case you’re using forks in a personal workspace to organize your work, you can directly apply your changes to the original collection. To do this, you must have an Editor role in the original collection. For more information on merging, you can check out the Merging Changes section on our Postman Learning Center.

Pull Requests

Imagine that Abhijit and Arlemi are service owners who manage the User API. They might want to review all changes being made to the API. You can use pull requests (PRs) in Postman to do just that.

PRs allow you to systematically merge changes to your collection and engage in meaningful discussions during the review process. Unlike code reviews, PRs in Postman focus on interface changes that may impact your consumers. They also help you group relevant changes and notify relevant stakeholders about the same.

Once you raise a PR, you don’t have to manually notify the reviewers through email or chat. Postman notifies the reviewers, asking them to review the PR. So, Abhijit and Arlemi get an email and an in-app notification asking them to take a look. Moreover, anyone interested can see a list of open PRs right from the collection tab.

After reviewing your PR, Abhijit or Arlemi can add comments requesting some changes or, if everything looks good, approve it.

Once the changes are ready to be integrated, you can merge PRs into the original collection using three strategies:

• Merge: Merge the changes from the forked collection to the original collection. No changes are made to the forked collection. The person merging the PR must have an Editor role on the original collection.
• Merge and update source: Changes made in the forked collection are merged to the original collection. Also, changes made in the original collection, after being forked, are made to the forked collection. The person merging the PR must have an Editor role for both the parent and forked collection.
• Merge and delete source: Changes made in the forked collection are merged and the forked collection is deleted. The person merging the PR must have an Editor role on both the parent and forked collection.

PRs can also be declined if the changes are no longer required.

Note: Merged and declined PRs cannot be reopened again.

Governance

Now, let’s say your team has grown significantly and a lot of people are working on this API. The team decides to enforce certain policies on how the API should be changed. All changes must now be approved by service owners (they’re the ones with direct edit access). Without their approval, the changes cannot be merged.

Postman gives you different ways to enforce such policies using PR merge checks. These checks ensure that a PR can be integrated only when a set of pre-defined conditions are met, helping you set up a change in governance.

You can set up merge checks for collections in shared workspaces on our Business and Enterprise plans. Use the “Manage Roles” option in the collection drop-down:

This blog post describes one of the many workflows possible in Postman. Head over to our Learning Center to learn more about version control in Postman. If you have features to request or bugs to report, create a ticket on our public issue tracker.

What do you think about this feature? Tell us in a comment below. You can also give product feedback through our Community forum and GitHub repository.