1. REST API versioning Group Name: ARC/PRO
Source: Mahdi Ben Alaya, LAAS-CNRS,
Thierry Monteil, LAAS-CNRS,
Khalil Drira, LAAS-CNRS,
Meeting Date:

2. What is the best strategy to version a REST API ?
There are many strategies to version a REST API, however there is no universally accepted method, nor does any standard specify one.
Versioning strategies can be classified into two main approaches (URI vs Header)
URI versioning
Changing hostnames.
Partitioning the URI space.
Adding the version as query parameter.
Header versioning
Adding a custom header for the version.
Versioning by content negotiation (media-type).
Versioning the profile.

3. A. URI versioning 1. Changing hostnames
This method is barely used. It consists at moving the API from one hostname to another. In other terms, you build a new API to the same resources. Examples:
Popular REST APIs:
Facebook Classic API : api.facebook.com
Facebook New API: graph.facebook.com
Avantages:
You can update the entire URI structure.
Drawbacks
Changing what URIs are being used for.
It is about building a new API more than versioning.

4. A. URI versioning 2. Partitioning the URI space
This is the most widely used method. The entire API is split into two disjoint APIs. Example:
Popular REST APIs:
Google:
Twitter:
Facebook,Paypal, LinkdIn, etc.
Avantages:
It is easy to implement into the first API.
Versions can have completely different application semantics, because any given client will use one of them exclusively.
Drawbacks
The URI should be specifying what the resource is, not how you want it represented.
A resource URI must be stable over time, not tightly coupled with the API version.
Introducing version identifiers in the URI leads to a very large URI footprint.
Inflexible: No way to simply evolve a single resource, or a small subset of the overall API.
The server must maintain different URI versions, otherwise old clients will break.
The cache will need to keep multiple copies of each Resource: one for every version.

5. A. URI Versioning 3. Adding the version as query parameter
The second most common versioning method. Example:
Popular REST APIs:
Ebay:
Amazon SQS:
Netfix :
Advantages
It can be optional or required depending on how you want the API to be used
Easy to see, understand, and initial code implementation is trivial
You can update a single resource, instead of the full API.
Drawbacks
Complex URI structure after few updates.
You can’t as easily change the resource URIs, so moving resources can be painful.
A URI identifies a resource not a version of a resource.
Non stable resource URIs.
URIs must be maintained by the server
Load the cache

6. B. Header versioning 1. Custom request header
This is method is similar to the previous one, but instead of specifying the version in the query parameters you specify it in a custom header. Example:
Request Header: Api-version: 2 or Accepts-version: 1.0
Popular REST APIs:
Microsoft Azure : x-ms-version:
Google Data API: GData-Version: 2.0
Advantages :
The URI are clean, not cluttered with versioning parameters.
Easily being able to ignore it or silently upgrade if the user does not specify.
All of your changes will still use the same URIs and media types.
Drawbacks:
What does the version property really apply to? Is it the media type, or the API?
Requests must be carefully constructed. You can’t just click on the URL to get the resource.
The accept header is the natural way to chose how to represent a resource, why reproduce it ?
The “Vary HTTP header” must be used for an efficient caching.

7. B. Header versioning 2. Versioning by content negotiation
The Accept header spec allows for custom vendor media types, and for parameters to be passed as part of the content negotiation. You can modify the accept header to specify the version. Examples
Accept: application/vnd.myapp.v2+xml
Accept: application/vnd.myapp;version=2
Accept: application/xml;version=2
Popular REST APIs:
Github : Accept: application/vnd.github.v3+json
Avantages:
Flexible: each resource version is incremented individually. 
This is the natural way to negotiate a resource representation.
All of your changes will still use the same URIs, so clients will no breaks.
Drawbacks
The “accept header” must be configured appropriately.
The “Vary HTTP header” must be configured for caching.

8. B. Header versioning 3. Versioning the profile
The “profile” definition from RFC 6906:
A profile is defined to not alter the semantics of the resource representation itself, but to allow clients to learn about additional semantics (…) associated with the resource representation, in addition to those defined by the media type (…).
A client can use the Link header to request the required profile. Or, it can use the Content-Type header and do normal content negotiation. Examples:
Link: <
Content-type: application/xml; profile=
Avantages:
The profile provides a machine-readable API documentation. When API change, clients will be able to adapt automatically by reading the new profile.
Drawbacks
Requires that you support the profile, and that you define your application semantics in a machine-readable format.
The “Vary HTTP header” must be configured for caching.

9. Rest API versioning best practices
So, what the best strategy to version REST API ? The answer: There is no answer.
Each versioning strategy has its own pros and cons regarding simplicity, flexibility, server overload, REST constraints, caching, etc.
Mark Nottingham (IETF HTTP WG chair), suggested the following practices for REST API versioning to not break existing clients.
Keep Compatible Changes Out of Names
Avoid New Major Versions
Make Changes Backwards-Compatible
Think about Forwards-Compatibility
Version at Appropriate Granularities
Make Minor and Patch Information Discoverable

10. References
« RESTful Web APIs » book - Leonard Richardson, Mike Amundsen, Sam Ruby. September ISBN:
“RESTful Web Services Cookbook - Solutions for Improving Scalability and Simplicity” By Subbu Allamaraju. February ISBN-13:
Mark Nottingham - Evolving HTTP APIs.
The profile Link Relation Type IETF RFC:
Versioning strategies in discussions and in popular REST APIs:

11. Thank you for your attention