From b585c8485d86c2ec9bc19d9f99ab442f9b375374 Mon Sep 17 00:00:00 2001 From: Chris Dent Date: Wed, 7 Mar 2018 13:09:40 +0000 Subject: [PATCH] Add guidance on needing cache-control headers This adds some practical guidance to the existing section on caching to make it clear that where responses are not making explicit assertions about controlling cache, they MUST "cache-control: no-cache" Change-Id: If13a5a19ff077cd9a2c9c400c24af70ea6f818d9 Closes-Bug: #1747935 --- guidelines/http/caching.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/guidelines/http/caching.rst b/guidelines/http/caching.rst index 1c40c04..2113ba0 100644 --- a/guidelines/http/caching.rst +++ b/guidelines/http/caching.rst @@ -37,3 +37,39 @@ Thinking carefully about cache semantics when implementing anything in the OpenStack API is critical to the API being compatible with the vast range of runtimes, programming languages, and proxy servers (open and commercial) that exist in the wild. + +Cache Headers in Practice +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Given what is said above ("caching [...] is to be expected in all cases"), +services MUST provide appropriate ``Cache-Control`` headers to avoid bugs like +those described in +`1747935 `_ wherein +an intermediary proxy caches a response indefinitely, despite a change in the +underlying resource. + +To avoid this problem, at a minimum, responses defined above as "cacheable" +that do not otherwise control caching MUST include a header of:: + + Cache-Control: no-cache + +Despite how it sounds, ``no-cache`` (defined by :rfc:`7234#section-5.2.1.4`) +means only use a cached resource if it can be validated against the origin +server. However, in the absence of headers which can be sent back to the +server in an ``If-Modified-Since`` or ``If-None-Match`` conditional request, +``no-cache`` means no caching will happen. For more on validation see +:rfc:`7234#section-4.3`. + +This means that at least all responses to ``GET`` requests that return a +``200`` status need the header, unless explicit caching requirements are +expressed in the response. + +MDN provides a good overview of the `Cache-Control header +`_ and +provides some guidance on ways to indicate that caching is desired. If caching +is expected, in addition to the ``Cache-Control`` header, headers such as +``ETag`` or ``Last-Modified`` must also be present. + +Describing how to do cache validation and conditional request handling is out +of scope for these guidelines because the requirements will be different from +service to service.