API lifecycle

Stage 1: Define

In the first stage of the API lifecycle, product managers and other stakeholders must define the operational, business, and security requirements for a single API or group of APIs. This requires them to agree on the API's intended use case—and identify the team members who will move it through each subsequent stage of the lifecycle. They should also create and configure a dedicated workspace where team members can collaborate, as well as a GitHub repository that is connected to a CI pipeline. These steps help stabilize the rest of the API lifecycle and establish locations and tooling for stage-specific work.

Stage 2: Design

API design involves making intentional decisions about how an API will expose data to consumers. These decisions are then captured in an API definition, which is a human- and machine-readable representation of an API's intended functionality. API definitions adhere to API specifications, such as OpenAPI and AsyncAPI, which provide a standardized format and vocabulary for API definitions and lay the foundation for API contracts, documentation, mocks, and tests.

Leaders may wish to standardize the design stage by defining organizational patterns and practices for shaping the surface area and behavior of APIs. For instance, they may require that all teams follow the OpenAPI specification, and they may also define style rules for capitalization, naming, and punctuation that can be enforced through automated checks.

Stage 3: Develop

After the API has been designed, developers are tasked with writing code that implements its intended functionality. Most development teams use Git for version control, which enables them to safely manage changes and revert to previous iterations if necessary. They also typically use GitHub or GitLab repositories to store their source code, keep track of code-related issues, and conduct code reviews. Development workflows vary widely, so it's important for leaders to clearly define these processes in order to standardize their team's approach.

Stage 4: Test

API testing, which occurs during the “develop,” “secure,” and “deploy” stages of the API lifecycle, enables developers and QA teams to confirm that an API is working as expected. API tests can be executed manually, or they can be automatically run from multiple geographic regions or within CI/CD pipelines. Testing early and often helps teams surface and remediate issues before they become ingrained or reach production.

There are many different types of API tests, and each one serves a unique purpose. For instance, contract tests are used to ensure that any changes do not cause the API to deviate from what was promised during the design stage. Performance tests, in contrast, can help confirm that an API is able to deliver responses in an appropriate amount of time.

Stage 5: Secure

The “secure” phase of the API lifecycle involves checking an API for common security vulnerabilities that can compromise an application's overall security posture. For instance, it's important to confirm that an API's authentication logic only allows legitimate users to interact with the API and access its data. These API security checks can be run manually or automatically within CI/CD pipelines, and they help ensure that every API within an organization's portfolio follows the same security standards.

Stage 6: Deploy

The “deploy” stage of the API lifecycle refers to the process of publishing APIs to development, staging, and production environments. Many teams leverage CI/CD pipelines and API gateways to standardize the deployment process and ensure that every batch of changes is properly tested and secured before it reaches consumers. Consistent processes make deployments more predictable, which is particularly important for agile teams that ship new code several times a week.

Stage 7: Observe

The “observe” stage of the API lifecycle involves collecting, visualizing, and alerting on API telemetry data in production. During this stage, SREs and DevOps engineers will configure monitors to automatically notify them of API performance and security issues—and leverage APM tools that place API performance data in context. API observability plays a crucial role in surfacing errors, latency, and security vulnerabilities before they negatively impact dependent services, partners, and customers.

Stage 8: Distribute

During the “distribute” stage, teams will focus on improving their API's discoverability.

Distribution may be the last stage of the API lifecycle, but it's not the end. API work is highly iterative, and teams will constantly return to the earliest lifecycle stages as they address consumer feedback and develop new features.