Check for Standards Before Creating a New One

I recently had a ticket opened on my team's backlog board requesting the ability to bypass our API's caching system. For context, our front-end team uses my team's API to make fairly heavy requests to ElasticSearch, and one of the features of our API gateway is to cache the results of heavy aggregations for ~30 seconds. It turns out, every once in a while they need to run two of the same query within the ~30-second caching window and want an updated result set.

The request that was opened read something like, "the API needs a parameter to disable caching for certain queries". When working in a REST-ish-ful API there are approximately math.MaxInt ways to accomplish that, and some of the first ones that immediately came to mind were:

• A ?cache=false query parameter
• A resource/no-cache endpoint extension
• A cache: false HTTP header
• A "cache": false" JSON payload in the body

As it turns out, there's already a standard for this sort of thing, the Cache-Control request directives.

Cache-Control: max-age=<seconds>
Cache-Control: max-stale[=<seconds>]
Cache-Control: min-fresh=<seconds>
Cache-Control: no-cache
Cache-Control: no-store
Cache-Control: no-transform
Cache-Control: only-if-cached

Using the standard header Cache-Control: no-store not only makes my job easier by requiring fewer API design decisions but also ensures that my API's clients aren't surprised by a new way to accomplish a common task.

I do want to point out, however, that just because you've decided to use a fairly well-supported standard, doesn't mean there aren't other standards your users will expect. It also doesn't mean that your users are aware of the existence of the standard you've chosen.

XKCD

Regardless of whether or not you think your API's behavior is "standard" or "to be expected", just add the behavior to your docs anyway. For me, the following snippet in our Readme.md was all we needed.

<h2 id="cache-busting" class="anchor heading-group"><span>Cache busting</span><a class="heading-link" href="#cache-busting" aria-label="Link to Cache busting"><svg class="heading-anchor" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/></svg></a></h2>

If you don't want your query cached, use the Cache-Control header.

Cache-Control: no-store