HTTP Caching

HTTP caching is a standard for caching of resources downloaded from the network. By default, all browsers have an implementation of an HTTP cache. This feature provides faster load-times and better server performance.

The caching details of each resource is provided in the response headers returned by the server as a part of the response to a resource request. The Cache-Control header specifies whether the resource can be cached, caching duration, and whether the cache is shareable or not.

By default, Cortex returns no-cache and no-transform directives in the Cache-Control header in the GET requests. The no-cache directive specifies that the client validates each GET request to the server and the no-transform indicates that the client must not modify the resource when caching.

The Cache-Control header for the resources with HTTP caching have the following directives:

• private: Specifies that the resource is for a single user and not shareable
• no-transform: Specifies that the resource must not be modified when cached
• max-age=<seconds>: Specifies for how long the cached resource is considered as up-to-date

ETag in Cortex Responses

Cortex returns an ETag header with all resources. The ETag header is used to validate a stale resource when the client sends a request for the same resource again. A resources is considered stale when the max-age expires or when a no-cache directive is returned.

For a stale resource, the next request from the client sends the ETag value in a If-None-Match header. When the ETag value on the server and client matches, the server sends a 304 Not Modified status without a body to the client. This response indicates that the client can use the previously returned response of the resource. With this header, server need not send the complete response back and can save the bandwidth.

Implementing HTTP Caching in New Resources

For a new Helix resource, to implement HTTP caching by providing the Cache-Control header , you must create a new Helix prototype that implements the Info interface of the resource.

1. Create the new resource.

2. Create a Helix prototype to implement the Info interface.

   For NavigationResource, create an InfoNavigationPrototype that implements the NavigationResource.Info interface as in the following example:

   /**
   * Navigation prototype for Info operation.
   */
   public class InfoNavigationPrototype implements NavigationResource.Info {
   
       private static final Single<ResourceInfo> INFO_SINGLE = Single.just(ResourceInfo.builder()
               .withMaxAge(NavigationsResourceConstants.MAX_AGE)
               .build());
   
       @Override
       public Single<ResourceInfo> onInfo() {
           return INFO_SINGLE;
       }
   }
   

In the prototype, a ResourceInfo is built and the max-age for the resource is returned.

Implementing HTTP Caching in Default Resources

If a default resource does not have HTTP caching, you must extend the resource by following the instruction to extend a Helix resource to enable caching. You must also create an Info prototype.

note

Do not add the @PrototypeExtension annotation to the Info prototype.

To enable HTTP caching for a new resource, create a prototype that implements the Info interface of the resource. For the NavigationResource, create a InfoNavigationPrototype that implements the NavigationResource.Info interface as in the following example:

/**
 * Navigation prototype for Info operation.
 */
public class InfoNavigationPrototype implements NavigationResource.Info {

    private static final Single<ResourceInfo> INFO_SINGLE = Single.just(ResourceInfo.builder()
            .withMaxAge(NavigationsResourceConstants.MAX_AGE)
            .build());

    @Override
    public Single<ResourceInfo> onInfo() {
        return INFO_SINGLE;
    }
}

Overriding HTTP Caching in a Default Resource

To override the max-age for a default resource, extend the Info prototype for the resource and provide the new value. For the NavigationResource, to override the max-age, do as in the following example:

/**
 * Navigation prototype for Info operation.
 */
@PrototypeExtension
public class InfoExtNavigationPrototype implements NavigationResource.Info {

    private static final Single<ResourceInfo> INFO_SINGLE = Single.just(ResourceInfo.builder()
            .withMaxAge(300)
            .build());

    @Override
    public Single<ResourceInfo> onInfo() {
        return INFO_SINGLE;
    }
}