HTTP Representation Variants

This specification introduces an alternative way to communicate a secondary cache key for a HTTP resource, using the HTTP “Variants” and “Variant-Key” response header fields. Its aim is to make HTTP proactive content negotiation more cache-friendly.¶

1. Introduction

HTTP proactive content negotiation ([RFC7231], Section 3.4.1) is seeing renewed interest, both for existing request headers like Accept-Language and for newer ones (for example, see [I-D.ietf-httpbis-client-hints]).¶

Successfully reusing negotiated responses that have been stored in a HTTP cache requires establishment of a secondary cache key ([RFC7234], Section 4.1). Currently, the Vary header ([RFC7231], Section 7.1.4) does this by nominating a set of request headers.¶

HTTP’s caching model allows a certain amount of latitude in normalising those request header field values, so as to increase the chances of a cache hit while still respecting the semantics of that header. However, normalisation is not formally defined, leading to divergence in cache behaviours.¶

Even when the headers’ semantics are understood, a cache does not know enough about the possible alternative representations available on the origin server to make an appropriate decision.¶

For example, if a cache has stored the following request/response pair:¶

GET /foo HTTP/1.1
Host: www.example.com
Accept-Language: en;q=0.5, fr;q=1.0

HTTP/1.1 200 OK
Content-Type: text/html
Content-Language: en
Vary: Accept-Language
Transfer-Encoding: chunked

[English content]

Provided that the cache has full knowledge of the semantics of Accept-Language and Content-Language, it will know that an English representation is available and might be able to infer that a French representation is not available. But, it does not know (for example) whether a Japanese representation is available without making another request, incurring possibly unnecessary latency.¶

This specification introduces the HTTP Variants response header field (Section 2) to enumerate the available variant representations on the origin server, to provide clients and caches with enough information to properly satisfy requests – either by selecting a response from cache or by forwarding the request towards the origin – by following the algorithm defined in Section 4.¶

Its companion Variant-Key response header field (Section 3) indicates the applicable key(s) that the response is associated with, so that it can be reliably reused in the future. When this specification is in use, the example above might become:¶

GET /foo HTTP/1.1
Host: www.example.com
Accept-Language: en;q=0.5, fr;q=1.0

HTTP/1.1 200 OK
Content-Type: text/html
Content-Language: en
Vary: Accept-Language
Variants: Accept-Language;de;en;jp
Variant-Key: en
Transfer-Encoding: chunked

[English content]

Proactive content negotiation mechanisms that wish to be used with Variants need to define how to do so explicitly; see Section 6. As a result, it is best suited for negotiation over request headers that are well-understood.¶

Variants also works best when content negotiation takes place over a constrained set of representations; since each variant needs to be listed in the header field, it is ill-suited for open-ended sets of representations.¶

Variants can be seen as a simpler version of the Alternates header field introduced by [RFC2295]; unlike that mechanism, Variants does not require specification of each combination of attributes, and does not assume that each combination has a unique URL.¶

1.1. Notational Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

This specification uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234] but relies on Structured Headers from [I-D.ietf-httpbis-header-structure] for parsing.¶

Additionally, it uses the “field-name” rule from [RFC7230], and “type”, “subtype”, “content-coding” and “language-range” from [RFC7231].¶

2. The “Variants” HTTP Header Field

The Variants HTTP response header field indicates what representations are available for a given resource at the time that the response is produced, by enumerating the request header fields that it varies on, along with the values that are available for each.¶

Variants is a Structured Header [I-D.ietf-httpbis-header-structure]. Its value MUST be a list-of-lists (Section 3.3 of [I-D.ietf-httpbis-header-structure]) whose members are strings (Section 3.8 of [I-D.ietf-httpbis-header-structure]) or tokens (Section 3.9 of [I-D.ietf-httpbis-header-structure]). Its ABNF is:¶

Variants        = sh-list-of-lists

If Structured Header parsing fails or a list-member has the wrong type, the client MUST treat the representation as having no Variants header field.¶

The Variants header field represents an ordered list of “variant-axes”, each of which consists of a request header “field-name” string and a list of “available-value” strings. Each inner-list in the Variants header field value is parsed into a variant-axis. The first list-member of the inner-list is interpreted as the field-name, and the remaining list-members are the available-values. Any list-member that is a token (Section 3.9 of [I-D.ietf-httpbis-header-structure]) is interpreted as a string containing the same characters.¶

Field-names in the Variants header field value MUST match the field-name production (Section 3.2 of [RFC7230]). Clients receiving an invalid field-name MUST NOT match it to any content negotiating mechanism.¶

