The New Postman API Platform: Announcing 6 Key Platform Improvements

APIs are the building blocks of all modern software.

Since the beginning of Postman, we have been obsessed with helping our users solve problems around their APIs. Postman started by making it easy for developers to make simple API calls and verify responses—as well as helping developers test and debug APIs. Since then, we’ve massively expanded the capabilities of Postman to support more aspects of the API lifecycle. What started as a simple API testing tool has grown to include designing and mocking APIs, documentation, monitoring, discovering APIs, and collaborating—not just within your own team and organization, but also across organizations via public workspaces.

From our vantage point in the industry, we have seen the rise of API-first companies that use APIs as the building blocks of their software strategy.

The transition from code-first to API-first is a significant technology shift, one that is often not easy to do. We spoke to many of our customers, ranging all the way from early-stage teams to Fortune 500 companies. We also looked inwards within Postman, how we as a growing organization build and manage our growing API Landscape as we go through our own API-first journey.

As a result of all those internal and external discussions, we realized that to succeed in this world, organizations need a system that integrates the different tools and processes to effectively build, manage, publish, and consume APIs. And this system goes all the way from the definition of the capabilities you intend to build to production and your interactions with consumers.

Today, we are excited to announce the new Postman API Platform that integrates deeply with your workflows and creates a best-in-class integrated experience that scales from individual developers to organizations with thousands of people working together.

Let’s start by elaborating the problem space.

API disambiguation

Sometimes when people use the term API, they talk not only about the Interface, but also the functionality or the code that powers that Interface.

The Interface is the language that describes the API, whereas the Implementation refers to the code that powers that API.

The Interface is usually expressed using protocols like HTTP or Thrift using formats such as JSON or XML whereas the Implementation is often written in a programming language like Java, Node.js, or PHP.

Decoupling the two is important and is what gives APIs their power. You can change the Implementation of a system at any point, while keeping the Interface used to access that system consistent, making it easier to make changes over time without disrupting your consumers.

API Landscape

An API Landscape is the complete set of APIs published by an organization—managed by different business domains, running on all platforms, and built by different teams. The APIs within this Landscape may be intended for different audiences: Partner, Public, and Private.

• Public APIs are publicly available for anyone in the world to consume, usually fronted by some kind of auth.
• Partner APIs are exposed to strategic business partners. They are not available to everyone and need specific access. Like Public APIs, Partner APIs are the above-the-surface portion of the iceberg, because they are the most visible ones and used to communicate beyond the organizational boundaries.
• Private APIs are hidden to everyone outside the organization and only exposed by internal systems. These Private (or Internal) APIs are used by teams within the organization to share capabilities and gain agility in the process. Private APIs also form the majority of the iceberg across most organizations.

Given the external visibility of Public and Partner APIs, there’s a disproportionate effort organizations put in to make these APIs consumable.

The Interfaces of Private APIs, on the other hand, tend to be more dynamic. Organizations need to be cognizant of the cost associated with constant change to these API Interfaces.

Internal APIs have internal consumers, whose jobs rely on the effectiveness and stability of these APIs.

A successful API-first organization realizes that the API-first philosophy is effective when it is applied consistently to both internal and external (i.e., Public or Partner) APIs. A strong Internal API Program can be a competitive advantage, and strengthen your external APIs in the process.

API-first at Postman

Being API-first is something that we have always strived towards at Postman. We, of course, dogfood the Postman platform heavily in this endeavor.

API-first companies acknowledge the isomorphism that exists between the business, the technology, and the organizational architecture. As such, we have been deliberate about designing against this isomorphism.

Organizationally, at Postman we operate as groups of cross-functional mission-driven teams, comprising members from Product, Engineering, and Design functions. This is a model that we see many of our customers adopting as well, and is not too dissimilar from Amazon’s two-pizza teams or Spotify’s Squad model. Here are the basic principles of this model:

• Each team takes end-to-end ownership for the domain of problems they are solving for; the teams need a deep understanding of the problem space, the users and personas, who they are, why they are facing that specific set of problems, and what are the jobs they’re trying to accomplish.
• Each team is successful if they’re able to operate as independently as possible, iterating and experimenting repeatedly.

After adopting this model, we learned that we shifted from a functional model of getting work done to a “graph of communication” within the organization, across our different teams. More bottom-up dependencies started getting created between these teams, which went against the intended design for independence. These dependencies often had to be resolved through meetings or coordinated releases.

For each of the nodes in this graph, there are two types of communication interfaces:

1. Programmatic: communication through what we commonly refer to as APIs
2. Human coordination: through discussions, meetings, shared objectives, etc.

We realized that if you create better programmatic interfaces (i.e., better APIs), the need for more human coordination (e.g., meetings and discussions) is reduced and this helps teams innovate more rapidly.

Here are some of the key attributes of these better APIs:

1. They have “Interfaces” that are designed to model the needs of their consumers, and not the internal concepts that “Implement” the API.
2. They focus on good API documentation and onboarding. Internal APIs with good documentation, when complemented with an onboarding guide, make your APIs actionable and useful.
3. They focus on good developer experience. This means that, as a producer, you acknowledge the existence of a continuous relationship between the consumer and your API and the expectation to support that relationship over time. You build for:
   1. easy discovery of APIs.
   2. an understanding of who is consuming your APIs and why, and you try to make sure their use cases are actively being met.
   3. monitoring of your APIs for errors and performance.

A simplified view of an API-first workflow

Let’s take a simplified view of an API-first workflow.

Note the iterative nature of this workflow. If you do a good job at these stages, you win the “luxury of doing it again”, this time with additional complexity and scope with acquired real-world feedback.

The simplified workflow could have the following stages:

1. Define: Here you outline the why and the what. You understand the consumers of your API and their needs, and you define the capabilities that are to be built or updated. You actively design the Interface of your APIs, before you build out the Implementation of your API. You build mocks, and you prototype and validate them against your consumers. If the API is actively being used in production, you augment your thinking with consumer feedback and instrumentation that helps you measure and observe your APIs.
2. Develop: This is where you write the code or the Implementation that brings these designed Interfaces to life. You test your APIs through a combination of manual, automated, functional/behavioral, contract, performance, security, etc. to ensure the API behaves as expected.
3. Deploy: This is where you deploy your APIs to your cloud or on-prem instances and make them accessible to your users. You publish reference guides, how-to documentation, and recipes to communicate how your API works, and you evangelize your APIs.
4. Monitor: This is where you keep an eye on multiple facets of your APIs. You see if your consumers are using your APIs as you designed them. You monitor your APIs to ensure they’re behaving as desired and alerting when things go wrong. You observe your APIs through a combination of business, technical, and product lenses.

Note that this prototypical API-first workflow is simplified for demonstration, and not designed to signal a waterfall approach. We see customers, and even our own internal teams, operating with varying degrees of parallelism across these stages.

As organizations adopt the API-first model, they engage more parts of their organization in the process and gain the superpowers that come along with being API-first.

The Postman API Platform

To succeed in the API-first world, engineering organizations need a new category of solutions: API Platforms, which are software systems with integrated tools and processes that allow producers and consumers to effectively build, manage, publish, and consume APIs.

Postman already provides amazing tools for the API lifecycle and collaborative capabilities for teams. With today’s launch, we are bringing deeper capabilities and integrating these tools with the broader platform: this new Postman API Platform brings together the different tools and processes in one definitive, authoritative place so your organization can focus on generating value for your customers.

Here are six key areas where we’ve improved the platform for you:

1. Deeper integration with version control systems

Version control systems have been among our most popular integrations. These integrations have enabled users to back up their collections (from Postman to the repository) and also synchronize API schemas (between Postman and the repository).

Many of our customers use version control systems to store the Implementation (code) of their APIs. Many like to keep the API Interfaces, modeled in specifications like OpenAPI, co-located with this code.

Recognizing that API constructs you define (collections, specifications, monitors, and mock servers) need to live with the code that powers your API, you can now harness the power of integrating Git to Postman’s API management workflows.

You can define API versions within Postman. API versions allow for parallel lines of development or deployment for an API. Consumers can choose which version they want to use.

You can link your Git repository with the API version—this links the branches and tags from your repository with API versions in Postman, and lets you keep schemas and collections in sync and iterate on the API definition in Postman as you code in your repository.

Make meaningful commits directly from Postman’s API Builder. You can also pull any changes you make in your repository (by merging a pull request, for example) into Postman, keeping your collections and specs in sync at all times.

Postman supports editing collections and specifications across all branches in your repository—this lets you use the Git workflow you’re comfortable with.

As you add features or fix bugs in your API, you can indicate that releases have “shipped” in Postman—these can map to tags in your repository. This creates a permanent link between the API definition in Postman and the source code that powers that specific release. Documentation, mock servers, and monitors can be locked to specific releases. This lets you evolve your API versions without changing the documentation your consumers see.

Releases represent the evolution of a version: each release points to a fixed state of a version during its evolution. A version’s changelog is a history of its releases.

Create multiple versions of your API to align with your strategy. You can manage your API lifecycle across numerous versions as you see fit: support multiple consumers or stick to a stricter versioning system. You also get an integrated API changelog so you can view changes to your API’s schema or underlying collections in one place.

We currently integrate with GitHub and Bitbucket, and plan to add support for GitLab and Azure DevOps soon.

2. The Private API Network

APIs should provide a great developer experience, and easy discovery of your APIs forms the starting point to that great developer experience. With a growing API landscape within most companies, it becomes harder for consumers to discover the API they are looking for, often leading to duplication of effort. But if you can make those APIs easily discoverable, you’ll open up existing capabilities for reuse by internal teams and reduce the time and resources needed to generate value for your users and customers.

With the Postman Private API Network, producers can publish APIs created within Postman for consumers to easily discover. The Private API Network provides a central directory of all APIs that exist within your organization, discoverable by anyone authorized to do so.

3. Improved governance of public APIs

A critical need for many organizations is having visibility into—and being able to govern—which APIs your organization exposes publicly for external consumers.

Today, millions of developers use public collection links to share their public APIs with prospective consumers. However, managing these links becomes a challenge—especially for larger teams since users do not have a central way to govern which collections have been shared with public links.

To make it easy for enterprise organizations to manage which collections they expose for public consumption, we are introducing a new feature that allows team members in enterprise organizations who hold the Community Manager role in Postman to view all public collection links created by members of their team in one place. Community Managers will also be able to know which team member created a specific link and delete links to collections they feel should not be public. Keep reading here to learn more about governing public API collection links.

4. API documentation and onboarding

All APIs should have good documentation and a well-thought-through onboarding experience.

With the Postman API Platform, you can link reference guides, how-to documentation, recipes, and other means of communication about how an API works to your APIs.

5. Integrated tooling

Most organizations use a wide variety of tools to build and manage their APIs. However, many of those tools are disconnected from each other, and teams spend a lot of time trying to integrate those tools through processes. Often, there is also no clear, single source of truth for your APIs, because they’re distributed across these disconnected tools.

To help you avoid these problems and govern your entire API landscape more seamlessly, the Postman API Platform integrates the following key components together with the definition of your APIs:

1. Source code management
2. CI/CD
3. API gateways
4. Application performance management (APM)

You can now link your CI/CD pipelines to your API tests. Your team will be able to see recent builds for your pipelines across all branches and re-trigger failed runs. With this release, we’re adding support for Travis CI and Circle CI. These accompany the tests you link to your API versions within Postman.

You can also integrate with your API gateway, you can view recent deployments and events, and get a one-click link to your logs and deployments. With this release, we’re adding support for the AWS API Gateway, with more to follow in future releases.

Finally, you can integrate with your APM system. You can link your API, and get Apdex scores, slow transactions, and more for your APIs, all in one place. With this release, we’re adding support for New Relic.

These integrations augment Postman monitors that allow you to monitor your APIs.

Postman acts as a single source of truth for all private and public APIs for your organization, with source code, application monitoring data, and deployments living close to schemas, collections, and mock servers.

6. Deployment control for the Postman Enterprise plan

The Postman Enterprise Application is a separate packaged binary for IT and system admins to deploy and control versions of the Postman app within an organization. This application is available as an MSI package for Windows and supports silent installation, system-wide installation, and additional configurations to control how and where Postman is installed on each device. It integrates with enterprise mobility management (EMM) and mobile application management (MAM) solutions.

The Postman Enterprise Application is now available in private beta for all teams on the Postman Enterprise plan and we look forward to helping you set up and deploy the new app in your organization. Read more about deploying Postman at enterprise scale here. To get started, reach out to your Postman account manager or write to us at [email protected]. Support for macOS is coming soon.

Building an API Platform for an API-first World

Improving API workflows through integrations, discovery, and governance are just part of our continuing efforts to support the needs of developers and others across the globe. At Postman, we believe that the world is undergoing a tectonic transition from code-first to API-first. Companies that don’t make this transition will be relegated to being niche players in their businesses, and new kinds of businesses will emerge quickly to take their place.

As we noted above, in order to succeed in the API-first world, engineering organizations need a new category of solutions: API Platforms. To learn more about API Platforms, and how the API Management category is being redefined in the API-first world, keep reading here.