Postman common functions. Streamline the API Development Lifecycle with Postman Version Control

Postman download exe

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.

A Postman collection which documents User API

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.

Creating a fork in Postman

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.

Collaborating in Postman with comments

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.

Different forking workflows

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

List of forks in 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.

Online Postman API test

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

Two options to integrate changes – merge and create PR

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.

Creating a pull request in Postman

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.

PR collaboration experience

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

Strategies available while merging a PR

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:

Pull Request merge checks

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.

Postman provides a wide range of functions and features to assist with API development, testing, and collaboration. Here are some commonly used functions in Postman:

• Creating and Managing Requests: Postman allows you to create API requests by specifying the request method, URL, headers, parameters, and body. You can manage and organize requests within collections, including creating folders, adding descriptions, and reordering requests.

• Request and Response Visualization: Postman provides a user-friendly interface to view and analyze request and response data. It supports syntax highlighting for various data formats such as JSON, XML, and HTML, making it easier to understand and validate the data.

• Environment and Variables: Postman allows you to define variables and environments. Variables enable you to store and reuse dynamic values across requests, making them flexible and easy to maintain. Environments provide sets of variables specific to different environments (e.g., development, staging, production).

• Tests and Assertions: Postman supports writing test scripts using JavaScript for automated API testing. You can write assertions to validate response status codes, headers, response bodies, and more. Postman's testing framework allows you to assert and validate different aspects of API responses.

• Pre-request Scripts: Postman enables you to execute scripts before sending API requests using pre-request scripts. These scripts can be used to dynamically generate values, manipulate data, or set variables based on specific conditions.

• Collection Runner: The Collection Runner allows you to execute a series of requests in a collection. It enables you to perform data-driven testing by iterating over multiple sets of data or environments. You can configure iterations, delays, and data sources for more comprehensive testing.

• Mock Servers: Postman allows you to create mock servers for simulating API responses without a live backend. Mock servers are useful during development, allowing frontend developers to work independently by providing simulated API responses.

• Documentation Generation: Postman can automatically generate documentation for your APIs based on your requests and collections. It provides a simple way to share API specifications and details with stakeholders.

• Collaboration and Teamwork: Postman offers collaboration features such as sharing collections, collaborating on requests, and commenting on specific requests or collections. It also supports version control integration to manage changes and updates effectively.

• Integration and Automation: Postman integrates with various tools and services, including version control systems (e.g., Git), CI/CD platforms (e.g., Jenkins), and API management solutions. It provides options for integrating with these tools to automate API testing and deployment processes.