Skip to main content

Serve answers from a cache

The orders catalogue changes rarely, yet every client asks the backend for it again and again. The plugin proxy-cache on orders-api keeps a copy of each answer in the gateway's memory for a minute. A repeat of the same request within that minute is answered from the copy, and the backend is not asked. At the end, the second of two equal requests within a minute is answered by the gateway from its memory.

Before you start​

  • This guide starts from orders-api as Route requests to a backend leaves it, with key-auth from Require an API key. The requests below call /orders/42. A plugin from another guide that this page does not name can change the answers below; remove it first or work on a copy of the route.
  • The host name of your gateway. In the console it is the first part of the Address line on a route's Overview tab, api.example.com in this page's examples; replace it in every request below.
  • Answers that every caller of the route may see. A cached answer is served to whoever asks next for the same key, so an answer that depends on who asks needs the care described under What to know.
  • The Editor or Environment administrator role in this environment.

Steps​

1. Choose proxy-cache​

Open orders-api under Routes, select its Plugins tab, then Add plugin at the top right of the tab. Open the Traffic category, or type proxy-cache in the search box. Select proxy-cache, then Configure.

2. Keep the answers in memory for a minute​

Under Basics, choose memory in Cache strategy. The fields for memory, Cache TTL among them, appear when you choose it. Fill in these fields and leave the rest as they are.

FieldValueWhy
Cache TTL60How long a copy is kept, in seconds.
Cache zonememory_cacheThe zone the gateway declares for memory. The default, disk_cache_one, belongs to the disk strategy and is refused beside memory.
Cache key$host and $request_uri, one part eachRequests for the same host, path and query string share one copy.
Cached response statuses, under Behavior200Only successful answers are kept. An error the backend sends is not served again from the cache.

Cache key and Cached response statuses are lists without an add button. Type one part into the box and press Enter, and it becomes an entry of the list. For the key, type $host and press Enter, then $request_uri and press Enter.

Select Add plugin at the bottom of the panel. The plugin is saved like this:

The Add proxy-cache panel with the in-memory zone, the methods cached and the time an answer is kept.
proxy-cache · as the console saves it
{
  "cache_strategy": "memory",
  "cache_zone": "memory_cache",
  "cache_ttl": 60,
  "cache_key": [
    "$host",
    "$request_uri"
  ],
  "cache_http_status": [
    200
  ]
}

Check it​

Send the same request twice within a minute. key-auth is on the route, so add the key of mobile-app in the x-api-key header to the request below. The answer carries a cache status header whose value is MISS the first time and HIT the second; look for those values in the headers curl -i prints.

curl
curl -i -L 'https://<gateway host>/orders/42'
First request
The first request is answered 200 by the backend, and the answer's cache status header reads MISS; the gateway keeps the answer.
Second request
The second request within the minute is answered 200 by the gateway from its memory, and the cache status header reads HIT; the backend is not called.

What to know​

  • Each part of Cache key is a variable or text of two characters or more. A variable the request lacks adds nothing to the key.
  • Only GET and HEAD requests are cached unless you change Cached request methods. A method other than GET, HEAD and POST is refused when you save.
  • An answer that depends on who asks needs Consumer isolation on, the default, so each consumer gets its own entries. Off, an entry cached for one consumer is served to the others.
  • An answer that carries a Set-Cookie header is never stored while Cache set cookie is off.
  • With Cache control on, the backend's own Cache-Control or Expires sets how long a copy lives, and Cache TTL is not read.
  • Under the disk strategy, the lifetime of a copy is set by the gateway's own cache configuration, which is why Cache TTL is drawn under memory alone.
  • To skip the cache for one request, fill in Cache bypass. With $arg_nocache there, a request whose nocache query parameter is set to anything but empty or 0 goes to the backend.
G8 dev