So, given this example header field:¶

Variants: Accept-Encoding;gzip

a recipient can infer that the only content-coding available for that resource is “gzip” (along with the “identity” non-encoding; see Appendix A.2).¶

Given:¶

Variants: accept-encoding

a recipient can infer that no content-codings (beyond identity) are supported. Note that as always, field-name is case-insensitive.¶

A more complex example:¶

Variants: Accept-Encoding;gzip;br, Accept-Language;en ;fr

Here, recipients can infer that two content-codings in addition to “identity” are available, as well as two content languages. Note that, as with all Structured Header lists, they might occur in the same header field or separately, like this:¶

Variants: Accept-Encoding;gzip;brotli
Variants: Accept-Language;en ;fr

The ordering of available-values after the field-name is significant, as it might be used by the header’s algorithm for selecting a response (in this example, the first language is the default; see Appendix A.3).¶

The ordering of the request header fields themselves indicates descending application of preferences; in the example above, a cache that has all of the possible permutations stored will honour the client’s preferences for Accept-Encoding before honouring Accept-Language.¶

Origin servers SHOULD consistently send Variant header fields on all cacheable (as per [RFC7234], Section 3) responses for a resource, since its absence will trigger caches to fall back to Vary processing.¶

Likewise, servers MUST send the Variant-Key response header field when sending Variants, since its absence means that the stored response will not be reused when this specification is implemented.¶

RFC EDITOR: Please remove the next paragraph before publication. ¶

Implementations of drafts of this specification MUST implement an HTTP header field named “Variants-##” instead of the “Variants” header field specified by the final RFC, with “##” replaced by the draft number being implemented. For example, implementations of draft-ietf-httpbis-variants-05 would implement “Variants-05”.¶

2.1. Relationship to Vary

This specification updates [RFC7234] to allow caches that implement it to ignore request header fields in the Vary header for the purposes of secondary cache key calculation ([RFC7234], Section 4.1) when their semantics are implemented as per this specification and their corresponding response header field is listed in Variants.¶

If any member of the Vary header does not have a corresponding variant that is understood by the implementation, it is still subject to the requirements there.¶

See Section 5.1.3 for an example.¶

In practice, implementation of Vary varies considerably. As a result, cache efficiency might drop considerably when Variants does not contain all of the headers referenced by Vary, because some implementations might choose to disable Variants processing when this is the case.¶

3. The “Variant-Key” HTTP Header Field

The Variant-Key HTTP response header field identifies a set of variants provided by the representation it occurs within. A variant is identified by a selection of one available-value from each variant-axis from the Variants header field.¶

Variant-Key is a Structured Header [I-D.ietf-httpbis-header-structure]. Its value MUST be a list-of-lists (Section 3.3 of [I-D.ietf-httpbis-header-structure]) whose members are strings (Section 3.8 of [I-D.ietf-httpbis-header-structure]) or tokens (Section 3.9 of [I-D.ietf-httpbis-header-structure]). Its ABNF is:¶

Variant-Key      = sh-list-of-lists

If Structured Header parsing fails or a list-member has the wrong type, the client MUST treat the representation as having no Variant-Key header field.¶

Each inner-list MUST have the same number of list-members as there are variant-axes in the representation’s Variants header field. If not, the client MUST treat the representation as having no Variant-Key header field.¶

Each list-member is treated as identifying an available-value for the corresponding variant-axis’ field-name. Any list-member that is a token (Section 3.9 of [I-D.ietf-httpbis-header-structure]) is interpreted as a string containing the same characters. These available-values do not need to explicitly appear in the Variants header field. For example, Accept-Encoding defines an implicit “identity” available-value (Appendix A.2).¶

For example:¶

Variants: Accept-Encoding;gzip;br, Accept-Language;en ;fr
Variant-Key: gzip;fr

This header pair indicates that the representation has a “gzip” content-coding and “fr” content-language.¶

If the response can be used to satisfy more than one request, they can be listed in additional members. For example:¶

Variants: Accept-Encoding;gzip;br, Accept-Language;en ;fr
Variant-Key: gzip;fr, "identity";fr

indicates that this response can be used for requests whose Accept-Encoding algorithm selects “gzip” or “identity”, as long as the Accept-Language algorithm selects “fr” – perhaps because there is no gzip-compressed French representation.¶

When more than one Variant-Key value is in a response, the first one present MUST correspond to the request that caused that response to be generated.¶

Parsing is strict. For example:¶

