Announcing Postman’s redesigned API Builder with native Git support
Today, APIs are the building blocks of modern software and business—having evolved beyond just a mere interface to become fundamental in expanding a software’s capabilities. More and more organizations across every industry are building APIs to offer external services as well as improve internal efficiencies.
API development involves multiple stages and stakeholders working across different tools and processes. In our Guide to API-First playbook, we explain the different stages of the API producer and the API consumer lifecycle, and how these two intersect.
Our mission with the Postman API Platform is to help you effectively navigate through the process of API development and management. With the launch of Postman v10, we are excited to announce our redesigned API Builder experience with native Git support.
What is the API Builder?
Postman’s API Builder is a place for you to create an API and manage the entire lifecycle of the API. The API Builder connects to the source code repository to automatically maintain API documentation, tests, and specifications alongside code. This allows Postman customers to improve collaboration with API producers because you can work with your team in a multi-user, multi-branch setup. You can commit and push changes without affecting your team or consumers until you’re ready to publish.
How to use the API Builder to manage your APIs
Step 1: Set up an API in the API Builder
Postman’s API abstraction is central to all API workflows. To get started, define your APIs in Postman’s API Builder. Start by linking a new or existing repository or add definitions or collections to define, debug, test, or document your API. If you already have API definitions available, you can import them into Postman. You can see below how we start by creating an API and adding an OpenAPI definition.
Step 2: Connect the API to a repository
With an increasing number of developer teams building APIs instead of shared libraries, collaborating on source code is often disconnected from other API workflows (Postman Collections, definitions, contract tests, and documentation). This leads to sub-optimal productivity; APIs being duplicated across the org and contracts not always being adhered to. We believe that the repository is an integral part of the broader API construct, as it holds the source code of the API.
One aspect of Postman v10 we are excited about is the new way of working with Git repositories. You can now start working on new features and perform all developer actions on branches. Switch to a branch to add a new endpoint, and you’ll see Postman’s API design, documentation, and testing capabilities at your disposal.
Click on the Connect button to start linking to an existing Git repository. You’ll be asked to authorize Postman and select specific folders where you want your API data to be saved.
Step 3: Design, develop, and collaborate with your teammates
Now that the API is set up, you can start designing and developing it. Add definitions and collections in Postman, and test the API by sending requests locally.
For the Git-linked API, you always work on a branch. The current branch is shown on the API (check the bottom right) and the Source Control panel is on the right. You can commit and push changes to your repository like you would in your IDE. At any point, you can also look at the commit history, compare your changes against the last commit, or even discard changes. All this is now possible from within the Postman app, enabling you to effectively work according to the Git workflow that your team has adopted.
One important part of API development is collaborating with your teammates. Your teammates can now pull the changes you have made and start collaborating on them. Postman allows you to resolve conflicts in case changes are made to the same file simultaneously.
The changes made are visible only to the editors of the API—they can switch to the branch and see all changes made on the repository.
If your API hasn’t been linked to a repository, any changes to the definition or collections will instantly reflect for other users of your API.
Note: We support GitHub, GitLab, Bitbucket, and Azure. Support for on-prem deployments of these services is available on Postman’s Enterprise plan.
Step 4: Testing and automating the API
You might have already explored Postman’s collection-level and request-level testing capabilities. Postman v10 extends this to the API, bringing together CI/CD workflows (see the integrations we support here), validating against your organization’s governance and security rules—all in one consolidated interface.
You can start by adding a test to your API. These can validate the functionality of your API by simulating complex API usage scenarios.
If you have an OpenAPI definition, Postman will automatically apply linting and validation rules. Read more to know about our API Governance features.
After developing a local development loop, all of the tests and validation steps can be included in your CI/CD pipelines. You can set up an integration with your CI/CD project by using the Generate CI configuration button. Postman CLI can execute these tests in a machine environment, as well as run governance and security rules validations for API schemas.
As your pipelines run, you’ll see results in your CI/CD console, and in Postman, along with compliance warnings thrown during your pipeline’s execution.
Once the API is developed, it is ready to be deployed in your runtime environments. You can also leverage Postman’s API gateway integrations to observe your deployments.
Step 5: Publish your API and distribute it to consumers
As a team working on a complex API across multiple branches, your stakeholders—both within and outside your team—will need a referenceable API, complete with documentation and a sandbox to enable evaluating endpoints.
You can now have versions of your API, which are like locked states of the API that you can ship to your consumers. Once a version is published, consumers will continue to see that version until you publish a new version. Consumers can also go back to any version that was published earlier. This helps you isolate any in-development changes from your API consumers, and they only see stable/ published versions of the API that you want them to consume.
Versions also help you document your API’s changelog over time, which could be used to indicate how new your API has evolved over multiple versions.
The API can also be added to your Private API Network where the internal teams can go about searching your API, evaluate it, and finally fork it to start integrating it within their own API.
Step 6: Gather feedback and iterate on your API
Once the API is published, you will get some feedback and might want to start adding new endpoints or fixing some issues. You might send a few requests from your collections to understand current API behavior and edit your API definition or collections.
If you have integrated with a repository, your next step will be to make updates and push changes to your repository. You can start by creating a new branch in Postman and making changes to the API.
At any point, you can discard the changes that you have made in your Postman app or look at the difference between the changes you have made vs the last state of the repository (look at the bin and diff icon against the files in the source control), and finally push the changes to the repository.
We hope this helps you get started leveraging Postman v10 for end-to-end API management. Stay tuned for more features to come. In the future, we plan to build additional capabilities around Git and Postman—including support for local Git repositories, pull request flows, and additional integrations with Postman CLI to support more use cases around test automation.
Sign up here for early access to the API Builder with native Git integration or schedule a time with us to learn more.
It’s hard for me to conceive of why collections, tests, etc. are not stored natively as files in the filesystem. Having to have postman development happen on its own dedicated branch is a non-starter for us. You guys shouldn’t be in the version control business at all. Just be a tool that does what you do well and let us determine our own workflows.