Right now someone is powering up an original iPhone. On their home screen, they’re tapping the icon for a 10 year old app. As it loads, it calls an endpoint that a development team would rather not maintain. For many APIs, a life of suspended animation is a big part of their story.
In API lifecycle terms, this is called maintenance, and it’s necessary. Even with careful planning, it’s the longest stage in an API’s life.
The Life of an API
For the best chance of success, you want to thoughtfully plan your API. Like any software, there’s more to it than writing the actual code. You need to know how it supports your other efforts and how it will be used.
The minimal stages of the API lifecycle include:
- Strategy: what’s the goal and why does the API achieve it?
- Design: what do you need to build it?
- Development: how will you build it?
- Deployment: how will you get it to production?
- Maintenance: how will you fix and improve it?
- Deprecation: how will you gracefully cease support?
The above six stages encompass the ideal journey an API will take, with the support of the teams behind it.
The Meta-cycle of Maintenance
Once an API is being used, it gets much harder to change. Yet, there are many factors that will move you to alter the API you’ve already designed and built. With each fix, improvement, and other updates, you may find yourself revisiting other stages of the API lifecycle.
For example, the goals for your API may change. That would require you reconsider the strategy and potentially the subsequent stages. If the API is not scaling with increased usage, you may need to refactor the code or look at more efficient DevOps practices for your deployment.
In addition to deciding what changes need to be made, you’ll need to make sure they don’t break anything. This is a key factor of this longest stage of the lifecycle. You’ll have an easier time making changes if you’ve considered potential maintenance upfront. Among the things to question is when it will make sense to deprecate the API instead of adding to it.
The Shortest Stage of the API Lifecycle
Done right, deprecation is a moment in time. You’ve already put in the effort up front to understand how the API will be used, which may limit the impact of a deprecated API. You’ve also made updates and taken all possible precautions during the maintenance phase.
When possible, contact your API consumers to upgrade their integrations before shutting down an API. At a minimum, you can use headers and planned downtime to provide advanced warning during a pre-deprecation maintenance phase.
It’s never ideal to stop supporting an API, but it’s an expected part of the lifecycle. As a best practice, keep the endpoint responding to point developers to the replacement service. They may be able to migrate their code to the new API, which is likely already well into its longest stage.