RESTful APIs - Versioning and Caching Hendrik Saly, codecentric AG 

Representational State Transfer Constraints Uniform interface Stateless Cacheable Layered system 

REST Maturity Model Level Meaning HTTP methods used 1 XML-RPC/SOAP with only one endpoint URI POST 2 Different endpoints and resources POST 3 Different endpoints and resources GET, POST, PUT, DELETE, … 4 Different endpoints and resources, HATEOAS GET, POST, PUT, DELETE, … (Typically level 3 is implemented) 

HATEOAS Hypermedia as the Engine of Application State Response contains hyperlinks to other resources Kind of finite state machine Not widely used { "name": "Foo", "links": [ { "rel": "self", "href": "http://localhost:8080/customer/1" } ], "details": "/details/1" } 

Meaning of HTTP methods Method Meaning Safe Idempotent Cacheable Has Body GET Read Y Y Y Response only HEAD Same as GET without body Y Y Y N POST Create N N Y Request/Response PUT Upsert N Y N Request/Response DELETE Delete N Y N Response only OPTIONS returns the HTTP methods that the server supports Y Y N Response only PATCH, TRACE, CONNECT, etc. are out of scope here 

Meaning of HTTP methods (2) URI type GET PUT POST DELETE Collection List of elements or URIs Replace entire collection create new collection delete complete collection Element Return element Replace or create element - delete element 

API versioning Why this might be necessary? API evolves over time Adding new resources or response parts is not critical but Renaming and/or deletion is Two possibilities to solve this Encode version of the API in the URI Encode version of the API in a header Depends especially on the type of client (Browser or other) 

URI versioning Pros Simple and clearly visible by looking on the URI Cons Its difficult to use separate parts of the API in different versions simultaneously Same resources have different URIs (REST constraint violation) Problem if client stores/bookmarks URIs cause also the version is stored along with the URI Can be used together with a Link header to relocate to newest API version /api/v1/customers/3 

Header versioning (Content negotiation) Pros Its easy to use separate parts of the API in different versions simultaneously Same resources have same URIs No problems with stored/bookmarked URIs Accept Header supports more than one version Accept: application/vnd.myapp-v1+json 

Header versioning (Content negotiation) (2) Cons Header is hidden You need own (self defined) mime types (thats no a real problem so far) To make HTTP caching work a Vary: Accept header is needed to make the Accept header part of the cache key Not widely spread (most devs are unfamiliar with that approach) 

API versioning - best practice Keep it simple for the developers and implement URI versioning Provide a non versioned URI alias which point to the most recent version For more complicated situations use Link header 

API caching Make sure all servers, proxies, web caches and clients support HTTP 1.1 Purpose is to decrease utilization of network bandwith/latency and discharge load on backend systems/HTTP server and therefore gain more performance (handle more load, increase responsiveness) Only GET and HEAD is cacheable If you not have such problems (and you don’t expect them in the future) do not use caching because there are several downsides 

API caching (1) Downsides Stale responses Invalidation Can get very complex Depending on a cache makes the cache mandatory 

API caching (2) There are three possibilities for caching: Let the browser do it Let the client do it (for example AngularJS caching) Cache costly backend operation on the server side (Not really API caching) 

API caching (3) Client side caching can reduce utilization of network bandwith and load on backend systems Clients are responsible, needs probably programming If client is a browser it depends on the implementation of the browser (IE and Safari might show bugs) It also depends on the infrastructure between the client and the originating server (proxies, webcaches, … ) For browser caches or HTPP 1.1 compliant client it work May i cache? If cached is it fresh? If stale is it valid on the server? 

States of Resource Representation Up-to-date (same as origin server) Fresh (as long as its not expired on client or proxy) Stale (expired) 

HTTP Cache-Control header An easy and simple method is to use the HTTP 1.1 Cache-Control header to indicate when a resource response is outdated. Until this point in time the browser will not connect to the rest endpoint but will server the response from its cache. What May be Stored by Caches (request/response) no-store no caching at all What is Cacheable (response only) public by any cache, no revalidation if fresh private by any non shared cache, no revalidation if fresh no-cache by any cache, enforce revalidation even if fresh (request/response) 

HTTP Cache-Control header (1) Expiration mechanism (request/response) max-age client is willing to accept a response whose age is no greater than the specified time Cache Revalidation and Reload Controls (response only) must-revalidate do an end-to-end revalidation every time proxy-revalidate sames as must-revalidate but not for private caches 

HTTP Cache-Control header (2) But thats really only suitable for static resources like CSS, Javascript, Images, etc. and not recommended for representations of business domain objects. Therefore do not use it for API caching. 

Validators If stale validate on the server. Last-Modified header (Time-based) ETag (Entity-Tag) header (Content-based) 

HTTP ETag header (Content-based) Another method is to use the ETag header to maintain a kind of hashcode for the content. Every time the content changes on the server side the value of the ETag does change. sent by origin server or the user agent Sometimes ETag is hard to maintain, especially in a distributed backend environment HTTP/1.1 200 OK ETag: "hgt5398j" GET /customer/1 HTTP/1.1 IF-None-Match: "hgt5398j" HTTP/1.1 304 Not Modified ETag: "hgt5398j" 

Disable HTTP caching completely Cache-Control: no-cache, no-store, must-revalidate Pragma: no-cache Expires: 0 

Server side application level caching Server side caching can reduce load on backend systems by caching data in memory Guava cache (which ships with Dropwizard) for costly database queries Simple Maps/Lists Needs enough memory to be available Invalidation is perfectly under control 

Client side application level caching Client side caching with Independent from the remote server or proxy Storage is Javascript heap memory AngularJS Alternatively angular-cache 

Combining header versioning and caching If the response depends on an Accept header too then we need to set the HTTP Vary Header (which is broken in IE and Safari) Normally content in the browser cache is matched agains its URI and HTTP Method. With the Vary Header additional constraints, like the Accept or Authorization header, can be included in the cache key. Vary: Accept 

Pitfalls Browser caches may not work for self-signed SSL certificates If a resource needs authentication this have to be included in the Vary header and Cache-control: private must be set to prevent shared caching of a security token Vary header is broken for some browsers and some types 

Recommended caching strategy for REST Best is do no caching at all If you must cache because of backend utilization Consider server side application level caching Consider HTTP content based caching with ETag validation Cache-Control: no-cache, max-age=0 for client Cache-Control: public, max-age=0, must-revalidate + ETag for server If you must cache because of network utilization Consider client side application level caching That is because of Browsers and intermediate infrastructure (like proxies are) are subject to change, sometimes buggy and sometimes 

Further reading https://redbot.org http://maxenglander.com/2013/04/23/basic-restful-api-versioning-in-jersey.html http://barelyenough.org/blog/2008/05/versioning-rest-web-services/ http://barelyenough.org/blog/2012/05/bookmarks-and-uri-based-versioning/ https://jakearchibald.com/2014/browser-cache-vary-broken/ http://www.apiacademy.co/how-to-http-caching-for-restful-hypermedia-apis/ https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9.1 http://odino.org/rest-better-http-cache/ http://www.tutorialspoint.com/restful/restful_caching.htm http://de.slideshare.net/Sperasoft/rest-services-caching http://de.slideshare.net/lfcipriani/api-caching-why-your-server 

Thank you! Follow me on Twitter: This work is licensed under a [email protected] @hendrikdev22 Creative Commons Attribution 4.0 International License