Versioning RESTful APIs has been a topic of great debate, mostly around the way versioning is implemented. The three main options for versioning are URI, HTTP Header, and Message Schema Identifier.
While there is no right or wrong answer, the recommendation is to set a standard and stick with that decision to reduce confusion from consumers of your API.
The URI-based versioning includes the version number in the URI for the RESTful API. As an example, the 3.0 version of the products API would appear as follows:
This approach is currently the most popular because it is very clear to see which API version is being utilized. Critics of the approach indicate that the URI to the resource should not change just because the version of the API is changing.
The HTTP Header approach focuses on keeping the URI clean and adds version information in the header. The 3.0 version of the products API would maintain a generic
However, the HTTP Header would include the following information:
While the URIs are always the same, critics of this approach point out that this approach is not a semantic way to describe the resource.
Message Schema Identifier (Content Type)
Like the HTTP Header option, the Message Schema Identifier (or Content Type) versioning strategy creates a custom internet content type within the header. So, the same generic URI is used:
The header is updated to reflect expecting a custom content type:
Again, the URIs are always the same, but critics of this approach point out that the version reference is hidden and that custom internet content types can appear messy and are difficult to test.
While not an option for public APIs, those who are developing APIs internally and have influence and control over all the consumers of the API may consider not implementing versioning at all. In this instance, the challenges associated with versioning and maintaining multiple versions can be avoided.
Critics of this approach are likely to point out that this approach is only one public integration away from versioning needing to be addressed. Thus, even private APIs should be designed and treated as publicly available resources – which would include the need for versioning.