API Lifecycle Stages: The 8-Point Blueprint

Kin Lane

January 14, 2022

A well-defined API lifecycle is essential for taking full advantage of operating on an API platform and being able to effectively govern hundreds or thousands of APIs across many different teams. Having a shared understanding of what the API lifecycle is across your org, and possessing a common vocabulary for describing it, will help your teams get on the same page when developing APIs with greater productivity, quality, and governance needed to drive your enterprise into the future.

Since the API lifecycle will mean many different things depending on who you’re talking to, we’ve provided this base API lifecycle blueprint to serve as a launching point. This lifecycle definition isn’t meant to match the needs of every enterprise organization but is intended to provide you with an example to help you think about what your own API lifecycle looks like. We hope this gives you a foundation for talking to your teams about how they are delivering APIs today so that you can then strategize how you’d like to improve and evolve upon that lifecycle.

8 stages of the API lifecycle

We’ve broken up the API lifecycle into eight stages. Depending on the type of API, and whether or not it is a new or existing API, its lifecycle will have different entry points. This blueprint shows eight of the most common areas of the API lifecycle that we see across Postman’s global users, but also some of the operating elements that shape and define each area of the API lifecycle and help standardize how teams work.

1. Define

This area of the API lifecycle is all about ensuring the operations around an API are properly defined. This lays the foundation for being able to effectively design and bring an API to life, while also establishing a known place to get all the information you need regarding each individual API or group of APIs.

• Team members: Formerly defining who on the team will be moving an API forward through all stages of its lifecycle, providing a clear definition of who is responsible for each part of producing an API.
• Team workspace: Establishing and properly setting up a dedicated workspace for each API helps ensure there is always a single place to go to find everything that is happening with an API across its entire lifecycle.
• Public workspace: Some APIs will benefit from establishing a public workspace where third-party consumers can learn about an API, view the moving parts of its operation, and engage with the team behind making the API lifecycle much more transparent.
• GitHub repository: Having a dedicated GitHub repository for an API provides a single place where code and other artifacts can be managed, with a pipeline, issues, and other supporting elements an API will need to operate.

2. Design

The design phase of the lifecycle focuses on establishing a formal process and approach to designing an API that helps establish consistency of each API that ends up in production, ensuring that APIs are developed using common industry and organizational patterns while establishing known practices for shaping the surface area and behaviors of APIs.

• OpenAPI: The OpenAPI Specification provides a common vocabulary for describing the surface area of request and response APIs, as well as webhooks, ensuring that API producers and consumers are on the same page when it comes to integration. It also helps stabilize multiple areas of the API lifecycle providing a contract that can be used for delivering documentation, mocks, testing, and more.
• Mock server: A mock server helps replicate as much of the functionality an API would have in production, before the time to actually have to write any code, making APIs more tangible and real early on in the lifecycle. This allows teams to rapidly design an API that meets the needs of everyone involved, providing usable elements that power design, documentation, testing, and other elements of the API lifecycle.
• Comments: Comments on APIs, collections, and other elements of API operations allow for more tightly coupled and inline conversations to occur around entire elements or specific parts and pieces of elements, allowing teams to collaborate and communicate across the API lifecycle.

3. Develop and Document

The document phase of the API lifecycle ensures there is always complete, accurate, and easy-to-follow documentation available for all APIs, alleviating the number one pain point for API consumers when it comes to onboarding with APIs by providing the human-readable technical details of what an API does. This helps minimize the time to the first API call.

• Reference documentation: Documenting the entire surface area of an API, providing a complete reference of what is possible with an API, allowing consumers to explore every path, parameter, schema, and other details of how an API works, making the digital resources and capabilities available via an API.
• Examples: Including examples of the API request, responses, and messages used across API operations help provide a versioned, evolvable, and reusable set of examples and synthetic data that can make documentation richer and make testing more relevant to actual business needs.

4. Test

A test-driven API lifecycle ensures that each API delivers the intended outcomes it was developed for in the first place, providing manual as well as automated ways to ensure an API hasn’t changed unexpectedly and is as performant as required. This establishes a consistent, high quality of service across all APIs.

• Contract testing: Contract tests can be derived from API artifacts like OpenAPI, JSON Schema, and GraphQL, and used to ensure there are no changes to what has been promised when an API was designed or developed. They provide a repeatable test that can be run manually, on a schedule from multiple regions, or as part of a CI/CD pipeline to ensure contracts with consumers are upheld.
• Performance testing: API performance tests can be defined as individual tests using collections, pulling from one or many individual API paths and measuring the time it takes for the response to be sent, They provide a test that can be run manually, scheduled across multiple geographic regions, or executed as part of a CI/CD pipeline, helping ensure an API is always meeting its expected performance benchmarks.