Variants: Accept-Encoding;gzip;br, Accept-Language;en ;fr
Variant-Key: gzip;fr, identity;fr, br;fr;oops

is treated as if the Variant-Key header were completely absent, which will tend to disable caching for the representation that contains it.¶

Note that in¶

Variant-Key: gzip ;fr
Variant-Key: "gzip ";fr

The whitespace after “gzip” in the first header field value is excluded by the token parsing algorithm, but the whitespace in the second header field value is included by the string parsing algorithm. This will likely cause the second header field value to fail to match client requests.¶

RFC EDITOR: Please remove the next paragraph before publication. ¶

Implementations of drafts of this specification MUST implement an HTTP header field named “Variant-Key-##” instead of the “Variant-Key” header field specified by the final RFC, with “##” replaced by the draft number being implemented. For example, implementations of draft-ietf-httpbis-variants-05 would implement “Variant-Key-05”.¶

4. Cache Behaviour

Caches that implement the Variants header field and the relevant semantics of the field-names it contains can use that knowledge to either select an appropriate stored representation, or forward the request if no appropriate representation is stored.¶

They do so by running this algorithm (or its functional equivalent) upon receiving a request:¶

Given incoming-request (a mapping of field-names to lists of field values), and stored-responses (a list of stored responses suitable for reuse as defined in Section 4 of [RFC7234], excepting the requirement to calculate a secondary cache key):¶

If stored-responses is empty, return an empty list.
Order stored-responses by the “Date” header field, most recent to least recent.
Let sorted-variants be an empty list.
If the freshest member of stored-responses (as per [RFC7234], Section 4.2) has one or more “Variants” header field(s) that successfully parse according to Section 2:
1. Select one member of stored-responses with a “Variants” header field-value(s) that successfully parses according to Section 2 and let variants-header be this parsed value. This SHOULD be the most recent response, but MAY be from an older one as long as it is still fresh.
2. For each variant-axis in variants-header:
  1. If variant-axis’ field-name corresponds to the request header field identified by a content negotiation mechanism that the implementation supports:
    1. Let request-value be the field-value associated with field-name in incoming-request (after being combined as allowed by Section 3.2.2 of [RFC7230]), or null if field-name is not in incoming-request.
    2. Let sorted-values be the result of running the algorithm defined by the content negotiation mechanism with request-value and variant-axis’ available-values.
    3. Append sorted-values to sorted-variants.
  At this point, sorted-variants will be a list of lists, each member of the top-level list corresponding to a variant-axis in the Variants header field-value, containing zero or more items indicating available-values that are acceptable to the client, in order of preference, greatest to least.
Return result of running Compute Possible Keys (Section 4.1) on sorted-variants, an empty list and an empty list.

This returns a list of lists of strings suitable for comparing to the parsed Variant-Keys (Section 3) that represent possible responses on the server that can be used to satisfy the request, in preference order, provided that their secondary cache key (after removing the headers covered by Variants) matches. Section 4.2 illustrates one way to do this.¶

4.1. Compute Possible Keys

This algorithm computes the cross-product of the elements of key-facets.¶

Given key-facets (a list of lists of strings), and key-stub (a list of strings representing a partial key), and possible-keys (a list of lists of strings):¶

Let values be the first member of key-facets.
Let remaining-facets be a copy of all of the members of key-facets except the first.
For each value in values:
1. Let this-key be a copy of key-stub.
2. Append value to this-key.
3. If remaining-facets is empty, append this-key to possible-keys.
4. Otherwise, run Compute Possible Keys on remaining-facets, this-key and possible-keys.
Return possible-keys.

4.2. Check Vary

This algorithm is an example of how an implementation can meet the requirement to apply the members of the Vary header field that are not covered by Variants.¶

Given stored-response (a stored response):¶

Let filtered-vary be the field-value(s) of stored-response’s “Vary” header field.
Let processed-variants be a list containing the request header fields that identify the content negotiation mechanisms supported by the implementation.
Remove any member of filtered-vary that is a case-insensitive match for a member of processed-variants.
If the secondary cache key (as calculated in [RFC7234], Section 4.1) for stored_response matches incoming-request, using filtered-vary for the value of the “Vary” response header, return True.
Return False.

This returns a Boolean that indicates whether stored-response can be used to satisfy the request.¶

Note that implementation of the Vary header field varies in practice, and the algorithm above illustrates only one way to apply it. It is equally viable to forward the request if there is a request header listed in Vary but not Variants.¶

4.3. Example of Cache Behaviour

For example, if the selected variants-header was:¶

Variants: Accept-Language;en;fr;de, Accept-Encoding;gzip;br

