liveBook · Manning

Cache policy

As explained in The Design of Web APIs, Second Edition

A caching policy is a set of rules that determines whether, where, and for how long data may be cached based on its characteristics and context.

A caching policy defines whether consumers may cache data, how long they may reuse it, and whether they must validate it before use. It balances performance and accuracy by considering data composition, change events, volatility, and usage context. section 13.4.3

Choose the policy according to the data and its consequences:

  • Cache stable data until a known change date, such as card pricing updated on the 15th. section 13.4.3
  • Allow caching but require validation when data changes unpredictably, such as an account balance affected by real-time transactions. section 13.4.3
  • Permit longer caching for approximate data, while exposing when it was calculated, as with a transaction categorization chart. section 13.4.3

Library search

For GET /books, policy decisions must account for monthly additions and availability changes caused by returns or reservations. An exercise asks which cache-related headers apply to a request made before the next scheduled addition. section 13.12

Record the policy in the operation or 2XX response description in OpenAPI, and check security, business, and regulatory constraints before enabling client-side caching. section 13.4.3

How The Design of Web APIs, Second Edition covers it

How deep it goes
Explains policy factors and contrasting data scenarios, then stops short of specifying every operation’s concrete header values.
Examples
Uses bank-card pricing, account balances, transaction charts, and library-book searches to compare freshness requirements.
What you can do after
Apply it via HTTP cache directives and conditional requests, documenting decisions in OpenAPI and validating stakeholder constraints.
How it connects
Connects caching policy with cache invalidation, conditional requests, HTTP caching, OpenAPI, and data volatility.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of The Design of Web APIs, Second Edition. The section links point to the parts of the book it draws on.