Managing API versions: The API lifecycle

Managing API versions are part of the bigger picture of API lifecycle management. Most importantly, the goal is to make sure that API consumption is as little impacted by changes in the API landscape as possible, while still allowing individual APIs and the entire landscape to evolve.

When thinking about managing API versions and how to manage the API lifecycle, it’s tempting to focus on details such as how to manage version numbers (we recommend semantic versioning) or how to represent versions in RESTful APIs (in the URI? Wherein the URI? Or should it be in HTTP header fields?). But it is important not to lose sight of the main goal behind managing versions: Doing it in a way that decouples API producers and consumers as much as possible so that every team can move at their own speed.

On the one hand, when consumers use an API, they should be able to do so in a stable way. But on the other hand, API product management should be able to improve and evolve APIs based on consumer feedback. The management of API versions has to tackle these conflicting goals. The best way to do this is by establishing and cultivating API design practices across the API landscape. We look at the two most important aspects of how managing API versions should be done:

• Use design patterns that allow you to evolve APIs in a backward-compatible way so that APIs can be evolved without having to be versioned (in non-backward-compatible ways). This allows APIs to gracefully evolve without having to publish a new “version” of the API (in semantic versioning terms: design your API so that most changes can be done with minor version changes).
• Plan ahead how non-backward-compatible API versions can be released with as little damage as possible. This means planning ahead for API deprecation and sunsetting so that API consumers can be alerted when an API is going to be replaced (in semantic versioning terms: when you have to release a major version, make sure that there is a plan in place how to alert API consumers of the upcoming breaking changes).

If you want to learn more about what to focus on for managing API versions, check out this video. This is the second video in a series about “API versioning,” along with my previous post discussing “Semantic versioning.”