Project: APISIX (Orchestration & Management / API Gateway)
File: proxy-cache.md

title: proxy-cache keywords: Apache APISIX API Gateway Proxy Cache description: This document contains information about the Apache APISIX proxy-cache Plugin, you can use it to cache the response from the Upstream. <!-- --> The `proxy-cache` Plugin can be used to cache the response from the Upstream. It can be used with other Plugins and currently supports disk-based and memory-based caching. The data to be cached can be filtered with response codes, request modes, or more complex methods using the `nocache` and `cachebypass` attributes. | Name | Type | Required | Default | Valid values | Description | |--|-|-||-|-| | cache_strategy | string | False | disk | ["disk","memory"] | Specifies where the cached data should be stored. | | cachezone | string | False | diskcache_one | | Specifies which cache area to use. Each cache area can be configured with different paths. Cache areas can be predefined in your configuration file (`conf/config.yaml`). If the specified cache area is inconsistent with the pre-defined cache area in your configuration file, the cache is invalid. | | cachekey | array[string] | False | ["$host", "$requesturi"] | | Key to use for caching. For example, `["$host", "$uri", "-cache-id"]`. | | cachebypass | array[string] | False | | | Conditions in which response from cache is bypassed. Whether to skip cache retrieval. If at least one value of the string parameters is not empty and is not equal to `0` then the response will not be taken from the cache. For example, `["$argbypass"]`. | | cache_method | array[string] | False | ["GET", "HEAD"] | ["GET", "POST", "HEAD"] | Request methods for which the response will be cached. | | cachehttpstatus | array[integer] | False | [200, 301, 404] | [200, 599] | HTTP status codes of the Upstream response for which the response will be cached. | | hidecacheheaders | boolean | False | false | | When set to `true`, hide the `Expires` and `Cache-Control` response headers. | | cache_control | boolean | False | false | | When set to `true`, complies with Cache-Control behavior in the HTTP specification. Used only for memory strategy. | | no_cache | array[string] | False | | | Conditions in which the response will not be cached. If at least one value of the string parameters is not empty and is not equal to `0` then the response will not be saved. | | cachettl | integer | False | 300 seconds | | Time that a response is cached until it is deleted or refreshed. Comes in to effect when the `cachecontrol` attribute is not enabled or the proxied server does not return cache header. Used only for memory strategy. | :::note The cache expiration time cannot be configured dynamically. It can only be set by the Upstream response header `Expires` or `Cache-Control`. The default expiration time is 10s if there is no `Expires` or `Cache-Control` in the Upstream response

If the Upstream service is not available and APISIX returns a `502` or `504` status code, it will be cached for 10s. Variables (start with `$`) can be specified in `cachekey`, `cachebypass` and `no_cache`. It's worth mentioning that the variable value will be an empty string if it doesn't exist. You can also combine a number of variables and strings (constants), by writing them into an array, eventually, variables will be parsed and stitched together with strings. ::: You can add your cache configuration in you APISIX configuration file (`conf/config.yaml`) as shown below: ```yaml title="conf/config.yaml" apisix: proxy_cache: cache_ttl: 10s # default cache TTL for caching on disk zones: name: diskcacheone memory_size: 50m disk_size: 1G diskpath: /tmp/diskcache_one cache_levels: 1:2 name: memory_cache memory_size: 50m ``` You can enable the Plugin on a Route as shown below. The Plugin uses the disk-based `cachestrategy` and `diskcacheone` as the `cachezone` by default: :::note You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: ```bash adminkey=$(yq '.deployment.admin.adminkey[0].key' conf/config.yaml | sed 's/"//g') ``` ::: ```shell curl http://127.0.0.1:9180/apisix/admin/routes/1 \ -H "X-API-KEY: $admin_key" -X PUT -d ' { "uri": "/ip", "plugins": { "proxy-cache": { "cache_key": ["$uri", "-cache-id"], "cachebypass": ["$argbypass"], "cache_method": ["GET"], "cachehttpstatus": [200], "hidecacheheaders": true, "nocache": ["$argtest"] } }, "upstream": { "nodes": { "httpbin.org": 1 }, "type": "roundrobin" } }' ``` You can enable the Plugin on a Route with in-memory `cachestrategy` and a corresponding in-memory `cachezone` as shown below: ```shell curl http://127.0.0.1:9180/apisix/admin/routes/1 \ -H "X-API-KEY: $admin_key" -X PUT -d ' { "uri": "/ip", "plugins": { "proxy-cache": { "cache_strategy": "memory", "cachezone": "memorycache", "cache_ttl": 10 } }, "upstream": { "nodes": { "httpbin.org": 1 }, "type": "roundrobin" } }' ``` Once you have configured the Plugin as shown above, you can make an initial request: ```shell curl http://127.0.0.1:9080/ip -i ``` ```shell HTTP/1.1 200 OK Apisix-Cache-Status: MISS hello ``` The `Apisix-Cache-Status` in the response shows `MISS` meaning that the response is not cached, as expected. Now, if you make another request, you will see that you get a cached response: ```shell curl http://127.0.0.1:9080/ip -i ``` ```shell HTTP/1.1 200 OK Apisix-Cache-Status: HIT hello ``` If you set `"cachezone": "invaliddisk_cache"` attribute to an invalid value (cache not configured in the your configuration file), then it will return a `404` response. :::tip To clear the cached data, you can send a request with `PURGE` method: ```shell curl -i http://127.0.0.1:9080/ip -X PURGE ``` ```shell HTTP/1.1 200 OK ``` If the response code is `200`, the deletion is successful. If the cached data is not found, a `404` response code will be returned. ::: To remove the `proxy-cache` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. ```shell curl http://127.0.0.1:9180/apisix/admin/routes/1 \ -H "X-API-KEY: $admin_key" -X PUT -d ' { "uri": "/ip", "plugins": {}, "upstream": { "type": "roundrobin", "nodes": { "httpbin.org": 1 } } }' ```