Better Practices for Git Version Control in Postman

Joyce

November 3, 2021

Git is the most broadly used version control system among technology teams to track and manage changes. Postman previously shared how to use forking and merging, pull requests, and other Postman version control features to collaborate asynchronously. Let’s take a look at some better practices when implementing Git workflows in Postman, and then you can decide what works best for your particular needs.

Real-time updates versus atomic changes

Let’s take an example of making changes to an API in Postman. If you don’t need to manage updates carefully, you can grant an editor role to collaborators within your Postman team. Everyone can make real-time updates to the specification, similar to editing in Google Docs. Editors make changes and viewers see those changes reflected in real time too.

However, consider that you want to manage your updates more carefully because you’re worried about making changes that upset someone else’s workflow. That’s where more robust version control comes in handy. Everyone can work asynchronously using separate forks so that you explicitly merge changes.

Postman supports Git workflows to let you manage collaboration within your team as well as collaboration with your broader communities so that you don’t release breaking changes. This means that you can make atomic, all or nothing, changes preserved in a changelog. These indivisible units of change are made as an explicit save, or commit, to make it easier to manage collaboration at scale. You can track down where things went wrong, reverse mistakes, and feel confident about rolling out changes to consumers.

How Git works in Postman

To continue our example of making changes to an API, here is a basic overview of how Git works in Postman:

1. Create a workspace in Postman.
2. Import or create an API specification in the workspace.
3. Connect a “repository” with a Git hosting tool (e.g., GitHub or Bitbucket).
4. “Commit” and save the changes to your workspace.
5. “Push” your changes to a branch in your connected repository.
6. Make a change to your specification with a Git hosting tool and commit.
7. “Pull” the changes to your workspace.
8. Create a “fork” (i.e., version or branch), make a change, commit the change.
9. Open a “pull request” to propose changes to the main branch.
10. “Merge” your branch to the main branch.

Single source of truth for internal teams

For many teams, the API specification is the single source of truth, where any other linkages are for reference only. In our example, suppose that you want to automatically generate a collection from the specification. The API specification remains the ultimate source of truth, and the collection can be used for documentation, tests, or whatever else. To manage your API, you can use the Git workflow outlined in the previous section and also manage version, release, and status for your API in Postman. You are currently not able to fork APIs.

If your team does not use API specifications, then you can skip that step. In that case, the collection then becomes your single source of truth. While you can still export and import collections as a standalone file, the recommendation is to fork the collection. When you fork a collection, you establish a link to the parent branch. This allows you to pull updates from the parent branch in case of any updates. You can also submit pull requests to propose updates to the parent branch.

If you don’t have an editor role for the collection or you want to make atomic changes, here is how you control your updates:

1. Import, generate, or create a collection in the workspace.
2. Create a “fork” (i.e., branch) of the collection, make, and save a change.
3. Open a “pull request” to propose changes to the main branch, or “push” your changes to the main branch if you have an editor role on the main branch.
4. “Merge” your branch to the main branch.
5. Make a change to the main branch of your collection and save.
6. “Pull” the changes to your fork.

The user group and roles available for your Postman team depend on your team’s Postman plan. Notice that roles are very precise and restrictive for security reasons. For example, a team admin can manage team members and team settings, while a collection editor can update a collection and merge pull requests. In Postman, there is currently not a “super admin” role with permissions to rip a path of destruction, like Godzilla, through the team’s work. Business and Enterprise plan users can also manage pull request settings to enforce additional checks prior to merging.

How it works for API publishers with public APIs

Some organizations only want to expose their public API when ready for public consumption. In this case, here is how you can control your updates:

1. Collaborate privately on the collection in a team workspace.
2. Fork the collection to a public workspace when ready.
3. Continue developing the collection in a team workspace.
4. Pull updates to the collection in the public workspace if needed.
5. Submit a pull request to the main branch in your team workspace if needed.
6. The process is the same for external contributors who fork the collection from a public workspace.

To create a pull request on a public collection, users must fork the collection to a public workspace. The fork must be in a public workspace so that reviewers can access it while reviewing the pull request.

Version control versus versioning

Although they sound very similar, “version control” is not the same as “versioning.” Version control is what we’ve talked about earlier regarding forking, merging, and pull requests. Teams create workflows around version control so that they don’t release breaking changes in a collaborative environment.

Versioning refers to tracking changes to something over time. For example, Twitter manages several public APIs, including Twitter API v2. Compared to v1, this API offers more endpoints, features, and access levels. You can manage multiple versions of APIs you create in Postman. You can then associate mocks, monitors, and documentation to specific versions of APIs. If you want to learn more about versioning APIs in Postman, check out these docs.

Related: What is API versioning?

In conclusion

Different teams follow their own recipes for version control, so always check with your team lead on the preferred way that your team works. Your team might choose to use any combination of these better practices depending on your specific goals and constraints. If your team has a unique workflow, share some of your tips or questions in the comments below.

For more details about version control and versioning, here are some helpful docs:

• Using version control for collections
• Versioning APIs to manage multiple versions of APIs
• Connect an external Git repository for APIs
• Integrations to back up your collections to GitHub, Bitbucket, or GitLab

Technical review by Arlemi Turpault and Preetham Mavin.