Version Identifier

Published: 27 January 2024

Known Uses

Versioning is a hotly debated topic in the API community and the book states correctly that the version strategies differ widely and are debated passionately. There are many questions and discussions floating around the internet about the correct way you should version your APIs. The HTTP header versioning (consumer gets to decide which version to request ) appeals to purist RESTafarians. In general, the most common approach is a combination of URI parameters and header criteria. However, in many cases, people tend to fixate blindly on the versioning issue. But the fact that there are so many perspectives on the topic of versioning probably indicates that there isn’t a single universal solution for this issue – there is no single ‘right way’. Perhaps the issue does not solely reside within the versioning strategy, but rather within the change strategy itself. The underlying problem is managing the impact of a change, and the appropriate version strategy can be applied based on this management. See Discussion Input below.

The book explains very well the various methods of implementing versioning to denote progress and maturity in API evolution. In addition to incorporating a Version Identifier in the URI, header, or payload, the more unconventional query-based versioning method is also utilized (however, we have never seen this in the wild).

Some known uses (to mention only a few):

Known Uses

An interesting observation is that the zealous discussion about the version numbering of an API is a red herring: the version number is not the problem. Instead of a versioning strategy, you should have a change strategy. This observation basically propagates not doing versioning at all, or using it as a last resort since it causes long-term maintenance issues. This can be achieved by making use of hypermedia controls, by reconsidering new resources instead breaking existing ones by applying the correct bounded context boundaries and by developing a smart change strategy that embraces a compatible versioning strategy being always backwards compatible without needless duplication.

When discussing change strategy, we struggle (within Enexis) with balancing API complexity and client-side impact; to what extent should APIs be future-proof (forward-compatible)? As API designers, we often suggest common generic data structures even if a particular consumer does not request this. For instance, even if one consumer is only interested in the numerical value of a total amount we would suggest exposing this in the API as a value and a currency. Hence future-proofing the API for consumers that might require the currency. This example might introduce little extra complexity, but in practice, it’s hard to define guidelines on where future-proofing is helpful and when you are better off accepting a new API version in the future.

The point is that version numbering on a Web API “seems like a simple solution to a simple problem, while in fact it is a very naïve solution to a very complex problem” (quoting Asbjørn Ulsberg). This observation is supported by the following principles: Bertrand Meyer’s open-closed principle suggests that software entities should be open for extension but closed for modification. When applied to APIs, the implication is that you can augment your resources but not change them. You could do more to share the burden of change between API and client. Postel’s law, often referred to as the Robustness Principle, states that you should be liberal in what you accept and conservative in what you send. In terms of APIs, this implies a certain tolerance for consuming services.

Recommended Reading

More information on this topic can be found here:

Read the complete pattern on api-patterns.org

Leave a Reply

Your email address will not be published. Required fields are marked *

Scroll to Top