and the request contained the headers:¶

Accept-Language: fr;q=1.0, en;q=0.1
Accept-Encoding: gzip

Then the sorted-variants would be:¶

[
  ["fr", "en"]         // prefers French, will accept English
  ["gzip", "identity"] // prefers gzip encoding, will accept identity
]

Which means that the result of the Cache Behaviour algorithm would be:¶

[
  ["fr", "gzip"],
  ["fr", "identity"],
  ["en", "gzip"],
  ["en", "identity"]
]

Representing a first preference of a French, gzip’d response. Thus, if a cache has a response with:¶

Variant-Key: fr; gzip

it could be used to satisfy the first preference. If not, responses corresponding to the other keys could be returned, or the request could be forwarded towards the origin.¶

4.3.1. A Variant Missing From the Cache

If the selected variants-header was:¶

Variants: Accept-Language;en;fr;de

And a request comes in with the following headers:¶

Accept-Language: de;q=1.0, es;q=0.8

Then sorted-variants in Cache Behaviour is:¶

[
  ["de"]         // prefers German; will not accept English
]

If the cache contains responses with the following Variant-Keys:¶

Variant-Key: fr
Variant-Key: en

Then the cache needs to forward the request to the origin server, since Variants indicates that “de” is available, and that is acceptable to the client.¶

4.3.2. Variants That Don’t Overlap the Client’s Request

If the selected variants-header was:¶

Variants: Accept-Language;en;fr;de

And a request comes in with the following headers:¶

Accept-Language: es;q=1.0, ja;q=0.8

Then sorted-variants in Cache Behaviour are:¶

[
  ["en"]
]

This allows the cache to return a “Variant-Key: en” response even though it’s not in the set the client prefers.¶

5. Origin Server Behaviour

Origin servers that wish to take advantage of Variants will need to generate both the Variants (Section 2) and Variant-Key (Section 3) header fields in all cacheable responses for a given resource. If either is omitted and the response is stored, it will have the effect of disabling caching for that resource until it is no longer stored (e.g., it expires, or is evicted).¶

Likewise, origin servers will need to assure that the members of both header field values are in the same order and have the same length, since discrepancies will cause caches to avoid using the responses they occur in.¶

The value of the Variants header should be relatively stable for a given resource over time; when it changes, it can have the effect of invalidating previously stored responses.¶

As per Section 2.1, the Vary header is required to be set appropriately when Variants is in use, so that caches that do not implement this specification still operate correctly.¶

Origin servers are advised to carefully consider which content negotiation mechanisms to enumerate in Variants; if a mechanism is not supported by a receiving cache, it will “downgrade” to Vary handling, which can negatively impact cache efficiency.¶

5.1. Examples

The operation of Variants is illustrated by the examples below.¶

5.1.1. Single Variant

Given a request/response pair:¶

GET /clancy HTTP/1.1
Host: www.example.com
Accept-Language: en;q=1.0, fr;q=0.5

HTTP/1.1 200 OK
Content-Type: image/gif
Content-Language: en
Cache-Control: max-age=3600
Variants: Accept-Language;en;de
Variant-Key: en
Vary: Accept-Language
Transfer-Encoding: chunked

Upon receipt of this response, the cache knows that two representations of this resource are available, one with a language of “en”, and another whose language is “de”.¶

Subsequent requests (while this response is fresh) will cause the cache to either reuse this response or forward the request, depending on what the selection algorithm determines.¶

So, if a request with “en” in Accept-Language is received and its q-value indicates that it is acceptable, the stored response is used. A request that indicates that “de” is acceptable will be forwarded to the origin, thereby populating the cache. A cache receiving a request that indicates both languages are acceptable will use the q-value to make a determination of what response to return.¶

A cache receiving a request that does not list either language as acceptable (or does not contain an Accept-Language at all) will return the “en” representation (possibly fetching it from the origin), since it is listed first in the Variants list.¶

Note that Accept-Language is listed in Vary, to assure backwards-compatibility with caches that do not support Variants.¶

5.1.2. Multiple Variants

A more complicated request/response pair:¶

GET /murray HTTP/1.1
Host: www.example.net
Accept-Language: en;q=1.0, fr;q=0.5
Accept-Encoding: gzip, br

HTTP/1.1 200 OK
Content-Type: image/gif
Content-Language: en
Content-Encoding: br
Variants: Accept-Language;en;jp;de
Variants: Accept-Encoding;br;gzip
Variant-Key: en;br
Vary: Accept-Language, Accept-Encoding
Transfer-Encoding: chunked