5. Secure

The security phase of the API lifecycle makes sure that there is a consistent approach to identity and access management for each API. In addition, proper security testing is put in place to make sure that all APIs are being scanned and secured in a consistent way, no matter which team developed the API, or whether they will be used for private, partner, or public use in applications.

• Authentication: The consistent application of standard authentication as part of an established API management layer strikes a balance between access to digital resources and ensuring that undesirable actors do not have access to valuable assets.
• Security testing: Security tests can be defined for any API using executable and shareable collections, testing for common OWASP vulnerabilities and other custom scenarios or business approaches. A single or suite of security tests that can be manually run, scheduled across multiple regions, or executed as part of a CI/CD pipeline, automating security consistently across APIs.

6. Deploy

This area is about providing a well-defined process to deploy an API into development, staging, and production environments, helping teams efficiently deliver future iterations of an API in a consistent and repeatable way. This ensures that APIs are properly tested, secured, and governed as a native part of the deployment process.

• CI/CD pipeline: Like other aspects of the software development lifecycle, APIs benefit from well-defined, repeatable CI/CD pipelines to deploy, test, automate, and orchestrate throughout the API lifecycle, publishing APIs to development, staging, and production environments.
• Gateway: API gateways provide a centralized or federated approach to the deployment and management of APIs at scale across an organization, leveraging commercial or open-source solutions to deploy APIs into development, staging, production, or another environment. This allows for the standardization of common elements of API management, and for the configuration of APIs using common policies.

7. Observe

This stage is about making sure that all APIs are fully monitored by scheduling contract, performance, security, and other tests from multiple cloud regions. In addition, monitoring the activity, changelog, and state of an API using notifications helps keep teams and consumers informed regarding the state of the APIs they depend on.

• Contract testing monitor: Monitors can be set up for all API contract testing, scheduling the run of contract testing when needed and configuring to run from the regions that matter most to business operations. This ensures that each individual API contract is never breaking with consumers and each API is delivering as expected on a 24/7 schedule.
• Performance testing monitor: Monitors can be set up for all API performance testing, scheduling the run of performance testing when needed and configuring to run from the regions where performance makes the most difference on business. This ensures that each individual API SLA is met, identifying API performance issues early on and before there is significant business impact.
• Security testing monitor: Monitors can be set up for all API security testing, scheduling the run of security tests when needed. This ensures that each individual API is regularly certified as being secured; APIs do not become a liability due to changes, and they remain compliant with the latest level of security testing occurring across an entire organization.
• Activity: The changes made to any aspect of operations by team members, providing observability into when APIs, mock servers, documentation, testing, monitors, and other critical elements of API operations are changed or configured..
• Changelog: A detailed history of the changes that have been made specifically to an API, showing all of the changes to the structure of an API as part of the design and development process; a single list of what has changed for consumers and other stakeholders to get up to speed.
• Notifications: Providing notifications about activity around the operation of any API, allowing for in-application, email, or type of message via integration with common platforms. This provides real-time updates about what is happening across API operations.

8. Distribute for discovery

This area of the API lifecycle is about enabling discovery across operations. The goal is to help teams find existing APIs before they develop new ones, properly matching API consumers with the right APIs and supporting API documentation, workflows, and the feedback loops that exist as part of the operation of internal, partner, and public APIs for applications and integrations.

• Search: Ensuring APIs are always available via search helps make sure that APIs can be found by consumers, but also by other producers who are looking to develop similar APIs. The search for APIs and the operations around each API are critical aspects of the API lifecycle that should be considered as early on in the design and development stages, but at least as it is deployed into production.
• Private network: Private API networks allow organizations, groups, and teams to establish private catalogs of APIs, collections, and the other artifacts and elements around them, making it easier for producers and consumers to find APIs that are being designed, developed, or operating in production. APIs are more accessible but only to an intended audience.
• Public network: Public API networks allow for teams, APIs, collections, and other elements to be made available for searching and browsing by a public audience, helping API producers reach a larger audience and helping consumers to quickly find the APIs and other resources they need in their applications and integrations. It connects consumers with producers in an ongoing and collaborative way.

There are many other elements to consider when it comes to API lifecycle planning, but these areas and elements represent what all API producers should be thinking about as they work to establish a common definition of what the API lifecycle means across their teams. While it’s easy to apply different labels to each of these areas, and some elements might vary depending on the type and maturity of an API, your teams should be considering everything in this blueprint—and then should start thinking about how each element can be applied consistently across your own operations now and tomorrow.