Using the Endpoint Caching middleware with Tyk Classic APIs

The Endpoint Caching middleware allows you to perform selective caching for specific endpoints rather than for the entire API, giving you granular control over which paths are cached.

When working with Tyk Classic APIs the middleware is configured in the Tyk Classic API Definition. You can do this via the Tyk Dashboard API or in the API Designer.

If you’re using the newer Tyk OAS APIs, then check out the Tyk OAS page.

Configuring the middleware in the Tyk Classic API Definition

When using the Tyk Classic API Definition, there are two options for endpoint caching - simple and advanced.

The simple option works with the API-level cache and allows you to select which endpoints are cached, but relies upon the cache timeout (refresh) configured at the API-level. It will cache all responses received from the endpoint regardless of the HTTP response code for all safe requests.

The advanced option allows you to cache more selectively, giving control over the HTTP response codes to be cached, a per-endpoint cache timeout and also the possibility of caching responses only to requests containing specific data in the request body.

Simple endpoint cache

To enable the simple middleware you must add a new cache object to the extended_paths section of your API definition. The cache object is a list of endpoints for which you wish to cache all safe requests.

In the API-level cache_options you must enable caching and configure the timeout whilst ensuring that the option to cache all safe requests is disabled.

The cache_options object has the following configuration:

• enable_cache: set to true to enable caching for this API
• cache_all_safe_requests: set to false to allow selective caching per-endpoint
• cache_timeout: set to the refresh period for the cache (in seconds)

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
    "cache_options": {
        "enable_cache": true,
        "cache_timeout": 60,
        "cache_all_safe_requests": false
    },

    "extended_paths": {
        "cache": [
            {
                "/widget",
                "/fish"
            }
        ]
    }
}

In this example the endpoint caching middleware has been configured to cache all safe requests to two endpoints (/widget and /fish) with a cache refresh period of 60 seconds.

Advanced endpoint cache

For ultimate control over what Tyk caches, you should use the advanced configuration options for the per-endpoint cache. You can separately configure, for each HTTP method for an endpoint:

• an individual cache refresh (timeout)
• a list of HTTP response codes that should be cached
• a pattern match to cache only requests containing specific data in the request body

To enable the advanced middleware you must add a new advance_cache_config object to the extended_paths section of your API definition.

In the API-level cache_options you must enable caching and ensure that the option to cache all safe requests is disabled. The timeout that you set here will be used as a default for any endpoints for which you don’t want to configure individual timeouts.

The advance_cache_config object has the following configuration:

• path: the endpoint path
• method: the endpoint method
• timeout: set to the refresh period for the cache (in seconds)
• cache_response_codes: HTTP responses codes to be cached (for example 200)
• cache_key_regex: pattern match for selective caching by body value

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

{
    "cache_options": {
        "enable_cache": true,
        "cache_timeout": 60,
        "cache_all_safe_requests": false
    },

    "extended_paths": {
        "advance_cache_config": [
            {
                "disabled": false,
                "method": "POST",
                "path": "/widget",
                "cache_key_regex": "",
                "cache_response_codes": [
                    200
                ],
                "timeout": 10
            }, 
            {
                "disabled": false,
                "method": "GET",
                "path": "/fish",
                "cache_key_regex": "^shark$",
                "cache_response_codes": [
                    200, 300
                ],
                "timeout": 0
            } 
        ]
    }
}

In this example the endpoint caching middleware has been configured to cache requests to two endpoints (/widget and /fish) as follows:

Configuring the middleware in the API Designer

You can use the API Designer in the Tyk Dashboard to configure the endpoint caching middleware for your Tyk Classic API by following these steps.

Simple endpoint cache

To enable and configure the simple endpoint cache, follow these instructions:

Step 1: Configure the API level caching options

From the Advanced Options tab configure the cache as follows:

• Enable caching to enable the cache middleware
• Cache timeout to configure the timeout (in seconds) for cached requests
• Cache only these status codes is a list of HTTP status codes that should be cached, remember to click Add after entering each code to add it to the list
• Cache all safe requests ensure that this is not selected, otherwise the responses from all endpoints for the API will be cached

Step 2: Add an endpoint for the path and select the plugin

From the Endpoint Designer add an endpoint that matches the path for which you want to cache responses. Select the Cache plugin.

Step 3: Save the API

Use the save or create buttons to save the changes and activate the middleware.

Advanced endpoint cache

To enable and configure the advanced endpoint cache, follow these instructions:

Step 1: Configure the API level caching options

From the Advanced Options tab configure the cache as follows:

• Enable caching to enable the cache middleware
• Cache timeout to configure the default timeout (in seconds) for any endpoints for which you don’t want to configure individual timeouts
• Cache only these status codes leave this blank
• Cache all safe requests ensure that this is not selected, otherwise the responses from all endpoints for the API will be cached

Step 2: Add an endpoint for the path and select the plugin

From the Endpoint Designer add an endpoint that matches the path for which you want to cache responses. Select the Advanced Cache plugin.

Step 3: Configure the Advanced Cache plugin

Set the timeout and HTTP response codes for the endpoint. If you don’t need to set a specific timeout for an endpoint you can leave this blank and Tyk will use the cache timeout configured at the API level.

Step 4: Save the API

Use the save or create buttons to save the changes and activate the middleware.