How the Platform API Uses Caching

Most Akana API Platform operations don't use caching at all. Generally, the Cache-Control header is set to no-cache, for both request and response messages, since the platform APIs generally pass database information that might change and should therefore not be cached.

The Cache-Control response header indicates to the browser that the response should not be cached.

However, there are a few operations that do use caching. In general, the types of information that might be cached are:

  • UI resource files: code-related components such as JavaScript files, templates, and stylesheets. Caching: 1 month.
  • Avatar images (such as a user's profile picture). Caching: until updated.
  • Data resources such as API documentation and online help. Caching: 1 hour.

The sections below provide additional information about how operations managing these types of information use caching:

Points at Which Caching Occurs

Caching might occur at any of these points in the message relay process:

  • Inside the Java container (with configurable refresh periods)
  • In reverse proxy servers (if configured)
  • In a CDN such as Akamai (if configured)
  • In web proxy servers (if included in the implementation)
  • In the browser

The information below applies to all caches.

Caching of UI Resource Files

UI resource files include all code-related components such as JavaScript files, templates, and stylesheets.

These types of files are cached for a longer period, one hour, to improve performance.

For all resource files, the URL includes a dynamically-constructed unique ID, called a Resource Version Key.

If a new version of the platform resource files is uploaded, there is a new Resource Version Key. Because the URL is different, the next time the file is retrieved, the latest version replaces the older version. Therefore, a CDN, browser cache, forward proxy, etc. will need to make a new call to get the latest version. The change in the URL triggers the new call, and the updated resource is served.

The key is dynamically constructed every 10 minutes. This means that if you update a file, you won't see the change immediately. To see the update, you'll need to do two things:

  1. Wait for 10 minutes to be sure the content is updated.
  2. Refresh the page so you'll see the change.

If you need to set up your platform version so that file updates are immediate, you'll need to:

  • Make sure you are not using any other components between the browser and the server, that might cache the file, such as a CDN, forward proxy, or reverse proxy.
  • Clear the browser cache and refresh the page.

The resource version key is used to construct the URL, but is not used when the request comes in. The server will always serve the latest file, independent of the version key specified in the URL. A request referencing an old version key will still get the new version in response.

Files that are returned by GET operations in the Console Resource service

Caching of Avatars

Avatar files are cached using a similar approach to that used for UI resource files; the URL to each version of the file includes a unique key. However, this is not the Resource Version Key, which is unique to a specific version of the platform resource files. Instead, each avatar has its own unique ID, randomly generated when the avatar is uploaded, and used in the avatar URL. If a new avatar is uploaded for the same resource, the new avatar will have a different ID, and therefore, a unique URL.

Unlike the Resource Version Key, which is refreshed every 10 minutes, the unique ID for the avatar remains the same for the life of the avatar.

With avatars, there are two approaches you can take to make sure you always get the latest version of the file:

  • As explained above in Caching of UI Resource Files: disabling caching completely at all points between the browser and the server, or waiting 10 minutes and then clearing cache and refreshing the page.
  • Run a GET operation to retrieve the details of the resource, which will include the avatar URL. Since there is no caching on the operations that retrieve the resource details, you will always get the latest avatar URL by running the GET operation for the applicable resource.

For example:

Caching of Content Files

Content files, returned by GET operations in the Content service (see GET /content/{contentpath}), include API documentation, platform online help, and customizable content pages such as the platform home page.

Content files do not have a unique ID. Page URLs are constructed as follows:

  • For platform content, the URL is determined by the platform page location. For example, for Hermosa Theme, the URL of the Support page is: http://{hostname}/{FedmemberID}/#/home/support.
  • For API documentation, the URL is constructed using the API ID/API Version ID in this pattern:

    {protocol}://{hostname}/{FedmemberID}/#/{APIID}/versions/{APIVersionID}/documents.

    Example:

    • API ID: f0809f3f-6d04-42a9-8bc8-653f16ebd6a8.acmepaymentscorp
    • API Version ID: 1756b78e-8ed5-4e14-9eff-a4b045e32044.acmepaymentscorp
    • API documentation main page: http://www.acmepaymentscorp.com/acmepaymentscorp/#/api/f0809f3f-6d04-42a9-8bc8-653f16ebd6a8.acmepaymentscorp/versions/1756b78e-8ed5-4e14-9eff-a4b045e32044.acmepaymentscorp/documents

Content files are cached for 1 hour. When you update any of these files and want to see the update, you'll need to do either of the following:

  • Make sure caching is disabled completely at all points between the browser and the server, and refresh the page.
  • Wait for 1 hour and then clear the browser cache and refresh the page.