HTTP cache key

An HTTP cache key is the information an HTTP cache uses to choose a stored response. The standard's minimum basis comprises the request method and target URI, while additional request information can distinguish negotiated responses or partition storage. Common caches that store only GET responses can use the URI alone for that minimum basis.^[ref]

For an own example, suppose a cache holds both JSON and HTML responses for GET /report, each with Vary: Accept. Their explanatory selection inputs are (GET, /report, Accept=application/json) and (GET, /report, Accept=text/html). The target and method agree, but the nominated field distinguishes the variants. Another matching request for JSON must not receive the HTML entry merely because its target is also /report.^[ref]

A request for /report?page=2 also has a different target from /report. Sharing a path prefix is not enough to identify a stored response. The example's tuples describe selection information rather than prescribe a particular serialized key or database implementation.

Field matching itself follows the specification. It can include the normalization permitted for the nominated fields; comparing every raw header string byte for byte is not the general rule. A missing field and an arbitrary different value also cannot be silently treated as equivalent.^[ref]

Selection and permission to reuse are separate steps. A matching stored response must still satisfy the applicable cache controls and HTTP freshness or validation requirements. An HTTP private cache and an HTTP shared cache differ in their scope and some controls, but neither can infer complete reuse permission from a key match alone.^[ref]

The key becomes especially important with HTTP content negotiation: several representations can belong to one resource without being interchangeable for every request. Identifying the selection dimensions explains both correct reuse and why one broadly shared target identifier need not yield one universal cached body.