An HTTP Cache Invalidation API

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 26 December 2023.¶

Copyright Notice

Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

Section 4.4 of [HTTP-CACHING] defines invalidation as the side effect of a state-changing request on one or more stored responses in an HTTP cache.¶

In practice, it has become common for caches to allow invalidation to be triggered through other mechanisms -- often, using a dedicated HTTP API. This is especially useful for caches that have a relationship with the origin server and wish to offer them finer-grained control, as is the case for reverse proxies and content delivery networks.¶

While many such APIs already exist, they are proprietary. That makes it difficult for the origin server or its delegates (for example, content management systems) to take advantage of those facilities, because each integration needs to created and maintained, hindering interoperability.¶

This document standardises an HTTP-based API for HTTP cache invalidation. Section 2 describes an HTTP resource that accepts requests to invalidate stored responses, using a format described in Section 3. Section 4 specifies a format that describes the capabilities and configuration of a cache's invalidation API, so that tools used by the origin server can easily consume it.¶

2. HTTP Cache Invalidation Resources

An HTTP Cache Invalidation Resource (hereafter, 'invalidation resource') is an HTTP resource (Section 3.1 of [HTTP]) that has the behaviours described in this section.¶

Invalidation resources SHOULD require requests to include some form of authentication. The specific mechanism is out of scope for this document, but note that Section 4 describes a way to specify a mechanism and credentials in the description format.¶

When an invalidation resource receives a POST request whose content is in the format described in Section 3, its expected behaviour will be to process the request and invalidate the responses it indicates that are stored in the cache(s) associated with it.¶

As described in Section 4.4 of [HTTP-CACHING]:¶

• invalidate means that the cache will either remove all stored responses whose target URI matches the given URI or mark them as "invalid" and in need of a mandatory validation before they can be sent in response to a subsequent request.¶

This includes all responses for the URI, including those who have cache keys that include information derived from the Vary response field (see Section 4.1 of [HTTP-CACHING]).¶

The authenticated user MUST be authorized to perform each invalidation. Unauthorized invalidations MUST be ignored; future extensions might allow description of which invalidations succeeded or failed.¶

Furthermore, some features in the event format described in Section 3 are not required to be implemented; for example, some event selector types might not be supported, or the "purge" member might not be supported. An invalidation resource that receives a request using an unsupported feature SHOULD respond with a 501 (Not Implemented) status code.¶

TODO: specify a problem details object for these errors¶

If the cache is able to invalidate the indicated stored responses in a reasonable amount of time (for example, 30 seconds), the invalidation resource SHOULD respond with a 200 (OK) status code only once all of those responses have been invalidated.¶

Otherwise (i.e., the cache cannot invalidate within a reasonable amount of time, or cannot estimate how long invalidation will take), it SHOULD immediately respond with a 202 (Accepted) status code.¶

This specification does not define a format for successful responses from invalidation resources; implementations MAY send responses with empty content. Future extensions might allow description of the results of invalidation.¶

3. HTTP Cache Invalidation Event Format

The HTTP Cache Invalidation Event Format (hereafter, 'event format') is a JSON-based [JSON] format that conveys a list of selectors that are used to identify the stored responses in a cache, along with additional instructions about the nature of invalidation being requested.¶

Its content is an object with the following two required members:¶

• "type": a case-sensitive string indicating the selector type for the invalidation event; see Section 3.1¶
• "selectors": an array of strings, each being a selector of the indicated type.¶

For example, this document contains an event using the "URI" selector type, and invalidates two URIs:¶

{
    "type": "uri",
    "selectors": [
      "https://example.com/foo/bar",
      "https://example.com/foo/bar/baz"
    ]
}

Additionally, this document defines one optional member of the top-level object:¶

• "purge": a boolean that when true indicates that the selected stored responses should be removed from cache, rather than just marked as invalid.¶

When a cache indicates support for purge (see Section 4) and purge is true, the cache MUST remove the relevant response(s) from volatile and non-volatile storage as promptly as possible, and if the cache indicates success with a 200 (OK) status code, MUST do so before returning the response.¶

Unrecognised members of the top-level object MUST be ignored, to allow future updates of this specification to add new features.¶

{
    "type": "group",
    "selectors": [
      "https://example.com:443",
      "https://www.example.com:443"
    ],
    "groups": [
      "scripts"
    ]
}

4. Gateway Description Format

To alloworigin servers and tools that they use to be easily configured, this document defines a Gateway Description Format that describes the configuration of an HTTP gateway (commonly, a "reverse proxy" or content delivery network). It is intended to be generated by gateways and made available out-of-band to origin servers using them.¶

The format is based upon JSON [JSON]. The root object can contain members with the following names and values:¶

• "generated": a string containing the date that the description was generated, in the IMF-fixdate format described in Section 5.6.7 of [HTTP]¶
• "description": a string containing a human-readable description of the gateway¶
• "invalidation": an invalidation description object (see below)¶
• "api-authentication": an API authentication description object (see below)¶
• "targeted-cc": an array of strings indicating the targeted cache-control header field(s) [TARGETED] supported by the gateway, in order of precedence (i.e., first entry overrides later entries)¶
• "vendor": an object containing arbitrary, vendor-specific extensions¶

Invalidation description objects can contain the following members and values:¶

• "uri": a string conveying the URI of the Invalidation Resource (Section 2)¶
• "selectors": an array of strings indicating the selectors (Section 3.1) that the Invalidation Resource supports¶
• "purge": a boolean indicating whether the Invalidation Resource supports the "purge" member in requests (see Section 3)¶
• "p95-latency": an integer indicating the number of milliseconds that 95% of invalidation requests should be fully applied to the scope indicated by the description.¶

API authentication objects can contain the following members and values:¶

• "bearer": a string containing a token to be used to authenticate to the API(s) described in the document, using Bearer HTTP authentication as described in Section 2.1 of [BEARER]¶

Unrecognised members of all of these objects MUST be ignored. New members may be introduced to them by updating this specification.¶

For example:¶

{
  "description": "The Example CDN",
  "generated": "",
  "invalidation": {
    "uri": "https://api.cdn.example.com/invalidate",
    "selectors": ["uri", "uri-prefix", "group"],
    "purge": true,
    "p95-latency": 2000
  },
  "targeted-cc": [
    "ExampleCDN-Cache-Control",
    "CDN-Cache-Control"
  ],
  "api-authentication": {
    "bearer": "mF_9.B5f-4.1JqM"
  }
}

5. IANA Considerations

6. Security Considerations

TBD¶

Appendix A. Acknowledgements

Thanks to Stephen Ludin for his review and suggestions.¶

Author's Address