diff --git a/execution/caching.md b/execution/caching.md index 4505e5b..4c08d5a 100644 --- a/execution/caching.md +++ b/execution/caching.md @@ -2,7 +2,27 @@ Every API implementation **SHOULD** return both the cache expiry information ([`Cache-Control` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)) and specific resource version information ([`ETag` HTTP Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag)). ## Cache-Control -Every API implementation's response **SHOULD** include information about cache-ability and cache expiration of the response. +Every API implementation's response **SHOULD** include information about cache-ability and cache expiration of the response. For HTTP 1.1 this is achieved using the `Cache-Control` header. + + +### Common Cache-Control Scenarios +Two, most common scenarios for controling the cache-ability of a response includes (1) Setting expiration and revalidation and (2) disabling the caching of a response. Refer to the [Cache-Control Documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) for additional controls. + +#### 1. Cache Expiration & Revalidation +Common scenario to set cache expiration and revalidation is to use the `max-age` and `must-revalidate` directives: + +``` +HTTP/1.1 200 OK +Date: Mon, 19 Aug 2017 00:00:00 GM +Cache-Control: max-age=3600,must-revalidate + +... +``` + + +#### 2. Disabling Cache + + ## ETag Every API implementation's response to a [cacheable request](https://github.com/for-GET/know-your-http-well/blob/master/methods.md#cacheable) **SHOULD** include the [`ETag` HTTP Header](https://tools.ietf.org/html/rfc7232#section-2.3) to identify the specific version of the returned resource.