{"id":19730,"date":"2024-10-10T16:48:08","date_gmt":"2024-10-10T15:48:08","guid":{"rendered":"https:\/\/www.equalexperts.com\/?p=19730"},"modified":"2024-12-09T14:23:53","modified_gmt":"2024-12-09T14:23:53","slug":"just-say-no-to-versioning-apis","status":"publish","type":"post","link":"https:\/\/www.equalexperts.com\/blog\/our-thinking\/just-say-no-to-versioning-apis\/","title":{"rendered":"Just say no – to versioning APIs"},"content":{"rendered":"

As a concept, non-versioning is controversial, but I believe that we should never version our APIs.<\/p>\n

In my experience, we all agree on the fundamental, core principle that producers of APIs should not break consumers of APIs through change. That\u2019s helpful common ground to start a debate – but let\u2019s define the principle more clearly: API consumers expect never to be broken by a change in the API that they consume.<\/p>\n

I\u2019m not the first to push the idea of no-versioning – the concept was first described by Roy Fielding, who wrote a thesis<\/a> describing RESTful APIs. Fielding introduced the world to the concept of HATEOAS (though the thesis never uses the weird acronym) and talks about no-versioning in the context of REST APIs. He adopts the attitude of \u2018be damned if you go for non-REST\u2019.<\/p>\n

REST is an elegant architectural style that makes building evolvable APIs easy, without succumbing to versioning. This post isn\u2019t a place for detailing REST (this book<\/a> is a particularly good resource) but using RESTful principles for API design is probably a strong starting position.<\/p>\n

However, REST isn\u2019t the only solution, and good API design can overcome versioning.<\/p>\n

API producers have broadly taken two approaches to not breaking consumers. The most common practice and the one that\u2019s considered to be the standard by most, is to version APIs, deprecating the older versions and encouraging consumers to migrate. There are multiple ways of describing the version in the request. The most visible (and the one most organisations default to) is in the URL. Others will pass the version via the Accept header in the request. You\u2019ll likely come across several resources that suggest this is best practice.<\/p>\n

However, API versioning has downsides regardless of the patterns used. For one thing, supporting more than one version of anything is a pain. Finding a bug in one version necessitates confirming it doesn\u2019t exist in other versions. If it does, you need to fix it in all versions (meaning more testing is needed) or fix the latest version only, and insist that consumers move to a version without the bug – which may be the latest, or does a superseded version need fixing?<\/p>\n

Of course, some patterns minimise the pain of versioning. And advocates of versioning will argue that the concerns I raise can be resolved – but this is fixing a self-inflicted problem. No-versioning stops the problem in its tracks. The API consumer benefits either way: they don\u2019t need to change, are not broken by changes to the API, always have the latest functionality, and the documentation they need to read is minimal.<\/p>\n

I started this post by saying that we should never version APIs. Backtracking slightly, I believe that versioning is unnecessary because I\u2019ve yet to come across a situation in API design and development that actually needed it. And I\u2019ve yet to be convinced in practice that versioning is a necessity, or even preferable to the alternative.<\/p>\n

Why you may want to version your API (but don\u2019t need to)\u00a0<\/strong><\/p>\n

I have yet to come across a situation in API design that needed versioning. Below is a sanitised version of the sort of conversation I have, when suggesting that we shouldn\u2019t version:<\/p>\n

What if we need to add a new mandatory field in the request?\u00a0<\/strong><\/p>\n

If it\u2019s really mandatory, why have an API version that doesn\u2019t require it?<\/p>\n

We need versioning to carry out new business logic\u00a0<\/strong><\/p>\n

Again, this shouldn\u2019t be described as \u2018mandatory\u2019 new business logic – at best, it\u2019s an optional field that may change the path your code goes down. If it\u2019s truly mandatory, why support a version that doesn\u2019t need it?<\/p>\n

We made a spelling mistake in the field name, and if we change field names, it will break the consumers\u00a0<\/strong><\/p>\n

So don\u2019t change the field name, if consumers are using it fine. If it isn\u2019t causing harm, leave it. If you really want to change a spelling or name, support both – maybe only document the new one, but don\u2019t break if the old spelling is used.<\/p>\n

We want to change the structure of our response\u00a0<\/strong><\/p>\n

Articulating why<\/strong><\/em> you need to change the structure may help you to design it in a non-breaking way. If necessary, consider content negotiation, where a consumer includes the media type they expect in the \u201caccept\u201d header. If the structure is significantly different maybe it isn\u2019t a new version of the API but a new representation of the resource that the API returns. The key is to handle the change internally rather than forcing consumers to change.<\/p>\n

Github versions APIs<\/strong><\/p>\n

I think Github does APIs really well. If you used them as your exemplar, you wouldn\u2019t go far wrong. Github is on version 4 of their APIs. How do we reconcile the two views – GitHub is good, but don\u2019t do versioning?<\/p>\n

Well, Github is only on version 4 of their APIs after 13 years. That\u2019s one new version every three (and a bit) years. But still, it is a new version.<\/p>\n

Another thing to note is that all the APIs were versioned at the same time, rather than individual versioning. There is a reason for that. The move from version 3 to version 4 was a move from REST APIs to GraphQL. This isn\u2019t about versioning the APIs, but rather the architectural style.<\/p>\n

While I\u2019m not privy to the thinking behind this, if you visit Github\u2019s docs home page they do not talk about version 3 and version 4 of their APIs, but the REST APIs and GraphQL APIs. I\u2019d suggest this is further evidence they see this as a change of architectural style.<\/p>\n

You\u00a0 will likely identify other scenarios requiring versioning, which I would love to hear about in the comments. I\u2019m even happy to work with people on the design. I don\u2019t want this to seem like a straightforward thing to do, especially if you do not start from a solid API design base.<\/p>\n

When you consider versioning as an option, take into account the following:<\/p>\n