API Gateway:Plug-ins of the Caching type

1. Usage notes

• Plug-ins of the Caching type can only cache responses to API requests that use the GET method.

• Responses are not cached for requests that use the system assigned public second-level domain name. The system assigned second-level domain name is for debugging and testing purposes only. If you use it to make API calls, you can make only 100 calls per day in regions outside the Chinese mainland and only 1,000 calls per day in regions in the Chinese mainland.

• When you configure a caching plug-in, you can use the following parameters to sort responses in a cache:

  • varyByApp: specifies whether to sort cached responses based on apps from which API requests are sent.

  • varyByParameters: specifies whether to sort cached responses based on values of request parameters in API requests. The plug-in uses the same request parameters of API operations that are bound to the plug-in to sort responses to API requests.

  • varyByHeaders: specifies whether to sort cached responses based on request header fields in API requests, for example, Accept and Accept-Language.

• API Gateway provides each user with 1 MB of cache space in each region. Caches are cleared after expiration. If a cache reaches its space limit, no more responses are stored in the cache.

• If the Cache-Control header field is specified in a response from the backend of an API, the response is stored in a cache based on the specified cache policy. If the Cache-Control header field is not specified in a response, the response is stored in a cache based on the default cache policy and for a period of time that is specified by the duration parameter of the plug-in of the Caching type that is bound to the API.

• A response can be stored in a cache for a maximum of 48 hours (172,800 seconds). If you set a period longer than 48 hours, the response is still stored for 48 hours in the cache.

• By default, API Gateway ignores the Cache-Control header field in client requests. You can specify the clientCacheControl parameter for a plug-in of the Caching type to decide whether to ignore or handle the Cache-Control header field in client requests. You can set the clientCacheControl parameter to the following modes:

  • off: ignores the Cache-Control header field in all client requests.

  • all: handles the Cache-Control header field in all client requests.

  • app: handles the Cache-Control header field in requests from apps that are specified by the apps parameter of the plug-in of the Caching type.

• By default, API Gateway caches only the Content-Type, Content-Encoding, and Content-Language header fields in responses. If you need to cache more header fields, add the header fields in the cacheableHeaders parameter of the plug-in of the Caching type.

2. Configure the plug-in

You can configure a plug-in of the Caching type in the JSON or YAML format. The two formats have the same schema and can be converted to each other by using a conversion tool. The following code describes a plug-in configuration template in YAML format:

---
varyByApp: false    # Specifies whether to match and serve cached responses based on the app IDs of API callers. Default value: false.
varyByParameters:   # Specifies whether to match and serve cached responses based on the values of specific parameters.
- userId            # The name of a backend parameter. If the backend parameter is mapped to a parameter with a different name, set this parameter to the mapped parameter name.
varyByHeaders:      # Specifies whether to match and serve cached responses based on different request headers.
- Accept            # Cached responses are matched and served based on the Accept header.
clientCacheControl: # API Gateway determines how to process the Cache-Control headers of client requests based on the clientCacheControl settings.
  mode: "app"       # Valid values: off, all, and apps. Default value: off. off indicates that API Gateway ignores the Cache-Control headers of all client requests. all indicates that API Gateway processes the Cache-Control headers of all client requests. apps indicates that API Gateway processes only the Cache-Control headers of client requests whose app IDs are included in the configured apps list.
  apps:             # A list of app IDs. If mode is set to app, API Gateway processes only the Cache-Control headers of client requests whose app IDs are in this list.
  - 1992323         # A sample app ID. It is not an AppKey.
  - 1239922         # A sample app ID. It is not an AppKey.
cacheableHeaders:   # The response header fields that can be cached. By default, only the `Content-Type`, `Content-Length`, and `Content-Language` header fields can be cached.
- X-Customer-Token  # The name of the response header that can be cached.
duration: 3600      # The default storage period of the response in the cache. Unit: seconds.        

3. Working mechanism

• If an API request hits the cache of an API, the X-Ca-Caching: true header is included in the response to the API request.

4. Limits

• The metadata of a single plug-in cannot exceed 50 KB in size.

• A response body that exceeds 128 KB in size cannot be cached.

• For API operations on shared instances, each user has a maximum of 1 MB of total cache space in each region. For information about limits on API operations on dedicated instances, see the specifications of dedicated instances.