Table of Contents
The more our lives become infused with technology, the more we seek ways to predict the future to solve problems before they manifest. We want to prepare ourselves for the obstacles ahead, so we are not thrown too far off course. The same is true when developing APIs.
API publishers want to have a plan in place for their API. However, they may be asking themselves, where do I start?
Just like the famous product lifecycle stages, an API has lifecycle stages as well. In case you forgot, a product’s lifecycle is broken down into introduction, growth, maturity, and decline1. By the end of this article, you’ll learn about the many stages of the API life cycle and clearly see how it compares to the product life cycle.
Additionally, we’ll discuss how API lifecycle management fits into API management and the benefits of lifecycle management.
API Management is a more recent term that describes several components that make up managing an API. The management process is divided into different categories across the industry, but the underlying components remain the same. When it comes to managing APIs, the different components are often interrelated.
Interestingly, API lifecycle management is an API management component, and the API lifecycle includes considerations like design and monetization. Furthermore, API design and monetization are API management components. To clear things up, let me provide a shortlist to diagram the API management structure. Below are the main components of API management:
- Lifecycle Management
However, we can find elements of each inside other components, for example:
- Includes security and lifecycle management considerations
- Includes analytics and security components
- Lifecycle Management
- Includes designing, securing, and monetizing the API
What’s important is that we understand the relationships between components and how they all work together to effectively create, deliver, and allow us to manage APIs.
Benefits of API Lifecycle Management
Before we start breaking down the different stages of the API lifecycle, let’s discuss the benefits of API lifecycle management.
First, an important part of managing is the ability to plan. Understanding the API lifecycle gives managers a framework for charting the course of the API. It gives the managers and team leaders more control over their future.
Second, it can help managers estimate how far along they are in their API project, like a checklist.
Third, proper API lifecycle management keeps different stakeholders involved and informed. Working in a larger organization, designers, developers, testers, and consumers could be siloed into different teams. Therefore, understanding what stage an API is in adds an implicit level of communication across teams.
Now that we have provided context and benefits of API lifecycle management let’s examine the different stages.
What is API Lifecycle Management?
An API’s lifecycle can be divided into seven stages2. The stages are mostly chronological, so they are designed to be done one after the other. However, in an API-first approach, one of the benefits includes allowing teams to work in parallel3.
For example, as the development team starts to build the API, the DevOps team will secure the API gateway. I don’t recommend trying to do it all at once. Especially if you are still trying to understand the full lifecycle or the individual components. Regardless of the approach, I hope you start to recognize that some stages can, and will, overlap.
Certainly, you were aware that API design was part of the lifecycle. It’s arguably the most important part. The design stage is where aspects of the API are defined, like:
- Resource naming
- Security protocols
- Response and request properties
This article describes the API lifecycle for web-APIs. Therefore, your API most likely will follow the REST architecture or a WebSocket, event-driven design. Each has there own specification. REST APIs follow the OpenAPI specification, and WebSocket APIs should consider the AsynchAPI specification.
This informs later stages on protocols, structuring data (schemas), accessing resources, and versioning. One of the benefits of using a specification to design an API is the portability of the specification. The spec is consumable by tools that help with testing, mocking, and documenting.
The development stage of an API depends on the programming language. Regardless, a development team is informed by the API specification on how each route is designed to interact with the defined resources.
Furthermore, developers are guided by schemas that, hopefully, exist in the spec. A specification is malleable. Developers may find that what designers want to do can be done in a better way. Or they need to change the naming of certain response properties.
This stage of the lifecycle benefits from a developer portal or collaboration space where teams can work together.
Learn the difference between an API Marketplace vs Developer Portal
Outlines for API security procedures may exist in the API specification. Additionally, an API gateway could secure the API. The security stage answers questions like:
- Who can access the API?
- How many requests can be sent?
- How does a client gain access?
Commons forms of API security include Oath2, API-keys, CORS, and IP whitelisting. Whether the API is an external, internal, or hybrid API plays a large role in choosing the most appropriate security. Since security deals with access, security is tethered to the monetization plan for an API in one way or another.
Publishing the API makes it available for clients to access and use. By this stage in the lifecycle, the API’s code is tested, and the documentation is refined and published. The development phase has built and tested the core functionality, the security phase has created access controls, and now the API is ready to use.
The Publish phase and the subsequent Monitor phase overlap significantly. Although the API is documented and out in the world, it feels like we’re setting it free without any way to know how it’s performing—or if it’s performing.
Either before we publish or in tandem with publishing, the API is monitored. The managing team will want to look at key analytics, especially in the early days of the API.
Furthermore, functional testing in the monitor phase allows teams to find errors, view performance, and test changes through CI/CD pipelines. Once the API is published, there’s good reason always to keep an eye on its use. Given there are no significant changes to the API, the monitor stage could go on until the API retires. That also means that teams are continuing to update the testing and monitoring tools with new API versions.
As previously mentioned, monetization is coupled with security and access controls. Some pricing plans use a pay-as-you-go model, where subscribers only for what they use. Other’s may limit the number of requests per tier and possibly, offer an unlimited tier.
At the end of the cycle, it’s time to retire the API. The more common term in software engineering is deprecating. For example, your organization has operated a successful API for three years. However, your product is evolving and incorporating new technology. Adding this new technology to the API is not compatible with the original version.
Therefore, when the new API is built, the original version of the API becomes deprecated, which can mean that you no longer are offering support, bug fixes, or guaranteeing the services because the next version of the API is out (and is in the middle of its own lifecycle). Just because an API is deprecated does not mean that the API no longer works. Previous versions of APIs can remain in use for many years and may still be accessed by applications.
All APIs experience entropy and the lucky ones are upgraded into better and more efficient versions.
I hope this article could lay out the API lifecycle stages in a clear and easy-to-follow manner. I will repeat that many stages overlap and depend on decisions made in previous stages. Consequently, the stages of your API may not follow the above stages exactly. The important part is recognizing that these components exist in one form or another, and your API management approach becomes clearer when you can recognize each phase.
Thank you for reading!
What is API Lifecycle Managment
Being aware of the different stages that an API will go through during its lifecycle to better plan for the future.
What is API management?
API Management is a set of processes, policies, principles, and practices that allow owners to gain control over their API. The integrated systems that make-up API management are born out of a large set of questions that project managers, developers, and team leads hope to answer.
What are the stages of API lifecycle management?
Design, develop, publish, monitor, monetize, and retire.
1 Kopp, Carol. “Understanding Product Life Cycles.” Investopedia, 27 Dec. 2020, www.investopedia.com/terms/p/product-life-cycle.asp. Accessed 3 Mar. 2021.
2 A Checklist for Every API Call: Managing the Complete API Lifecycle. Apigee, apigee.com/about/cp/api-management-checklist. Accessed 2 Mar. 2021. Lifecycle stages are modified from the diagram on page 2.
3 Wagner, Janet. “Understanding the API-First Approach to Building Products.” Swagger.io, 2021, swagger.io/resources/articles/adopting-an-api-first-approach/. Accessed 4 Mar. 2021.