RFC 7231
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
Internet Engineering Task Force (IETF) โจ RFC 7231 ๐
Okay bestie, let's get into this ๐ Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content ๐ฆ. It's giving foundational, and it's Standards Track ๐, which means it went through public review and got the IETF community's consensus ๐ .
Here's the title-block tea โ. It's authored by R. Fielding, Ed. from Adobe ๐ and J. Reschke, Ed. from greenbytes ๐ซถ. It's dated June 2014 ๐ธ and the ISSN is 2070-1721 โจ. It obsoletes RFC 2616 ๐ (so the old one is out, no cap) and updates RFC 2817 ๐ฅ.
This is part 1 of 23, so more is coming, periodt ๐ง.
Abstract ๐
Okay so, HTTP is a stateless, application-level protocol for distributed, collaborative, hypertext information systems โจ. This doc defines the semantics of HTTP/1.1 messages, which means what they actually mean ๐. That covers request methods, request header fields, response status codes, and response header fields, plus the payload of messages (metadata and body content) and the mechanisms for content negotiation ๐ . Literally the whole vibe of how the web talks ๐ฆ.
Status of This Memo ๐
This is an Internet Standards Track document ๐.
It's a product of the Internet Engineering Task Force (IETF) ๐. It represents the consensus of the IETF community, received public review, and got approved for publication by the Internet Engineering Steering Group (IESG) ๐ซถ. If you want more on Internet Standards, check out Section 2 of RFC 5741 ๐ธ.
Info about the current status of this doc, any errata, and how to give feedback can be found at http://www.rfc-editor.org/info/rfc7231 ๐ฅ.
Copyright Notice ๐
Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved ๐ .
This doc 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 ๐. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they're provided without warranty as described in the Simplified BSD License ๐.
This doc may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008 โจ. The people controlling the copyright in some of that material may not have granted the IETF Trust the right to allow modifications outside the IETF Standards Process ๐. So unless you've got an adequate license from those copyright holders, this doc may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside that process either ๐ซถ. The exceptions are formatting it for publication as an RFC or translating it into languages other than English ๐ฆ.
Ok that's the boring legal part done, but it matters ๐
Table of Contents ๐
1. Introduction ....................................................6
1.1. Conformance and Error Handling .............................6
1.2. Syntax Notation ............................................6
2. Resources .......................................................7
3. Representations .................................................7
3.1. Representation Metadata ....................................8
3.1.1. Processing Representation Data ......................8
3.1.2. Encoding for Compression or Integrity ..............11
3.1.3. Audience Language ..................................13
3.1.4. Identification .....................................14
3.2. Representation Data .......................................17
3.3. Payload Semantics .........................................17
3.4. Content Negotiation .......................................18
3.4.1. Proactive Negotiation ..............................19
3.4.2. Reactive Negotiation ...............................20
4. Request Methods ................................................21
4.1. Overview ..................................................21
4.2. Common Method Properties ..................................22
4.2.1. Safe Methods .......................................22
4.2.2. Idempotent Methods .................................23
4.2.3. Cacheable Methods ..................................24
4.3. Method Definitions ........................................24
4.3.1. GET ................................................24
4.3.2. HEAD ...............................................25
4.3.3. POST ...............................................25
4.3.4. PUT ................................................26
4.3.5. DELETE .............................................29
4.3.6. CONNECT ............................................30
4.3.7. OPTIONS ............................................31
4.3.8. TRACE ..............................................32
5. Request Header Fields ..........................................33
5.1. Controls ..................................................33
5.1.1. Expect .............................................34
5.1.2. Max-Forwards .......................................36
5.2. Conditionals ..............................................36
5.3. Content Negotiation .......................................37
5.3.1. Quality Values .....................................37
5.3.2. Accept .............................................38
5.3.3. Accept-Charset .....................................40
5.3.4. Accept-Encoding ....................................41
5.3.5. Accept-Language ....................................42
5.4. Authentication Credentials ................................44
5.5. Request Context ...........................................44
5.5.1. From ...............................................44
5.5.2. Referer ............................................45
5.5.3. User-Agent .........................................46
6. Response Status Codes ..........................................47
6.1. Overview of Status Codes ..................................48
6.2. Informational 1xx .........................................50
6.2.1. 100 Continue .......................................50
6.2.2. 101 Switching Protocols ............................50
6.3. Successful 2xx ............................................51
6.3.1. 200 OK .............................................51
6.3.2. 201 Created ........................................52
6.3.3. 202 Accepted .......................................52
6.3.4. 203 Non-Authoritative Information ..................52
6.3.5. 204 No Content .....................................53
6.3.6. 205 Reset Content ..................................53
6.4. Redirection 3xx ...........................................54
6.4.1. 300 Multiple Choices ...............................55
6.4.2. 301 Moved Permanently ..............................56
6.4.3. 302 Found ..........................................56
6.4.4. 303 See Other ......................................57
6.4.5. 305 Use Proxy ......................................58
6.4.6. 306 (Unused) .......................................58
6.4.7. 307 Temporary Redirect .............................58
6.5. Client Error 4xx ..........................................58
6.5.1. 400 Bad Request ....................................58
6.5.2. 402 Payment Required ...............................59
6.5.3. 403 Forbidden ......................................59
6.5.4. 404 Not Found ......................................59
6.5.5. 405 Method Not Allowed .............................59
6.5.6. 406 Not Acceptable .................................60
6.5.7. 408 Request Timeout ................................60
6.5.8. 409 Conflict .......................................60
6.5.9. 410 Gone ...........................................60
6.5.10. 411 Length Required ...............................61
6.5.11. 413 Payload Too Large .............................61
6.5.12. 414 URI Too Long ..................................61
6.5.13. 415 Unsupported Media Type ........................62
6.5.14. 417 Expectation Failed ............................62
6.5.15. 426 Upgrade Required ..............................62
6.6. Server Error 5xx ..........................................62
6.6.1. 500 Internal Server Error ..........................63
6.6.2. 501 Not Implemented ................................63
6.6.3. 502 Bad Gateway ....................................63
6.6.4. 503 Service Unavailable ............................63
6.6.5. 504 Gateway Timeout ................................63
6.6.6. 505 HTTP Version Not Supported .....................64
7. Response Header Fields .........................................64
7.1. Control Data ..............................................64
ed 7.1.1. Origination Date ...................................65
7.1.2. Location ...........................................68
7.1.3. Retry-After ........................................69
7.1.4. Vary ...............................................70
7.2. Validator Header Fields ...................................71
7.3. Authentication Challenges .................................72
7.4. Response Context ..........................................72
7.4.1. Allow ..............................................72
7.4.2. Server .............................................73
8. IANA Considerations ............................................73
8.1. Method Registry ...........................................73
8.1.1. Procedure ..........................................74
8.1.2. Considerations for New Methods .....................74
8.1.3. Registrations ......................................75
8.2. Status Code Registry ......................................75
8.2.1. Procedure ..........................................75
8.2.2. Considerations for New Status Codes ................76
8.2.3. Registrations ......................................76
8.3. Header Field Registry .....................................77
8.3.1. Considerations for New Header Fields ...............78
8.3.2. Registrations ......................................80
8.4. Content Coding Registry ...................................81
8.4.1. Procedure ..........................................81
8.4.2. Registrations ......................................81
9. Security Considerations ........................................81
9.1. Attacks Based on File and Path Names ......................82
9.2. Attacks Based on Command, Code, or Query Injection ........82
9.3. Disclosure of Personal Information ........................83
9.4. Disclosure of Sensitive Information in URIs ...............83
9.5. Disclosure of Fragment after Redirects ....................84
9.6. Disclosure of Product Information .........................84
9.7. Browser Fingerprinting ....................................84
10. Acknowledgments ...............................................85
11. References ....................................................85
11.1. Normative References .....................................85
11.2. Informative References ...................................86
Appendix A. Differences between HTTP and MIME .....................89
A.1. MIME-Version ..............................................89
A.2. Conversion to Canonical Form ..............................89
A.3. Conversion of Date Formats ................................90
A.4. Conversion of Content-Encoding ............................90
A.5. Conversion of Content-Transfer-Encoding ...................90
A.6. MHTML and Line Length Limitations .........................90
Appendix B. Changes from RFC 2616 .................................91
Appendix C. Imported ABNF .........................................93
Appendix D. Collected ABNF ........................................94
Index .............................................................971. Introduction โจ
Okay so, every Hypertext Transfer Protocol (HTTP) message is either a request or a response ๐. A server sits there listening on a connection for a request, parses each message it gets, works out what the message means for the identified request target, and replies with one or more response messages ๐ซถ. A client builds request messages to say exactly what it wants, checks the responses to see whether those intentions actually got carried out โจ, and figures out how to read the results ๐ง . This document defines HTTP/1.1 request and response semantics in terms of the architecture defined in [RFC7230] ๐.
HTTP gives you a uniform interface for interacting with a resource (Section 2) ๐ฆ, no matter what type it is, what it's like, or how it's implemented ๐ . You get there by manipulating and transferring representations (Section 3) ๐ธ.
HTTP semantics cover the intentions behind each request method (Section 4) ๐ฅ, the extensions to those semantics that can be described in request header fields (Section 5) ๐, what status codes mean when they're indicating a machine-readable response (Section 6) ๐ค, and what the other control data and resource metadata given in response header fields mean (Section 7) ๐.
This document also defines representation metadata, which describes how a payload is meant to be interpreted by a recipient ๐ฆ, the request header fields that can influence content selection ๐, and the various selection algorithms that get collectively called "content negotiation" (Section 3.4) ๐.
1.1. Conformance and Error Handling ๐
okay so when this doc says "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", or "OPTIONAL", those words mean exactly what [RFC2119] says they mean ๐
the rules for conformance and for what to do when things go wrong are in Section 2.5 of [RFC7230] ๐ง
1.2. Syntax Notation ๐ธ
this spec writes its grammar in ABNF from [RFC5234] and adds a list extension from Section 7 of [RFC7230] ๐ the extension is the '#' operator, which makes comma-separated lists way more compact. it works kind of like how '*' means repetition. Appendix C lists the rules borrowed from other docs, and Appendix D has the full grammar with every list operator expanded into plain ABNF ๐งพ
the words "character", "character encoding scheme", "charset", and "protocol element" mean what [RFC6365] defines them to mean ๐ค
2. Resources โจ
the target of an HTTP request is called a "resource" ๐ฏ HTTP doesn't limit what a resource can be. it just gives you an interface you can use to interact with resources ๐ฆ each resource is identified by a Uniform Resource Identifier (URI), as described in Section 2.7 of [RFC7230] ๐
when a client builds an HTTP/1.1 request message, it sends the target URI in one of several forms, as defined in (Section 5.3 of [RFC7230]). when a server receives a request, it rebuilds an effective request URI for the target resource (Section 5.5 of [RFC7230]) ๐งฉ
one of HTTP's design goals is to keep resource identification separate from request semantics. that works because the request semantics live in the request method (Section 4) and a few request-modifying header fields (Section 5) ๐ if the method semantics conflict with any semantic implied by the URI itself, as described in Section 4.2.1, the method semantics win ๐
3. Representations โจ
okay this part is a big deal bestie ๐ a resource could be literally anything, and HTTP is kind of like a window you look through to see it and poke at it. you only get to do that by sending messages to some independent actor on the other side. so we need an abstraction that stands in for the current or desired state of that thing in our messages. that abstraction is called a representation [REST] ๐ช
for HTTP, a "representation" is information meant to reflect a past, current, or desired state of a resource. it's in a format that can be easily sent over the protocol, and it's made of a set of representation metadata plus a potentially unbounded stream of representation data ๐
an origin server might have multiple representations that all try to reflect the current state of a target resource, or it might be able to generate them. in that case, the origin server uses some algorithm to pick the one that's most applicable to a given request, usually through content negotiation ๐ง this "selected representation" supplies the data and metadata for evaluating conditional requests [RFC7232], and it's also what goes into the payload for 200 (OK) and 304 (Not Modified) responses to GET (Section 4.3.1) โจ
3.1. Representation Metadata ๐
representation header fields give you metadata about the representation ๐ when a message has a payload body, these fields tell you how to interpret the representation data inside that body. in a response to a HEAD request, they describe the representation data that would have been in the payload body if the same request had been a GET ๐
these header fields carry representation metadata:
+-------------------+-----------------+
| Header Field Name | Defined in... |
+-------------------+-----------------+
| Content-Type | Section 3.1.1.5 |
| Content-Encoding | Section 3.1.2.2 |
| Content-Language | Section 3.1.3.2 |
| Content-Location | Section 3.1.4.2 |
+-------------------+-----------------+3.1.1. Processing Representation Data ๐ง
3.1.1.1. Media Type ๐ฆ
HTTP uses Internet media types [RFC2046] in the Content-Type (Section 3.1.1.5) and Accept (Section 5.3.2) header fields. that gives it open, extensible data typing and type negotiation ๐ท a media type defines both a data format and the processing models that say how to handle that data in each context where it shows up ๐ ๏ธ
media-type = type "/" subtype *( OWS ";" OWS parameter )
type = token
subtype = tokenthe type/subtype MAY be followed by parameters written as name=value pairs ๐
parameter = token "=" ( token / quoted-string )the type, subtype, and parameter name tokens are case-insensitive ๐ parameter values might or might not be case-sensitive, depending on what the parameter name means. whether a parameter is there or not might matter for processing, depending on how the media type registry defines it ๐
a parameter value that matches the token production can be sent as a plain token or wrapped in a quoted-string, and both forms are equivalent ๐ all of these are equivalent, but the first one is the preferred style for consistency โจ
text/html;charset=utf-8
text/html;charset=UTF-8
Text/HTML;Charset="utf-8"
text/html; charset="utf-8"Internet media types ought to be registered with IANA following the procedures in [BCP13] ๐๏ธ
Note: unlike some similar constructs in other header fields, media type parameters do not allow whitespace (even "bad" whitespace) around the "=" character. ๐ซ
3.1.1.2. Charset ๐ค
HTTP uses charset names to indicate or negotiate the character encoding scheme of a textual representation [RFC6365]. a charset is identified by a case-insensitive token ๐
charset = tokencharset names ought to be registered in the IANA "Character Sets" registry (<http://www.iana.org/assignments/character-sets>) following the procedures in [RFC2978] ๐
3.1.1.3. Canonicalization and Text Defaults ๐งผ
Internet media types are registered with a canonical form so they can work across systems that use different native encodings ๐ representations selected or transferred via HTTP ought to be in canonical form too, for many of the same reasons MIME explains [RFC2045]. BUT email and the Web are different vibes. email is store-and-forward between peers, while HTTP is server-based information services, so the performance needs are really different ๐ฌ also, MIME's constraints for compatibility with older mail transfer protocols don't apply to HTTP (see Appendix A) ๐ โโ๏ธ
MIME's canonical form says media subtypes of the "text" type use CRLF as the text line break. HTTP allows plain CR or plain LF to represent a line break, as long as the line breaks are consistent across an entire representation ๐ซถ an HTTP sender MAY generate line breaks that are CRLF, bare CR, or bare LF, and a recipient MUST be able to parse all three ๐ฅ text media in HTTP also isn't limited to charsets that use octets 13 and 10 for CR and LF ๐ง
this line break flexibility only applies to text inside a representation that has a "text" media type. it does NOT apply to "multipart" types or to HTTP elements outside the payload body, like header fields ๐ง
if a representation is encoded with a content-coding, the underlying data ought to be in one of the forms defined above before it gets encoded ๐
3.1.1.4. Multipart Types ๐งฉ
MIME has a bunch of "multipart" types, which are encapsulations of one or more representations inside a single message body ๐ฆ they all share the same syntax from Section 5.1.1 of [RFC2046] and include a boundary parameter as part of the media type value. the message body is itself a protocol element, and a sender MUST generate only CRLF to represent line breaks between body parts ๐
HTTP message framing does NOT use the multipart boundary as an indicator of message body length. implementations might still use it when they generate or process the payload ๐ for example, "multipart/form-data" is often used to carry form data in a request, as described in [RFC2388]. the "multipart/byteranges" type is defined by this spec for use in some 206 (Partial Content) responses [RFC7233] ๐ธ
3.1.1.5. Content-Type ๐
the "Content-Type" header field tells you the media type of the associated representation. that's either the representation enclosed in the message payload or the selected representation, depending on the message semantics ๐ the media type defines the data format and how the recipient is meant to process that data, within the scope of the received message semantics, after any content codings listed in Content-Encoding are decoded ๐ง
Content-Type = media-typemedia types are defined in Section 3.1.1.1 โจ here's an example of the field:
Content-Type: text/html; charset=ISO-8859-4a sender that generates a message with a payload body SHOULD generate a Content-Type header field in that message, unless the intended media type of the enclosed representation is unknown to the sender ๐ if a Content-Type header field isn't there, the recipient MAY either assume a media type of "application/octet-stream" ([RFC2046], Section 4.5.1) or examine the data to figure out its type ๐
real talk, resource owners don't always configure their origin server to send the correct Content-Type for a representation. so some clients end up examining the payload's content and overriding the type they were given ๐ฌ clients that do this risk drawing wrong conclusions, which might expose extra security risks (e.g., "privilege escalation") ๐จ it's also impossible to know the sender's intent just by looking at the data format, because lots of data formats match multiple media types that only differ in how they're processed ๐ implementers are encouraged to provide a way to turn off this "content sniffing" when it happens ๐ก๏ธ
3.1.2. Encoding for Compression or Integrity ๐๏ธ
3.1.2.1. Content Codings ๐
content coding values indicate an encoding transformation that has been applied, or could be applied, to a representation ๐ they're mainly used so a representation can be compressed or otherwise transformed without losing the identity of its underlying media type or any information. often the representation gets stored in coded form, sent as is, and only decoded by the final recipient ๐ฆ
content-coding = tokenall content-coding values are case-insensitive and ought to be registered in the "HTTP Content Coding Registry", as defined in Section 8.4 ๐๏ธ they're used in the Accept-Encoding (Section 5.3.4) and Content-Encoding (Section 3.1.2.2) header fields ๐ซ
these content-coding values are defined by this specification:
compress(andx-compress): See Section 4.2.1 of [RFC7230]. ๐๏ธdeflate: See Section 4.2.2 of [RFC7230]. ๐ซงgzip(andx-gzip): See Section 4.2.3 of [RFC7230]. ๐ฆ
3.1.2.2. Content-Encoding โจ
okay so the Content-Encoding header field ๐ tells you which content codings have been layered onto the representation, on top of whatever is already part of the media type ๐. That means it tells you which decoding steps to run so you can get back to the media type named in the Content-Type header field. it's mainly there so a representation's data can get compressed without losing track of its underlying media type โจ
Content-Encoding = 1#content-codingan example looks like this ๐:
Content-Encoding: gzipif one or more encodings have been applied to a representation, the sender that applied them MUST generate a Content-Encoding header field that lists the content codings in the order they were applied ๐
. other header fields that this specification doesn't define can carry extra info about the encoding parameters ๐ง.
unlike Transfer-Encoding (Section 3.3.1 of [RFC7230]), the codings listed in Content-Encoding are a characteristic of the representation ๐ธ. the representation is defined in terms of its coded form, and all the other metadata about it describes that coded form too, unless the metadata definition says otherwise. usually the representation only gets decoded right before it's rendered or used in a similar way ๐.
if the media type has an inherent encoding, like a data format that's always compressed, then that encoding doesn't get restated in Content-Encoding, even if it happens to use the same algorithm as one of the content codings ๐. a content coding would only get listed if, for some bizarre reason, it's applied a second time to form the representation ๐. also, an origin server might publish the same data as several representations that differ only in whether the coding is defined as part of Content-Type or Content-Encoding ๐ฆ. that's because some user agents handle each response differently (for example, they might open a "Save as ..." dialog instead of automatically decompressing and rendering the content) ๐ญ.
an origin server MAY respond with a status code of 415 (Unsupported Media Type) if a representation in the request message has a content coding that isn't acceptable ๐ฅ.
3.1.3. Audience Language ๐
3.1.3.1. Language Tags
a language tag, as defined in [RFC5646], identifies a natural language that humans speak, write, or otherwise use to communicate information to other humans ๐ซถ. computer languages are explicitly excluded, sorry robots ๐ค.
HTTP uses language tags in the Accept-Language and Content-Language header fields โจ. Accept-Language uses the broader language-range production defined in Section 5.3.5, while Content-Language uses the language-tag production defined below ๐.
language-tag = <Language-Tag, see [RFC5646], Section 2.1>a language tag is a sequence of one or more case-insensitive subtags, separated by a hyphen character ("-", %x2D) ๐. most of the time, a tag has a primary language subtag that identifies a broad family of related languages (for example, "en" = English). that can be followed by a series of subtags that refine or narrow that language's range (for example, "en-CA" = the variety of English used in Canada) ๐. whitespace is not allowed inside a language tag ๐
. some example tags:
fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GNsee [RFC5646] for more info ๐.
3.1.3.2. Content-Language
the Content-Language header field describes the natural language(s) of the intended audience for the representation ๐ท. heads up, this might not match every language used inside the representation ๐.
Content-Language = 1#language-taglanguage tags are defined in Section 3.1.3.1 ๐
. the main purpose of Content-Language is to let a user identify and tell apart representations based on their own preferred language ๐ง. so if the content is only meant for a Danish-literate audience, the right field is:
Content-Language: daif no Content-Language is specified, the default is that the content is intended for all language audiences ๐. that could mean the sender doesn't think it's specific to any natural language, or that the sender doesn't know which language it's for ๐คทโโ๏ธ.
multiple languages MAY be listed for content intended for multiple audiences ๐. for example, a rendition of the "Treaty of Waitangi" presented at the same time in the original Mฤori and English versions would call for:
Content-Language: mi, enjust because a representation contains multiple languages doesn't mean it's meant for multiple linguistic audiences ๐. take "A First Lesson in Latin", a beginner's language primer. it's clearly meant for an English-literate audience, so itsContent-Languageshould properly only include"en"๐.
Content-Language MAY be applied to any media type. it's not limited to textual documents ๐ฆ.
3.1.4. Identification โจ
3.1.4.1. Identifying a Representation
when a complete or partial representation is transferred in a message payload, it's often useful for the sender to supply an identifier for a resource that corresponds to that representation, or for the recipient to figure one out ๐.
for a request message:
- if the request has a
Content-Locationheader field, then the sender is asserting that the payload is a representation of the resource identified by theContent-Locationfield-value. BUT that assertion can't be trusted unless it can be verified by other means (not defined by this specification) ๐. the info might still be handy for revision history links ๐ฐ๏ธ. - otherwise, the payload is unidentified ๐ซฅ.
for a response message, the following rules get applied in order until one matches ๐ :
- if the request method is GET or HEAD and the response status code is 200 (OK), 204 (No Content), 206 (Partial Content), or 304 (Not Modified), the payload is a representation of the resource identified by the effective request URI (Section 5.5 of [RFC7230]) ๐ฏ.
- if the request method is GET or HEAD and the response status code is 203 (Non-Authoritative Information), the payload is a potentially modified or enhanced representation of the target resource, as provided by an intermediary ๐ง.
- if the response has a
Content-Locationheader field and its field-value is a reference to the same URI as the effective request URI, the payload is a representation of the resource identified by the effective request URI ๐ธ. - if the response has a
Content-Locationheader field and its field-value is a reference to a URI different from the effective request URI, then the sender is asserting that the payload is a representation of the resource identified by theContent-Locationfield-value. again, that assertion can't be trusted unless it can be verified by other means (not defined by this specification) ๐ฉ. - otherwise, the payload is unidentified ๐ซฅ.
3.1.4.2. Content-Location โจ
okay so the Content-Location header field points at a URI that can be used as an identifier ๐ for one specific resource that matches the representation in this message's payload ๐. basically, if you sent a GET to that URI at the moment this message was made, a 200 (OK) response would come back with the exact same representation that's enclosed as the payload here ๐.
Content-Location = absolute-URI / partial-URIthe Content-Location value is not a replacement for the effective Request URI (Section 5.5 of [RFC7230]) ๐ โโ๏ธ. it's representation metadata ๐ง. it has the same syntax and semantics as the header field of the same name defined for MIME body parts in Section 4 of [RFC2557], but its appearance in an HTTP message has some special implications for HTTP recipients ๐.
if Content-Location shows up in a 2xx (Successful) response and its value refers (after conversion to absolute form) to a URI that is the same as the effective request URI, then the recipient MAY consider the payload to be a current representation of that resource at the time indicated by the message origination date ๐ซถ. for a GET (Section 4.3.1) or HEAD (Section 4.3.2) request, this is the same as the default semantics when the server doesn't provide a Content-Location at all ๐ . for a state-changing request like PUT (Section 4.3.4) or POST (Section 4.3.3), it means the server's response contains the new representation of that resource ๐ฅ. that's what separates it from representations that might only report about the action (e.g., "It worked!") ๐. this lets authoring apps update their local copies without needing a follow-up GET request, which is so efficient it's giving ๐คฉ.
if Content-Location shows up in a 2xx (Successful) response and its field-value refers to a URI that's different from the effective request URI, then the origin server is claiming that the URI identifies a different resource that corresponds to the enclosed representation ๐ฆ. that claim can only be trusted if both identifiers share the same resource owner, and HTTP can't figure that out programmatically ๐ฌ.
- for a response to a GET or HEAD request, this is a signal that the effective request URI refers to a resource that is subject to content negotiation, and the Content-Location field-value is a more specific identifier for the selected representation ๐ธ.
- for a 201 (Created) response to a state-changing method, a Content-Location field-value that's identical to the Location field-value means this payload is a current representation of the newly created resource ๐ง.
- otherwise, a Content-Location like that means this payload is a representation reporting on the requested action's status, and the same report is available (for future access with GET) at the given URI ๐. for example, a purchase made via a POST request might include a receipt document as the payload of the 200 (OK) response, and the Content-Location field-value gives you an identifier to grab a copy of that same receipt later ๐งพ.
a user agent that sends Content-Location in a request message is saying that its value refers to where the user agent originally got the content of the enclosed representation (before any changes that user agent made) ๐. basically, it's leaving a back link to the source of the original representation ๐โจ.
an origin server that receives a Content-Location field in a request message MUST treat that information as transitory request context, not as metadata to be saved word-for-word as part of the representation ๐ง . the origin server MAY use that context to guide how it processes the request, or save it for other uses, such as source links or versioning metadata ๐๏ธ. however, the origin server MUST NOT use that context information to alter the request semantics ๐ซ.
for example, if a client makes a PUT request on a negotiated resource and the origin server accepts that PUT (without redirection), then the new state of that resource is expected to be consistent with the one representation supplied in that PUT ๐. Content-Location can't be used as a form of reverse content selection identifier to update only one of the negotiated representations ๐ญ. if the user agent had wanted that behavior, it would have applied the PUT directly to the Content-Location URI ๐ฏ.
3.2. Representation Data ๐
the representation data associated with an HTTP message is either provided as the payload body of the message, or referred to by the message semantics and the effective request URI ๐ฆ. the representation data is in a format and encoding defined by the representation metadata header fields ๐ง.
the data type of the representation data is determined by the header fields Content-Type and Content-Encoding ๐ . these define a two-layer, ordered encoding model:
representation-data := Content-Encoding( Content-Type( bits ) )3.3. Payload Semantics ๐
some HTTP messages transfer a complete or partial representation as the message "payload" ๐. sometimes a payload only has the associated representation's header fields (e.g., responses to HEAD), or only some part(s) of the representation data (e.g., the 206 (Partial Content) status code) โ๏ธ.
the purpose of a payload in a request is defined by the method semantics ๐ง . like, a representation in the payload of a PUT request (Section 4.3.4) represents the desired state of the target resource if the request is successfully applied, whereas a representation in the payload of a POST request (Section 4.3.3) represents information to be processed by the target resource ๐ฅ.
in a response, the payload's purpose is defined by both the request method and the response status code ๐ซถ. for example, the payload of a 200 (OK) response to GET (Section 4.3.1) represents the current state of the target resource, as observed at the time of the message origination date (Section 7.1.1.2) ๐. meanwhile, the payload of that same status code in a response to POST might represent either the processing result or the new state of the target resource after the processing is applied ๐ฆ. response messages with an error status code usually contain a payload that represents the error condition, so it describes the error state and what next steps are suggested for fixing it ๐.
header fields that specifically describe the payload, rather than the associated representation, are called "payload header fields" ๐. those are defined in other parts of this specification because of how much they affect message parsing ๐ง.
+-------------------+----------------------------+
| Header Field Name | Defined in... |
+-------------------+----------------------------+
| Content-Length | Section 3.3.2 of [RFC7230] |
| Content-Range | Section 4.2 of [RFC7233] |
| Trailer | Section 4.4 of [RFC7230] |
| Transfer-Encoding | Section 3.3.1 of [RFC7230] |
+-------------------+----------------------------+3.4. Content Negotiation ๐ธ
when responses carry payload information, whether that's a success or an error, the origin server often has different ways of representing that info ๐. like, different formats, languages, or encodings ๐. different users or user agents might also have different capabilities, characteristics, or preferences that could change which representation is the best one to send ๐ป. so HTTP gives us mechanisms for content negotiation ๐ค.
this spec defines two patterns of content negotiation you can actually see in the protocol ๐. the first is "proactive," where the server picks the representation based on the user agent's stated preferences ๐ฏ. the second is "reactive" negotiation, where the server gives the user agent a list of representations to choose from ๐. other patterns exist too: "conditional content," where the representation has multiple parts that get selectively rendered based on user agent parameters; "active content," where the representation contains a script that makes additional (more specific) requests based on user agent characteristics; and "Transparent Content Negotiation" ([RFC2295]), where an intermediary does the selecting ๐ฆ. these patterns aren't mutually exclusive, and each one has its own trade-offs in applicability and practicality โ๏ธ.
โ ๏ธ bestie, note this one: in all cases, HTTP is not aware of the resource semantics ๐. how consistently an origin server responds to requests, over time and across the different dimensions of content negotiation, is determined entirely by whatever entity or algorithm picks or generates those responses ๐ฒ. so the "sameness" of a resource's observed representations over time is totally up to that entity. HTTP pays no attention to the man behind the curtain ๐งโโ๏ธโจ.
3.4.1. Proactive Negotiation ๐ฎ
when the user agent sends content negotiation preferences in a request to encourage an algorithm at the server to pick the preferred representation, that's called proactive negotiation (a.k.a., server-driven negotiation) ๐. the selection is based on the available representations for a response (the dimensions it might vary over, like language, content-coding, etc.) compared to various info in the request. that includes both the explicit negotiation fields of Section 5.3 and implicit characteristics, like the client's network address or parts of the User-Agent field ๐ต๏ธโโ๏ธ.
proactive negotiation is really useful when the algorithm for choosing among the available representations is hard to explain to a user agent, or when the server wants to send its "best guess" along with the first response ๐ฏ. the hope is to skip the round-trip delay of a follow-up request, if that "best guess" is good enough for the user ๐. to make the server's guess better, a user agent MAY send request header fields that describe its preferences ๐.
proactive negotiation has some serious downsides, though ๐ฌ:
- it's impossible for the server to accurately figure out what might be "best" for any given user, since that would require complete knowledge of both the user agent's capabilities and the intended use for the response (e.g., does the user want to view it on screen or print it on paper?) ๐จ๏ธ;
- having the user agent describe its capabilities in every request can be super inefficient (given that only a small percentage of responses have multiple representations) and a potential risk to the user's privacy ๐;
- it complicates the implementation of an origin server and the algorithms for generating responses to a request; and,
- it limits how reusable responses are for shared caching ๐ซ .
a user agent can't rely on proactive negotiation preferences being consistently honored ๐. the origin server might not implement proactive negotiation for the requested resource, or it might decide that sending a response that doesn't match the user agent's preferences is better than sending a 406 (Not Acceptable) response ๐คทโโ๏ธ.
a Vary header field (Section 7.1.4) is often sent in a response subject to proactive negotiation, to show which parts of the request info were used in the selection algorithm ๐งฉโจ.
3.4.2. Reactive Negotiation ๐ฆ
okay so reactive negotiation (aka agent-driven negotiation) ๐ง is where the user agent does the picking. After the origin server sends back an initial response with a list of resources for alternative representations, the user agent chooses the best one, whatever the status code is. If that first representation isn't good enough, the user agent can send a GET request to one or more of the alternative resources, picked based on the metadata in that list, to get a different form of the representation. The user agent might pick automatically, or the user might pick by hand from a generated (possibly hypertext) menu. ๐
Quick heads up: this is about representations of the response in general, not representations of the resource. The alternatives only count as representations of the target resource if the response carrying them has the semantics of being a representation of the target resource (like a 200 (OK) response to a GET request), or if it has the semantics of providing links to alternative representations for the target resource (like a 300 (Multiple Choices) response to a GET request). ๐
A server might decide not to send an initial representation at all, sending only the list of alternatives. That tells the client reactive negotiation is the preferred route. For example, the alternatives in 300 (Multiple Choices) and 406 (Not Acceptable) responses include info about the available representations, so the user or user agent can react and make a choice. โจ
Reactive negotiation shines when the response would vary over commonly used dimensions (like type, language, or encoding), when the origin server can't figure out a user agent's capabilities just by looking at the request, and generally when public caches are used to spread out server load and cut down on network usage. ๐
It does have downsides though. Sending a list of alternatives to the user agent can slow things down from the user's point of view if that list goes in the header section, and getting an alternate representation takes a second request. ๐ญ Also, this specification doesn't define a way to do automatic selection, but nothing stops that from being built later as an extension. ๐ฅ
4. Request Methods ๐
4.1. Overview ๐ธ
The request method token is the main source of request semantics. It tells the server why the client made this request and what the client expects as a successful result. ๐
The semantics of a request method can be further specialized by the semantics of some header fields in a request (Section 5), as long as those extra semantics don't conflict with the method. For example, a client can send conditional request header fields (Section 5.2) to make the requested action depend on the current state of the target resource ([RFC7232]). ๐
method = tokenHTTP was originally designed to work as an interface to distributed object systems. The request method was meant to apply semantics to a target resource, kind of like how calling a defined method on an identified object applies semantics. The method token is case-sensitive, because it might be used as a gateway to object-based systems that have case-sensitive method names. ๐ง
Standardized request methods in HTTP are different from distributed objects in that they aren't resource-specific. Uniform interfaces give better visibility and reuse in network-based systems [REST], so that's the vibe. โจ Once a standardized method is defined, it ought to have the same semantics no matter which resource it's applied to, though each resource decides for itself whether those semantics are implemented or allowed. ๐
This specification defines a bunch of standardized methods that are commonly used in HTTP, as the table below shows. By convention, standardized methods are written in all-uppercase US-ASCII letters. ๐ฆ
+---------+-------------------------------------------------+-------+
| Method | Description | Sec. |
+---------+-------------------------------------------------+-------+
| GET | Transfer a current representation of the target | 4.3.1 |
| | resource. | |
| HEAD | Same as GET, but only transfer the status line | 4.3.2 |
| | and header section. | |
| POST | Perform resource-specific processing on the | 4.3.3 |
| | request payload. | |
| PUT | Replace all current representations of the | 4.3.4 |
| | target resource with the request payload. | |
| DELETE | Remove all current representations of the | 4.3.5 |
| | target resource. | |
| CONNECT | Establish a tunnel to the server identified by | 4.3.6 |
| | the target resource. | |
| OPTIONS | Describe the communication options for the | 4.3.7 |
| | target resource. | |
| TRACE | Perform a message loop-back test along the path | 4.3.8 |
| | to the target resource. | |
+---------+-------------------------------------------------+-------+Okay, the big rule: all general-purpose servers MUST support the methods GET and HEAD. Every other method is OPTIONAL. ๐ฅ
Extra methods outside the scope of this specification have also been standardized for use in HTTP. All of those ought to be registered in the "Hypertext Transfer Protocol (HTTP) Method Registry" that IANA maintains, as defined in Section 8.1. ๐
The set of methods a target resource allows can be listed in an Allow header field (Section 7.4.1). But the allowed set can change over time, so keep that in mind. ๐ When an origin server gets a request method it doesn't recognize or hasn't implemented, it SHOULD respond with the 501 (Not Implemented) status code. When an origin server knows the method but it isn't allowed for that target resource, it SHOULD respond with the 405 (Method Not Allowed) status code. ๐
4.2. Common Method Properties ๐
4.2.1. Safe Methods ๐ธ
A request method counts as "safe" if its defined semantics are basically read-only. In other words, the client doesn't ask for, and doesn't expect, any state change on the origin server from using a safe method on a target resource. Also, using a safe method reasonably shouldn't cause any harm, loss of property, or unusual burden on the origin server. ๐ซถ
This definition doesn't stop an implementation from doing stuff that's potentially harmful, not totally read-only, or has side effects while handling a safe method. What matters is that the client didn't ask for that extra behavior, so it can't be blamed for it. ๐ For example, most servers add request info to access log files after every response, no matter the method. That still counts as safe, even though the log storage might fill up and crash the server. Same deal with a safe request started by clicking an ad on the Web. It often has the side effect of charging an advertising account. ๐ธ
Of the request methods defined in this specification, GET, HEAD, OPTIONS, and TRACE are defined to be safe. โจ
Why do we even split safe from unsafe? So automated retrieval processes (spiders) and cache performance optimization (pre-fetching) can run without worrying about causing harm. It also lets a user agent put sensible limits on automated use of unsafe methods when it's handling potentially untrusted content. ๐ก๏ธ
A user agent SHOULD distinguish between safe and unsafe methods when showing potential actions to a user, so the user can be warned about an unsafe action before it's requested. ๐จ
Here's the tricky part. When a resource is built so that parameters in the effective request URI pick the action, the resource owner is responsible for making sure that action matches the request method semantics. For example, it's pretty common for web-based content editing software to put actions in query parameters, like page?do=delete. If a resource like that is meant to perform an unsafe action, then the resource owner MUST disable or disallow that action when it's accessed with a safe request method. If they don't, automated processes doing a GET on every URI reference for link maintenance, pre-fetching, building a search index, and so on will cause unfortunate side effects. ๐ฑ
4.2.2. Idempotent Methods ๐
A request method counts as "idempotent" if sending multiple identical requests with it has the same intended effect on the server as sending a single one. Of the request methods defined in this specification, PUT, DELETE, and the safe request methods are idempotent. ๐
Just like with safe, the idempotent property only covers what the user actually asked for. A server is free to log each request separately, keep a revision control history, or add other non-idempotent side effects for each idempotent request. ๐
So why do we care about idempotent methods? Because the request can be repeated automatically if a communication failure happens before the client can read the server's response. For example, say a client sends a PUT request and the connection closes before any response comes back. The client can open a new connection and retry the idempotent request. It knows repeating the request will have the same intended effect, even if the original request worked, though the response might be different. ๐ง
4.2.3. Cacheable Methods ๐ง
Request methods can be defined as "cacheable" to say that responses to them are allowed to be stored for future reuse. For the specific requirements, check [RFC7234]. Generally, safe methods that don't depend on a current or authoritative response are defined as cacheable. This specification defines GET, HEAD, and POST as cacheable, though the overwhelming majority of cache implementations only support GET and HEAD. ๐
4.3. Method Definitions ๐
4.3.1. GET ๐ง
okay so GET is literally the main character of HTTP ๐ It requests transfer of a current selected representation for the target resource. It's the primary way to retrieve info and the focus of almost all the performance optimizations ๐ฅ So whenever people say they're retrieving some identifiable info over HTTP, they're basically talking about making a GET request ๐
ngl it's tempting to picture resource identifiers as remote file system pathnames, with representations being copies of the contents of those files ๐ธ And honestly, that IS how plenty of resources are built (see Section 9.1 for related security considerations ๐). But there are no such limits in practice! The HTTP interface for a resource could just as easily be a tree of content objects, a programmatic view on database records, or a gateway to other information systems ๐ฆ Even when the URI mapping is tied to a file system, an origin server might be set up to run the files with the request as input and send the output back as the representation, instead of transferring the files directly โจ Either way, only the origin server needs to know how each of its resource identifiers maps to an implementation, and how each implementation picks and sends a current representation of the target resource in a response to GET ๐
a client can make GET a "range request" ๐ asking for only some part(s) of the selected representation by sending a Range header field in the request ([RFC7233]).
โ ๏ธ bestie, a payload within a GET request message has no defined semantics! Sending a payload body on a GET request might cause some existing implementations to reject the request ๐
the response to a GET request is cacheable ๐ง A cache MAY use it to satisfy subsequent GET and HEAD requests, unless otherwise indicated by the Cache-Control header field (Section 5.2 of [RFC7234]) ๐
4.3.2. HEAD ๐ฆ
the HEAD method is identical to GET except that the server MUST NOT send a message body in the response (i.e., the response terminates at the end of the header section) ๐ โโ๏ธ The server SHOULD send the same header fields in response to a HEAD request as it would have sent if the request had been a GET, except that the payload header fields (Section 3.3) MAY be omitted ๐ซถ This method is super useful for grabbing metadata about the selected representation without transferring the representation data. It's often used for testing hypertext links for validity, accessibility, and recent modification ๐ very main-character behavior ๐
same deal as GET: a payload within a HEAD request message has no defined semantics, and sending a payload body on a HEAD request might cause some existing implementations to reject the request ๐ญ
the response to a HEAD request is cacheable too ๐ A cache MAY use it to satisfy subsequent HEAD requests, unless otherwise indicated by the Cache-Control header field (Section 5.2 of [RFC7234]). A HEAD response might also have an effect on previously cached responses to GET; see Section 4.3.5 of [RFC7234] โจ
4.3.3. POST ๐
okay the POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics ๐ธ It's the multitasker of methods! For example, POST is used for things like:
- Providing a block of data, such as the fields entered into an HTML form, to a data-handling process ๐
- Posting a message to a bulletin board, newsgroup, mailing list, blog, or similar group of articles ๐ฃ
- Creating a new resource that has yet to be identified by the origin server; and ๐ง
- Appending data to a resource's existing representation(s) ๐
an origin server tells you what the response means by picking an appropriate status code based on the result of processing the POST request ๐ Almost all of the status codes defined by this specification might be received in a response to POST. The exceptions are 206 (Partial Content), 304 (Not Modified), and 416 (Range Not Satisfiable) ๐
if one or more resources got created on the origin server as a result of successfully processing a POST request, the origin server SHOULD send a 201 (Created) response ๐
That response contains a Location header field that provides an identifier for the primary resource created (Section 7.1.2), plus a representation that describes the status of the request while referring to the new resource(s) โจ
responses to POST requests are only cacheable when they include explicit freshness information (see Section 4.2.1 of [RFC7234]) ๐ง Honestly, POST caching isn't widely implemented, though ๐
For cases where an origin server wants the client to be able to cache the result of a POST in a way that can be reused by a later GET, the origin server MAY send a 200 (OK) response containing the result, along with a Content-Location header field that has the same value as the POST's effective request URI (Section 3.1.4.2) ๐ซถ
last but not least, if the result of processing a POST would be equivalent to a representation of an existing resource, an origin server MAY redirect the user agent to that resource by sending a 303 (See Other) response with the existing resource's identifier in the Location field ๐ฆ This gives the user agent a resource identifier and transfers the representation via a method that's more amenable to shared caching ๐ The tradeoff? An extra request if the user agent doesn't already have the representation cached ๐ฅบ
4.3.4. PUT โจ
okay bestie, PUT is the method where the client says "make this resource look like THIS," and the request payload is the new state ๐
. If it works, a GET on that same target afterwards should give back an equivalent representation in a 200 (OK) response ๐ฆ. BUT ngl there's no promise that it sticks, because other user agents could be poking the same resource at the same time, or the origin server could be doing its own dynamic stuff before your GET shows up ๐. So a successful response only means your intent was achieved at the moment the origin server processed it. That's it, that's the whole vibe ๐ธ
If the target resource doesn't have a current representation and the PUT creates one, the origin server MUST tell the user agent with a 201 (Created) response ๐. If the resource already has a current representation and it gets successfully changed to match the enclosed one, the origin server MUST send either a 200 (OK) or a 204 (No Content) response to say the request finished โจ
The origin server SHOULD ignore unrecognized header fields it gets in a PUT request, which means it shouldn't save them as part of the resource state ๐ง
The origin server SHOULD also check that the PUT representation matches any constraints it has for the target resource that can't or won't be changed by the PUT. This matters a LOT when the server uses internal config tied to the URI to set representation metadata on GET responses ๐ญ If the PUT representation doesn't match the target resource, the origin server SHOULD either make them match, by transforming the representation or changing the resource config, or send back an error message with enough info to explain why the representation is unsuitable ๐ The 409 (Conflict) or 415 (Unsupported Media Type) status codes are suggested, and the 415 one is specifically for constraints on Content-Type values ๐
For example, say the target resource is always set to Content-Type "text/html" and the representation being PUT is "image/jpeg". The origin server ought to do one of these:
- reconfigure the target resource to reflect the new media type;
- transform the PUT representation to a format that matches the resource before saving it as the new resource state; or
- reject the request with a
415 (Unsupported Media Type)response saying the target resource is limited to"text/html", maybe with a link to a different resource that would be a better target for the new representation ๐
HTTP doesn't define exactly how a PUT changes the state of an origin server, beyond what's captured by the user agent's intent and the semantics of the server's response ๐คทโโ๏ธ It also doesn't define what a resource is, in any sense of the word, beyond the interface HTTP gives you. It doesn't say how resource state is "stored," how that storage changes when resource state changes, or how the origin server turns resource state into representations. Basically, all the implementation details behind the resource interface are intentionally hidden by the server ๐ซถ
An origin server MUST NOT send a validator header field (Section 7.2), like an ETag or Last-Modified field, in a successful response to PUT. The only exception is when the request's representation data was saved without any transformation applied to the body (so the new resource representation is identical to what came in the PUT), AND the validator field value reflects that new representation ๐ฅ Why does this matter? It lets the user agent know that the body it already has in memory is still current after the PUT, so it doesn't need to fetch it again, and the new validators can be used for future conditional requests to prevent accidental overwrites (Section 5.2) โจ
Here's the big difference between POST and PUT: it's all about the intent behind the enclosed representation ๐ For POST, the target resource is meant to handle the enclosed representation according to its own semantics. For PUT, the enclosed representation is defined as replacing the state of the target resource. So PUT is idempotent and visible to intermediaries, even though only the origin server knows the exact effect ๐
Proper interpretation of a PUT request assumes the user agent knows which target resource it wants. So if a service picks a proper URI for the client after getting a state-changing request, that service SHOULD be built using POST instead of PUT ๐ฆ And if the origin server won't make the requested PUT change to the target resource and wants it applied to a different resource instead (like when the resource has moved to a different URI), the origin server MUST send an appropriate 3xx (Redirection) response. The user agent MAY then decide for itself whether to follow the redirect ๐ธ
A PUT on the target resource can also have side effects on other resources ๐ Like, an article might have a URI for "the current version" (a resource) that's separate from the URIs for each particular version (different resources that at one point shared the same state as the current version). A successful PUT on the "current version" URI might create a brand new version resource on top of changing the target's state, and it might also add links between the related resources ๐ง
An origin server that allows PUT on a given target resource MUST send a 400 (Bad Request) response to any PUT request that contains a Content-Range header field (Section 4.2 of [RFC7233]). Why? The payload is probably partial content that got mistakenly PUT as a full representation ๐ญ Partial updates ARE possible, though. You can target a separately identified resource whose state overlaps a portion of the bigger resource, or use a different method that's specifically defined for partial updates, like the PATCH method defined in [RFC5789] ๐
Responses to PUT are not cacheable. And if a successful PUT request goes through a cache that has one or more stored responses for the effective request URI, those stored responses get invalidated (see Section 4.4 of [RFC7234]) ๐ซง
4.3.5. DELETE โจ
DELETE is when the client asks the origin server to remove the association between the target resource and its current functionality ๐ It's kind of like the rm command in UNIX: it's a deletion operation on the server's URI mapping, not a promise that the info that used to be there gets deleted ๐
If the target resource has one or more current representations, the origin server might or might not destroy them, and the storage might or might not get reclaimed. It all depends on what the resource is and how the origin server implements it, which is beyond the scope of this spec ๐ Similarly, other implementation stuff might need to be deactivated or archived after a DELETE, like database or gateway connections. In general, the origin server is assumed to only allow DELETE on resources it has a set mechanism for deleting ๐
Honestly, very few resources allow DELETE. Its main use is in remote authoring environments, where the user has some say over what it does ๐ For example, a resource that was made with a PUT request, or one identified by the Location header field after a 201 (Created) response to a POST request, might allow a matching DELETE to undo those actions โจ Custom user agents that do authoring stuff, like revision control clients using HTTP for remote operations, might use DELETE too, assuming the server's URI space has been set up to match a version repository ๐ซถ
If a DELETE is successfully applied, the origin server SHOULD send:
- a
202 (Accepted)status code if the action will probably succeed but hasn't been enacted yet; - a
204 (No Content)status code if the action has been enacted and there's no further info to share; or - a
200 (OK)status code if the action has been enacted and the response includes a representation describing the status ๐
A payload inside a DELETE request message has no defined semantics. Sending a payload body on a DELETE request might make some existing implementations reject the request, so be careful out there ๐โ ๏ธ
โ ๏ธ bestie, a DELETE payload has NO defined meaning, and some implementations will just reject your request if you send one ๐ญ
Responses to DELETE are not cacheable. And if a DELETE request goes through a cache that has one or more stored responses for the effective request URI, those stored responses get invalidated (see Section 4.4 of [RFC7234]) ๐ฆ
4.3.6. CONNECT ๐ฆ
okay so CONNECT is giving "build me a secret tunnel" ๐๐. It asks the recipient to set up a tunnel to the destination origin server named in the request-target. If that works, the recipient then restricts itself to blindly forwarding packets in both directions until the tunnel is closed. Tunnels are super popular for making an end-to-end virtual connection through one or more proxies, and then you can lock the whole thing down with TLS (Transport Layer Security, [RFC5246]) ๐โจ
CONNECT is intended only for requests to a proxy ๐. An origin server that gets a CONNECT request for itself MAY respond with a 2xx (Successful) status code to say the connection is established. ngl, most origin servers just don't implement CONNECT ๐.
A client sending a CONNECT request MUST send the authority form of request-target (Section 5.3 of [RFC7230]). That means the request-target is only the host name and port number of the tunnel destination, separated by a colon ๐. For example:
CONNECT server.example.com:80 HTTP/1.1
Host: server.example.com:80The recipient proxy can set up the tunnel in one of two ways. It can connect directly to the request-target, or, if it's configured to use another proxy, it can forward the CONNECT request to the next inbound proxy ๐ง. Any 2xx (Successful) response means the sender (and all inbound proxies) switch to tunnel mode right after the blank line that ends the response's header section. Any data received after that blank line comes from the server named in the request-target. Any other response means the tunnel hasn't formed yet, and the connection is still governed by HTTP ๐ธ.
A tunnel gets closed when a tunnel intermediary notices that either side has closed its connection. Then the intermediary MUST attempt to send any outstanding data that came from the closed side to the other side, close both connections, and then discard any leftover data that never got delivered ๐ซถ.
Proxy authentication might be used to establish the authority to create a tunnel. For example:
CONNECT server.example.com:80 HTTP/1.1
Host: server.example.com:80
Proxy-Authorization: basic aGVsbG86d29ybGQ=โ ๏ธ bestie, there are serious risks with setting up tunnels to random servers ๐ญ. This is especially true when the destination is a well-known or reserved TCP port that isn't meant for Web traffic. For example, a CONNECT to a request-target of "example.com:25" would ask the proxy to connect to the reserved port for SMTP traffic. If that's allowed, it could trick the proxy into relaying spam email ๐๐ง.
Proxies that support CONNECT SHOULD restrict its use to a limited set of known ports or a configurable whitelist of safe request targets ๐.
A server MUST NOT send any Transfer-Encoding or Content-Length header fields in a 2xx (Successful) response to CONNECT. A client MUST ignore any Content-Length or Transfer-Encoding header fields it receives in a successful response to CONNECT ๐ โโ๏ธ.
A payload within a CONNECT request message has no defined semantics. Sending a payload body on a CONNECT request might cause some existing implementations to reject the request ๐.
Responses to the CONNECT method are not cacheable ๐ซ.
4.3.7. OPTIONS ๐
The OPTIONS method asks for information about the communication options available for the target resource. That can be at the origin server or at an intervening intermediary ๐. It lets a client figure out the options and/or requirements tied to a resource, or what a server is capable of, without implying any resource action. Very chill, very informative ๐.
An OPTIONS request with an asterisk ("") as the request-target (Section 5.3 of [RFC7230]) applies to the server in general, not to one specific resource. A server's communication options usually depend on the resource, so the "" request is only really useful as a "ping" or "no-op" type of method. It does nothing except let the client test the server's capabilities. For example, this can be used to test a proxy for HTTP/1.1 conformance (or lack thereof) ๐งช.
If the request-target is not an asterisk, the OPTIONS request applies to the options that are available when communicating with the target resource ๐ฏ.
A server generating a successful response to OPTIONS SHOULD send any header fields that might indicate optional features it implements and that apply to the target resource (e.g., Allow). That includes potential extensions not defined by this specification โจ. The response payload, if there is one, might also describe the communication options in a machine or human-readable representation. This specification doesn't define a standard format for that representation, but future extensions to HTTP might ๐งโโ๏ธ. A server MUST generate a Content-Length field with a value of "0" if no payload body is going to be sent in the response ๐.
A client MAY send a Max-Forwards header field in an OPTIONS request to target a specific recipient in the request chain (see Section 5.1.2) ๐ฆ. A proxy MUST NOT generate a Max-Forwards header field while forwarding a request, unless that request was received with a Max-Forwards field ๐ โโ๏ธ.
A client that generates an OPTIONS request containing a payload body MUST send a valid Content-Type header field describing the representation media type. This specification doesn't define any use for that payload, but future extensions to HTTP might use the OPTIONS body to make more detailed queries about the target resource ๐ฎ.
Responses to the OPTIONS method are not cacheable ๐ซ.
4.3.8. TRACE ๐
The TRACE method asks for a remote, application-level loop-back of the request message. It's like the server holding up a mirror ๐ชโจ. The final recipient of the request SHOULD reflect the message it received back to the client, minus some fields described below. It does this as the message body of a 200 (OK) response with a Content-Type of "message/http" (Section 8.3.1 of [RFC7230]). The final recipient is either the origin server or the first server to receive a Max-Forwards value of zero (0) in the request (Section 5.1.2) ๐ .
A client MUST NOT generate header fields in a TRACE request that contain sensitive data which the response might disclose. For example, it would be foolish for a user agent to send stored user credentials [RFC7235] or cookies [RFC6265] in a TRACE request ๐. The final recipient of the request SHOULD exclude any request header fields that are likely to contain sensitive data when it generates the response body ๐.
TRACE lets the client see what's being received at the other end of the request chain, and use that data for testing or diagnostics ๐ฉบ. The value of the Via header field (Section 5.7.1 of [RFC7230]) is especially interesting, since it acts as a trace of the request chain ๐บ๏ธ. Using the Max-Forwards header field lets the client limit the length of the request chain. That's useful for testing a chain of proxies that might forward messages in an infinite loop ๐๐.
A client MUST NOT send a message body in a TRACE request ๐ โโ๏ธ.
Responses to the TRACE method are not cacheable ๐ซ.
5. Request Header Fields ๐
A client sends request header fields to give more information about the request context. They can make the request conditional on the target resource state, suggest preferred formats for the response, supply authentication credentials, or change the expected request processing. These fields act as request modifiers, kinda like the parameters on a programming language method invocation ๐โจ.
5.1. Controls ๐๏ธ
Controls are request header fields that direct specific handling of the request ๐ง .
+-------------------+--------------------------+
| Header Field Name | Defined in... |
+-------------------+--------------------------+
| Cache-Control | Section 5.2 of [RFC7234] |
| Expect | Section 5.1.1 |
| Host | Section 5.4 of [RFC7230] |
| Max-Forwards | Section 5.1.2 |
| Pragma | Section 5.4 of [RFC7234] |
| Range | Section 3.1 of [RFC7233] |
| TE | Section 4.3 of [RFC7230] |
+-------------------+--------------------------+5.1.1. Expect โจ
okay so the Expect header field in a request is basically the client going "hey server, before I send you this, make sure you can handle these vibes" ๐ The only expectation defined in this spec is 100-continue, no cap.
Expect = "100-continue"The Expect field-value is case-insensitive ๐
If a server gets an Expect field-value that isn't 100-continue, it MAY respond with a 417 (Expectation Failed) status code to say the unexpected expectation can't be met. ๐
A 100-continue expectation tells the recipients that the client is about to send a (probably huge) message body and would like a 100 (Continue) interim response first, but only if the request-line and header fields aren't already enough to get an instant success, redirect, or error response. โจ This lets the client check that it's worth sending the body before it actually sends it. It's super efficient when the body is massive, or when the client expects an error, like when it's sending a state-changing method for the first time without previously verified authentication credentials. ๐ซถ
Here's an example of a request that starts like this:
PUT /somewhere/fun HTTP/1.1
Host: origin.example.com
Content-Type: video/h264
Content-Length: 1234567890987
Expect: 100-continueWith that, the origin server can instantly reply with an error like 401 (Unauthorized) or 405 (Method Not Allowed) ๐ โโ๏ธ before the client starts flooding the pipes with a pointless data transfer. ๐ญ
Requirements for clients:
- A client MUST NOT generate a 100-continue expectation in a request that does not include a message body.
- A client that will wait for a 100 (Continue) response before sending the request message body MUST send an Expect header field containing a 100-continue expectation.
- A client that sends a 100-continue expectation is not required to wait for any specific length of time; such a client MAY proceed to send the message body even if it has not yet received a response. Furthermore, since 100 (Continue) responses cannot be sent through an HTTP/1.0 intermediary, such a client SHOULD NOT wait for an indefinite period before sending the message body. ๐ธ
- A client that receives a 417 (Expectation Failed) status code in response to a request containing a 100-continue expectation SHOULD repeat that request without a 100-continue expectation, since the 417 response merely indicates that the response chain does not support expectations (e.g., it passes through an HTTP/1.0 server). ๐ฆ
Requirements for servers:
- A server that receives a 100-continue expectation in an HTTP/1.0 request MUST ignore that expectation.
- A server MAY omit sending a 100 (Continue) response if it has already received some or all of the message body for the corresponding request, or if the framing indicates that there is no message body. ๐
- A server that sends a 100 (Continue) response MUST ultimately send a final status code, once the message body is received and processed, unless the connection is closed prematurely. ๐
- A server that responds with a final status code before reading the entire message body SHOULD indicate in that response whether it intends to close the connection or continue reading and discarding the request message (see Section 6.6 of [RFC7230]). ๐
An origin server MUST, upon receiving an HTTP/1.1 (or later) request-line and a complete header section that contains a 100-continue expectation and indicates a request message body will follow, either send an immediate response with a final status code, if that status can be determined by examining just the request-line and header fields, or send an immediate 100 (Continue) response to encourage the client to send the request's message body. The origin server MUST NOT wait for the message body before sending the 100 (Continue) response. โญ
A proxy MUST, upon receiving an HTTP/1.1 (or later) request-line and a complete header section that contains a 100-continue expectation and indicates a request message body will follow, either send an immediate response with a final status code, if that status can be determined by examining just the request-line and header fields, or begin forwarding the request toward the origin server by sending a corresponding request-line and header section to the next inbound server. If the proxy believes (from configuration or past interaction) that the next inbound server only supports HTTP/1.0, the proxy MAY generate an immediate 100 (Continue) response to encourage the client to begin sending the message body. ๐ง
Note: The Expect header field was added after the original publication of HTTP/1.1 [RFC2068] as both the means to request an interim 100 (Continue) response and the general mechanism for indicating must-understand extensions. However, the extension mechanism has not been used by clients and the must-understand requirements have not been implemented by many servers, rendering the extension mechanism useless. This specification has removed the extension mechanism in order to simplify the definition and processing of 100-continue. ๐
5.1.2. Max-Forwards
okay the Max-Forwards header field is the tool for the TRACE (Section 4.3.8) and OPTIONS (Section 4.3.7) request methods, and it limits how many times proxies can forward the request. ๐ It's seriously useful when a client is trying to trace a request that looks like it's failing or looping somewhere mid-chain. ๐
Max-Forwards = 1*DIGITThe Max-Forwards value is a decimal integer that tells you how many more times this request message can be forwarded. ๐ข
Each intermediary that gets a TRACE or OPTIONS request containing a Max-Forwards header field MUST check and update its value before forwarding the request. If the received value is zero (0), the intermediary MUST NOT forward the request; instead, the intermediary MUST respond as the final recipient. If the received Max-Forwards value is greater than zero, the intermediary MUST generate an updated Max-Forwards field in the forwarded message with a field-value that is the lesser of a) the received value decremented by one (1) or b) the recipient's maximum supported value for Max-Forwards. ๐งฎ
A recipient MAY ignore a Max-Forwards header field received with any other request methods. ๐ซ
5.2. Conditionals
The HTTP conditional request header fields [RFC7232] let a client put a precondition on the state of the target resource ๐ So if the precondition evaluates to false, the action that goes with the method semantics won't get applied. Each precondition defined here compares a set of validators from earlier representations of the target resource against the current validators for the selected representation (Section 7.2). ๐ So these preconditions basically check whether the target resource has changed since the state the client last knew about. The result depends on the method semantics and which conditional is used, as defined in Section 5 of [RFC7232]. โจ
+---------------------+--------------------------+
| Header Field Name | Defined in... |
+---------------------+--------------------------+
| If-Match | Section 3.1 of [RFC7232] |
| If-None-Match | Section 3.2 of [RFC7232] |
| If-Modified-Since | Section 3.3 of [RFC7232] |
| If-Unmodified-Since | Section 3.4 of [RFC7232] |
| If-Range | Section 3.2 of [RFC7233] |
+---------------------+--------------------------+5.3. Content Negotiation
These request header fields are sent by a user agent to do proactive negotiation of the response content, as defined in Section 3.4.1. ๐ The preferences sent in these fields apply to any content in the response, including representations of the target resource, representations of error or processing status, and potentially even the miscellaneous text strings that might show up within the protocol. ๐คฏ
+-------------------+---------------+
| Header Field Name | Defined in... |
+-------------------+---------------+
| Accept | Section 5.3.2 |
| Accept-Charset | Section 5.3.3 |
| Accept-Encoding | Section 5.3.4 |
| Accept-Language | Section 5.3.5 |
+-------------------+---------------+5.3.1. Quality Values
Lots of the request header fields for proactive negotiation share a parameter called "q" (case-insensitive), which gives a relative "weight" to the preference for that kind of content. ๐ This weight is called a "quality value" (or "qvalue"), because servers often use the same parameter name in their configs to weight the relative quality of the different representations they could pick for a resource. ๐ฆ
The weight is normalized to a real number from 0 through 1, where 0.001 is the least preferred and 1 is the most preferred. A value of 0 means "not acceptable". ๐ โโ๏ธ If there's no "q" parameter, the default weight is 1. ๐
weight = OWS ";" OWS "q=" qvalue
qvalue = ( "0" [ "." 0*3DIGIT ] )
/ ( "1" [ "." 0*3("0") ] )A sender of qvalue MUST NOT generate more than three digits after the decimal point. User configuration of these values ought to be limited in the same fashion. ๐ฅ
5.3.2. Accept โจ
okay so the Accept header is how a user agent tells the server which response media types it's willing to take ๐
it can even say "I only want this small set of types," like when it's asking for an in-line image ๐ผ๏ธ
Accept = #( media-range [ accept-params ] )
media-range = ( "*/*"
/ ( type "/" "*" )
/ ( type "/" subtype )
) *( OWS ";" OWS parameter )
accept-params = weight *( accept-ext )
accept-ext = OWS ";" OWS token [ "=" ( token / quoted-string ) ]the asterisk * is the group-chat-friendly way to say "a whole bunch of stuff" ๐ */* means every media type, and type/* means every subtype of that one type ๐ฆ the media-range can also carry media type parameters that only apply to that range ๐
each media-range can be followed by zero or more media type parameters (like charset), then an optional q parameter for the relative weight from Section 5.3.1, and then zero or more extension parameters ๐ the q is literally required if any accept-ext stuff is there, because it's the separator between the two parameter sets. no q, no extensions, bestie ๐
โโ๏ธ
Note: Using q as the name that separates media type parameters from Accept extension parameters is due to historical practice ๐ฐ๏ธ Yes, this means no media type parameter named "q" can be used with a media range. But that's believed to be unlikely, since there are no "q" parameters in the IANA media type registry and hardly anyone uses media type parameters in Accept anyway ๐ Future media types are discouraged from registering any parameter named "q" ๐ซ
so this example:
Accept: audio/*; q=0.2, audio/basicbasically means "I prefer audio/basic, but send me any audio type if it's the best available after an 80% markdown in quality" ๐งโจ
if a request has no Accept header at all, that implies the user agent will take any media type in the response ๐ but if the header IS there and none of the available representations have an acceptable media type, the origin server gets to pick: it can honor the header by sending a 406 (Not Acceptable) response, or ignore the header and treat the response as if it's not subject to content negotiation at all ๐ซถ
a more elaborate one:
Accept: text/plain; q=0.5, text/html,
text/x-dvi; q=0.8, text/x-cthe vibe here is "text/html and text/x-c are the equally preferred types, but if those don't exist, send text/x-dvi, and if that's not there either, send text/plain" ๐ธ
media ranges can get overridden by more specific media ranges or specific media types ๐ if more than one range applies to a type, the most specific one wins. for example:
Accept: text/*, text/plain, text/plain;format=flowed, */*has this precedence, highest first:
text/plain;format=flowedtext/plaintext/**/*
the media type quality factor for a given type comes from whichever matching media range has the highest precedence ๐ฅ like this one:
Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1,
text/html;level=2;q=0.4, */*;q=0.5would give these values:
+-------------------+---------------+
| Media Type | Quality Value |
+-------------------+---------------+
| text/html;level=1 | 1 |
| text/html | 0.7 |
| text/plain | 0.3 |
| image/jpeg | 0.5 |
| text/html;level=2 | 0.4 |
| text/html;level=3 | 0.7 |
+-------------------+---------------+Note: A user agent might come with a default set of quality values for certain media ranges ๐ But unless it's a closed system that can't talk to other rendering agents, that default set ought to be configurable by the user ๐ฅฐ
5.3.3. Accept-Charset ๐ค
the Accept-Charset header is how a user agent says which charsets it's cool with in textual response content ๐ it's especially useful for agents that can handle fancier or special-purpose charsets, since it lets them signal that to a server that can actually represent stuff in those charsets โจ
Accept-Charset = 1#( ( charset / "*" ) [ weight ] )charset names are defined in Section 3.1.1.2 ๐ A user agent MAY attach a quality value to each charset to show how much it prefers that one, as defined in Section 5.3.1. for example:
Accept-Charset: iso-8859-5, unicode-1-1;q=0.8the special * value matches every charset that isn't mentioned somewhere else in the Accept-Charset field ๐ and if there's no * in there, then any charset not explicitly listed is considered "not acceptable" to the client ๐
โโ๏ธ
no Accept-Charset header in a request implies the user agent will take any charset back ๐ Most general-purpose user agents don't send this header unless someone specifically configures them to, because a detailed charset list makes it easier for a server to identify a specific person from the request's characteristics (Section 9.7) ๐ privacy, bestie ๐
if an Accept-Charset header is in the request and none of the available representations has a charset that's listed as acceptable, the origin server can either honor the header by sending a 406 (Not Acceptable) response, or disregard it by treating the resource as if it isn't subject to content negotiation ๐ซถ
5.3.4. Accept-Encoding ๐๏ธ
the Accept-Encoding header lets user agents say which response content-codings (Section 3.1.2.1) they're happy to receive ๐ the identity token is the synonym for "no encoding," so it can say when no encoding is preferred ๐
Accept-Encoding = #( codings [ weight ] )
codings = content-coding / "identity" / "*"each codings value MAY get a quality value showing how much the user agent prefers that encoding, as defined in Section 5.3.1 โจ the * in an Accept-Encoding field matches any available content-coding that isn't explicitly listed in the header ๐ธ
some examples:
Accept-Encoding: compress, gzip
Accept-Encoding:
Accept-Encoding: *
Accept-Encoding: compress;q=0.5, gzip;q=1.0
Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0no Accept-Encoding header means the user agent has no preferences about content-codings ๐คทโโ๏ธ That lets the server use any content-coding in the response, but it does NOT mean the user agent can actually process every encoding correctly ๐ญ read the room!
a server checks whether a content-coding for a given representation is acceptable using these rules, in order:
- If no Accept-Encoding field is in the request, any content-coding is considered acceptable by the user agent. ๐
- If the representation has no content-coding, then it is acceptable by default unless specifically excluded by the Accept-Encoding field stating either "identity;q=0" or "*;q=0" without a more specific entry for "identity". ๐
- If the representation's content-coding is one of the content-codings listed in the Accept-Encoding field, then it is acceptable unless it is accompanied by a qvalue of 0. (As defined in Section 5.3.1, a qvalue of 0 means "not acceptable".) ๐ซ
- If multiple content-codings are acceptable, then the acceptable content-coding with the highest non-zero qvalue is preferred. ๐
an Accept-Encoding header with a combined field-value that's empty means the user agent doesn't want any content-coding in the response ๐ซง And if an Accept-Encoding header is in the request and none of the available representations has a content-coding that's listed as acceptable, the origin server SHOULD send a response without any content-coding ๐
Note: Most HTTP/1.0 applications don't recognize or obey qvalues attached to content-codings ๐ฌ So qvalues might not work, and they are not permitted with x-gzip or x-compress ๐ โโ๏ธ
5.3.5. Accept-Language โจ
okay so the Accept-Language header field is how a user agent tells the server which natural languages it'd prefer the response in ๐ language tags are defined in Section 3.1.3.1, btw
Accept-Language = 1#( language-range [ weight ] )
language-range =
<language-range, see [RFC4647], Section 2.1>each language-range can get its own quality value, which is basically an estimate of how much the user wants that language, as defined in Section 5.3.1. like:
Accept-Language: da, en-gb;q=0.8, en;q=0.7this one literally means: "I prefer Danish, but will accept British English and other types of English" ๐ฉ๐ฐ๐ซ
if a request has no Accept-Language at all, the server assumes the user agent will take any language ๐ซถ but if the header IS there and none of the available representations have a matching language tag, the origin server has two options. it can ignore the header and treat the response like it's not subject to content negotiation, OR it can honor the header and send a 406 (Not Acceptable) response. ngl the second one is not encouraged, because it can stop users from getting content they could actually use, like with translation software ๐
one thing to know: some recipients read the order of the language tags as a priority list, especially when tags have the same quality value (no value is the same as q=1). but that behavior cannot be relied upon ๐
โโ๏ธ for consistency and better interop, a lot of user agents give each language tag its own unique quality value AND list them in order of decreasing quality. more on language priority lists is in Section 2.3 of [RFC4647] ๐
for matching, Section 3 of [RFC4647] has a few matching schemes, and implementations can pick whichever one fits their needs best ๐ the "Basic Filtering" scheme ([RFC4647], Section 3.3.1) is the exact same matching scheme that HTTP used to define in Section 14.4 of [RFC2616] ๐
sending your full linguistic preferences in every single request might be a privacy no-no for the user (Section 9.7) ๐
and bc intelligibility depends so much on the individual person, user agents need to let the user control the linguistic preference. they can do that through the user agent's own configuration, or by defaulting to a system setting the user can control ๐ซถ a user agent that doesn't give the user that control MUST NOT send an Accept-Language header field. no exceptions, periodt ๐
Note: user agents ought to give users guidance when they set a preference, bc most people don't know the details of language matching. like, users might assume that picking "en-gb" means they'll get ANY kind of English doc if British English isn't available. in that case, a user agent might suggest adding "en" to the list for better matching behavior ๐ง โจ
5.4. Authentication Credentials ๐
two header fields carry authentication credentials, as defined in [RFC7235]. also, a bunch of custom user auth mechanisms use the Cookie header field for this, as defined in [RFC6265] ๐ช
+---------------------+--------------------------+
| Header Field Name | Defined in... |
+---------------------+--------------------------+
| Authorization | Section 4.2 of [RFC7235] |
| Proxy-Authorization | Section 4.4 of [RFC7235] |
+---------------------+--------------------------+5.5. Request Context ๐ธ
these request header fields give extra info about the request context, like the user, the user agent, and the resource behind the request ๐ง
+-------------------+---------------+
| Header Field Name | Defined in... |
+-------------------+---------------+
| From | Section 5.5.1 |
| Referer | Section 5.5.2 |
| User-Agent | Section 5.5.3 |
+-------------------+---------------+5.5.1. From ๐
the From header field has an Internet email address for the human who controls the requesting user agent. the address ought to be machine-usable, as defined by "mailbox" in Section 3.4 of [RFC5322] ๐จ
From = mailbox
mailbox = <mailbox, see [RFC5322], Section 3.4>example:
From: webmaster@example.orghonestly, non-robotic user agents rarely send From ๐ญ a user agent SHOULD NOT send a From header field without explicit configuration by the user, bc it could clash with the user's privacy interests or their site's security policy ๐
a robotic user agent SHOULD send a valid From header field, so the person running the robot can be contacted if things go wrong on servers. like if the robot is spamming excessive, unwanted, or invalid requests ๐ค๐
and a server SHOULD NOT use the From header field for access control or authentication, bc most recipients will assume that field value is public info ๐
5.5.2. Referer ๐
the "Referer" [sic] header field lets the user agent say which URI reference the target URI was obtained from. so it's the "referrer", even tho the field name is misspelled ๐คญ a user agent MUST NOT include the fragment and userinfo components of the URI reference [RFC3986], if any, when it generates the Referer field value ๐ โโ๏ธ
Referer = absolute-URI / partial-URIservers use Referer to make back-links to other resources for simple analytics, logging, optimized caching, etc. it also helps find obsolete or mistyped links for maintenance ๐ some servers use it to block links from other sites ("deep linking") or to limit cross-site request forgery (CSRF), but not all requests have it ๐
example:
Referer: http://www.example.org/hypertext/Overview.htmlif the target URI came from a source with no URI of its own (like input from the user's keyboard, or an entry in their bookmarks/favorites), the user agent MUST either exclude the Referer field or send it with a value of "about:blank" ๐
Referer can reveal the user's request context or browsing history, which is a privacy concern if the referring resource's identifier shows personal info (like an account name) or a resource that's supposed to be confidential (like something behind a firewall or internal to a secured service) ๐ต๏ธโโ๏ธ most general-purpose user agents don't send Referer when the referring resource is a local "file" or "data" URI. and a user agent MUST NOT send a Referer header field in an unsecured HTTP request if the referring page was received over a secure protocol ๐ see Section 9.4 for more security considerations.
some intermediaries have been known to remove Referer headers from outgoing requests indiscriminately ๐ค that messes with CSRF protection, which can be way more harmful to their users. intermediaries and user agent extensions that want to limit info disclosure in Referer ought to keep their changes to specific edits, like swapping internal domain names for pseudonyms or truncating the query and/or path components โ๏ธ and an intermediary SHOULD NOT modify or delete the Referer header field when the field value shares the same scheme and host as the request target ๐ซถ
5.5.3. User-Agent ๐ชช
the User-Agent header field has info about the user agent that's sending the request. servers often use it to figure out the scope of reported interop problems, to work around or tailor responses to dodge particular user agent limitations, and for analytics about browser or OS use ๐ a user agent SHOULD send a User-Agent field in each request, unless it's specifically configured not to โจ
User-Agent = product *( RWS ( product / comment ) )the User-Agent field-value is one or more product identifiers, each followed by zero or more comments (Section 3.2 of [RFC7230]). together they identify the user agent software and its significant subproducts ๐งฉ by convention, the product identifiers go in decreasing order of significance for identifying the user agent software. each product identifier has a name and an optional version ๐ท๏ธ
product = token ["/" product-version]
product-version = tokena sender SHOULD limit generated product identifiers to what's necessary to identify the product. and a sender MUST NOT generate advertising or other nonessential info inside a product identifier ๐ซ๐ฃ a sender SHOULD NOT put anything in product-version that isn't a version identifier. like, successive versions of the same product name ought to differ ONLY in the product-version portion of the product identifier (lowercase "only" vibes, but yes, that's the rule) ๐
example:
User-Agent: CERN-LineMode/2.15 libwww/2.17b3a user agent SHOULD NOT generate a User-Agent field with needlessly fine-grained detail, and SHOULD limit how many subproducts third parties add ๐ โโ๏ธ overly long, detailed User-Agent values make requests slower AND raise the risk of "fingerprinting", which is when someone gets identified against their wishes ๐ฌ
also, implementations are encouraged not to use other implementations' product tokens to claim compatibility, bc that defeats the whole purpose of the field ๐ฅด if a user agent pretends to be a different one, recipients can assume the user actually wants responses tailored to that identified user agent, even if they might not work as well for the real one ๐ญ
6. Response Status Codes ๐ฆ
the status-code element is a three-digit integer that tells you the result of trying to understand and satisfy the request ๐ข
status codes are extensible ๐งฉ HTTP clients don't have to understand every registered status code, tho understanding them is obviously a good look ๐
BUT a client MUST understand the class of any status code (the first digit tells you), and treat an unrecognized status code as if it were the x00 status code of that class. the one exception is that a recipient MUST NOT cache a response with an unrecognized status code ๐
โโ๏ธ
for example, if a client gets an unrecognized status code of 471, it can assume something was wrong with its request and treat the response as if it got a 400 (Bad Request) status code. the response message will usually have a representation that explains the status ๐
the first digit of the status-code defines the class of response. the last two digits don't have any categorization role ๐ซ there are five values for the first digit:
1xx(Informational): the request was received, continuing process โณ2xx(Successful): the request was successfully received, understood, and accepted โ3xx(Redirection): further action needs to be taken in order to complete the request โช๏ธ4xx(Client Error): the request contains bad syntax or cannot be fulfilled ๐5xx(Server Error): the server failed to fulfill an apparently valid request ๐
6.1. Overview of Status Codes โจ
okay so the status codes below are defined in this spec, in Section 4 of [RFC7232], in Section 4 of [RFC7233], and in Section 3 of [RFC7235] ๐ the reason phrases are only suggestions tbh. you can swap them for local versions and the protocol is still totally fine ๐ซถ
responses with status codes that are cacheable by default (like 200, 203, 204, 206, 300, 301, 404, 405, 410, 414, and 501 in this spec) can be reused by a cache with heuristic expiration, unless the method definition or explicit cache controls [RFC7234] say otherwise ๐ every other status code is NOT cacheable by default, so no sneaky reuse for those ๐
+------+-------------------------------+--------------------------+
| Code | Reason-Phrase | Defined in... |
+------+-------------------------------+--------------------------+
| 100 | Continue | Section 6.2.1 |
| 101 | Switching Protocols | Section 6.2.2 |
| 200 | OK | Section 6.3.1 |
| 201 | Created | Section 6.3.2 |
| 202 | Accepted | Section 6.3.3 |
| 203 | Non-Authoritative Information | Section 6.3.4 |
| 204 | No Content | Section 6.3.5 |
| 205 | Reset Content | Section 6.3.6 |
| 206 | Partial Content | Section 4.1 of [RFC7233] |
| 300 | Multiple Choices | Section 6.4.1 |
| 301 | Moved Permanently | Section 6.4.2 |
| 302 | Found | Section 6.4.3 |
| 303 | See Other | Section 6.4.4 |
| 304 | Not Modified | Section 4.1 of [RFC7232] |
| 305 | Use Proxy | Section 6.4.5 |
| 307 | Temporary Redirect | Section 6.4.7 |
| 400 | Bad Request | Section 6.5.1 |
| 401 | Unauthorized | Section 3.1 of [RFC7235] |
| 402 | Payment Required | Section 6.5.2 |
| 403 | Forbidden | Section 6.5.3 |
| 404 | Not Found | Section 6.5.4 |
| 405 | Method Not Allowed | Section 6.5.5 |
| 406 | Not Acceptable | Section 6.5.6 |
| 407 | Proxy Authentication Required | Section 3.2 of [RFC7235] |
| 408 | Request Timeout | Section 6.5.7 |
| 409 | Conflict | Section 6.5.8 |
| 410 | Gone | Section 6.5.9 |
| 411 | Length Required | Section 6.5.10 |
| 412 | Precondition Failed | Section 4.2 of [RFC7232] |
| 413 | Payload Too Large | Section 6.5.11 |
| 414 | URI Too Long | Section 6.5.12 |
| 415 | Unsupported Media Type | Section 6.5.13 |
| 416 | Range Not Satisfiable | Section 4.4 of [RFC7233] |
| 417 | Expectation Failed | Section 6.5.14 |
| 426 | Upgrade Required | Section 6.5.15 |
| 500 | Internal Server Error | Section 6.6.1 |
| 501 | Not Implemented | Section 6.6.2 |
| 502 | Bad Gateway | Section 6.6.3 |
| 503 | Service Unavailable | Section 6.6.4 |
| 504 | Gateway Timeout | Section 6.6.5 |
| 505 | HTTP Version Not Supported | Section 6.6.6 |
+------+-------------------------------+--------------------------+this list is NOT the whole list ๐ it doesn't include extension status codes from other specs. IANA keeps the complete list, so check Section 8.2 for the details ๐
6.2. Informational 1xx ๐ฆ
the 1xx (Informational) class is all about interim responses. they tell you about connection status or how far along your request is, before the action is finished and the final response shows up ๐ 1xx responses end at the first empty line after the status-line (that empty line is the end of the header section, bestie ๐ง)
since HTTP/1.0 never defined any 1xx status codes, a server MUST NOT send a 1xx response to an HTTP/1.0 client. no exceptions, periodt ๐
a client MUST be able to parse one or more 1xx responses that show up before a final response, even if it wasn't expecting any ๐ซถ a user agent MAY ignore 1xx responses it didn't ask for. totally valid ๐ธ
a proxy MUST forward 1xx responses, unless the proxy itself asked for the 1xx response to be generated. for example, if a proxy adds an Expect: 100-continue field when it forwards a request, then it doesn't need to forward the matching 100 (Continue) response(s) ๐
6.2.1. 100 Continue โจ
the 100 (Continue) status code says the start of a request has arrived and the server hasn't rejected it yet ๐ท the server plans to send a final response once the whole request has come in and been dealt with ๐ฅ
if the request has an Expect header field with a 100-continue expectation, the 100 response means the server wants to receive the request payload body, as described in Section 5.1.1 ๐ the client ought to keep sending the request and throw out the 100 response ๐
if the request didn't have an Expect header field with the 100-continue expectation, the client can just toss this interim response ๐
6.2.2. 101 Switching Protocols ๐ฆ
the 101 (Switching Protocols) status code means the server gets the client's request and is willing to go along with it. the request used the Upgrade header field (Section 6.7 of [RFC7230]) to ask for a change in the application protocol on this connection ๐ the server MUST generate an Upgrade header field in the response that says which protocol(s) will be switched to right after the empty line ending the 101 response ๐ง
it's assumed the server will only agree to switch when it's actually worth it ๐ like, switching to a newer version of HTTP might be better than an older one, and switching to a real-time, synchronous protocol might be a good call when delivering resources that use those features โจ
6.3. Successful 2xx ๐
the 2xx (Successful) class means the client's request was received, understood, and accepted ๐
6.3.1. 200 OK ๐
the 200 (OK) status code means the request succeeded ๐ธ what comes in the payload of a 200 response depends on the request method. for the methods defined in this spec, the intended meaning of the payload goes like this:
GET ๐ a representation of the target resource;
HEAD ๐ซถ the same representation as GET, just without the representation data;
POST ๐ a representation of the status of, or results obtained from, the action;
PUT, DELETE โจ a representation of the status of the action;
OPTIONS ๐ฆ a representation of the communications options;
TRACE ๐ a representation of the request message as the end server received it.
apart from responses to CONNECT, a 200 response always has a payload, though an origin server MAY generate a payload body of zero length ๐ if no payload is wanted, an origin server ought to send 204 (No Content) instead ๐ง for CONNECT, no payload is allowed, because the successful result is a tunnel that starts right after the 200 response header section ๐ฅ
a 200 response is cacheable by default, unless the method definition or explicit cache controls say otherwise (see Section 4.2.2 of [RFC7234]) ๐
6.3.2. 201 Created ๐
the 201 (Created) status code means the request got fulfilled and created one or more new resources ๐ท the main resource the request made is identified by either a Location header field in the response or, if no Location field came back, by the effective request URI ๐
the 201 response payload usually describes and links to the resource(s) that got created ๐ check out Section 7.2 for what validator header fields like ETag and Last-Modified mean in a 201 response ๐ซถ
6.3.3. 202 Accepted ๐
the 202 (Accepted) status code means the request was accepted for processing, but the processing isn't finished yet ๐ธ the request might or might not eventually get acted on, since it could be disallowed by the time processing actually happens ๐ HTTP has no way to re-send a status code from an asynchronous operation, so no take-backs ๐ญ
the 202 response is intentionally noncommittal, and honestly it's giving very chill energy ๐ง its purpose is to let a server accept a request for some other process (like a batch job that only runs once a day) without making the user agent's connection stick around until the process finishes ๐ฆ the representation sent with this response ought to describe the request's current status and point to (or embed) a status monitor that can tell the user roughly when the request will be fulfilled โจ
6.3.4. 203 Non-Authoritative Information ๐
the 203 (Non-Authoritative Information) status code means the request was successful, but a transforming proxy (Section 5.7.2 of [RFC7230]) changed the enclosed payload from what the origin server's 200 (OK) response had ๐ this lets the proxy tell recipients that a transformation was applied, which matters because it can change later decisions about the content ๐ฅ for example, future cache validation requests for the content might only make sense along the same request path (through the same proxies) ๐
a 203 response is kinda similar to the Warning code 214 Transformation Applied (Section 5.5 of [RFC7234]) ๐ซถ the difference is 203 has the advantage of working with responses of any status code ๐
a 203 response is cacheable by default, unless the method definition or explicit cache controls say otherwise (see Section 4.2.2 of [RFC7234]) โจ
6.3.5. 204 No Content ๐ง
okay so the 204 (No Content) status code is giving "job done, nothing else to show you" ๐ . The server successfully fulfilled the request and there's no additional content in the response payload body. Any metadata in the response header fields refers to the target resource and its selected representation after the requested action was applied ๐ซถ.
For example, if a 204 comes back for a PUT request and the response has an ETag header field, then the PUT worked, and that ETag field-value is the entity-tag for the new representation of the target resource ๐.
The 204 response lets a server say the action was successfully applied to the target resource, while implying the user agent doesn't need to leave its current "document view" (if there is one) ๐ฆ. The server trusts that the user agent will show its user some kind of success indicator in line with its own interface, and will apply any new or updated metadata to its active representation ๐.
A 204 is super common with "save" buttons in document editing interfaces, so the doc stays right there for the user to keep editing ๐. It's also big in interfaces built for automated data transfers, like distributed version control systems ๐ค.
A 204 response is terminated by the first empty line after the header fields, because it cannot contain a message body ๐.
A 204 response is cacheable by default; i.e., unless otherwise indicated by the method definition or explicit cache controls (see Section 4.2.2 of [RFC7234]) โจ.
6.3.6. 205 Reset Content ๐ธ
The 205 (Reset Content) status code means the server fulfilled the request and wants the user agent to reset the "document view" that caused the request to be sent back to its original state as received from the origin server ๐.
This is built for a really common data entry situation. The user gets content that supports data entry (a form, notepad, canvas, etc.), types or manipulates data in it, submits that data in a request, and then the entry mechanism resets so they can easily start another input ๐ .
Since 205 implies no additional content will be provided, a server MUST NOT generate a payload in a 205 response. In other words, a server MUST do one of the following for a 205 response:
- a) indicate a zero-length body for the response by including a
Content-Lengthheader field with a value of0; - b) indicate a zero-length payload for the response by including a
Transfer-Encodingheader field with a value ofchunkedand a message body consisting of a single chunk of zero-length; or, - c) close the connection immediately after sending the blank line terminating the header section.
6.4. Redirection 3xx ๐ฆ
The 3xx (Redirection) class of status code means further action needs to be taken by the user agent to fulfill the request ๐โโ๏ธ. If a Location header field (Section 7.1.2) is provided, the user agent MAY automatically redirect its request to the URI referenced by the Location field value, even if the specific status code isn't understood. Automatic redirection needs to done with care for methods not known to be safe, as defined in Section 4.2.1, since the user might not wish to redirect an unsafe request โ ๏ธ.
There are several types of redirects:
- Redirects that indicate the resource might be available at a different URI, as provided by the Location field, as in the status codes 301 (Moved Permanently), 302 (Found), and 307 (Temporary Redirect).
- Redirection that offers a choice of matching resources, each capable of representing the original request target, as in the 300 (Multiple Choices) status code.
- Redirection to a different resource, identified by the Location field, that can represent an indirect response to the request, as in the 303 (See Other) status code.
- Redirection to a previously cached result, as in the 304 (Not Modified) status code.
Note: In HTTP/1.0, the status codes 301 (Moved Permanently) and 302 (Found) were defined for the first type of redirect ([RFC1945], Section 9.3). Early user agents split on whether the method applied to the redirect target would be the same as the original request or would be rewritten as GET. Although HTTP originally defined the former semantics for 301 and 302 (to match its original implementation at CERN), and defined 303 (See Other) to match the latter semantics, prevailing practice gradually converged on the latter semantics for 301 and 302 as well. The first revision of HTTP/1.1 added 307 (Temporary Redirect) to indicate the former semantics without being impacted by divergent practice. Over 10 years later, most user agents still do method rewriting for 301 and 302; therefore, this specification makes that behavior conformant when the original request is POST.
A client SHOULD detect and intervene in cyclical redirections (i.e., "infinite" redirection loops) ๐.
Note: An earlier version of this specification recommended a maximum of five redirections ([RFC2068], Section 10.3). Content developers need to be aware that some clients might implement such a fixed limitation.
6.4.1. 300 Multiple Choices ๐
The 300 (Multiple Choices) status code means the target resource has more than one representation, each with its own more specific identifier. Information about the alternatives is provided so the user (or user agent) can pick a preferred representation by redirecting its request to one or more of those identifiers. In other words, the server wants the user agent to do reactive negotiation to select the most appropriate representation(s) for its needs (Section 3.4) ๐.
If the server has a preferred choice, the server SHOULD generate a Location header field containing a preferred choice's URI reference. The user agent MAY use the Location field value for automatic redirection.
For request methods other than HEAD, the server SHOULD generate a payload in the 300 response containing a list of representation metadata and URI reference(s) the user or user agent can choose from, with the most preferred one picked out. The user agent MAY make a selection from that list automatically if it understands the provided media type. A specific format for automatic selection is not defined by this specification, because HTTP tries to remain orthogonal to the definition of its payloads. In practice, the representation is provided in some easily parsed format believed to be acceptable to the user agent, as determined by shared design or content negotiation, or in some commonly accepted hypertext format ๐.
A 300 response is cacheable by default; i.e., unless otherwise indicated by the method definition or explicit cache controls (see Section 4.2.2 of [RFC7234]) โจ.
Note: The original proposal for the 300 status code defined the URI header field as providing a list of alternative representations, such that it would be usable for 200, 300, and 406 responses and be transferred in responses to the HEAD method. However, lack of deployment and disagreement over syntax led to both URI and Alternates (a subsequent proposal) being dropped from this specification. It is possible to communicate the list using a set of Link header fields [RFC5988], each with a relationship of "alternate", though deployment is a chicken-and-egg problem ๐ฅ.
6.4.2. 301 Moved Permanently ๐
The 301 (Moved Permanently) status code means the target resource has been assigned a new permanent URI, and any future references to this resource ought to use one of the enclosed URIs. Clients with link-editing capabilities ought to automatically re-link references to the effective request URI to one or more of the new references sent by the server, where possible ๐.
The server SHOULD generate a Location header field in the response containing a preferred URI reference for the new permanent URI. The user agent MAY use the Location field value for automatic redirection. The server's response payload usually contains a short hypertext note with a hyperlink to the new URI(s) ๐.
Note: For historical reasons, a user agent MAY change the request method from POST to GET for the subsequent request. If this behavior is undesired, the 307 (Temporary Redirect) status code can be used instead.
A 301 response is cacheable by default; i.e., unless otherwise indicated by the method definition or explicit cache controls (see Section 4.2.2 of [RFC7234]) ๐พ.
6.4.3. 302 Found ๐
The 302 (Found) status code means the target resource temporarily lives under a different URI. Since the redirection might change on occasion, the client ought to keep using the effective request URI for future requests ๐.
The server SHOULD generate a Location header field in the response containing a URI reference for the different URI. The user agent MAY use the Location field value for automatic redirection. The server's response payload usually contains a short hypertext note with a hyperlink to the different URI(s) ๐.
Note: For historical reasons, a user agent MAY change the request method from POST to GET for the subsequent request. If this behavior is undesired, the 307 (Temporary Redirect) status code can be used instead.
6.4.4. 303 See Other ๐ง
The 303 (See Other) status code means the server is redirecting the user agent to a different resource, as indicated by a URI in the Location header field. That URI is meant to provide an indirect response to the original request. A user agent can perform a retrieval request targeting that URI (a GET or HEAD request if using HTTP), which might also get redirected, and then present the eventual result as the answer to the original request ๐ฏ. Note that the new URI in the Location header field is not considered equivalent to the effective request URI.
This status code applies to any HTTP method. It's mainly used so the output of a POST action can redirect the user agent to a selected resource, since that gives the POST response info in a form that can be separately identified, bookmarked, and cached, independent of the original request ๐.
A 303 response to a GET request means the origin server doesn't have a representation of the target resource that it can transfer over HTTP. However, the Location field value refers to a resource that describes the target resource, so a retrieval request on that other resource might result in a representation that's useful to recipients, without implying it represents the original target resource. Note that answers to the questions of what can be represented, what representations are adequate, and what might be a useful description are outside the scope of HTTP ๐คทโโ๏ธ.
Except for responses to a HEAD request, the representation of a 303 response ought to contain a short hypertext note with a hyperlink to the same URI reference provided in the Location header field ๐.
6.4.5. 305 Use Proxy ๐ซ
The 305 (Use Proxy) status code was defined in a previous version of this specification and is now deprecated (Appendix B) ๐.
6.4.6. 306 (Unused) ๐
okay so the 306 status code was a thing in an older version of this spec, but it's been retired ๐ชฆ and nobody uses it anymore. The code is still reserved, so nobody can grab it for something else ๐
6.4.7. 307 Temporary Redirect ๐ฆ
the 307 (Temporary Redirect) status code means the target resource is temporarily living under a different URI ๐งณ. If the user agent does an automatic redirect to that new URI, it MUST NOT change the request method ๐ซ. Like, if it was a POST, it stays a POST. No sneaky switching to GET ๐. Since the redirect might change over time, the client ought to keep using the original effective request URI for future requests ๐ .
The server SHOULD include a Location header field in the response, with a URI reference for the different URI ๐. The user agent MAY use that Location field value to redirect automatically โจ. The response payload usually has a short hypertext note with a hyperlink to the different URI(s) ๐.
Note: This status code is similar to 302 (Found), except that it does not allow changing the request method from POST to GET. This specification defines no equivalent counterpart for 301 (Moved Permanently) ([RFC7238], however, defines the status code 308 (Permanent Redirect) for this purpose). ๐ธ
6.5. Client Error 4xx ๐จ
the 4xx (Client Error) class is for when the client seems to have messed up ๐. Except when responding to a HEAD request, the server SHOULD send a representation that explains the error and says whether it's a temporary or permanent situation ๐. These status codes apply to any request method ๐. User agents SHOULD display any included representation to the user ๐.
6.5.1. 400 Bad Request ๐
the 400 (Bad Request) status code means the server can't or won't process the request, because it looks like a client error ๐ โโ๏ธ. Examples include malformed request syntax, invalid request message framing, or deceptive request routing ๐ต๏ธโโ๏ธ.
6.5.2. 402 Payment Required ๐ธ
the 402 (Payment Required) status code is reserved for future use ๐ฎ. Hold tight, it's coming ๐.
6.5.3. 403 Forbidden ๐ซ
the 403 (Forbidden) status code means the server understood the request but refuses to authorize it ๐. A server that wants to share the reason for the forbidden request can describe it in the response payload, if there is one ๐ฃ.
If authentication credentials were sent in the request, the server considers them insufficient to grant access ๐. The client SHOULD NOT automatically repeat the request with the same credentials ๐ โโ๏ธ. The client MAY repeat the request with new or different credentials ๐๏ธ. Still, a request might be forbidden for reasons that have nothing to do with the credentials ๐คทโโ๏ธ.
An origin server that wants to "hide" the current existence of a forbidden target resource MAY respond with a 404 (Not Found) status code instead ๐ซฃ.
6.5.4. 404 Not Found ๐
the 404 (Not Found) status code means the origin server did not find a current representation for the target resource, or it isn't willing to say that one exists ๐ต๏ธ. A 404 doesn't tell you whether the missing representation is temporary or permanent ๐ค. The 410 (Gone) status code is preferred over 404 if the origin server knows, probably through some configurable setup, that the situation is likely permanent ๐.
A 404 response is cacheable by default ๐ฆ, unless the method definition or explicit cache controls say otherwise (see Section 4.2.2 of [RFC7234]) โณ.
6.5.5. 405 Method Not Allowed ๐ โโ๏ธ
the 405 (Method Not Allowed) status code means the origin server knows the method in the request-line but the target resource doesn't support it ๐. The origin server MUST generate an Allow header field in a 405 response, listing the methods the target resource currently supports ๐.
A 405 response is cacheable by default ๐ฆ, unless the method definition or explicit cache controls say otherwise (see Section 4.2.2 of [RFC7234]) โณ.
6.5.6. 406 Not Acceptable ๐
the 406 (Not Acceptable) status code means the target resource doesn't have a current representation that the user agent would accept, based on the proactive negotiation header fields in the request (Section 5.3), and the server won't supply a default representation either ๐ค.
The server SHOULD generate a payload with a list of the available representation characteristics and their resource identifiers ๐๏ธ, so the user or user agent can pick the best one ๐. A user agent MAY automatically select the best choice from that list โจ. However, this specification doesn't define any standard for automatic selection, as described in Section 6.4.1 ๐ค.
6.5.7. 408 Request Timeout โฐ
the 408 (Request Timeout) status code means the server didn't get a complete request message in the time it was willing to wait ๐ฐ๏ธ. A server SHOULD send the "close" connection option (Section 6.1 of [RFC7230]) in the response, since a 408 means the server has decided to close the connection instead of waiting longer ๐ช. If the client has an outstanding request in transit, the client MAY repeat that request on a new connection ๐.
6.5.8. 409 Conflict โ๏ธ
the 409 (Conflict) status code means the request couldn't be completed because it clashes with the current state of the target resource ๐ฅ. This code is used when the user might be able to fix the conflict and resubmit the request ๐ ๏ธ. The server SHOULD generate a payload with enough information for a user to figure out where the conflict came from ๐.
Conflicts are most likely to happen with a PUT request ๐ . For example, if versioning is being used and the representation being PUT changes a resource in a way that clashes with an earlier (third-party) request, the origin server might send a 409 to say it can't finish the request ๐ โโ๏ธ. In that case, the response representation would likely include info that helps merge the differences, based on the revision history ๐งฉ.
6.5.9. 410 Gone ๐ป
the 410 (Gone) status code means access to the target resource is no longer available at the origin server, and the situation is likely permanent ๐ชฆ. If the origin server doesn't know, or has no way to find out, whether the situation is permanent, the 404 (Not Found) status code ought to be used instead ๐คทโโ๏ธ.
The 410 response is mainly there to help with web maintenance ๐งน. It tells the recipient that the resource is intentionally unavailable, and that the server owners want remote links to that resource removed ๐โ๏ธ. This is common for limited-time promo stuff and for resources belonging to people who aren't associated with the origin server's site anymore ๐๏ธ. You don't have to mark every permanently gone resource as "gone", or keep that mark forever. That's up to the server owner ๐.
A 410 response is cacheable by default ๐ฆ, unless the method definition or explicit cache controls say otherwise (see Section 4.2.2 of [RFC7234]) โณ.
6.5.10. 411 Length Required ๐
the 411 (Length Required) status code means the server won't accept the request without a defined Content-Length (Section 3.3.2 of [RFC7230]) ๐ โโ๏ธ. The client MAY repeat the request if it adds a valid Content-Length header field with the length of the message body in the request message ๐.
6.5.11. 413 Payload Too Large ๐ฆ
the 413 (Payload Too Large) status code means the server is refusing to process a request because the payload is bigger than the server can handle ๐ฅต. The server MAY close the connection to stop the client from continuing the request ๐ช.
If the condition is temporary, the server SHOULD generate a Retry-After header field to say it's temporary and after what time the client MAY try again โณ.
6.5.12. 414 URI Too Long ๐
the 414 (URI Too Long) status code means the server is refusing to service the request because the request-target (Section 5.3 of [RFC7230]) is longer than the server is willing to interpret ๐. This rare situation usually happens when a client wrongly turns a POST request into a GET request with a lot of query info ๐, when the client gets stuck in a "black hole" of redirection (like a redirected URI prefix that points to a suffix of itself) ๐ณ๏ธ, or when the server is under attack by a client trying to exploit potential security holes ๐จ.
A 414 response is cacheable by default ๐ฆ, unless the method definition or explicit cache controls say otherwise (see Section 4.2.2 of [RFC7234]) โณ.
6.5.13. 415 Unsupported Media Type ๐๏ธ
the 415 (Unsupported Media Type) status code means the origin server is refusing to service the request because the payload is in a format this method doesn't support on the target resource ๐ โโ๏ธ. The problem might come from the request's indicated Content-Type or Content-Encoding, or from inspecting the data directly ๐.
6.5.14. 417 Expectation Failed ๐ฌ
the 417 (Expectation Failed) status code means the expectation in the request's Expect header field (Section 5.1.1) couldn't be met by at least one of the inbound servers ๐ซ .
6.5.15. 426 Upgrade Required ๐
the 426 (Upgrade Required) status code means the server refuses to do the request using the current protocol, but it might be willing to do it after the client upgrades to a different protocol ๐. The server MUST send an Upgrade header field in a 426 response to say which protocol(s) are required (Section 6.7 of [RFC7230]) ๐ฃ.
Example:
HTTP/1.1 426 Upgrade Required
Upgrade: HTTP/3.0
Connection: Upgrade
Content-Length: 53
Content-Type: text/plain
This service requires use of the HTTP/3.0 protocol.6.6. Server Error 5xx ๐ฅ
the 5xx (Server Error) class means the server knows it messed up, or it can't perform the requested method at all ๐ญ. Except when responding to a HEAD request, the server SHOULD send a representation that explains the error and says whether it's a temporary or permanent condition ๐. A user agent SHOULD display any included representation to the user ๐. These response codes apply to any request method ๐.
6.6.1. 500 Internal Server Error ๐ฅ
the 500 (Internal Server Error) status code means the server ran into an unexpected condition that stopped it from fulfilling the request ๐.
6.6.2. 501 Not Implemented ๐ ๏ธ
the 501 (Not Implemented) status code means the server doesn't support the functionality needed to fulfill the request ๐. This is the right response when the server doesn't recognize the request method and can't support it for any resource ๐ โโ๏ธ.
A 501 response is cacheable by default ๐ฆ, unless the method definition or explicit cache controls say otherwise (see Section 4.2.2 of [RFC7234]) โณ.
6.6.3. 502 Bad Gateway ๐
the 502 (Bad Gateway) status code means the server, while acting as a gateway or proxy, got an invalid response from an inbound server it contacted while trying to fulfill the request ๐ซ .
6.6.4. 503 Service Unavailable ๐ซถ
okay so 503 is the server basically saying "sorry bestie, I'm slammed rn" ๐ญ It means the server can't handle the request right now because it's temporarily overloaded or doing scheduled maintenance, and that should get better after some delay ๐
The server MAY send a Retry-After header field (Section 7.1.3) to suggest a good amount of time for the client to wait before retrying the request ๐ง
Note: ngl, the existence of the 503 status code doesn't mean a server has to use it when it gets overloaded ๐ Some servers might just refuse the connection.
6.6.5. 504 Gateway Timeout ๐ธ
the 504 is for when a server is acting as a gateway or proxy ๐ช and it didn't get a timely response from an upstream server it needed to reach in order to finish the request. it's giving "I waited and nobody showed up" ๐
6.6.6. 505 HTTP Version Not Supported ๐ฆ
the 505 means the server doesn't support the major version of HTTP that was used in the request, or it just refuses to ๐ โโ๏ธ It's saying it can't or won't finish the request using the same major version as the client, as described in Section 2.6 of [RFC7230], and the only thing it's sending back is this error message. The server SHOULD generate a representation for the 505 response that explains why that version isn't supported and what other protocols that server does support ๐
7. Response Header Fields โจ
response header fields let the server pass extra info about the response, beyond what's in the status-line ๐ They tell you about the server, about further access to the target resource, or about related resources.
Every response header field has its own defined meaning, but generally the exact semantics can get refined by the request method and/or the response status code, so context matters ๐ง
7.1. Control Data ๐
Response header fields can carry control data that backs up the status code, directs caching, or tells the client where to go next ๐บ๏ธ
+-------------------+--------------------------+
| Header Field Name | Defined in... |
+-------------------+--------------------------+
| Age | Section 5.1 of [RFC7234] |
| Cache-Control | Section 5.2 of [RFC7234] |
| Expires | Section 5.3 of [RFC7234] |
| Date | Section 7.1.1.2 |
| Location | Section 7.1.2 |
| Retry-After | Section 7.1.3 |
| Vary | Section 7.1.4 |
| Warning | Section 5.5 of [RFC7234] |
+-------------------+--------------------------+7.1.1. Origination Date ๐ฐ๏ธ
7.1.1.1. Date/Time Formats ๐
back before 1995, servers used three different formats to share timestamps ๐ตโ๐ซ For compatibility with old implementations, all three are defined here. The preferred one is a fixed-length, single-zone subset of the date and time spec used by the Internet Message Format [RFC5322] ๐
HTTP-date = IMF-fixdate / obs-dateAn example of the preferred format is:
Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdateExamples of the two obsolete formats are:
Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format
Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() formatokay the rule here is that a recipient that parses a timestamp in an HTTP header field MUST accept all three HTTP-date formats ๐ซถ And when a sender generates a header field with one or more timestamps defined as HTTP-date, the sender MUST generate those timestamps in the IMF-fixdate format โจ
an HTTP-date value represents time as an instance of Coordinated Universal Time (UTC) ๐ The first two formats show UTC with the three-letter abbreviation "GMT", which is kind of a predecessor of the UTC name. Values in the asctime format are assumed to be in UTC. If a sender makes HTTP-date values from a local clock, it ought to use NTP ([RFC5905]) or some similar protocol to sync that clock to UTC โฐ
Preferred format:
IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT
; fixed length/zone/capitalization subset of the format
; see Section 3.3 of [RFC5322]
day-name = %x4D.6F.6E ; "Mon", case-sensitive
/ %x54.75.65 ; "Tue", case-sensitive
/ %x57.65.64 ; "Wed", case-sensitive
/ %x54.68.75 ; "Thu", case-sensitive
/ %x46.72.69 ; "Fri", case-sensitive
/ %x53.61.74 ; "Sat", case-sensitive
/ %x53.75.6E ; "Sun", case-sensitive
date1 = day SP month SP year
; e.g., 02 Jun 1982
day = 2DIGIT
month = %x4A.61.6E ; "Jan", case-sensitive
/ %x46.65.62 ; "Feb", case-sensitive
/ %x4D.61.72 ; "Mar", case-sensitive
/ %x41.70.72 ; "Apr", case-sensitive
/ %x4D.61.79 ; "May", case-sensitive
/ %x4A.75.6E ; "Jun", case-sensitive
/ %x4A.75.6C ; "Jul", case-sensitive
/ %x41.75.67 ; "Aug", case-sensitive
/ %x53.65.70 ; "Sep", case-sensitive
/ %x4F.63.74 ; "Oct", case-sensitive
/ %x4E.6F.76 ; "Nov", case-sensitive
/ %x44.65.63 ; "Dec", case-sensitive
year = 4DIGIT
GMT = %x47.4D.54 ; "GMT", case-sensitive
time-of-day = hour ":" minute ":" second
; 00:00:00 - 23:59:60 (leap second)
hour = 2DIGIT
minute = 2DIGIT
second = 2DIGITObsolete formats:
obs-date = rfc850-date / asctime-date
rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT
date2 = day "-" month "-" 2DIGIT
; e.g., 02-Jun-82
day-name-l = %x4D.6F.6E.64.61.79 ; "Monday", case-sensitive
/ %x54.75.65.73.64.61.79 ; "Tuesday", case-sensitive
/ %x57.65.64.6E.65.73.64.61.79 ; "Wednesday", case-sensitive
/ %x54.68.75.72.73.64.61.79 ; "Thursday", case-sensitive
/ %x46.72.69.64.61.79 ; "Friday", case-sensitive
/ %x53.61.74.75.72.64.61.79 ; "Saturday", case-sensitive
/ %x53.75.6E.64.61.79 ; "Sunday", case-sensitive
asctime-date = day-name SP date3 SP time-of-day SP year
date3 = month SP ( 2DIGIT / ( SP 1DIGIT ))
; e.g., Jun 2HTTP-date is case sensitive ๐ A sender MUST NOT generate additional whitespace in an HTTP-date beyond what's specifically included as SP in the grammar. The meanings of day-name, day, month, year, and time-of-day are the same as the Internet Message Format constructs with the matching names ([RFC5322], Section 3.3) ๐
Recipients of a timestamp in rfc850-date format, which uses a two-digit year, MUST interpret a timestamp that seems to be more than 50 years in the future as the most recent year in the past that had the same last two digits ๐
Recipients of timestamp values are encouraged to be robust when parsing timestamps, unless the field definition restricts them otherwise ๐ซ For example, messages are sometimes forwarded over HTTP from a non-HTTP source that might produce any of the date and time specifications defined by the Internet Message Format.
Note: HTTP requirements for the date/time stamp format only apply to how they're used inside the protocol stream. Implementations are not required to use these formats for user presentation, request logging, etc.
7.1.1.2. Date ๐
the Date header field represents the date and time when the message was originated ๐ It has the same semantics as the Origination Date Field (orig-date) defined in Section 3.6.1 of [RFC5322]. The field value is an HTTP-date, as defined in Section 7.1.1.1 โจ
Date = HTTP-dateAn example is:
Date: Tue, 15 Nov 1994 08:12:31 GMTWhen a Date header field is generated, the sender SHOULD generate its field value as the best available approximation of the date and time of message generation ๐ซ In theory, the date ought to represent the moment just before the payload is generated. In practice, the date can be generated at any time during message origination.
An origin server MUST NOT send a Date header field if it doesn't have a clock that can give a reasonable approximation of the current moment in Coordinated Universal Time ๐ซโฐ An origin server MAY send a Date header field if the response is in the 1xx (Informational) or 5xx (Server Error) class of status codes. An origin server MUST send a Date header field in all other cases ๐
A recipient with a clock that receives a response message without a Date header field MUST record the time it was received and append a matching Date header field to the message's header section if it's cached or forwarded downstream ๐งพ
A user agent MAY send a Date header field in a request, though it generally won't unless it's believed to convey useful information to the server ๐ For example, custom applications of HTTP might convey a Date if the server is expected to adjust its interpretation of the user's request based on differences between the user agent's and server's clocks ๐
7.1.2. Location โจ
okay so the Location header field is how a response points at a specific resource, bestie ๐ง the vibe of the pointer depends on the combo of request method and status code, so it's giving context ๐
Location = URI-referenceThe field value is one single URI-reference ๐ If it's a relative reference ([RFC3986], Section 4.2), the final value gets worked out by resolving it against the effective request URI ([RFC3986], Section 5). Relative refs are lowkey the main character of this whole thing ๐ฆ
For 201 (Created) responses, Location points at the primary resource that the request created ๐ธ For 3xx (Redirection) responses, Location points at the preferred target resource for automatically redirecting the request ๐ฅ
If the Location value in a 3xx (Redirection) response has no fragment component, a user agent MUST process the redirection as if the value inherits the fragment component of the URI reference used to generate the request target (i.e., the redirection inherits the original reference's fragment, if any). So the fragment carries over, no cap ๐
Example time! ๐ A GET request made for the URI reference "http://www.example.org/~tim" might get a 303 (See Other) response with this header:
Location: /People.html#timThat basically suggests the user agent redirect to "http://www.example.org/People.html#tim" โจ
Same energy with a GET for the URI reference "http://www.example.org/index.html#larry". It might get a 301 (Moved Permanently) response with this header:
Location: http://www.example.net/index.htmlThat suggests the user agent redirect to "http://www.example.net/index.html#larry", preserving the original fragment identifier ๐ซถ
Some situations make a fragment in Location a total no-go ๐ For example, a 201 (Created) response's Location is supposed to give a URI that's specific to the created resource, so no fragment there, periodt.
Note: Some recipients try to recover from Location fields that are not valid URI references. This specification does not mandate or define such processing, but does allow it for the sake of robustness. ๐ง
Note: The Content-Location header field (Section 3.1.4.2) is different from Location. Content-Location refers to the most specific resource corresponding to the enclosed representation. So it's totally possible for a response to have both the Location and Content-Location header fields, iykyk ๐
7.1.3. Retry-After โจ
Servers send the Retry-After header field to say how long the user agent ought to wait before making a follow-up request โณ When it comes with a 503 (Service Unavailable) response, Retry-After tells you how long the service is expected to be unavailable to the client ๐ When it comes with any 3xx (Redirection) response, Retry-After gives the minimum time the user agent is asked to wait before sending the redirected request ๐
The value can be either an HTTP-date or a number of seconds to delay after the response is received ๐
Retry-After = HTTP-date / delay-secondsA delay-seconds value is a non-negative decimal integer, representing time in seconds ๐
delay-seconds = 1*DIGITTwo examples, bestie ๐ฆ
Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
Retry-After: 120In the second one, the delay is 2 minutes โฐ math is mathing ๐
7.1.4. Vary โจ
The Vary header field in a response describes which parts of a request message, aside from the method, Host header field, and request target, might influence the origin server's process for picking and representing this response ๐ง The value is either a single asterisk ("*") or a list of header field names (case-insensitive) ๐ธ
Vary = "*" / 1#field-nameA Vary value of "*" signals that anything about the request might play a role in picking the response representation, possibly even stuff outside the message syntax (e.g., the client's network address) ๐ A recipient can't tell whether this response fits a later request without forwarding that request to the origin server, so it's a whole mystery ๐ A proxy MUST NOT generate a Vary field with a "*" value ๐ซ
A Vary value that's a comma-separated list of names means the named request header fields, called the selecting header fields, might have a role in picking the representation ๐ The potential selecting header fields aren't limited to the ones defined in this spec, so there's room to grow โจ
For example, a response with
Vary: accept-encoding, accept-languageis saying the origin server might have used the request's Accept-Encoding and Accept-Language fields (or the lack of them) as deciding factors when it chose the content for this response ๐
An origin server might send Vary with a list of fields for two purposes:
- To tell cache recipients that they MUST NOT use this response to satisfy a later request unless the later request has the same values for the listed fields as the original request (Section 4.1 of [RFC7234]). In other words, Vary expands the cache key required to match a new request to the stored cache entry ๐
- To tell user agent recipients that this response is subject to content negotiation (Section 5.3) and that a different representation might be sent in a subsequent request if extra parameters are provided in the listed header fields (proactive negotiation) ๐
An origin server SHOULD send a Vary header field when its algorithm for picking a representation varies based on aspects of the request message other than the method and request target. The exception is when the variance can't be crossed, or when the origin server has been deliberately configured to prevent cache transparency ๐ซถ For example, there's no need to send the Authorization field name in Vary, because reuse across users is already constrained by the field definition (Section 4.2 of [RFC7235]) ๐ And an origin server might use Cache-Control directives (Section 5.2 of [RFC7234]) to supplant Vary if it decides the variance matters less than Vary's impact on caching performance ๐
7.2. Validator Header Fields โจ
Validator header fields convey metadata about the selected representation (Section 3) ๐ In responses to safe requests, validator fields describe the selected representation the origin server picked while handling the response. Heads up though: depending on the status code semantics, the selected representation for a given response isn't always the same as the representation enclosed as the response payload ๐
In a successful response to a state-changing request, validator fields describe the new representation that replaced the prior selected representation as a result of processing the request ๐ฆ
For example, an ETag header field in a 201 (Created) response communicates the entity-tag of the newly created resource's representation. That way it can be used in later conditional requests to prevent the "lost update" problem [RFC7232] ๐ก๏ธ
+-------------------+--------------------------+
| Header Field Name | Defined in... |
+-------------------+--------------------------+
| ETag | Section 2.3 of [RFC7232] |
| Last-Modified | Section 2.2 of [RFC7232] |
+-------------------+--------------------------+7.3. Authentication Challenges โจ
Authentication challenges tell the client what mechanisms are available for providing authentication credentials in future requests ๐
+--------------------+--------------------------+
| Header Field Name | Defined in... |
+--------------------+--------------------------+
| WWW-Authenticate | Section 4.1 of [RFC7235] |
| Proxy-Authenticate | Section 4.3 of [RFC7235] |
+--------------------+--------------------------+7.4. Response Context โจ
The remaining response header fields give more info about the target resource, for potential use in later requests ๐ง
+-------------------+--------------------------+
| Header Field Name | Defined in... |
+-------------------+--------------------------+
| Accept-Ranges | Section 2.3 of [RFC7233] |
| Allow | Section 7.4.1 |
| Server | Section 7.4.2 |
+-------------------+--------------------------+7.4.1. Allow โจ
The Allow header field lists the set of methods advertised as supported by the target resource ๐ Its whole purpose is strictly to tell the recipient which request methods are valid for the resource ๐ฏ
Allow = #methodExample of use:
Allow: GET, HEAD, PUTThe actual set of allowed methods is defined by the origin server at the time of each request. An origin server MUST generate an Allow field in a 405 (Method Not Allowed) response and MAY do so in any other response ๐ An empty Allow field value means the resource allows no methods, which might happen in a 405 response if the resource has been temporarily disabled by configuration ๐
A proxy MUST NOT modify the Allow header field -- it doesn't need to understand all of the indicated methods in order to handle them according to the generic message handling rules ๐ซถ
7.4.2. Server โจ
The Server header field has info about the software the origin server used to handle the request ๐ฅ๏ธ Clients often use it to help identify the scope of reported interoperability problems, to work around or tailor requests to dodge particular server limitations, and for analytics about server or operating system use ๐ An origin server MAY generate a Server field in its responses ๐ธ
Server = product *( RWS ( product / comment ) )The Server field-value is one or more product identifiers, each followed by zero or more comments (Section 3.2 of [RFC7230]). Together they identify the origin server software and its significant subproducts ๐งฉ By convention, the product identifiers are listed in decreasing order of significance for identifying the origin server software. Each product identifier is a name plus an optional version, as defined in Section 5.5.3 ๐
Example:
Server: CERN/3.0 libwww/2.17An origin server SHOULD NOT generate a Server field with needlessly fine-grained detail, and SHOULD limit the addition of subproducts by third parties ๐ซ Overly long and detailed Server values make responses slower and can reveal internal implementation details, which might make it (slightly) easier for attackers to find and exploit known security holes ๐ญ๐
8. IANA Considerations โจ
8.1. Method Registry โจ
The "Hypertext Transfer Protocol (HTTP) Method Registry" defines the namespace for the request method token (Section 4) ๐๏ธ The method registry has been created and is now maintained at <http://www.iana.org/assignments/http-methods> ๐
8.1.1. Procedure โจ
HTTP method registrations MUST include the following fields:
- Method Name (see Section 4)
- Safe ("yes" or "no", see Section 4.2.1)
- Idempotent ("yes" or "no", see Section 4.2.2)
- Pointer to specification text
Values added to this namespace require IETF Review (see [RFC5226], Section 4.1) ๐
8.1.2. Considerations for New Methods โจ
okay so standardized methods are super generic, bestie ๐ they could be applicable to basically any resource, not just one media type, kind of resource, or app. That's why it's preferred that new methods get registered in a document that isn't tied to one application or data format, because orthogonal technologies deserve orthogonal specification ๐ฆ (iconic, ngl ๐ญ)
Message parsing (Section 3.3 of [RFC7230]) needs to stay independent of method semantics (aside from responses to HEAD) ๐ so definitions of new methods cannot change the parsing algorithm or prohibit the presence of a message body on either the request or the response message ๐ they can specify that only a zero-length message body is allowed, by requiring a Content-Length header field with a value of "0" ๐
A new method definition needs to indicate whether it is safe (Section 4.2.1), idempotent (Section 4.2.2), cacheable (Section 4.2.3), what semantics are to be associated with the payload body if any is present in the request, and what refinements the method makes to header field or status code semantics. main character energy, all of it ๐ If the new method is cacheable, its definition ought to describe how, and under what conditions, a cache can store a response and use it to satisfy a subsequent request. The new method ought to describe whether it can be made conditional (Section 5.2) and, if so, how a server responds when the condition is false. Likewise, if the new method might have some use for partial response semantics ([RFC7233]), it ought to document this, too ๐ง
Note: Avoid defining a method name that starts with "M-", since that prefix might be misinterpreted as having the semantics assigned to it by [RFC2774]. ๐ โโ๏ธ
8.1.3. Registrations ๐
The "Hypertext Transfer Protocol (HTTP) Method Registry" has been populated with the registrations below:
+---------+------+------------+---------------+
| Method | Safe | Idempotent | Reference |
+---------+------+------------+---------------+
| CONNECT | no | no | Section 4.3.6 |
| DELETE | no | yes | Section 4.3.5 |
| GET | yes | yes | Section 4.3.1 |
| HEAD | yes | yes | Section 4.3.2 |
| OPTIONS | yes | yes | Section 4.3.7 |
| POST | no | no | Section 4.3.3 |
| PUT | no | yes | Section 4.3.4 |
| TRACE | yes | yes | Section 4.3.8 |
+---------+------+------------+---------------+8.2. Status Code Registry ๐ธ
The "Hypertext Transfer Protocol (HTTP) Status Code Registry" defines the namespace for the response status-code token (Section 6). The status code registry is maintained at <http://www.iana.org/assignments/http-status-codes>.
This section replaces the registration procedure for HTTP Status Codes previously defined in Section 7.1 of [RFC2817]. the glow-up is real ๐
8.2.1. Procedure
A registration MUST include the following fields:
- Status Code (3 digits)
- Short Description
- Pointer to specification text
Values to be added to the HTTP status code namespace require IETF Review (see [RFC5226], Section 4.1). ๐
8.2.2. Considerations for New Status Codes ๐
When it is necessary to express semantics for a response that are not defined by current status codes, a new status code can be registered. Status codes are generic, too; they are potentially applicable to any resource, not just one particular media type, kind of resource, or application of HTTP. So it's preferred that new status codes be registered in a document that isn't specific to a single application.
New status codes are required to fall under one of the categories defined in Section 6. To allow existing parsers to process the response message, new status codes cannot disallow a payload, although they can mandate a zero-length payload body. ๐ซถ
Proposals for new status codes that are not yet widely deployed ought to avoid allocating a specific number for the code until there is clear consensus that it will be registered. Instead, early drafts can use a notation such as "4NN", or "3N0" .. "3N9", to indicate the class of the proposed status code(s) without consuming a number prematurely. not us stealing numbers early ๐
โโ๏ธ
The definition of a new status code ought to explain the request conditions that would cause a response containing that status code (e.g., combinations of request header fields and/or method(s)), along with any dependencies on response header fields (e.g., what fields are required, what fields can modify the semantics, and what header field semantics are further refined when used with the new status code).
The definition of a new status code ought to specify whether or not it is cacheable. Note that all status codes can be cached if the response they occur in has explicit freshness information; however, status codes that are defined as being cacheable are allowed to be cached without explicit freshness information. Likewise, the definition of a status code can place constraints upon cache behavior. See [RFC7234] for more information. ๐ง
Finally, the definition of a new status code ought to indicate whether the payload has any implied association with an identified resource (Section 3.1.4.1). โจ
8.2.3. Registrations ๐ฆ
The status code registry has been updated with the registrations below:
+-------+-------------------------------+----------------+
| Value | Description | Reference |
+-------+-------------------------------+----------------+
| 100 | Continue | Section 6.2.1 |
| 101 | Switching Protocols | Section 6.2.2 |
| 200 | OK | Section 6.3.1 |
| 201 | Created | Section 6.3.2 |
| 202 | Accepted | Section 6.3.3 |
| 203 | Non-Authoritative Information | Section 6.3.4 |
| 204 | No Content | Section 6.3.5 |
| 205 | Reset Content | Section 6.3.6 |
| 300 | Multiple Choices | Section 6.4.1 |
| 301 | Moved Permanently | Section 6.4.2 |
| 302 | Found | Section 6.4.3 |
| 303 | See Other | Section 6.4.4 |
| 305 | Use Proxy | Section 6.4.5 |
| 306 | (Unused) | Section 6.4.6 |
| 307 | Temporary Redirect | Section 6.4.7 |
| 400 | Bad Request | Section 6.5.1 |
| 402 | Payment Required | Section 6.5.2 |
| 403 | Forbidden | Section 6.5.3 |
| 404 | Not Found | Section 6.5.4 |
| 405 | Method Not Allowed | Section 6.5.5 |
| 406 | Not Acceptable | Section 6.5.6 |
| 408 | Request Timeout | Section 6.5.7 |
| 409 | Conflict | Section 6.5.8 |
| 410 | Gone | Section 6.5.9 |
| 411 | Length Required | Section 6.5.10 |
| 413 | Payload Too Large | Section 6.5.11 |
| 414 | URI Too Long | Section 6.5.12 |
| 415 | Unsupported Media Type | Section 6.5.13 |
| 417 | Expectation Failed | Section 6.5.14 |
| 426 | Upgrade Required | Section 6.5.15 |
| 500 | Internal Server Error | Section 6.6.1 |
| 501 | Not Implemented | Section 6.6.2 |
| 502 | Bad Gateway | Section 6.6.3 |
| 503 | Service Unavailable | Section 6.6.4 |
| 504 | Gateway Timeout | Section 6.6.5 |
| 505 | HTTP Version Not Supported | Section 6.6.6 |
+-------+-------------------------------+----------------+8.3. Header Field Registry ๐
HTTP header fields are registered within the "Message Headers" registry located at <http://www.iana.org/assignments/message-headers>, as defined by [BCP90]. ok that's the whole IANA section, periodt ๐
๐
8.3.1. Considerations for New Header Fields โจ
Okay so header fields are basically key:value pairs that carry info about the message, its payload, the target resource, or the connection (aka control data) ๐. For the general definition of header field syntax in HTTP messages, check Section 3.2 of [RFC7230] ๐.
The rules for header field names live in [BCP90] ๐.
Authors writing specs for brand-new fields are advised to keep the name as short as practical, and to skip the X- prefix unless the field will never be used on the Internet ๐ซถ. Honestly the X- thing got SO misused in real life ๐. It was only ever meant for dodging name collisions inside proprietary software or intranet processing, since the prefix means private names never collide with a newly registered Internet name. See [BCP178] for the full tea ๐ต.
New header field values usually get their syntax defined with ABNF ([RFC5234]), using the extension from Section 7 of [RFC7230] when needed, and they're normally limited to US-ASCII characters ๐ค. Fields that need a wider range of characters can use an encoding like the one in [RFC5987] ๐.
Leading and trailing whitespace in raw field values gets removed when the field is parsed (Section 3.2.4 of [RFC7230]) โ๏ธ. Fields where that edge whitespace actually matters will need a container syntax like quoted-string (Section 3.2.6 of [RFC7230]) ๐.
Commas are the generic delimiter between field-values, so they need extra care if they're allowed inside a field-value ๐. Usually, anything that might contain a comma gets protected with double-quotes using the quoted-string production ๐. For example, a textual date and a URI (either of which might contain a comma) could be safely carried in field-values like these:
Example-URI-Field: "http://example.com/a.html,foo",
"http://without-a-comma.example.com/"
Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005"Double-quote delimiters almost always go with the quoted-string production. Using a different syntax inside double-quotes will likely cause unnecessary confusion ๐
Lots of header fields use a format with named parameters (case-insensitively), like Content-Type from Section 3.1.1.5 ๐ง. Allowing both unquoted (token) and quoted (quoted-string) syntax for the parameter value lets recipients reuse existing parser components ๐ง. When both forms are allowed, the meaning of a parameter value ought to be independent of which syntax was used. For an example, see the notes on parameter handling for media types in Section 3.1.1.1 ๐ธ.
Authors of specs defining new header fields are advised to consider documenting the following:
- Whether the field is a single value or whether it can be a list (delimited by commas; see Section 3.2 of [RFC7230]).
If it does not use the list syntax, document how to treat messages where the field occurs multiple times (a sensible default would be to ignore the field, but this might not always be the right choice) ๐ค.
Note that intermediaries and software libraries might combine multiple header field instances into a single one, even if the field's definition doesn't allow the list syntax ๐ง. A robust format lets recipients figure out when this happened. Good example: "Content-Type", since the comma can only appear inside quoted strings. Bad example: "Location", since a comma can occur inside a URI ๐.
- Under what conditions the header field can be used, e.g., only in responses or requests, in all messages, only on responses to a particular request method, etc. ๐ฏ
- Whether the field should be stored by origin servers that understand it upon a PUT request ๐พ.
- Whether the field semantics are further refined by the context, such as by existing request methods or status codes ๐.
- Whether it is appropriate to list the field-name in the Connection header field (i.e., if the header field is to be hop-by-hop; see Section 6.1 of [RFC7230]) ๐.
- Under what conditions intermediaries are allowed to insert, delete, or modify the field's value ๐ต๏ธ.
- Whether it is appropriate to list the field-name in a Vary response header field (e.g., when the request header field is used by an origin server's content selection algorithm; see Section 7.1.4) ๐ฆ.
- Whether the header field is useful or allowable in trailers (see Section 4.1 of [RFC7230]) ๐.
- Whether the header field ought to be preserved across redirects ๐.
- Whether it introduces any additional security considerations, such as disclosure of privacy-related data ๐.
8.3.2. Registrations ๐
The "Message Headers" registry has been updated with the following permanent registrations ๐:
+-------------------+----------+----------+-----------------+
| Header Field Name | Protocol | Status | Reference |
+-------------------+----------+----------+-----------------+
| Accept | http | standard | Section 5.3.2 |
| Accept-Charset | http | standard | Section 5.3.3 |
| Accept-Encoding | http | standard | Section 5.3.4 |
| Accept-Language | http | standard | Section 5.3.5 |
| Allow | http | standard | Section 7.4.1 |
| Content-Encoding | http | standard | Section 3.1.2.2 |
| Content-Language | http | standard | Section 3.1.3.2 |
| Content-Location | http | standard | Section 3.1.4.2 |
| Content-Type | http | standard | Section 3.1.1.5 |
| Date | http | standard | Section 7.1.1.2 |
| Expect | http | standard | Section 5.1.1 |
| From | http | standard | Section 5.5.1 |
| Location | http | standard | Section 7.1.2 |
| Max-Forwards | http | standard | Section 5.1.2 |
| MIME-Version | http | standard | Appendix A.1 |
| Referer | http | standard | Section 5.5.2 |
| Retry-After | http | standard | Section 7.1.3 |
| Server | http | standard | Section 7.4.2 |
| User-Agent | http | standard | Section 5.5.3 |
| Vary | http | standard | Section 7.1.4 |
+-------------------+----------+----------+-----------------+The change controller for the above registrations is: "IETF (iesg@ietf.org) - Internet Engineering Task Force" ๐งโโ๏ธ.
8.4. Content Coding Registry ๐จ
The "HTTP Content Coding Registry" defines the namespace for content coding names (Section 4.2 of [RFC7230]) ๐. The content coding registry is maintained at <http://www.iana.org/assignments/http-parameters> ๐.
8.4.1. Procedure ๐
Content coding registrations MUST include the following fields:
- Name
- Description
- Pointer to specification text
Names of content codings MUST NOT overlap with names of transfer codings (Section 4 of [RFC7230]), unless the encoding transformation is identical (as is the case for the compression codings defined in Section 4.2 of [RFC7230]) ๐ โโ๏ธ. Basically, no name clashes unless it's the exact same transformation ๐ .
Values to be added to this namespace require IETF Review (see Section 4.1 of [RFC5226]) and MUST conform to the purpose of content coding defined in this section ๐.
8.4.2. Registrations ๐
The "HTTP Content Coding Registry" has been updated with the registrations below โญ:
+----------+----------------------------------------+---------------+
| Name | Description | Reference |
+----------+----------------------------------------+---------------+
| identity | Reserved (synonym for "no encoding" in | Section 5.3.4 |
| | Accept-Encoding) | |
+----------+----------------------------------------+---------------+9. Security Considerations ๐
This section is here to inform developers, information providers, and users about known security concerns relevant to HTTP semantics and using HTTP to move information across the Internet ๐ก๏ธ. Considerations about message syntax, parsing, and routing are covered in Section 9 of [RFC7230] ๐ฆ.
The list below is not exhaustive, bestie ๐. Most security concerns with HTTP semantics are about securing server-side applications (the code sitting behind the HTTP interface), securing user agent processing of payloads received over HTTP, or secure use of the Internet in general, rather than security of the protocol itself ๐ป. Various organizations keep topical info and links to current research on Web application security (e.g., [OWASP]) ๐.
9.1. Attacks Based on File and Path Names ๐
Origin servers often use their local file system to map from the effective request URI to resource representations ๐๏ธ. Most file systems weren't designed to guard against malicious file or path names ๐ฌ. So an origin server needs to avoid touching names that have special significance to the system when mapping the request target to files, folders, or directories ๐ซ.
For example, UNIX, Microsoft Windows, and other operating systems use ".." as a path component meaning one directory level up, and they use specially named paths or file names to send data to system devices ๐ณ๏ธ. Other storage systems might have similar naming conventions too. Local storage systems also have an annoying tendency to prefer user-friendliness over security when handling invalid or unexpected characters, recomposing decomposed characters, and case-normalizing case-insensitive names ๐.
Attacks using these special names usually aim at either denial-of-service (e.g., telling the server to read from a COM port) ๐ฅ or disclosing configuration and source files that were never meant to be served ๐ซฃ.
9.2. Attacks Based on Command, Code, or Query Injection ๐
Origin servers often use parameters within the URI to identify system services, select database entries, or pick a data source ๐๏ธ. But data received in a request cannot be trusted ๐จ. An attacker could build any of the request data elements (method, request-target, header fields, or body) to contain data that might get misread as a command, code, or query when passed through a command invocation, language interpreter, or database interface ๐.
For example, SQL injection is a classic attack where extra query language gets slipped into some part of the request-target or header fields (e.g., Host, Referer, etc.) ๐ฏ. If the received data goes straight into a SELECT statement, the query language might be run as a database command instead of being treated as a simple string value ๐ฑ. This kind of implementation vulnerability is extremely common, even though it's super easy to prevent ๐คฆโโ๏ธ.
In general, resource implementations ought to avoid using request data in contexts that get processed or interpreted as instructions โ. Parameters ought to be compared to fixed strings, and then acted upon based on that comparison, rather than passed through an interface that isn't ready for untrusted data ๐. Received data that isn't based on fixed parameters ought to be carefully filtered or encoded so it doesn't get misinterpreted ๐งผ.
Similar considerations apply to request data when it's stored and processed later, such as in log files, monitoring tools, or when included in a data format that allows embedded scripts ๐๐.
9.3. Disclosure of Personal Information ๐
Okay bestie, clients are literally privy to SO much personal info ๐ซฃ. That includes what the user types in to interact with resources (their name, location, mail address, passwords, encryption keys, etc.) and info about their browsing activity over time (history, bookmarks, etc.) ๐ . Implementations need to prevent unintentional disclosure of personal information ๐.
9.4. Disclosure of Sensitive Information in URIs ๐
URIs are meant to be shared, not secured, even when they identify secure resources ๐. They get shown on displays, added to templates when a page is printed, and stashed in all kinds of unprotected bookmark lists ๐. So it's unwise to put anything sensitive, personally identifiable, or risky to disclose inside a URI ๐ซ.
Authors of services ought to avoid GET-based forms for submitting sensitive data, because that data ends up in the request-target ๐ฌ. Lots of existing servers, proxies, and user agents log or display the request-target in places where third parties might see it ๐. Those services ought to use POST-based form submission instead ๐.
Since the Referer header field tells a target site about the context that resulted in a request, it can reveal the user's immediate browsing history and any personal info in the referring resource's URI ๐ต๏ธโโ๏ธ. Limitations on the Referer header field are described in Section 5.5.2 to address some of its security considerations ๐ก๏ธ.
9.5. Disclosure of Fragment after Redirects ๐งฉ
Fragment identifiers used within URI references aren't sent in requests, but implementers ought to be aware that they're visible to the user agent and any extensions or scripts running as a result of the response ๐๏ธ. The tricky bit is when a redirect happens and the original request's fragment is inherited by the new reference in Location (Section 7.1.2). That can end up disclosing one site's fragment to another site ๐ฑ. If the first site uses personal info in fragments, it ought to make sure its redirects to other sites include a (possibly empty) fragment component, so that inheritance gets blocked ๐ง.
9.6. Disclosure of Product Information ๐ท๏ธ
The User-Agent (Section 5.5.3), Via (Section 5.7.1 of [RFC7230]), and Server (Section 7.4.2) header fields often reveal info about the respective sender's software systems ๐ฅ๏ธ. In theory, that can make it easier for an attacker to exploit known security holes. In practice though, attackers tend to try all potential holes regardless of the apparent software versions being used ๐คทโโ๏ธ.
Proxies that serve as a portal through a network firewall ought to take special precautions about transferring header info that might identify hosts behind the firewall ๐งฑ. The Via header field allows intermediaries to replace sensitive machine names with pseudonyms ๐ญ.
9.7. Browser Fingerprinting ๐ต๏ธ
Browser fingerprinting is a set of techniques for identifying a specific user agent over time through its unique set of characteristics ๐. These might include info about its TCP behavior, feature capabilities, and scripting environment, though what's of particular interest here is the set of unique characteristics that might be communicated via HTTP ๐. Fingerprinting is a privacy concern because it enables tracking a user agent's behavior over time without the controls the user might have over other forms of data collection (e.g., cookies) ๐จ. Many general-purpose user agents (i.e., Web browsers) have taken steps to reduce their fingerprints ๐งผ.
There are a number of request header fields that might reveal info to servers that's unique enough to enable fingerprinting ๐งพ. The From header field is the most obvious, though it's expected that From will only be sent when the user wants self-identification ๐. Likewise, Cookie header fields are deliberately designed to enable re-identification, so fingerprinting concerns only apply to situations where cookies are disabled or restricted by the user agent's configuration ๐ช.
The User-Agent header field might contain enough info to uniquely identify a specific device, usually when combined with other characteristics, particularly if the user agent sends excessive details about the user's system or extensions ๐ฑ. However, the source of unique info that's least expected by users is proactive negotiation (Section 5.3), including the Accept, Accept-Charset, Accept-Encoding, and Accept-Language header fields ๐ณ.
Beyond the fingerprinting concern, detailed use of the Accept-Language header field can reveal info the user might consider private ๐ซข. For example, understanding a given language set might be strongly correlated to membership in a particular ethnic group ๐. An approach that limits that loss of privacy would be for a user agent to omit sending Accept-Language except for sites that have been whitelisted, perhaps via interaction after detecting a Vary header field that indicates language negotiation might be useful ๐.
In environments where proxies are used to enhance privacy, user agents ought to be conservative about sending proactive negotiation header fields ๐ก๏ธ. General-purpose user agents that offer a high degree of header field configurability ought to inform users about the loss of privacy that might result if too much detail is provided ๐ฃ. As an extreme privacy measure, proxies could filter the proactive negotiation header fields in relayed requests ๐งน.
10. Acknowledgments ๐ซถ
See Section 10 of [RFC7230].
11. References ๐
11.1. Normative References
- [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996.
- [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, November 1996.
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005.
- [RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of Language Tags", BCP 47, RFC 4647, September 2006.
- [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008.
- [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, September 2009.
- [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in Internationalization in the IETF", BCP 166, RFC 6365, September 2011.
- [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 2014.
- [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests", RFC 7232, June 2014.
- [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, June 2014.
- [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", RFC 7234, June 2014.
- [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, June 2014.
11.2. Informative References ๐
- [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, January 2013.
- [BCP178] Saint-Andre, P., Crocker, D., and M. Nottingham, "Deprecating the "X-" Prefix and Similar Constructs in Application Protocols", BCP 178, RFC 6648, June 2012.
- [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration Procedures for Message Header Fields", BCP 90, RFC 3864, September 2004.
- [OWASP] van der Stock, A., Ed., "A Guide to Building Secure Web Applications and Web Services", The Open Web Application Security Project (OWASP) 2.0.1, July 2005,
<https://www.owasp.org/>. - [REST] Fielding, R., "Architectural Styles and the Design of Network-based Software Architectures", Doctoral Dissertation, University of California, Irvine, September 2000,
<http://roy.gbiv.com/pubs/dissertation/top.htm>. - [RFC1945] Berners-Lee, T., Fielding, R., and H. Nielsen, "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945, May 1996.
- [RFC2049] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples", RFC 2049, November 1996.
- [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, January 1997.
- [RFC2295] Holtman, K. and A. Mutz, "Transparent Content Negotiation in HTTP", RFC 2295, March 1998.
- [RFC2388] Masinter, L., "Returning Values from Forms: multipart/form-data", RFC 2388, August 1998.
- [RFC2557] Palme, F., Hopmann, A., Shelness, N., and E. Stefferud, "MIME Encapsulation of Aggregate Documents, such as HTML (MHTML)", RFC 2557, March 1999.
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
- [RFC2774] Frystyk, H., Leach, P., and S. Lawrence, "An HTTP Extension Framework", RFC 2774, February 2000.
- [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1", RFC 2817, May 2000.
- [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration Procedures", BCP 19, RFC 2978, October 2000.
- [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008.
- [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008.
- [RFC5322] Resnick, P., "Internet Message Format", RFC 5322, October 2008.
- [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, March 2010.
- [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, "Network Time Protocol Version 4: Protocol and Algorithms Specification", RFC 5905, June 2010.
- [RFC5987] Reschke, J., "Character Set and Language Encoding for Hypertext Transfer Protocol (HTTP) Header Field Parameters", RFC 5987, August 2010.
- [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
- [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, April 2011.
- [RFC6266] Reschke, J., "Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)", RFC 6266, June 2011.
- [RFC7238] Reschke, J., "The Hypertext Transfer Protocol (HTTP) Status Code 308 (Permanent Redirect)", RFC 7238, June 2014.
Appendix A. Differences between HTTP and MIME ๐ฆ
HTTP/1.1 borrows a bunch of constructs from the Internet Message Format [RFC5322] and the Multipurpose Internet Mail Extensions (MIME) [RFC2045], so a message body can show up in an open variety of representations with extensible header fields. But okay, here's the tea: [RFC2045] is only about email, and HTTP apps are super different from email, so HTTP has features that don't match MIME. Those choices were intentional ๐ . They help performance over binary connections, give new media types more freedom, make date comparisons easier, and acknowledge what some early HTTP servers and clients were already doing.
This appendix spells out the specific areas where HTTP differs from MIME. Proxies and gateways going to and from strict MIME environments need to know about these differences and do the right conversions where necessary โจ.
A.1. MIME-Version
HTTP is not a MIME-compliant protocol ๐
. However, messages can include a single MIME-Version header field to say which version of the MIME protocol was used to build the message. Using the MIME-Version header field means the message is in full conformance with the MIME protocol (as defined in [RFC2045]). Senders are responsible for making sure of full conformance (where possible) when they export HTTP messages to strict MIME environments ๐.
A.2. Conversion to Canonical Form
MIME requires that an Internet mail body part be converted to canonical form before it gets transferred, as described in Section 4 of [RFC2049]. Section 3.1.1.3 of this document describes the forms allowed for subtypes of the "text" media type when transmitted over HTTP. [RFC2046] requires that content with a type of "text" represent line breaks as CRLF, and it forbids the use of CR or LF outside of line break sequences. HTTP allows CRLF, bare CR, and bare LF to indicate a line break within text content ๐ธ.
A proxy or gateway from HTTP to a strict MIME environment ought to translate all line breaks within the text media types described in Section 3.1.1.3 of this document to the RFC 2049 canonical form of CRLF. Note, however, that this might get complicated by the presence of a Content-Encoding, and by the fact that HTTP allows the use of some charsets that do not use octets 13 and 10 to represent CR and LF, respectively ๐.
Conversion will break any cryptographic checksums applied to the original content unless the original content is already in canonical form. So the canonical form is recommended for any content that uses such checksums in HTTP ๐ฅ.
A.3. Conversion of Date Formats
HTTP/1.1 uses a restricted set of date formats (Section 7.1.1.1) to simplify the process of date comparison, which is so iconic of it ๐ง. Proxies and gateways from other protocols ought to make sure that any Date header field present in a message conforms to one of the HTTP/1.1 formats, and rewrite the date if necessary.
A.4. Conversion of Content-Encoding
MIME does not include any concept equivalent to HTTP/1.1's Content-Encoding header field. Since this acts as a modifier on the media type, proxies and gateways from HTTP to MIME-compliant protocols ought to either change the value of the Content-Type header field or decode the representation before forwarding the message ๐. (Some experimental applications of Content-Type for Internet mail have used a media-type parameter of ;conversions=<content-coding> to perform a function equivalent to Content-Encoding. However, this parameter is not part of the MIME standards ๐.)
A.5. Conversion of Content-Transfer-Encoding
HTTP does not use the Content-Transfer-Encoding field of MIME ๐
. Proxies and gateways from MIME-compliant protocols to HTTP need to remove any Content-Transfer-Encoding prior to delivering the response message to an HTTP client.
Proxies and gateways from HTTP to MIME-compliant protocols are responsible for ensuring that the message is in the correct format and encoding for safe transport on that protocol, where "safe transport" is defined by the limitations of the protocol being used ๐. Such a proxy or gateway ought to transform and label the data with an appropriate Content-Transfer-Encoding if doing so will improve the likelihood of safe transport over the destination protocol ๐ซถ.
A.6. MHTML and Line Length Limitations
HTTP implementations that share code with MHTML [RFC2557] implementations need to be aware of MIME line length limitations. Since HTTP does not have this limitation, HTTP does not fold long lines ๐. MHTML messages being transported by HTTP follow all conventions of MHTML, including line length limitations and folding, canonicalization, etc., since HTTP transfers message-bodies as payload. Aside from the "multipart/byteranges" type (Appendix A of [RFC7233]), HTTP does not interpret the content or any MIME header lines that might be contained therein ๐ฆ.
Appendix B. Changes from RFC 2616 ๐
okay so the big glow-up in this revision is mostly editorial, bestie ๐ง the messaging syntax got pulled out into its own doc, and HTTP semantics got split up into separate docs for the core features, conditional requests, partial requests, caching, and authentication. ๐ The conformance language got tightened so it clearly targets requirements, and the terminology got cleaned up so payload, representations, and resources are all distinct things now. no more mixing them up ๐ญ
Here's the tea on the actual changes, section by section โจ
A new requirement says that semantics embedded in a URI should be turned off when they don't match the request method, because apparently this is a super common reason things break between implementations ๐ (Section 2)
There's a new algorithm for figuring out whether a payload is associated with a specific identifier ๐ฅ (Section 3.1.4.1)
The default charset of ISO-8859-1 for text media types is gone ๐ now the default is whatever the media type definition says. Special treatment of ISO-8859-1 got removed from the Accept-Charset header field too, so it's giving "no more special cases" ๐ (Section 3.1.1.3 and Section 5.3.3)
Content-Location no longer changes the base URI for resolving relative URI references ๐ฆ this happened because implementations barely supported it, and it could break relative links in content-negotiated resources, which is a whole mess ๐ญ (Section 3.1.4.2)
The definition of GET got relaxed so requests can have a body ๐ this is to match the method-neutral parsing algorithm of [RFC7230], even though a body has no real meaning for GET ๐คทโโ๏ธ (Section 4.3.1)
Servers aren't required to handle every Content-* header field anymore ๐ซถ and Content-Range is officially banned in PUT requests ๐ซ (Section 4.3.4)
The CONNECT method definition moved over here from [RFC2817] ๐ (Section 4.3.6)
OPTIONS and TRACE are now defined as safe methods โจ (Section 4.3.7 and Section 4.3.8)
The Expect header field's extension mechanism got removed because too many widely deployed implementations were broken ๐ (Section 5.1.1)
Max-Forwards is now restricted to OPTIONS and TRACE ๐ before this, extension methods could use it too (Section 5.1.2)
"about:blank" is suggested as a Referer value when there's no referring URI that applies ๐ธ this lets you tell that case apart from the ones where Referer isn't sent or got removed (Section 5.5.2)
These status codes are now cacheable, meaning a cache can store and reuse them even without explicit freshness info: 204, 404, 405, 414, 501 ๐ฅ (Section 6)
The 201 (Created) description now allows for more than one resource being created at once ๐ (Section 6.3.2)
203 (Non-Authoritative Information) got broadened to cover payload transformations too โจ (Section 6.3.4)
The set of request methods that are safe to automatically redirect is no longer a closed list ๐ฆ user agents can work that out from the method semantics instead. Also, the redirect status codes 301, 302, and 307 don't have normative requirements on response payloads or user interaction anymore ๐ (Section 6.4)
301 and 302 now let user agents rewrite POST to GET ๐ง (Sections 6.4.2 and 6.4.3)
The 303 (See Other) description changed so it can be cached if explicit freshness info is given, and there's a specific definition for a 303 response to GET ๐ (Section 6.4.4)
305 (Use Proxy) is deprecated because of security concerns about configuring a proxy in-band ๐จ (Section 6.4.5)
400 (Bad Request) isn't limited to syntax errors anymore ๐ (Section 6.5.1)
426 (Upgrade Required) got brought in from [RFC2817] ๐ซถ (Section 6.5.15)
The requirements on HTTP-date and the Date header field now only target the systems that generate the date, not every system that sends one ๐ (Section 7.1.1)
Location's syntax now allows all URI references, including relative references and fragments ๐ there are also some clarifications about when fragments wouldn't be a good fit โจ (Section 7.1.2)
Allow got reclassified as a response header field, so it can't be specified in a PUT request anymore ๐ โโ๏ธ the requirements about what Allow contains got relaxed too, which means clients don't have to always trust its value ๐ธ (Section 7.4.1)
A Method Registry is defined now ๐ฅ (Section 8.1)
The Status Code Registry got redefined by this spec ๐ before, it lived in Section 7.1 of [RFC2817] (Section 8.2)
Registering content codings now needs IETF Review ๐ (Section 8.4)
Content-Disposition got removed from this doc because [RFC6266] defines it now ๐ฆ
Content-MD5 got removed too ๐ it was inconsistently implemented when it came to partial responses, so it's gone
Appendix C. Imported ABNF ๐
the following core rules are included by reference, as defined in Appendix B.1 of [RFC5234] ๐ง ALPHA (letters), CR (carriage return), CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF (line feed), OCTET (any 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII character) โจ
the rules below are defined in [RFC7230] ๐
BWS = <BWS, see [RFC7230], Section 3.2.3>
OWS = <OWS, see [RFC7230], Section 3.2.3>
RWS = <RWS, see [RFC7230], Section 3.2.3>
URI-reference = <URI-reference, see [RFC7230], Section 2.7>
absolute-URI = <absolute-URI, see [RFC7230], Section 2.7>
comment = <comment, see [RFC7230], Section 3.2.6>
field-name = <comment, see [RFC7230], Section 3.2>
partial-URI = <partial-URI, see [RFC7230], Section 2.7>
quoted-string = <quoted-string, see [RFC7230], Section 3.2.6>
token = <token, see [RFC7230], Section 3.2.6>Appendix D. Collected ABNF ๐ธ
in the collected ABNF below, list rules get expanded as per Section 1.2 of [RFC7230] ๐
Accept = [ ( "," / ( media-range [ accept-params ] ) ) *( OWS "," [
OWS ( media-range [ accept-params ] ) ] ) ]
Accept-Charset = *( "," OWS ) ( ( charset / "*" ) [ weight ] ) *( OWS
"," [ OWS ( ( charset / "*" ) [ weight ] ) ] )
Accept-Encoding = [ ( "," / ( codings [ weight ] ) ) *( OWS "," [ OWS
( codings [ weight ] ) ] ) ]
Accept-Language = *( "," OWS ) ( language-range [ weight ] ) *( OWS
"," [ OWS ( language-range [ weight ] ) ] )
Allow = [ ( "," / method ) *( OWS "," [ OWS method ] ) ]
BWS = <BWS, see [RFC7230], Section 3.2.3>
Content-Encoding = *( "," OWS ) content-coding *( OWS "," [ OWS
content-coding ] )
Content-Language = *( "," OWS ) language-tag *( OWS "," [ OWS
language-tag ] )
Content-Location = absolute-URI / partial-URI
Content-Type = media-type
Date = HTTP-date
Expect = "100-continue"
From = mailbox
GMT = %x47.4D.54 ; GMT
HTTP-date = IMF-fixdate / obs-date
IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT
Location = URI-reference
Max-Forwards = 1*DIGIT
OWS = <OWS, see [RFC7230], Section 3.2.3>
RWS = <RWS, see [RFC7230], Section 3.2.3>
Referer = absolute-URI / partial-URI
Retry-After = HTTP-date / delay-seconds
Server = product *( RWS ( product / comment ) )
URI-reference = <URI-reference, see [RFC7230], Section 2.7>
User-Agent = product *( RWS ( product / comment ) )
Vary = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name ]
) )
absolute-URI = <absolute-URI, see [RFC7230], Section 2.7>
accept-ext = OWS ";" OWS token [ "=" ( token / quoted-string ) ]
accept-params = weight *accept-ext
asctime-date = day-name SP date3 SP time-of-day SP year
charset = token
codings = content-coding / "identity" / "*"
comment = <comment, see [RFC7230], Section 3.2.6>
content-coding = token
date1 = day SP month SP year
date2 = day "-" month "-" 2DIGIT
date3 = month SP ( 2DIGIT / ( SP DIGIT ) )
day = 2DIGIT
day-name = %x4D.6F.6E ; Mon
/ %x54.75.65 ; Tue
/ %x57.65.64 ; Wed
/ %x54.68.75 ; Thu
/ %x46.72.69 ; Fri
/ %x53.61.74 ; Sat
/ %x53.75.6E ; Sun
day-name-l = %x4D.6F.6E.64.61.79 ; Monday
/ %x54.75.65.73.64.61.79 ; Tuesday
/ %x57.65.64.6E.65.73.64.61.79 ; Wednesday
/ %x54.68.75.72.73.64.61.79 ; Thursday
/ %x46.72.69.64.61.79 ; Friday
/ %x53.61.74.75.72.64.61.79 ; Saturday
/ %x53.75.6E.64.61.79 ; Sunday
delay-seconds = 1*DIGIT
field-name = <comment, see [RFC7230], Section 3.2>
hour = 2DIGIT
language-range = <language-range, see [RFC4647], Section 2.1>
language-tag = <Language-Tag, see [RFC5646], Section 2.1>
mailbox = <mailbox, see [RFC5322], Section 3.4>
media-range = ( "*/*" / ( type "/*" ) / ( type "/" subtype ) ) *( OWS
";" OWS parameter )
media-type = type "/" subtype *( OWS ";" OWS parameter )
method = token
minute = 2DIGIT
month = %x4A.61.6E ; Jan
/ %x46.65.62 ; Feb
/ %x4D.61.72 ; Mar
/ %x41.70.72 ; Apr
/ %x4D.61.79 ; May
/ %x4A.75.6E ; Jun
/ %x4A.75.6C ; Jul
/ %x41.75.67 ; Aug
/ %x53.65.70 ; Sep
/ %x4F.63.74 ; Oct
/ %x4E.6F.76 ; Nov
/ %x44.65.63 ; Dec
obs-date = rfc850-date / asctime-date
parameter = token "=" ( token / quoted-string )
partial-URI = <partial-URI, see [RFC7230], Section 2.7>
product = token [ "/" product-version ]
product-version = token
quoted-string = <quoted-string, see [RFC7230], Section 3.2.6>
qvalue = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] )
rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT
second = 2DIGIT
subtype = token
time-of-day = hour ":" minute ":" second
token = <token, see [RFC7230], Section 3.2.6>
type = token
weight = OWS ";" OWS "q=" qvalue
year = 4DIGITIndex โจ
Okay bestie, this is the lookup table for the whole spec ๐ง Every status code class, header field, method, and grammar rule, with the page where it lives. Let's go ๐
1
1xx Informational (status code class) 50
2
2xx Successful (status code class) 51
3
3xx Redirection (status code class) 54
4
4xx Client Error (status code class) 58
5
5xx Server Error (status code class) 62
1
100 Continue (status code) 50
100-continue (expect value) 34
101 Switching Protocols (status code) 50
2
200 OK (status code) 51
201 Created (status code) 52
202 Accepted (status code) 52
203 Non-Authoritative Information (status code) 52
204 No Content (status code) 53
205 Reset Content (status code) 53
3
300 Multiple Choices (status code) 55
301 Moved Permanently (status code) 56
302 Found (status code) 56
303 See Other (status code) 57
305 Use Proxy (status code) 58
306 (Unused) (status code) 58
307 Temporary Redirect (status code) 58
4
400 Bad Request (status code) 58
402 Payment Required (status code) 59
403 Forbidden (status code) 59
404 Not Found (status code) 59
405 Method Not Allowed (status code) 59
406 Not Acceptable (status code) 59
408 Request Timeout (status code) 60
409 Conflict (status code) 60
410 Gone (status code) 60
411 Length Required (status code) 61
413 Payload Too Large (status code) 61
414 URI Too Long (status code) 61
415 Unsupported Media Type (status code) 62
417 Expectation Failed (status code) 62
426 Upgrade Required (status code) 62
5
500 Internal Server Error (status code) 63
501 Not Implemented (status code) 63
502 Bad Gateway (status code) 63
503 Service Unavailable (status code) 63
504 Gateway Timeout (status code) 63
505 HTTP Version Not Supported (status code) 64
A
Accept header field 38
Accept-Charset header field 40
Accept-Encoding header field 41
Accept-Language header field 42
Allow header field 72
C
cacheable 24
compress (content coding) 11
conditional request 36
CONNECT method 30
content coding 11
content negotiation 6
Content-Encoding header field 12
Content-Language header field 13
Content-Location header field 15
Content-Transfer-Encoding header field 89
Content-Type header field 10
D
Date header field 67
deflate (content coding) 11
DELETE method 29
E
Expect header field 34
F
From header field 44
G
GET method 24
Grammar
Accept 38
Accept-Charset 40
Accept-Encoding 41
accept-ext 38
Accept-Language 42
accept-params 38
Allow 72
asctime-date 66
charset 9
codings 41
content-coding 11
Content-Encoding 12
Content-Language 13
Content-Location 15
Content-Type 10
Date 67
date1 65
day 65
day-name 65
day-name-l 65
delay-seconds 69
Expect 34
From 44
GMT 65
hour 65
HTTP-date 65
IMF-fixdate 65
language-range 42
language-tag 13
Location 68
Max-Forwards 36
media-range 38
media-type 8
method 21
minute 65
month 65
obs-date 66
parameter 8
product 46
product-version 46
qvalue 38
Referer 45
Retry-After 69
rfc850-date 66
second 65
Server 73
subtype 8
time-of-day 65
type 8
User-Agent 46
Vary 70
weight 38
year 65
gzip (content coding) 11
H
HEAD method 25
I
idempotent 23
L
Location header field 68
M
Max-Forwards header field 36
MIME-Version header field 89
O
OPTIONS method 31
P
payload 17
POST method 25
PUT method 26
R
Referer header field 45
representation 7
Retry-After header field 69
S
safe 22
selected representation 7, 71
Server header field 73
Status Codes Classes
1xx Informational 50
2xx Successful 51
3xx Redirection 54
4xx Client Error 58
5xx Server Error 62
T
TRACE method 32
U
User-Agent header field 46
V
Vary header field 70
X
x-compress (content coding) 11
x-gzip (content coding) 11Authors' Addresses ๐ฆ
Last but not least, here's who wrote this thing and how to reach them. Slay the paperwork ๐
Roy T. Fielding (editor)
Adobe Systems Incorporated
345 Park Ave
San Jose, CA 95110
USA
EMail: fielding@gbiv.com
URI: http://roy.gbiv.com/
Julian F. Reschke (editor)
greenbytes GmbH
Hafenweg 16
Muenster, NW 48155
Germany
EMail: julian.reschke@greenbytes.de
URI: http://greenbytes.de/tech/webdav/That's the whole RFC, bestie ๐โจ Literally iconic work from the editors ๐๐ซถ
๐ฆ where this page comes from
- ietf: rfc7231 2014-06
- ๐ girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms