The Base of the API Lifecycle

Every organization creating APIs has an API lifecycle, whether they know it or not. The difference separating high-performing API companies from those with inconsistent results is a thoughtful and practiced approach. Below are key aspects of the API lifecycle, common characterists worth focusing on, and how Postman’s API platform supports each.

Discover

Before starting a new API endeavor, it is crucial to discover if the solution to the problem you're trying to solve already exists. Building on already existing functionality brings products and services to market faster. Postman has several elements that make this discovery step easier.

Search

Search is the fundamental element of API discovery, allowing API producers to search for existing APIs before they begin the development of new APIs, as well as API consumers to search for APIs they can use as part of their applications and integrations. A healthy API lifecycle depends on the ability to search internally and externally for APIs, as well as the operations around them. The indexing of workspaces, APIs, and the elements of the API lifecycle like documentation, mock servers, and tests should occur by default across all teams before the desired efficiency and velocity will be realized across operations. Postman platform search provides visibility across these dimensions of API operations, looking across private, partner, and public dimensions, but then also leverages a role based approach to what elements of API operations are surfaced based upon your role–making API search a priority as part of the API lifecycle.

Watch

Watching APIs, as well as collections, provide a very precise way for team members to tune into the APIs that matter to them, as well as the elements surrounding them. Because collections can be used to power documentation, mock servers, and a variety of testing and governance approaches, the ability to watch a specific collection is amplified significantly. Anytime a team member or public consumers watches an API or collection within a team or public API workspace they will receive notifications when changes are made to that API or collection, letting them know in the Postman application and via email when they need to pay attention. Making the API lifecycle much more event-driven, allowing team members and consumers to define which APIs matter to them, as well as which elements supporting that API are important to their own personal goals.

Private Network

A private network is available for any team as part of the Postman platform. The private team network is accessible via the home page and provides a place to publish APIs, and each version of an API so they can be discovered by internal consumers. APIs can be added to the private network from the network itself, as well as part of managing the API within any workspace where the API is being managed. APIs in the private network will show up in the wider search, and allow for grouping and browsing by folder. Enabling teams who are producing APIs to easily increase the visibility of their APIs across teams, and beyond the workspaces where they are being developed. Increasing the chance that other teams will find before they begin developing a potentially duplicate API, or be able to put it to use within the application or integration they have planned.

Design

Designing an interface is one of the most critical steps in the API's lifecycle. It involves making decisions on how the interface will look and feel when used. American software engineer Grady Booch calls these decisions "significant", where significance is measured by the cost of change. Once your API has its first user, the cost of changing that interface increases significantly. Applying the appropriate rigor at this stage of the lifecycle will decrease the likelihood that change is necessary later. This includes, but is not limited to, defining performance, functionality, and security expectations.

Techniques

Delivering consistent APIs across many teams takes establishing and usage of common techniques for defining, designing, deploying, and managing APIs. There are a number of proven standards and process in use across the API sector that help teams better develop their process for delivering APIs at scale across a large organization. This element is about acknowledging at the highest level that there are numerous techniques to consider as you are developing your API lifecycle strategy, and provide access to some of these other techniques that can help your team be more successful across all areas of your API lifecycle.

Goals

Having goals for each API helps articulate the value an API should be delivering in plain language. Goals can be as simple as a paragraph narrative or a bulleted list. Goals should help a team better understand what the business value for an API will be, and help keep the technical details of an API more precise when it comes to design and development, as well as iteration with each version. Keeping goals an active part of each version of an API, and making sure they are published as part of documentation, and within reach of the team within a workspace helps make sure APIs are as coherent as possible in their evolution.

Comments

Comments can be applied to APIs and collections, providing a feedback loop for each individual API artifact, as well as inline comments for each part of an API artifact. Comments can be used to keep the feedback loop localized with each API, as well as allowing team members and the public to be more precise by highlighting and commenting on a specific path, parameter, or part of a script automating or testing an API. Comments are a little buried beneath the details of each API and collection, but once your team realizes they are there and they can comment, mention, and have a conversation about each part of producing or consuming APIs, they’ll prefer commenting here rather than via other external channels, helping any other team members or public consumers join in and learn from the discussion.

Sharing

Sharing is essential across the API lifecycle for collaborating with team members, partners, and 3rd party consumers, making APIs, documentation, tests, mock servers, environments, and other elements of the API lifecycle available for use. The most common way to share API lifecycle artifacts is across workspaces with different levels of access by team members, partners, and the general public. APIs, collections, and environments can be easily shared across workspaces designed to target a specific team or audience. Next, sharing of collections can be done using the URL to the raw JSON behind, or by publishing the collection using the Run in Postman button, which can be embedded in any HTML page. Sharing is a fundamental ingredient for how API operations move forward and act as the factory floor for an organization. Without sharing there is no internal collaboration amongst team members or engagement with the public across the API lifecycle.

Documentation

API documentation is the number one pain point for API consumers, and is the toughest area to keep accurate and up to date for API producers. API documentation has evolved over the last decade and become a natural part of API developer portals, something that is baked into API management solutions, as well as seeing waves of open source solutions emerge. API documentation is rarely hand-crafted, and most times generated using OpenAPI definitions, and natively part of defining any API using a Postman collection. API documentation should be publishable, sharable, and something that is always keeping up to date with the latest changes, allowing any API stakeholder to read and easily understand what they need to do to put an API to work in their application or integration.

Publish

Publishing is the act of making an *implementation* available that executes a service's interface in an accessible environment. This act requires more than just pushing a deployment to a cloud host. Publishing an API entails communicating documentation and, in some cases, code to the appropriate audience.

Private Network

A private network is available for any team as part of the Postman platform. The private team network is accessible via the home page and provides a place to publish APIs, and each version of an API so they can be discovered by internal consumers. APIs can be added to the private network from the network itself, as well as part of managing the API within any workspace where the API is being managed. APIs in the private network will show up in the wider search, and allow for grouping and browsing by folder. Enabling teams who are producing APIs to easily increase the visibility of their APIs across teams, and beyond the workspaces where they are being developed. Increasing the chance that other teams will find before they begin developing a potentially duplicate API, or be able to put it to use within the application or integration they have planned.

Public Network

The Postman public network is where you will find APIs from leading providers like Stripe, Twilio, and Salesforce, while also being the place you can publish your own public APIs for discovery by millions of Postman users. The public network is where teams can discover other public APIs they can put to work, or help make their own public APIs more discoverable by other 3rd party consumers. APIs can be published to the public network by changing the visibility of the workspaces they are in to be public, making the APIs, collections, environments, and other elements viewable by anyone browsing or searching the Postman public API network. The public network isn’t just about API discovery, it is also about helping bring observability and engagement with public API consumers more discoverable and accessible. Moving from the many siloed API portals of the past, where API producers work to build their own API ecosystems, to where API producers just participate as part of a larger API platform ecosystem–where developers already exist.

Secure

An APIs usefulness to automation also makes APIs a potential target for malicious actors. Ensuring security is accounted for and applied consistently for all APIs produced is a significant step.

Role Based Access Control

As a team admin, you have the power to define Postman access at the team level. You can utilize Postman’s role-based access control system to limit visibility of team resources, define your development workflow, and provide access to administrative personnel. Team members with the billing role can modify who else has billing roles at the team level. Workspace admins can modify the admin and collaborator roles for the workspace. Editors of particular elements (APIs, collections, environments, monitors, and mock servers) can modify the editor and viewer role on the element. With these roles, you and your teammates can manage access for each individual, or, if you are on a Postman Enterprise plan, for groups.

Security Testing

Security testing ensures that 100% of the surface area of an API is secure against the common types of attacks as defined by OWASP. The OpenAPI for each API can be used to generate collections that provide 100% test coverage for all API paths, ensuring that every API, and detail of the API is evaluated as part of common security practices. No API should move into production without having a security collection defined for testing for all of the known vulnerabilities, moving the security conversation further left in the API lifecycle–allowing developers to manually test as they develop an API, but then also allowing for the automation of API security testing as part of the deployment pipeline, or scheduled via a monitor. Security testing is just one part of a larger testing, but also security strategy, helping standardize how security is applied, while also properly equipping teams with the latest information and practices they need to be successful in securing API operations.

Monitor

To properly manage APIs and how they flow through the API lifecycle, it is vital to have accurate and up-to-date information. Postman provides several valuable elements to track APIs across the platform.

Activity

Tracking the activity that occurs across the design, development, and operation of APIs allows the ability to see what changes are made by teams to APIs and the supporting artifacts. Ensuring that there is observability present across the management of each API without teams having to do any additional work, tracking all changes, and then make this information visible to everyone involved. Providing an ongoing snapshot of the activity involved with moving each API forward, making sure nothing gets lost along the way. You can find an activity for each workspace using the overview tab and across workspaces via the home page of your Postman application.

Change Log

The change log for an API should inform stakeholders regarding what has happened with the design and development of an API, providing a single place that any team member or consumers can go to get up to speed on what has changed. Providing a self-service log of the change that has occurred, reducing the need to talk to designers and developers, helping increase velocity of team members, while also making sure there is a thorough record available for each API to keep all stakeholders informed regarding the change that is occurring across a platform.

Notifications

Notifications are designed to keep developers informed across the APIs that matter. Providing in-application, email, and other types of integration-enabled notifications via existing channels. Notifications help make API operations and the API lifecycle real time and event-driven, helping keep developers up to speed on what is happening without having to go find the information themselves. Notifications provide the heartbeat of what teams are up and what they are doing when it comes to producing and consuming APIs. Notifications represents the next generation of communication around API operations, replacing email, chat, and other existing forms of communicating, making notifications more precise and applicable to what developers are worried about.

Manage

Markets, strategies, team experience, and professional expectations change. So too, do APIs. However, changing an interface is no trivial task, given the number of integrations depending on it. Learning to prioritize and schedule changes to minimize the negative impacts is a skill. Thankfully, Postman includes elements to navigate through this step of growing importance.

Versioning

The versioning of each API and supporting artifact play an important role in help teams manage change across many different APIs. Providing a clear marker for when changes are made to an API, helping team members, as well as consumers understand what has changed along the way. Semantic versioning is the primary approach applied to APIs and other artifacts used as part fo the API lifecycle, providing a notation for how you define the version of an API, and how you increment that version based upon major, minor, and patch changes. Versioning is how you signal and communicate where everyone is regarding change to API infrastructure and help consumers understand and navigate change with as little friction as possible. Helping organizations effectively manage change and achieve the velocity needed to keep applications and integrations accomplishing what is need to realize the desired business outcomes.

Deprecate

API deprecation should be considered as early on in the lifecycle of an API as possible, establishing estimates for how long each version of an API will be maintained and what the overall lifespan of an API should look like. However, it is common for many teams to not think about deprecation early on as they are focused on only delivering new features and increasing the adoption of an API. Even with this reality there should still be a formal strategy for developers to consider when it comes to how they should be thinking about API deprecation, providing a common blueprint they can follow to properly shut-down an API without causing friction with consumers.

Conclusion