Web API Caching

The Web API supports server side cashing. This opens up for so-called conditional requests from Web API clients. This can reduce the number of times a server needs to send a fresh representation of a resource to the client.

Currently, caching is implemented for Timeseries, GIS and Accounts. The cashing lifetimes (timeouts) are configurable in the web.config file. For example, the below setting defines that a response from a time series query (a GET request) is cached on the server for 10 minutes.

<setting name="CacheTimeSeriesTimeout" serializeAs="String">
    <value>00:10:00</value>
</setting>

The cache timeout setting for the different resources (time series, feature collections etc.) can be individually configured.

Note

Any unsafe command (a POST, PUT or DELETE request) on a resource will lead to an invalidation of the resource cache.

The Web API uses standard HTTP 1.1 headers to support caching. When the Web API is serving a cached representation, the response comprises a Cache-Control header with a max-age value representing the lifetime (in seconds) of the cached representation.

The header also comprises a so-called ETag (entity tag) for cache validation. The ETag enable clients to make conditional requests (see more below).

HTTP/1.1 200 OK
Cache-Control: must-revalidate, max-age=600
ETag: "6916d895-f549-4fd2-a0de-b3cc411e2ff7"
Date: Tue, 09 Aug 2016 12:18:58 GMT
...

Conditional Requests

Conditional requests can reduce the number of times a server needs to send a fresh representation of a resource to the client. If the client stores representations locally, it can use a conditional GET request to detect whether a cached representation can still be considered fresh.

The ETag response header, described above, is used to support such conditional requests. If this Etag is stored along with the resource representation data, it can be used in future requests of that same resource in a If-None-Match header.

Example

The first time you request a list of user accounts, the response will include a Cache-Control header with a max-age value of 600 telling you that the representation (the list of accounts) has been cached with a freshness lifetime of 10 minutes. It also includes an ETag header with an opaque identification of the cached representation:

Request:

GET http://localhost:17510/api/account/list
accept: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate, max-age=600
ETag: "115429df-1837-4a8f-b307-01333be2007b"
Date: Tue, 09 Aug 2016 13:58:53 GMT
...

[
  {
    "Activated": true,
    "EncryptedPassword": "ffoyPzN5C679iey0RZc9RfcHR8=",
    "Roles": "Guest, User",
    "Name": "John Doe",
    "Id": "john.doe"
  },
  ...
]

Now, at a later time, the client can verify whether the server changed the representation (the list of accounts) by including an If-None-Match header in subsequent requests. If the server cache is not yet invalidated - meaning that client's copy of the representation is still fresh - the server responds with a short message comprising headers only and the 304 Not Modified status code. This response also extends the freshness lifetime for another 10 minutes from the time the server responded.

Request:

GET http://localhost:17510/api/account/list
accept: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==
If-None-Match: "115429df-1837-4a8f-b307-01333be2007b"

Response:

HTTP/1.1 304 Not Modified
Cache-Control: must-revalidate, max-age=600
Date: Tue, 09 Aug 2016 14:17:38 GMT
...

If the timespan between subsequent requests exceeds the lifetime of the cache, and the cache is thus invalidated, the above request will lead to a response with a fresh representation, status code 200 OK and a new ETag-value, to be used in subsequent requests:

HTTP/1.1 200 OK
Cache-Control: must-revalidate, max-age=600
ETag: "667a24d6-567f-40ac-bad6-41c4ba91a5c2"
Date: Tue, 09 Aug 2016 14:34:09 GMT
...

[
  {
    "Activated": true,
    "EncryptedPassword": "ffoyPzN5C679iey0RZc9RfcHR8=",
    "Roles": "Guest, User",
    "Name": "John Doe",
    "Id": "john.doe"
  },
  ...
]