All Products
Search

This Product

    API Gateway:Caching plug-ins

    Document Center

    API Gateway:Caching plug-ins

    Last Updated:Jun 15, 2026

    Caching plug-ins cache backend responses in API Gateway, reducing backend load and shortening response time.

    1. Usage notes

    • Only responses to the GET method are cached.

    • You cannot cache requests that use the default group second-level domain. The default group second-level domain is for testing only and has a limit of 1,000 calls per day, or 100 calls per day for regions outside mainland China and in China (Hong Kong).

    • Add the following configurations to differentiate caches:

      • varyByApp: Differentiates caches based on the app.

      • varyByParameters: Differentiates caches based on parameter values. Parameters must match the names defined in the bound API.

      • varyByHeaders: Differentiates caches based on request headers, such as Accept and Accept-Language.

    • Each user has 1 MB of cache space per region. Space is released based on an expiration policy. If the cache is full, subsequent responses are not cached.

    • If a backend response includes the Cache-Control header, API Gateway caches the response according to that policy. Otherwise, the response is cached for the duration specified by the duration parameter in the caching plug-in.

    • The maximum expiration time is 48 hours (172,800 seconds). Any value that exceeds this limit is treated as invalid and defaults to 48 hours.

    • By default, API Gateway ignores the client's Cache-Control header. Use the clientCacheControl parameter to change this behavior. The mode accepts the following values:

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

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

      • app: Processes the Cache-Control header only for requests whose AppId is in the apps configuration list.

    • By default, API Gateway caches only the Content-Type, Content-Encoding, and Content-Language response headers. To cache additional headers, configure the cacheableHeaders parameter.

    2. Configure the plug-in

    Configure the plug-in in JSON or YAML format. Both formats share the same schema and can be converted with a yaml to json tool. The following template uses 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. Running Rules

    • When a cache hit occurs in API Gateway, the response includes the X-Ca-Caching: true header.

    4. Limits

    • The size of plug-in metadata is limited to 50 KB.

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

    • For Serverless instances, the total cache limit for each user is 1 MB per region. For dedicated instances, refer to the instance specifications.