Caching responses

Caching can reduce latency, avoid unnecessary requests and help applications remain within their assigned rate limits.

Follow response headers

Treat the API's HTTP response headers as the source of truth. When present, Cache-Control indicates whether and for how long a response may be reused.

An ETag identifies a particular representation of a resource. A client can send it in a later conditional request:

If-None-Match: "RESOURCE_ETAG"

If the representation has not changed, the server can return:

304 Not Modified

The response has no new body, and the client can continue using its cached copy.

Do not assume caching support

Not every endpoint or deployment necessarily returns the same caching headers. Do not invent a cache lifetime when the response explicitly prohibits caching.

When no caching instruction is present, choose a conservative application-level refresh policy based on how time-sensitive the data is.

Cache keys

For list and search responses, include the complete normalized query in the cache key. These requests are different:

/v1/clubs?near=Hamburg&country=DE&limit=20
/v1/clubs?near=Hamburg&country=DE&public=true&limit=20

Authentication scope can also affect a response. Do not share private or differently scoped responses between users or API clients unless the response headers explicitly allow it.

Club details

Detailed club records are often suitable for longer caching than interactive searches, but access rules and prices can still change. Revalidate records instead of treating them as permanent.

Error responses

Do not cache authentication errors. Cache temporary server errors only when explicitly permitted by the response headers.