RFC 7694

Hypertext Transfer Protocol (HTTP) Client-Initiated Content-Encoding

📅 published November 2015, from ietf

RFC 7694 🎀 Client-Initiated Content-Encoding in HTTP

Okay bestie, this is RFC 7694!! 💖 The title is Hypertext Transfer Protocol (HTTP) Client-Initiated Content-Encoding. It's a Standards Track doc, so it's a real IETF spec 🏆.

  • Authors: J. Reschke (greenbytes) 🦋
  • Category: Standards Track
  • Date: November 2015
  • ISSN: 2070-1721
  • Obsoletes / updates: The header doesn't list anything it obsoletes. It does update stuff inside the body, though: it updates the definition of the "Accept-Encoding" header field and of status code 415 (Unsupported Media Type), see Section 1 and Section 3 👑

Abstract ✨

Okay so in HTTP, content codings are how payloads get encoded, like for compression or integrity checks 🗜️. The famous one is "gzip", which gets used a LOT for payload data in response messages 🔥.

Content codings can also show up in request messages, but ngl, they're way less discoverable than in responses 😭. This doc fixes that by extending the HTTP "Accept-Encoding" header field so it can be used in responses. That way it can tell you which content codings are supported in requests 💅.

Status of This Memo 📜

This is an Internet Standards Track document. 🏆

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). For more on Internet Standards, check Section 2 of RFC 5741 🧐.

Info about the current status of this doc, any errata, and how to send feedback lives at http://www.rfc-editor.org/info/rfc7694.

Copyright (c) 2015 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 (http://trustee.ietf.org/license-info) as in effect on the date of publication. Please read these carefully, because they spell out your rights and restrictions for this document 📖. Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License 🫶.

Table of Contents 📑

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
2.  Notational Conventions  . . . . . . . . . . . . . . . . . . .   2
3.  Using the 'Accept-Encoding' Header Field in Responses . . . .   3
4.  Example . . . . . . . . . . . . . . . . . . . . . . . . . . .   4
5.  Deployment Considerations . . . . . . . . . . . . . . . . . .   4
6.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   5
  7.1.  Header Field Registry . . . . . . . . . . . . . . . . . .   5
  7.2.  Status Code Registry  . . . . . . . . . . . . . . . . . .   6
8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   6
  8.1.  Normative References  . . . . . . . . . . . . . . . . . .   6
  8.2.  Informative References  . . . . . . . . . . . . . . . . .   6
Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .   7
Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   7

1. Introduction ✨

Okay so the intro says content codings let you do payload encodings like compression or integrity checks ([RFC7231], Section 3.1.2). The gzip content coding ([RFC7230], Section 4.2) is the main character here, since it's widely used for payload data sent in response messages 🔥.

Content codings can be used in request messages too, but discoverability is not on par with responses 🫠. This doc extends the HTTP "Accept-Encoding" header field ([RFC7231], Section 5.3.4) so it works in responses, to show which content codings are supported in requests 🎀. It also updates the definition of status code 415 (Unsupported Media Type) ([RFC7231], Section 6.5.13), recommending that the "Accept-Encoding" header field be included when appropriate 💜.

2. Notational Conventions 🧐

The BCP 14 key words, "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL", are how this doc signals how strict each rule is 💅. They're interpreted as described in [RFC2119].

This doc reuses terms from the base HTTP specs, namely Section 2 of [RFC7230] and Section 3.1.2 of [RFC7231] 🦋.

3. Using the 'Accept-Encoding' Header Field in Responses 🌸

Okay so Section 5.3.4 of [RFC7231] defines "Accept-Encoding" as a request header field only 🙃.

This spec expands that definition so "Accept-Encoding" can be a response header field too ✨. When it's in a response, it tells you what content codings the resource was willing to accept in the associated request. If the field value only contains "identity", that means no content codings were supported 🫶.

Note: this info is specific to the associated request. The set of supported encodings might be different for other resources on the same server, could change over time, or could depend on other parts of the request (like the request method) 👀.

Section 6.5.13 of [RFC7231] defines status code 415 (Unsupported Media Type) for problems related to both media types and content codings 🎀.

Servers that fail a request because of an unsupported content coding ought to respond with a 415 status, and ought to include an "Accept-Encoding" header field in that response. This lets clients tell content coding issues apart from media type issues 🧠. To avoid confusion with media type issues, servers that fail a request with a 415 status for reasons unrelated to content codings MUST NOT include the "Accept-Encoding" header field 🚫.

💀 Heads up: the MUST NOT above is the only BCP 14 key word in this section, so it's the one strict rule here.

It's expected that the most common use of "Accept-Encoding" in responses will be the 415 (Unsupported Media Type) status code, responding to optimistic use of a content coding by clients 🥹. But the header field can also tell clients that content codings are supported, which helps optimize future interactions ⭐. For example, a resource might include it in a 2xx response when the request payload was big enough to justify a compression coding but the client failed to do so 🍓.

4. Example 🧚

A client submits a POST request using the "compress" content coding ([RFC7231], Section 3.1.2.1):

POST /edit/ HTTP/1.1
Host: example.org
Content-Type: application/atom+xml;type=entry
Content-Encoding: compress

...compressed payload...

The server rejects the request because it only allows the "gzip" content coding:

HTTP/1.1 415 Unsupported Media Type
Date: Fri, 09 May 2014 11:43:53 GMT
Accept-Encoding: gzip
Content-Length: 68
Content-Type: text/plain

This resource only supports the "gzip" content coding in requests.

At this point, the client can retry the request with the supported "gzip" content coding 🔁.

Alternatively, a server that doesn't support any content codings in requests could answer with:

HTTP/1.1 415 Unsupported Media Type
Date: Fri, 09 May 2014 11:43:53 GMT
Accept-Encoding: identity
Content-Length: 61
Content-Type: text/plain

This resource does not support content codings in requests.
⏭️ To be continued!! Part 2 picks up with Section 5 (Deployment Considerations) and keeps going from there 💜🌈

8.2. Informative References

Okay, these are the bonus reads 📚✨ They're not required to implement this, but they give you the backstory, bestie.

Acknowledgements 🫶

Huge thank-yous to the Hypertext Transfer Protocol Working Group participants, namely Amos Jeffries, Ben Campbell, Mark Nottingham, Pete Resnick, Stephen Farrell, and Ted Hardie. You all are literally the reason this stuff works, and I'm obsessed 💖🌈

Author's Address 💌

Julian F. Reschke
greenbytes GmbH
Hafenweg 16
Muenster, NW  48155
Germany

Email: julian.reschke@greenbytes.de
URI:   http://greenbytes.de/tech/webdav/
📦 where this page comes from