The Reimagined API-First Workflow, Part 1: for Developers

With the launch of the new Postman API Platform earlier this year, Postman now supports API-centric workflows to help your team move toward being API-first. API-first is the new model of software development in which applications are conceptualized and built as an interconnection of internal and external services through APIs.

Though some might argue that APIs are technically just the interface, we’ve realized in our many conversations with our users that the term is ill-defined. In the real world, it encapsulates source code, definition files, tests, performance measurements, documentation, security audits, and everything in between, which is what the Postman API Platform brings together. Check out our recent graphic novel for a different twist on the subject.

Let’s walk through what API-first development looks like using the new, reimagined model. We’ll create a sample application using API-first principles. By the end of it, you’ll have a web application that’s built using the Postman API Platform, with tests, monitoring, and deployment phases integrated. Through this process, you’ll be able to –

1. Use Postman as the source of truth for APIs in your team.
2. Implement your team’s API versioning strategy in Postman.
3. Continue to use existing tooling that your team is comfortable with.

If you’re a developer on a team that’s working on building or maintaining an API, the most significant benefit you get is a way to think about the API as one entity, instead of treating the code, the definition, and Postman Collections and tests independently. Development, testing, commits, reviews, and more are all done on the API instead of on specific components. Here’s what you need before you get started:

