Anyone creating or maintaining APIs is surely aware that sometimes APIs become outdated. While we do our best to create APIs that last, there’s a natural evolution. In some cases, we need to close down APIs, or transition to a new approach. The earlier you accept the natural lifecycle, the easier you’ll make things on yourself in the future.
Below we’ll cover five stages of the API lifecycle:
Each stage brings with it a specific focus, a single question that should be top-of-mind. Your answer to these five questions will inform how your API moves through the lifecycle.
Conception: Do You Need an API?
For many, this stage of the lifecycle is skipped with an implicit understanding that a new API is the right solution. Development plows ahead, without ever really asking the question or understanding the answer.
Your organization would do better to have a deliberate discussion at this early stage. Internally you should understand the business and technical reasons behind this new API. Take stock of how it might augment, replace, or meaningfully impact other APIs. Most importantly, look forward to other stages of the lifecycle and commit to supporting this API through each of those stages. Starting something is easy, but providing for it over the long term can become a burden.
The conception stage is also a good time to become clear on your audience. If this is a public API, what type of developer will use it? If the API is internal, who will be the first consumers? Often, the audience will be somewhere between public and private. For these sort of partnership-driven APIs, it’s even more important to think through who will use it and how they will gain access.
Better yet, your audience will inform the next stage, where the API begins to take shape.
Design: What Will Your API Do?
Now you’ve decided to move forward with an API. You know who will use it and have committed to supporting it through every stage of the lifecycle. Now is the time to design the API, using tools that make it easy to share your work. Like the initial conception, this second question is often skipped or glossed over before an organization really understands its answer.
Granted, what your API will do is a big question. If answered too quickly, often with implementation details, you’ll come up with an incomplete answer that may make future stages difficult. This question should be tackled from a user perspective. Put another way, **what use cases should this API support**?
Here’s where your understanding of the audience will help. When you know who is using your API, you can better figure out what the end user of their software needs. At a minimum, you can ask your early consumers for more detail on use cases. The API design process is about mocking up API requests and responses to describe what you’ve heard from your consumers, then see if it meets their needs.
Eventually you’ll want to create an API description (such as one based on the OpenAPI spec) to codify what you’ve learned. Beforehand, and in addition, it can be useful to create Postman Collections to share requests and responses amongst teammates. While a description covers the endpoints of an API, Collections can describe use cases and user stories through a sequence of API requests.
During the design phase, your consumers can call cloud-hosted mock servers to test as if they were calling a live API. These prototype servers can be generated from Postman Collections or OpenAPI documents. They take you from conceptual API to something that seems real enough to catch issues you might otherwise miss. Finally, it’s likely easier to make updates to mock servers than to production servers, especially when collaborating with non-engineers.
Development: How Should You Build Your API?
This third question is where most organizations begin their journey with a new API. Elements from the skipped stages arise unpredictably within the development phase. Due to the lack of focus and clarity, API development takes much longer when it has not been thoughtfully conceived or designed. Worse, when you’re “almost done”, you could have to start over if it doesn’t match the consumer’s expectations.
Your answer to the development stage question becomes much easier when you have the answers from the previous two stages. Your audience and endpoints are already determined. Development can focus on implementation, exposing the right data and systems. You may still have technical details to figure out, but they won’t be muddied by unclear business needs or data formats.
If you’ve given proper consideration to the other stages, initial development may be your shortest stage. Of course, even with proper planning, you’ll be developing your API over the years as you maintain it.
Maintenance: What Needs to Change in Your API?
With initial development complete, your API is in production. Everything that happens now is either maintenance or deprecation. How long you maintain your API depends on how much control you have over the clients that consume it. For example, your mobile application may continue to receive calls to outdated endpoints for years due to users not updating their apps. Again, it’s important to get the first stages of an API right, but you’ll still need to make updates to your API. You should always be assessing what’s working and what needs improvement.
There are two primary places to look for feedback about what needs to change in your API: your own systems and your API consumers.
First, you want to see your systems the way your consumers do. Create API monitoring that periodically tests your endpoints from the outside. API errors and downtime comes with even the best software, but you want to be proactive. Don’t count on others to report outages. In addition, you’ll likely have other ways to monitor usage internally. For example, you might look at server and database load.
Another internal monitor to consider is actually a signal of external usage. You’ll want a way to see which endpoints are called the most and least. In addition, look for other signs of how developers are consuming your API. Check support logs for frequent questions. Better yet, take a page from the early phases and talk to developers. You’ll learn what could be improved, then ensure it can be implemented in a way that does not break existing functionality.
Deprecation: Is it Time to Retire Your API?
Lastly, at some point during the API lifecycle, you’ll find that the required changes can’t happen without disrupting current implementations. Or, perhaps you’ve built a new API and more consumers have adopted the replacement. There are many reasons to retire an API, but it’s almost certain that you’ll be ready before your consumer. To ease the pain, you can provide a heads up and help upgrading.
How much notice, if any, you are required to give your API consumers is determined by terms you set either for all your APIs, for this specific API, or for a specific consumer. Regardless of what you’re required to do, you should aim to give plenty of notice to an API consumer. Anything less than 90 days will impact their short term roadmap. Unless they want their software to break, they’ll need to take attention from another project in order to fix the problem caused by your API deprecation. This could cause even bigger issues with an internal API, because you may require this disruption of dozens of your own teams.
In addition to offering as much notice as possible, you can help your API consumers by providing an upgrade path. For example, if your deprecated API is being replaced by a new version, help your consumers see what needs to happen to update their code. Sometimes you’ll be able to supply a tool to make it easy, but at least document what it takes to transition. If the versions have different authentication, you can supply an endpoint so their users don’t need to re-authenticate. In some cases, there won’t be a new version, but you can point users to other options, such as a self-hosted open source alternative.
While nobody likes to see APIs retired, it’s often the buffer you need to build and support something new. The API lifecycle is just that—a cycle—one that is repeated as you discover new opportunities, technologies, and business needs. Ask yourself these five questions throughout your API journey to conceive, design, build, and maintain better APIs.