What is API Versioning? Two Strategies for Designing Better APIs

API versioning matters, in particular when you're looking at API as products that can have many consumers but that you still want to evolve over time. How can you minimize the impact of changes so that your API consumers get the best possible experience?

We're diving into this and look at the two main strategies that you can use to minimize the impact of API versioning on your consumers.

Keep in mind that in both cases this does require a bit of upfront work. When you're designing the API and hopefully informed by API guidelines of your organization, you can go one of two ways:

① Design your API to be extensible from the very start. Extensibility can mean different things, but the essence always is to create a design that has clear extension points and to clearly document that consumers have to expect extensions and handle them appropriately.

② Design your APIs to be static but also design a way how new versions can be announced. That way new versions are something that consumers have to explicitly switch to, but you have a communication channel how you can announce new versions and how you can manage the lifecycle of different parallel versions.

Which approach you are choosing is up to you. In practice, there seems to be a preference for the first variant. It may place a little bit more responsibilities on consumers, but it greatly simplifies the operational complexity for providers. Choose wisely because it will be hard to switch from one model to the other.

#api #apimanagement #versioning #design #apidesign #gettingapistowork #digitaltransformation

[majed]

Very nice explanation, Thanks so much!!

[def]

Focused and insightful as always. Thank you!

[apiopsatlanta]

thanks for sharing Erik. Question: So, can we think of extensibility as evolvability? I talk about designing APIs to be evolvable so that we don't create a new version (i.e. api/v2, etc). And a follow-up: creating a /v2 is then then choosing option 2 right? Thanks.

[DreamsAPI]

Hi @Erik, it was great catching you in the OpenAPI session.