REST API versioning Group Name: ARC/PRO Source: Mahdi Ben Alaya, LAAS-CNRS, ben.alaya@laas.fr Thierry Monteil, LAAS-CNRS, monteil@laas.fr Khalil Drira, LAAS-CNRS, drira@laas.fr Meeting Date: 2014-09-22

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.

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: http://www.example.com/resource http://www.example2.com/resource 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.

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: http://example.com/v2/resource Popular REST APIs: Google: https://www.googleapis.com/customsearch/v1?params Twitter: https://api.twitter.com/1.1/statuses 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.

A. URI Versioning 3. Adding the version as query parameter The second most common versioning method. Example: http://example.com/resource?version=2 Popular REST APIs: Ebay: http://open.api.ebay.com/shopping?version=713 Amazon SQS: http://sqs.amazonaws.com/?Action=c&Version=2011-10-01 Netfix : http://api.netflix.com/catalog/titles/series/7002?v=1.5 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

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: 2011-08-18 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.

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.

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 (…). http://tools.ietf.org/html/rfc6906 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: <http://www.example.com/profile2>;rel="profile"  Content-type: application/xml; profile= http://www.example.com/profile2 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.

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

References « RESTful Web APIs » book - Leonard Richardson, Mike Amundsen, Sam Ruby. September 2013. ISBN: 1449358063. “RESTful Web Services Cookbook - Solutions for Improving Scalability and Simplicity” By Subbu Allamaraju. February 2010. ISBN-13: 978-0596801687 Mark Nottingham - Evolving HTTP APIs. https://www.mnot.net/blog/2012/12/04/api-evolution The profile Link Relation Type IETF RFC: http://tools.ietf.org/html/rfc6906 Versioning strategies in discussions and in popular REST APIs: http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/

Thank you for your attention