Client caching is enabled or disabled using the @Endpoint cache property. By default, the cache property is set to false, which disables client caching. When client-side caching is disabled, the framework adds a no-cache header to the response indicating to the client that the response cannot be cached. You must explicitly set the cache property to true to allow client caching. For example, you might use this property if a resource response is fairly static and does not include sensitive data.

The no-cache headers can be configured. For example:

noCacheHeaders=\
        Cache-Control=public,,must-revalidate,,proxy-revalidate,\
        Edge-control=no-store

Using Etags for Version Tracking

The framework supports client caching by creating Etags, which is a hash of the JSON response, the URI, and the resource version.

The framework generates an Etag for every resource representation in a response. These Etags include the version of the resource instance, which can be used for caching the response. Additionally, they can be used for If-Match or If-None-Match header preconditions.

If a PUT request uses an If-Match header that contains an Etag value, the ETagService verifies that the Etag’s resource version number matches the current resource version. This allows the framework to track the version of a resource.

If a GET request uses an If-None-Match header, the ETagService verifies that the hash of the current response matches the hash of the Etag set by the client. If the hash matches, then a Not Modified response code is returned. If the Etags do not match, or if the If-None-Match header is not set, a new Etag is created for the response.

Etag generation can be disabled by setting generateETags=false as a query parameter of the request. The query parameter is parsed from the request by the framework and sets the generateETags property of the current REST context. If the client request does not specify the generateETags query parameter when retrieving embedded resources, it is set to false by default.

Tracking the Current Resource Version

The version property of the RepresentationModel allows the endpoint to specify the version number for the resource. If the version property is not set then the framework attempts to get the version number from the RepresentationModel state, provided that the state is a RepositoryItem and the RepositoryItem has a version property. If the version number cannot be obtained from the RepresentationModel the framework uses the ResourceVersionRepository to track the version. The version number is incremented for each PUT request so that the appropriate error can be returned if a client as a stale version of the resource.

Version tracking can be disabled by setting the RestResource annotation trackVersion attribute to false. When false, the resource version is identified as 1.

Disabling Client-Side Caching

To disable client caching, use the cache property of the @Endpoint annotation. When you set the cache property to false, no cache headers are set on the response headers.