1. A Postman account and team (create one for free at https://www.postman.com). You can create up to 5 integrations as part of the free tier.
2. A repository on a version control system (Github or Bitbucket, for example).
3. A local or web-based IDE
4. Access to your team’s CI/CD, APM, and API Gateway tooling (if applicable)

Setup

1. Create a new API:
   1. Start your journey by creating an API in Postman. An API is bounded by the problem space it addresses and represents a set of long-term producer-consumer relationships. If your team exposes an Identity API to other teams in your organization, that’ll map to one API. In this example, let’s create our “Hello API-first world” API.
      
   2. You’ll need to label the first version of the API and specify the format its schema is in. It’s possible to design your API using collections too. Postman’s API versioning supports multiple strategies which we’ll explore in a later section. You’ll find most of your time spent within an API version—the API definition, linked collections, mock servers, monitors, and environments are associated with a version. We’ll use OpenAPI in YAML as our format.
2. A great way to integrate your API development process with code is by linking to your repository. This assumes that the source code that powers your API is stored and collaborated on in a repo. Postman also supports scenarios where you might already have Postman Collections or an API definition in your repository. Here’s how you can set it up:
   1. With the API Version view opened, click the Connect Repository link on the top-right. Postman currently supports GitHub, Bitbucket, and Gitlab (support for other providers is coming soon). You’ll be asked to authorize Postman to access your repository.
      
   2. Select the branches that Postman should use:
      1. The development branch is where you’ll pull and push Postman’s schema/collection changes. This could be develop, or any other branch, depending on your API workflow. Postman lets you select any branch in your repository as the development branch – that’s used as the “root” or “trunk” of your API dev process. We recommend that active work on definitions and collections happens in the development branch – this is backed by Postman’s powerful annotation and real-time collaboration mechanisms.
      2. The main branch is where you typically release to production from.
   3. If you don’t have your schemas or collections saved in your repository yet, leave the two folder selection options as is. Postman will create the postman/schemas and postman/collections folders once you integrate. If you’re already saving them in your repo, select the relevant folder.
   4. Once you hit Connect, Postman will automatically sync your schema and collections into the selected folders of your repository. This will be the only automatic commit Postman makes—all future commits will be user-initiated. At this time, if you have collections already present in your repository, they’ll be imported and added to your API.
3. Here’s what the configured integration looks like:

Development

Now that the setup is done, let’s go through a basic workflow that simulates an update cycle to your API. We’ll add an endpoint to return a welcome message, “Hello API-first world”:

1. Since we’re doing API-first, let’s update the default schema to reflect the new endpoint we want to add.
   
2. If your API only has a definition, create collections for your API. Documentation and mock servers are a good place to start—your API’s consumers can use these to start their development process without waiting for your implementation. Once the collections are created, you’ll see them under the API version in the sidebar. This lets the API construct be the anchor for all your activity in Postman. Any collections you add to the API later will show up here too.
   
3. At this point, your API’s interface is updated and can be saved to the repository, similar to a code-level interface change. Open the repository menu, and hit push. Postman will list the files that’ll be pushed to the repository—in this case, the API definition—and any collections that you added. You’ll need to add a commit message –  this mirrors the code flow where you make one meaningful “commit” with a number of source files updated.
   
4. Set your version’s stage to in development, indicating how or if the version is meant to be consumed externally. This piece of information is relevant to other members of your team (to understand whether to start the review process, for example), or potential consumers (a version that’s in beta might not be used for critical applications). The “edit version” option also lets you configure consumer visibility—if it hasn’t been made available for consumers, it shouldn’t show up on the API network.
   
5. This is a great time to introduce Postman’s new server boilerplate feature, which lets you generate a server stub in one of four languages: Go (Chi server), NodeJS (Express), Java (JAX-RS), and Python (Flask). You’ll get a ready-to-run application that lets you start adding business logic. With the API version tab open, click the < /> code icon on the right. You can select the language/framework of your choice and download the server stub. You’ll get a zip file that you can extract in your working directory.
6. Let’s assume you’re authoring code on a feature branch to allow for code review. A typical workflow might involve pulling the latest develop and creating a new feature branch to begin development in your IDE of choice. You can add business logic to the boilerplate generated earlier, or update existing code. In this example, let’s add the business logic to implement the route we configured earlier.
7. In your editor, you can also make minor changes to the API interface. If you realize during development that a max. size restriction hasn’t been enforced on a particular field, the definition and any collections can be changed directly in the IDE.
8. You can also continue using any other tools you’re comfortable with—as long as they use the repository to read and write schemas/collections, they’ll seamlessly blend into Postman’s workflow.
9. Once your code is updated and unit tests are run, push to the feature branch as you normally would. In our example, this includes changes to the source code, API definition, and one or more collections.
10. Send a pull request to develop once your automated tests run, as you would in a code-first workflow.
    
11. The new API Platform enables review of the API as a whole, instead of just the source code. As a reviewer, in addition to reviewing the PR on Github, you can also review the schema and collections in Postman. Switch to the relevant feature branch—all collections that are part of the API will show up under the API in the left sidebar. You can examine the updated API definition or collections, and even update them if you need to. Once you’ve made changes, push to the repository as described earlier.
12. Once the pull request is merged in your version control system, the development branch contains the latest state of the API—the updated definition, collections that power documentation and mock servers, and of course, your code.
13. This is where you might “release” to beta or production. This can be done with the tools and processes your team is already using— your CI/CD scripts might perform deployment, for example. You’ll probably end up creating a tag on Github, indicating the snapshot of code that was released.
14. Pull the latest develop branch into Postman. This ensures the API is up-to-date with the repository.
    
15. To record this change on the API, create a release on the API version in Postman. You can specify the Git tag that you created earlier. Doing this creates a link between the API construct in Postman and the source code in the repository.
16. Once created, releases show up in the version’s changelog. You can expand/collapse releases to get a high-level view of how your API has evolved over time. Setting a description for the release makes this more meaningful. The list of releases is the changelog that your consumers are looking for—indicating what changed and why. Releases also let you control their visibility—a minor release might not be something you want to make visible on the API network, for example.
17. Releases also act as a point-in-time snapshot of your API. If you make more changes to the version and return to the release view,  you’ll see the collections and definition anchored at the point of release, even if the version has been updated. To view the release snapshot, click the view this release link, you’ll be able to view the schema and collections in the read-only mode. This is a powerful feature; you can create documentation and mock on this release. While publishing documentation, select the release with the collection—any consumer who views documentation will see the state of the API you intend them to see.
    

This illustration shows how versions and releases in Postman work with Git:

Versioning

Now that we’ve seen how to set up the API and perform an iterative change, let’s explore the new versioning capabilities Postman has to offer. With Postman’s API versioning, you can:

1. Publish multiple versions of your API at the same time.
2. List relevant API versions together on the Postman API Network.
3. Continue using headers or path/query params for routing in your gateway or load-balancer.

Continuing from where we left off earlier, we’ll work on creating a new version for parallel deployment. It’s up to you when you want to do this—a good rule of thumb is that if your consumers need to have a choice, or if you want to continue development on two or more tracks, you should create multiple versions. Here’s an illustration depicting an API’s evolution over time:

To create a new version:

1. From the API sidebar, open the API’s context menu, then click Create a version. You’ll see a bunch of options:
   • Name: This represents the version everywhere. This will be consumer-facing if you publish your version, so choose this carefully.
   • Visibility: This determines whether or not the version will show up in the API’s listing. If you have an API where v1 is available for consumers but v2 is not, the visibility property will prove useful.
   • Elements to carry forward: This represents the relationship between previous versions and the new one you’re creating. If you are creating the new API definition from scratch (v1 is a REST API and v2 is GraphQL, for example), don’t carry forward any elements. If v2 is an evolution over v1, with 80% of endpoints being the same but some breaking changes being introduced, you can choose to carry forward specific elements, like the schema or collections. These will be duplicated into the new version, so you can still work on the old version independently.
     
2. Once the new version is created, you can link it to a repository. All versions in an API have to link to the same repository. This means you have a couple of options:
   • Choose the same branch as before: if a new version (v2) is linked to the same development branch as v1, the older version will be prevented from making pushes/pulls from the branch. v2 will be considered the “active” version. For v1, you can still edit your schemas and collections in Postman.
     
   • Choose a different branch for active development: many of our internal teams and users use a develop-v2 or equivalent while working on a new version of the same API.
3. The versions will appear in the left sidebar under the parent API. Clicking a version will open the version’s tab, from which its collections, schemas, documentation, tests, monitors, and integrations will be accessible.

You can learn more about these features in our documentation or recent webinar. We have many exciting updates coming up over the next few months, all to bring us closer to building the next-generation API platform that gives you and your team API-first superpowers. We’re eager to understand your API-first use cases better and hear how your experience with the new Postman API Platform has been. If you have any thoughts or questions, feel free to reach out with a comment below. You can also give product feedback through our Community forum and GitHub repository.

This post described one cycle of API-first development and introduced Postman’s powerful new version control integration. In the next blog post, we talk about how the API platform can align with testing workflows.

Try Postman now