What are the best strategies to implement REST API versioning? URI and Media Type-Header Versioning Strategies and Examples

When considering REST API Versioning strategy , there are few different options available such as REST api URI versioning or Media Type Header versioning.
As our Restful web services application grows and the need for API upgrades or feature enhancement becomes necessary, we tend to think about creating new versions of APIs. Versioning of REST APIs is an important task and there should be a thorough analysis before adopting a particular strategy. Here we discuss some important strategies to consider while considering the release of new versions of existing REST webservice APIs.

As mentioned by Brandon Byars on Martin Fowler Blog Use versioning only as a last resort.

 "An important corollary to the definition of a logical environment is the notion of cohesion - each environment should have only one instance of a given service".

But as mentioned in the article, this usually leads to classic diamond dependency problem with large projects with multiple teams working in parallel. Following the Robustness principle, (“Be conservative in what you send, be liberal in what you accept”) is one way to avoid API versioning to a great extent. But this may not be achievable always.

HATEOAS and The API Contracts with Clients.

When we discussed HATEOAS and Hypermedia Aware Services And Clients we discussed why Media Types are part of the contract. As outlined by Roy Fielding,

  "A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types."  

And Also;

A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience. From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. 

So apart from the initial URI or bookmark, the contract is entirely driven by the defined media types and the selection of server provided choices. In the below article we discuss how the Hypermedia acts as the engine of the application state.
HATEOAS and Hypermedia Aware Services And Clients.

REST API versioning Strategies

Before we start on API versioning, it is always good to consider the Semantic Versioning.

Semantic Versioning

Semantic versioning is a simple scheme to add much useful meaning to MAJOR.MINOR.PATCH portions of a version, including incrementing the MAJOR version for breaking changes.
Given a version number MAJOR.MINOR.PATCH, increment the:

For example consider a version format of X.Y.Z (Major.Minor.Patch). When releasing bug fixes that doesn’t affect the API, then increment the patch version, for backwards compatible API additions/updates, increment the minor version, and for backwards incompatible API changes(new features etc.) increment the major version.

There are two popular strategies for versioning Rest APIs and Services.

1. URI Versioning
2. Media Type Versioning/HTTP Header versioning

REST API URI Versioning and Example

URI versioning involved including a version number in the URI. For example, when releasing a new version of “/account” API, use the “/v2/account” by including a version number in the URI. Here the MAJOR vesion in the semantic versioning is sufficient for the API versioning.

http://host/account
http://host/v2/account

Few Points to Consider

The main flaw asociated with this approach is that when hyperlinked service upgrades to a new version, coordinating upgrades across all the dependencies may become complex.
In general keeping API version in URL would disrupt the concept of HATEOAS. Resource URIs that API that are exposed to should be permalinks. That indicates that API versions should not be kept in resource URIs for a long time.
For example, you have the initial service “/v1/account” and after a period of time you created a version “/v2/account”. Now the version “v2” is the latest version of the API. API cosumers and clients who still point to the old API should be informed to use the latest previous API version. To handle this particular case, accessing the old “v1” API should retrun appropriate HTTP response to the clients.
We have the following options:

HTTP 410 Gone:

From w3.org Status Code Definitions.

"The requested resource is no longer available at the server and no forwarding address is known. This condition is expected to be considered permanent. Clients with link editing capabilities SHOULD delete references to the Request-URI after user approval. 

The 410 response is primarily intended to assist the task of web maintenance by notifying the recipient that the resource is intentionally unavailable and that the server owners desire that remote links to that resource be removed."

HTTP 301 Moved Permanently:

From w3.org Status Code Definitions.

"The requested resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs. Clients with link editing capabilities ought to automatically re-link references to the Request-URI to one or more of the new references returned by the server, where possible."

HTTP Header versioning or Media Type Versioning and Example

HTTP header versioning adds information into the HTTP header indicating which version the consumer will accept. This is most commonly associated with meida Content-Type. The REST API would make use of custom vendor MIME media types. For example instead of generic media types such as application/json these media types are going to be versioned.
See the example below

GET /account/5555 HTTP/1.1
Accept: application/vnd.globinch.v1+json

HTTP/1.1 200 OK
Content-Type: application/vnd.globinch.v1+json
{
  "account": {
    "account_number": "5555",
    "balance": {
      "currency": "usd",
      "balance": "-250.00"
    },
    "link": {
      "rel": "deposit",
      "href": "/account/5555/deposit"
    },
      {
        "rel": "view",
        "href": "/account/9999/view"
      }
  }
}

Few Points to Consider

In this case the consumer gets to decide which version to request. The complexity attached to this approach is the challenges attached to caching. The versioned header was designed to enable the same URL to be cached in different ways. But this versioned header adds complexity to your network configuration and the network cache that ignores the versioned header.
Also there may be issues with header versioning in some cases such as the HTML

  First name: 

  Last name: 

  

Where, enctype can be,

In General as a good practice, give advanced notice of deprecation to all stakeholders by providing updated specification documents and other mechanisms.

References

1. Use versioning only as a last resort
2. Semantic Versioning
3. Status Code Definitions
4. HTML form enctype Attribute