Here, the cache knows that there are two axes that the response varies upon; language and encoding. Thus, there are a total of nine possible representations for the resource (including the identity encoding), and the cache needs to consider the selection algorithms for both axes.¶

Upon a subsequent request, if both selection algorithms return a stored representation, it can be served from cache; otherwise, the request will need to be forwarded to origin.¶

5.1.3. Partial Coverage

Now, consider the previous example, but where only one of the Vary’d axes (encoding) is listed in Variants:¶

GET /bar HTTP/1.1
Host: www.example.net
Accept-Language: en;q=1.0, fr;q=0.5
Accept-Encoding: gzip, br

HTTP/1.1 200 OK
Content-Type: image/gif
Content-Language: en
Content-Encoding: br
Variants: Accept-Encoding;br;gzip
Variant-Key: br
Vary: Accept-Language, Accept-Encoding
Transfer-Encoding: chunked

Here, the cache will need to calculate a secondary cache key as per [RFC7234], Section 4.1 – but considering only Accept-Language to be in its field-value – and then continue processing Variants for the set of stored responses that the algorithm described there selects.¶

Appendix A. Variants for Existing Content Negotiation Mechanisms

This appendix defines the required information to use existing proactive content negotiation mechanisms (as defined in [RFC7231], Section 5.3) with the Variants header field.¶

A.1. Accept

This section defines variant handling for the Accept request header (section 5.3.2 of [RFC7231]).¶

The syntax of an available-value for Accept is:¶

accept-available-value = type "/" subtype

To perform content negotiation for Accept given a request-value and available-values:¶

Let preferred-available be an empty list.
Let preferred-types be a list of the types in the request-value (or the empty list if request-value is null), ordered by their weight, highest to lowest, as per Section 5.3.2 of [RFC7231] (omitting any coding with a weight of 0). If a type lacks an explicit weight, an implementation MAY assign one.
For each preferred-type in preferred-types:
1. If any member of available-values matches preferred-type, using the media-range matching mechanism specified in Section 5.3.2 of [RFC7231] (which is case-insensitive), append those members of available-values to preferred-available (preserving the precedence order implied by the media ranges’ specificity).
If preferred-available is empty, append the first member of available-values to preferred-available. This makes the first available-value the default when none of the client’s preferences are available.
Return preferred-available.

Note that this algorithm explicitly ignores extension parameters on media types (e.g., “charset”).¶

A.2. Accept-Encoding

This section defines variant handling for the Accept-Encoding request header (section 5.3.4 of [RFC7231]).¶

The syntax of an available-value for Accept-Encoding is:¶

accept-encoding-available-value = content-coding / "identity"

To perform content negotiation for Accept-Encoding given a request-value and available-values:¶

Let preferred-available be an empty list.
Let preferred-codings be a list of the codings in the request-value (or the empty list if request-value is null), ordered by their weight, highest to lowest, as per Section 5.3.1 of [RFC7231] (omitting any coding with a weight of 0). If a coding lacks an explicit weight, an implementation MAY assign one.
If “identity” is not a member of preferred-codings, append “identity”.
Append “identity” to available-values.
For each preferred-coding in preferred-codings:
1. If there is a case-insensitive, character-for-character match for preferred-coding in available-values, append that member of available-values to preferred-available.
Return preferred-available.

Note that the unencoded variant needs to have a Variant-Key header field with a value of “identity” (as defined in Section 5.3.4 of [RFC7231]).¶

A.3. Accept-Language

This section defines variant handling for the Accept-Language request header (section 5.3.5 of [RFC7231]).¶

The syntax of an available-value for Accept-Language is:¶

accept-encoding-available-value = language-range

To perform content negotiation for Accept-Language given a request-value and available-values:¶

Let preferred-available be an empty list.
Let preferred-langs be a list of the language-ranges in the request-value (or the empty list if request-value is null), ordered by their weight, highest to lowest, as per Section 5.3.1 of [RFC7231] (omitting any language-range with a weight of 0). If a language-range lacks a weight, an implementation MAY assign one.
For each preferred-lang in preferred-langs:
1. If any member of available-values matches preferred-lang, using either the Basic or Extended Filtering scheme defined in Section 3.3 of [RFC4647], append those members of available-values to preferred-available (preserving their order).
If preferred-available is empty, append the first member of available-values to preferred-available. This makes the first available-value the default when none of the client’s preferences are available.
Return preferred-available.

HTTP Representation Variants

Abstract

Note to Readers

Status of this Memo

Copyright Notice