You can bind a plug-in of the Caching type to an API operation to cache responses from the backend service of the API operation in API Gateway. This effectively reduces load on the backend and shortens response time.

1. Usage notes

  • Plug-ins of the Caching type can only cache responses to API requests that use the GET method.
  • Plug-ins of the Caching type cannot cache responses to API requests that use the default second-level domain name of the corresponding API group. The default second-level domain name of an API group can only be used for testing API calls and can be used for a maximum of 1,000 times per day.
  • When you configure a plug-in of the Caching type, you can use the following parameters to sort responses in a cache:
    • varyByApp: specifies whether to sort cached responses based on applications 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, sorts responses based on the Accept or Accept-Language header field.
  • API Gateway provides each user with 5 MB of cache space in each region. Caches are cleared upon expiration. After a cache reaches its space limit, no more responses will be stored in the cache.
  • If the Cache-Control header field is specified in a response from the backend of an API operation, 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 operation.
  • A response can be stored in a cache for a maximum of 48 hours, that is, 172,800 seconds. If you set the duration parameter of a plug-in of the Caching type to a value greater than 172800, the cache retention period is still 48 hours.
  • 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 applications 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. Configurations

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 snippet is a YAML template for configuring a plug-in of the Caching type:

---
varyByApp: false    # Specifies whether to sort cached responses based on the IDs of applications from which API requests are sent. Default value: false.
varyByParameters:   # Specifies whether to sort cached responses based on values of request parameters in API requests.
- userId            # The name of a request parameter that is used to sort cached responses. If a request parameter is mapped to a different name at the backend, use the name after mapping.
varyByHeaders:      # Specifies whether to sort cached responses based on request header fields in API requests.
- Accept            # A request header field that is used to sort cached responses. In this example, the `Accept` header field is used.
clientCacheControl: # Specifies whether to allow the `Cache-Control` header field in client requests to affect the cache policy. Default value: `off`.
  mode: "app" # The mode of the clientCacheControl parameter. Valid values: off: ignores the Cache-Control header field in all client requests. all: handles the Cache-Control header field in all client requests. apps: handles the Cache-Control header field in requests from applications that are specified by the `apps` parameter.
  apps:             # The applications from which the Cache-Control header field in API requests is allowed to affect the cache policy. Before you set this parameter, you must set the clientCacheControl parameter to `apps`.
  - 1992323         # The AppId of an application. Do not confuse the AppId and the AppKey of an application.
  - 1239922         # The AppId of an application. Do not confuse the AppId and the AppKey of an application.
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 a response header field that can be cached.
duration: 3600      # The default cache retention period. Unit: seconds.	

3. Working mechanism

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

4. Limits

  • For each plug-in of the Caching type, you can configure a maximum of 16,380 bytes of metadata.
  • A response body that exceeds 128 KB in size cannot be cached.
  • For API operations on shared instances, each user has a maximum of 30 MB of total cache space in each region. For information about limits on API operations on dedicated instances, see the specifications of dedicated instances.