Latest Updates to Syncing Your Specs with Collections

A while back, I shared how to sync your specs to Postman Collections. Since then, Postman has streamlined this process allowing each version of an API in Postman to have its own specification, repository, and collections. If you’re not familiar with how Git works in Postman, make sure you already know these better practices for Git version control in Postman. Then let’s connect the dots with an example workflow starting with defining our API.

Many teams use an API specification, such as OpenAPI, to describe the long-term relationship between an API producer and potential API consumers. They can then use the OpenAPI to generate user documentation in the form of a collection. And then keep their collection and specification up to date as their API grows.

Step 1: Connect your API to Git version control

Let’s start by creating a new API in Postman and give it a required version, such as “1.0.0”. Note that you can also import an API specification into Postman from a remote Git-based repository.

Most teams use Git version control hosted on a platform like GitLab or Azure DevOps, for example, to track and manage changes to their API specification. Let’s connect our new API version 1.0.0 in Postman to a GitHub repository.

Once this is completed, you can see Postman creates a directory in the repository called postman/schemas containing the specification. Now you can use Git to continue synchronizing changes between Postman and the repository for this version of your API. If you update the specification in Postman, you can push changes to the repository. And if you update the specification in the repository, you can pull changes to the specification in Postman. As with Git, you can work off multiple branches and precisely control what and when to commit and merge, in order to enable collaboration among your team.

Step 2: Generate a collection from the API specification

In Postman, you can generate collections from an API specification if you have one in order to establish a link. You can also link an existing collection to an API. These linked collections might be categorized as documentation, tests, mock servers, or monitors. In addition to clearly organizing your Postman elements, this establishes an association between an API specification and its collection(s).

Once again, commit and push the changes to the repo now that a new collection has been added in Postman.

Once you do this, Postman creates a second directory in the repository called postman/collections containing the collection. Just like before, you can update the collection in Postman, and then commit and push changes to the repository. Or update the collection in the repository, and pull changes to the collection in Postman.

In the next step, let’s see how associating the collection with the specification can keep them aligned with each other.

Step 3: Align the spec and collections via schema validation

Once a collection is associated with the specification, you can keep them aligned. If you update the collection in a way that violates the API specification, Postman validates the schema and highlights issues to be resolved. Similarly, Postman highlights issues in the API specification that become misaligned with the collection.

This is how you can keep the collection and specification aligned within Postman. But what happens when the specification is updated in the repository? How can changes cascade into our collection? Let’s walk through step by step.

In the screenshot below, you can see Postman is one commit behind the repository. Let’s pull the latest updates so the API specification version 1.0.0 in Postman is the same as the specification in the repository.

For the next part, let’s explore two different options.

Option #1 to manually update the same version: You can manually update the collection in Postman by examining the highlighted issues to make the corresponding changes to the collection. If the collection and specification fall out of sync in a way that does not violate any stated rules defined in the specification, updates can be manually tracked in the specification changelog and reconciled in the collection. You can also rename the existing version in Postman, so version 1.0.0 becomes 1.1.0.

This approach might be tedious, depending on the magnitude of the updates. Another way to do this is to explicitly create a new version of the API, as we will investigate in the next step.

Step 4: Create the next version of your API

Option #2 to create a new version: When you create a new version in Postman, you can choose whether or not to carry over the linked collections.

• Minor version: If you choose to carry over these elements, such as for a minor or patch version, then manually edit both the collections and schema to keep them aligned if needed. This is good for a minor or patch version, and allows you to switch between version 1.0.0 and 1.1.0 of the API in Postman.
• Major version: You can also choose not to carry over these elements due to the significance of the changes. This requires that you generate a new collection from this new version of your specification. This is good for a major version, and allows you to switch between version 1.0.0 and 2.0.0 of the API in Postman.

In either case, you can switch between different versions of the API in Postman and connect a different repository to keep the versions synchronized to source control.

Some teams that follow a workflow similar to option #2, like Stripe and Datadog, also rename their collections to include a date for consumers to see the most recent version of an API. One drawback is that consumers who fork a collection cannot then watch for new updates and pull changes into their local collection since the source collection is frequently re-generated. The alternative is to carry over the same documentation collection over to subsequent versions and manually update it.

How API producers can deprecate or maintain parallel versions of an API, create a new version and carry over documentation and tests in @getpostman – Let me know if your team is using OpenAPI alongside collections👂

Full video 📽️ https://t.co/vfePWC0tQT #openapi pic.twitter.com/2f7nRr79xY

— Joyce Lin (@PetuniaGray) December 21, 2021

Step 5: Designate a release

When you’re ready to deploy a version of the API to an environment, like staging or production, you can designate a release in Postman. Releases represent milestones in your API, such as minor version updates. And when you are connected to an external Git repo, releases can be mapped to the Git release tags.

In your specification changelog, you can refer back to previous releases to see the state of the system as of version 1.0.0 vs 1.1.0, for example. However, you will not be able to edit your specification, documentation, or tests within each release. This ensures that consumers see the precise documentation associated with a specific version of your API.

How to do API-first in @getpostman, starting with OpenAPI to generating documentation, server stubs, managing versions and releases throughout the API lifecycle, etc

Full video here w/timestamps📽️https://t.co/tEKmKnXYiE pic.twitter.com/eEo3CxYKyn

— Joyce Lin (@PetuniaGray) December 20, 2021

So what is an API version and release in Postman?

Each API in Postman has one or more versions, and versions have multiple releases. Each version also has a status to more clearly communicate with team members and potential consumers. Let’s dig deeper into these versioning concepts in Postman.

• Versions represent concurrent lines of development, while releases represent a serial set of increments. You can create different versions in a situation where older customers might be on version 1 of an API and newer customers on version 2. For adding a small feature or fixing an issue, you can create a release on the relevant version.
• Releases are created at the point you decide to deploy to an environment. The deployment might first happen on beta, then on staging, then on production environments. At each stage, they are like snapshots in the history of your API. In most cases, this point corresponds to a “minor version”. Releases can also be made public so that consumers see clear demarcations in the changelog.

Let us know about your API development process

These are a few key features in Postman to help you manage your API development. You might want to deprecate the older version or maintain parallel versions that can be developed and consumed independently of each other. Managing versions and releases allow you to clearly communicate changes about your API to colleagues and consumers of your API. These Postman features offer some flexibility to customize your workflow, so let us know how you’re managing your API lifecycle.

Technical review by Steven Baxter and Abhijit Kane