Output Caching

All responses from data retrieval methods are cacheable by default - you can improve the performance even more by performing conditional HTTP requests to check whether the data was modified and skip loading the content if your cached copy is still fresh. As with compression, many HTTP clients support it out of stock and make it completely transparent for you - JavaScript’s XMLHttpRequest, NET’s HttpWebRequest, Java’s CachingHttpClientBuilder. If caching is not supported it is fairly easy to write thin wrapper to implement this logic for the API given that we are using its small subset.

Only GET requests are cacheable.

Responses with Cache-Control header containing "no-cache" are not cacheable.

First time send the request unconditionally:

GET https://www.teamdesk.net/secure/api/v2/21995/user.json

You’ll get ETag header and the content.

HTTP/1.1 200 OK
Cache-Control: private, must-revalidate, max-age=0
ETag: "0123456789"  

{ id: 1, name: "John", ... }

Use URL including query parameters to store the value of the ETag header and content of the response in a file system or database.

Next time find stored ETag from the URL and query parameters and issue the request with If-None-Match header set to ETag value.

GET https://www.teamdesk.net/secure/api/v2/21995/user.json
If-None-Match: "0123456789"

You’ll get back either

HTTP/1.1 304 Not Modified

when it is OK to use cached copy or new ETag and content to update the cache with

HTTP/1.1 200 OK
Cache-Control: private, must-revalidate, max-age=0
ETag: "43210.98765"

{ id: 1, name: "Jane", ... }