On: How to Version an API

[greencurry43]

I personally like to think about managing change well rather than versioning an entire API. In this, API designers provide instructions on how APIs will evolve over time, how features will be deprecated, and how this process will be communicated to API consumers. Change management also includes recommendations for client developers on how to evolve along with the API and build clients that don't fail when something as small as a JSON property is absent or added. You don't necessarily need version numbers to do this.

An API version says to me that one day the entire API may introduce a major change that is separate from the current API. If you plan to never introduce a major change like this, you may not need a "/v1" in the URL.

Kudos to the author for putting together a nice article :)

[tetraodonpuffer → greencurry43]

API consumers might also not be very flexible when it comes to adapting to API changes: some might have developed fragile/inflexible code that will go up in flames if you even add a new field to an object (leading to support calls and escalations), this is why depending on your domain you might need very strict versioning requirements.

Some APIs will not change a version number even if new objects/fields are added, others will, it really depends by what space you are in and your customer needs and it should be taken into account when designing your API.

[greencurry43 → tetraodonpuffer]

I think you are right here. It takes two to tango, and if the clients are tightly coupled to the API, the best intentions for evolving slowly will fail. :)

[nradov → greencurry43]

Never say never. It's generally impossible to predict how an API will have to evolve over time in response to changing requirements.

[greencurry43 → nradov]

That's true. However, I think this falls under YAGNI [0]. If you happen to get to a point where you have to change your an entire API rather than evolve what you have, you should consider it a new, separate API rather than instruct all client developers to plan for it up front. Plan for evolvability and handling changing requirements up front.

[0] https://martinfowler.com/bliki/Yagni.html

[ljcrabs → greencurry43]

And how would you name this new API? Bob? Or version 2?

[greencurry43 → ljcrabs]

Name it whatever you want. Point is, you don't have to plan for such a drastic change when a separate domain/subdomain will solve it for you.

[_pmf_ → greencurry43]

As an API consumer, clean cuts are much, much more manageable than a continuous stream of small breakages.

[greencurry43 → _pmf_]

True. I would consider a continuous stream like that to not be helpful change management. But if you have to have continuous breaking changes like that, you would want clean cuts. My point is, find ways to evolve your API without breaking things.