frankenRFC723x_sem.txt | draft-ietf-httpbis-semantics-06.txt | |||
---|---|---|---|---|
Internet Engineering Task Force (IETF) R. Fielding, Ed. | HTTP Working Group R. Fielding, Ed. | |||
Request for Comments: 7231 Adobe | Internet-Draft Adobe | |||
Obsoletes: 2616 J. Reschke, Ed. | Obsoletes: M. Nottingham, Ed. | |||
Updates: 2817 greenbytes | 2818,7230,7231,7232,7233,7235 Fastly | |||
Category: Standards Track June 2014 | ,7538,7615 (if approved) J. Reschke, Ed. | |||
ISSN: 2070-1721 | Intended status: Standards Track greenbytes | |||
Expires: May 7, 2020 November 4, 2019 | ||||
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content | HTTP Semantics | |||
draft-ietf-httpbis-semantics-06 | ||||
Abstract | Abstract | |||
The Hypertext Transfer Protocol (HTTP) is a stateless application- | The Hypertext Transfer Protocol (HTTP) is a stateless application- | |||
level protocol for distributed, collaborative, hypertext information | level protocol for distributed, collaborative, hypertext information | |||
systems. This document defines the semantics of HTTP/1.1 messages, | systems. This document defines the semantics of HTTP: its | |||
as expressed by request methods, request header fields, response | architecture, terminology, the "http" and "https" Uniform Resource | |||
status codes, and response header fields, along with the payload of | Identifier (URI) schemes, core request methods, request header | |||
messages (metadata and body content) and mechanisms for content | fields, response status codes, response header fields, and content | |||
negotiation. | negotiation. | |||
This document obsoletes RFC 2818, RFC 7231, RFC 7232, RFC 7233, RFC | ||||
7235, RFC 7538, RFC 7615, and portions of RFC 7230. | ||||
Editorial Note | ||||
This note is to be removed before publishing as an RFC. | ||||
Discussion of this draft takes place on the HTTP working group | ||||
mailing list (ietf-http-wg@w3.org), which is archived at | ||||
<https://lists.w3.org/Archives/Public/ietf-http-wg/>. | ||||
Working Group information can be found at <https://httpwg.org/>; | ||||
source code and issues list for this draft can be found at | ||||
<https://github.com/httpwg/http-core>. | ||||
The changes in this draft are summarized in Appendix J.7. | ||||
Status of This Memo | Status of This Memo | |||
This is an Internet Standards Track document. | This Internet-Draft is submitted in full conformance with the | |||
provisions of BCP 78 and BCP 79. | ||||
This document is a product of the Internet Engineering Task Force | Internet-Drafts are working documents of the Internet Engineering | |||
(IETF). It represents the consensus of the IETF community. It has | Task Force (IETF). Note that other groups may also distribute | |||
received public review and has been approved for publication by the | working documents as Internet-Drafts. The list of current Internet- | |||
Internet Engineering Steering Group (IESG). Further information on | Drafts is at https://datatracker.ietf.org/drafts/current/. | |||
Internet Standards is available in Section 2 of RFC 5741. | ||||
Information about the current status of this document, any errata, | Internet-Drafts are draft documents valid for a maximum of six months | |||
and how to provide feedback on it may be obtained at | and may be updated, replaced, or obsoleted by other documents at any | |||
http://www.rfc-editor.org/info/rfc7231. | time. It is inappropriate to use Internet-Drafts as reference | |||
material or to cite them other than as "work in progress." | ||||
This Internet-Draft will expire on May 7, 2020. | ||||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2014 IETF Trust and the persons identified as the | Copyright (c) 2019 IETF Trust and the persons identified as the | |||
document authors. All rights reserved. | document authors. All rights reserved. | |||
This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
Provisions Relating to IETF Documents | Provisions Relating to IETF Documents | |||
(http://trustee.ietf.org/license-info) in effect on the date of | (https://trustee.ietf.org/license-info) in effect on the date of | |||
publication of this document. Please review these documents | publication of this document. Please review these documents | |||
carefully, as they describe your rights and restrictions with respect | carefully, as they describe your rights and restrictions with respect | |||
to this document. Code Components extracted from this document must | to this document. Code Components extracted from this document must | |||
include Simplified BSD License text as described in Section 4.e of | include Simplified BSD License text as described in Section 4.e of | |||
the Trust Legal Provisions and are provided without warranty as | the Trust Legal Provisions and are provided without warranty as | |||
described in the Simplified BSD License. | described in the Simplified BSD License. | |||
This document may contain material from IETF Documents or IETF | This document may contain material from IETF Documents or IETF | |||
Contributions published or made publicly available before November | Contributions published or made publicly available before November | |||
10, 2008. The person(s) controlling the copyright in some of this | 10, 2008. The person(s) controlling the copyright in some of this | |||
skipping to change at line 64 ¶ | skipping to change at page 2, line 41 ¶ | |||
modifications of such material outside the IETF Standards Process. | modifications of such material outside the IETF Standards Process. | |||
Without obtaining an adequate license from the person(s) controlling | Without obtaining an adequate license from the person(s) controlling | |||
the copyright in such materials, this document may not be modified | the copyright in such materials, this document may not be modified | |||
outside the IETF Standards Process, and derivative works of it may | outside the IETF Standards Process, and derivative works of it may | |||
not be created outside the IETF Standards Process, except to format | not be created outside the IETF Standards Process, except to format | |||
it for publication as an RFC or to translate it into languages other | it for publication as an RFC or to translate it into languages other | |||
than English. | than English. | |||
Table of Contents | Table of Contents | |||
1. Introduction ....................................................6 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 | |||
1.1. Conformance and Error Handling .............................6 | 1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 9 | |||
1.2. Syntax Notation ............................................6 | 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 9 | |||
2. Resources .......................................................7 | 2. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 10 | |||
3. Representations .................................................7 | 2.1. Client/Server Messaging . . . . . . . . . . . . . . . . . 10 | |||
3.1. Representation Metadata ....................................8 | 2.2. Intermediaries . . . . . . . . . . . . . . . . . . . . . 12 | |||
3.1.1. Processing Representation Data ......................8 | 2.3. Caches . . . . . . . . . . . . . . . . . . . . . . . . . 14 | |||
3.1.2. Encoding for Compression or Integrity ..............11 | 2.4. Uniform Resource Identifiers . . . . . . . . . . . . . . 15 | |||
3.1.3. Audience Language ..................................13 | 2.5. Resources . . . . . . . . . . . . . . . . . . . . . . . . 16 | |||
3.1.4. Identification .....................................14 | 2.5.1. http URI Scheme . . . . . . . . . . . . . . . . . . . 16 | |||
3.2. Representation Data .......................................17 | 2.5.2. https URI Scheme . . . . . . . . . . . . . . . . . . 18 | |||
3.3. Payload Semantics .........................................17 | 2.5.3. Fragment Identifiers on http(s) URI References . . . 20 | |||
3.4. Content Negotiation .......................................18 | 2.5.4. http and https URI Normalization and Comparison . . . 20 | |||
3.4.1. Proactive Negotiation ..............................19 | 3. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 21 | |||
3.4.2. Reactive Negotiation ...............................20 | 3.1. Implementation Diversity . . . . . . . . . . . . . . . . 21 | |||
4. Request Methods ................................................21 | 3.2. Role-based Requirements . . . . . . . . . . . . . . . . . 21 | |||
4.1. Overview ..................................................21 | 3.3. Parsing Elements . . . . . . . . . . . . . . . . . . . . 22 | |||
4.2. Common Method Properties ..................................22 | 3.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 23 | |||
4.2.1. Safe Methods .......................................22 | 3.5. Protocol Versioning . . . . . . . . . . . . . . . . . . . 23 | |||
4.2.2. Idempotent Methods .................................23 | 4. Header Fields . . . . . . . . . . . . . . . . . . . . . . . . 24 | |||
4.2.3. Cacheable Methods ..................................24 | 4.1. Header Field Names . . . . . . . . . . . . . . . . . . . 24 | |||
4.3. Method Definitions ........................................24 | 4.1.1. Header Field Name Registry . . . . . . . . . . . . . 27 | |||
4.3.1. GET ................................................24 | 4.1.2. Header Field Extensibility . . . . . . . . . . . . . 28 | |||
4.3.2. HEAD ...............................................25 | 4.2. Header Field Values . . . . . . . . . . . . . . . . . . . 28 | |||
4.3.3. POST ...............................................25 | 4.2.1. Header Field Order . . . . . . . . . . . . . . . . . 29 | |||
4.3.4. PUT ................................................26 | 4.2.2. Header Field Limits . . . . . . . . . . . . . . . . . 30 | |||
4.3.5. DELETE .............................................29 | 4.2.3. Header Field Value Components . . . . . . . . . . . . 30 | |||
4.3.6. CONNECT ............................................30 | 4.3. Trailer Fields . . . . . . . . . . . . . . . . . . . . . 32 | |||
4.3.7. OPTIONS ............................................31 | 4.3.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . 32 | |||
4.3.8. TRACE ..............................................32 | 4.3.2. Limitations . . . . . . . . . . . . . . . . . . . . . 32 | |||
5. Request Header Fields ..........................................33 | 4.3.3. Trailer . . . . . . . . . . . . . . . . . . . . . . . 33 | |||
5.1. Controls ..................................................33 | 4.4. Considerations for New Header Fields . . . . . . . . . . 33 | |||
5.1.1. Expect .............................................34 | 5. Message Routing . . . . . . . . . . . . . . . . . . . . . . . 35 | |||
5.1.2. Max-Forwards .......................................36 | 5.1. Identifying a Target Resource . . . . . . . . . . . . . . 35 | |||
5.2. Conditionals ..............................................36 | 5.2. Routing Inbound . . . . . . . . . . . . . . . . . . . . . 36 | |||
5.3. Content Negotiation .......................................37 | 5.3. Effective Request URI . . . . . . . . . . . . . . . . . . 36 | |||
5.3.1. Quality Values .....................................37 | 5.4. Host . . . . . . . . . . . . . . . . . . . . . . . . . . 37 | |||
5.3.2. Accept .............................................38 | 5.5. Message Forwarding . . . . . . . . . . . . . . . . . . . 38 | |||
5.3.3. Accept-Charset .....................................40 | 5.5.1. Via . . . . . . . . . . . . . . . . . . . . . . . . . 39 | |||
5.3.4. Accept-Encoding ....................................41 | 5.5.2. Transformations . . . . . . . . . . . . . . . . . . . 40 | |||
5.3.5. Accept-Language ....................................42 | 6. Representations . . . . . . . . . . . . . . . . . . . . . . . 41 | |||
5.4. Authentication Credentials ................................44 | 6.1. Representation Data . . . . . . . . . . . . . . . . . . . 42 | |||
5.5. Request Context ...........................................44 | 6.1.1. Media Type . . . . . . . . . . . . . . . . . . . . . 42 | |||
5.5.1. From ...............................................44 | 6.1.2. Content Codings . . . . . . . . . . . . . . . . . . . 44 | |||
5.5.2. Referer ............................................45 | 6.1.3. Language Tags . . . . . . . . . . . . . . . . . . . . 46 | |||
5.5.3. User-Agent .........................................46 | 6.1.4. Range Units . . . . . . . . . . . . . . . . . . . . . 47 | |||
6. Response Status Codes ..........................................47 | 6.2. Representation Metadata . . . . . . . . . . . . . . . . . 51 | |||
6.1. Overview of Status Codes ..................................48 | 6.2.1. Content-Type . . . . . . . . . . . . . . . . . . . . 51 | |||
6.2. Informational 1xx .........................................50 | 6.2.2. Content-Encoding . . . . . . . . . . . . . . . . . . 52 | |||
6.2.1. 100 Continue .......................................50 | 6.2.3. Content-Language . . . . . . . . . . . . . . . . . . 53 | |||
6.2.2. 101 Switching Protocols ............................50 | 6.2.4. Content-Length . . . . . . . . . . . . . . . . . . . 54 | |||
6.3. Successful 2xx ............................................51 | 6.2.5. Content-Location . . . . . . . . . . . . . . . . . . 55 | |||
6.3.1. 200 OK .............................................51 | 6.3. Payload . . . . . . . . . . . . . . . . . . . . . . . . . 57 | |||
6.3.2. 201 Created ........................................52 | 6.3.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . 57 | |||
6.3.3. 202 Accepted .......................................52 | 6.3.2. Identification . . . . . . . . . . . . . . . . . . . 58 | |||
6.3.4. 203 Non-Authoritative Information ..................52 | 6.3.3. Payload Body . . . . . . . . . . . . . . . . . . . . 59 | |||
6.3.5. 204 No Content .....................................53 | 6.3.4. Content-Range . . . . . . . . . . . . . . . . . . . . 59 | |||
6.3.6. 205 Reset Content ..................................53 | 6.3.5. Media Type multipart/byteranges . . . . . . . . . . . 61 | |||
6.4. Redirection 3xx ...........................................54 | 6.4. Content Negotiation . . . . . . . . . . . . . . . . . . . 63 | |||
6.4.1. 300 Multiple Choices ...............................55 | 6.4.1. Proactive Negotiation . . . . . . . . . . . . . . . . 64 | |||
6.4.2. 301 Moved Permanently ..............................56 | 6.4.2. Reactive Negotiation . . . . . . . . . . . . . . . . 65 | |||
6.4.3. 302 Found ..........................................56 | 7. Request Methods . . . . . . . . . . . . . . . . . . . . . . . 66 | |||
6.4.4. 303 See Other ......................................57 | 7.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 66 | |||
6.4.5. 305 Use Proxy ......................................58 | 7.2. Common Method Properties . . . . . . . . . . . . . . . . 67 | |||
6.4.6. 306 (Unused) .......................................58 | 7.2.1. Safe Methods . . . . . . . . . . . . . . . . . . . . 68 | |||
6.4.7. 307 Temporary Redirect .............................58 | 7.2.2. Idempotent Methods . . . . . . . . . . . . . . . . . 69 | |||
6.5. Client Error 4xx ..........................................58 | 7.2.3. Methods and Caching . . . . . . . . . . . . . . . . . 70 | |||
6.5.1. 400 Bad Request ....................................58 | 7.3. Method Definitions . . . . . . . . . . . . . . . . . . . 70 | |||
6.5.2. 402 Payment Required ...............................59 | 7.3.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 70 | |||
6.5.3. 403 Forbidden ......................................59 | 7.3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 71 | |||
6.5.4. 404 Not Found ......................................59 | 7.3.3. POST . . . . . . . . . . . . . . . . . . . . . . . . 72 | |||
6.5.5. 405 Method Not Allowed .............................59 | 7.3.4. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 73 | |||
6.5.6. 406 Not Acceptable .................................60 | 7.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 75 | |||
6.5.7. 408 Request Timeout ................................60 | 7.3.6. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 76 | |||
6.5.8. 409 Conflict .......................................60 | 7.3.7. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 78 | |||
6.5.9. 410 Gone ...........................................60 | 7.3.8. TRACE . . . . . . . . . . . . . . . . . . . . . . . . 79 | |||
6.5.10. 411 Length Required ...............................61 | 7.4. Method Extensibility . . . . . . . . . . . . . . . . . . 79 | |||
6.5.11. 413 Payload Too Large .............................61 | 7.4.1. Method Registry . . . . . . . . . . . . . . . . . . . 79 | |||
6.5.12. 414 URI Too Long ..................................61 | 7.4.2. Considerations for New Methods . . . . . . . . . . . 80 | |||
6.5.13. 415 Unsupported Media Type ........................62 | 8. Request Header Fields . . . . . . . . . . . . . . . . . . . . 80 | |||
6.5.14. 417 Expectation Failed ............................62 | 8.1. Controls . . . . . . . . . . . . . . . . . . . . . . . . 81 | |||
6.5.15. 426 Upgrade Required ..............................62 | 8.1.1. Expect . . . . . . . . . . . . . . . . . . . . . . . 81 | |||
6.6. Server Error 5xx ..........................................62 | 8.1.2. Max-Forwards . . . . . . . . . . . . . . . . . . . . 83 | |||
6.6.1. 500 Internal Server Error ..........................63 | 8.2. Preconditions . . . . . . . . . . . . . . . . . . . . . . 84 | |||
6.6.2. 501 Not Implemented ................................63 | 8.2.1. Evaluation . . . . . . . . . . . . . . . . . . . . . 85 | |||
6.6.3. 502 Bad Gateway ....................................63 | 8.2.2. Precedence . . . . . . . . . . . . . . . . . . . . . 86 | |||
6.6.4. 503 Service Unavailable ............................63 | 8.2.3. If-Match . . . . . . . . . . . . . . . . . . . . . . 88 | |||
6.6.5. 504 Gateway Timeout ................................63 | 8.2.4. If-None-Match . . . . . . . . . . . . . . . . . . . . 89 | |||
6.6.6. 505 HTTP Version Not Supported .....................64 | 8.2.5. If-Modified-Since . . . . . . . . . . . . . . . . . . 90 | |||
7. Response Header Fields .........................................64 | 8.2.6. If-Unmodified-Since . . . . . . . . . . . . . . . . . 91 | |||
7.1. Control Data ..............................................64 | 8.2.7. If-Range . . . . . . . . . . . . . . . . . . . . . . 93 | |||
7.1.1. Origination Date ...................................65 | 8.3. Range . . . . . . . . . . . . . . . . . . . . . . . . . . 94 | |||
7.1.2. Location ...........................................68 | 8.4. Content Negotiation . . . . . . . . . . . . . . . . . . . 95 | |||
7.1.3. Retry-After ........................................69 | 8.4.1. Quality Values . . . . . . . . . . . . . . . . . . . 96 | |||
7.1.4. Vary ...............................................70 | 8.4.2. Accept . . . . . . . . . . . . . . . . . . . . . . . 97 | |||
7.2. Validator Header Fields ...................................71 | 8.4.3. Accept-Charset . . . . . . . . . . . . . . . . . . . 99 | |||
7.3. Authentication Challenges .................................72 | 8.4.4. Accept-Encoding . . . . . . . . . . . . . . . . . . . 100 | |||
7.4. Response Context ..........................................72 | 8.4.5. Accept-Language . . . . . . . . . . . . . . . . . . . 101 | |||
7.4.1. Allow ..............................................72 | 8.5. Authentication Credentials . . . . . . . . . . . . . . . 102 | |||
7.4.2. Server .............................................73 | 8.5.1. Challenge and Response . . . . . . . . . . . . . . . 102 | |||
8. IANA Considerations ............................................73 | 8.5.2. Protection Space (Realm) . . . . . . . . . . . . . . 104 | |||
8.1. Method Registry ...........................................73 | 8.5.3. Authorization . . . . . . . . . . . . . . . . . . . . 105 | |||
8.1.1. Procedure ..........................................74 | 8.5.4. Proxy-Authorization . . . . . . . . . . . . . . . . . 105 | |||
8.1.2. Considerations for New Methods .....................74 | 8.5.5. Authentication Scheme Extensibility . . . . . . . . . 106 | |||
8.1.3. Registrations ......................................75 | 8.6. Request Context . . . . . . . . . . . . . . . . . . . . . 108 | |||
8.2. Status Code Registry ......................................75 | 8.6.1. From . . . . . . . . . . . . . . . . . . . . . . . . 108 | |||
8.2.1. Procedure ..........................................75 | 8.6.2. Referer . . . . . . . . . . . . . . . . . . . . . . . 109 | |||
8.2.2. Considerations for New Status Codes ................76 | 8.6.3. User-Agent . . . . . . . . . . . . . . . . . . . . . 110 | |||
8.2.3. Registrations ......................................76 | ||||
8.3. Header Field Registry .....................................77 | 9. Response Status Codes . . . . . . . . . . . . . . . . . . . . 111 | |||
8.3.1. Considerations for New Header Fields ...............78 | 9.1. Overview of Status Codes . . . . . . . . . . . . . . . . 112 | |||
8.3.2. Registrations ......................................80 | 9.2. Informational 1xx . . . . . . . . . . . . . . . . . . . . 113 | |||
8.4. Content Coding Registry ...................................81 | 9.2.1. 100 Continue . . . . . . . . . . . . . . . . . . . . 114 | |||
8.4.1. Procedure ..........................................81 | 9.2.2. 101 Switching Protocols . . . . . . . . . . . . . . . 114 | |||
8.4.2. Registrations ......................................81 | 9.3. Successful 2xx . . . . . . . . . . . . . . . . . . . . . 114 | |||
9. Security Considerations ........................................81 | 9.3.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . 114 | |||
9.1. Attacks Based on File and Path Names ......................82 | 9.3.2. 201 Created . . . . . . . . . . . . . . . . . . . . . 115 | |||
9.2. Attacks Based on Command, Code, or Query Injection ........82 | 9.3.3. 202 Accepted . . . . . . . . . . . . . . . . . . . . 115 | |||
9.3. Disclosure of Personal Information ........................83 | 9.3.4. 203 Non-Authoritative Information . . . . . . . . . . 116 | |||
9.4. Disclosure of Sensitive Information in URIs ...............83 | 9.3.5. 204 No Content . . . . . . . . . . . . . . . . . . . 116 | |||
9.5. Disclosure of Fragment after Redirects ....................84 | 9.3.6. 205 Reset Content . . . . . . . . . . . . . . . . . . 117 | |||
9.6. Disclosure of Product Information .........................84 | 9.3.7. 206 Partial Content . . . . . . . . . . . . . . . . . 117 | |||
9.7. Browser Fingerprinting ....................................84 | 9.4. Redirection 3xx . . . . . . . . . . . . . . . . . . . . . 120 | |||
10. Acknowledgments ...............................................85 | 9.4.1. 300 Multiple Choices . . . . . . . . . . . . . . . . 122 | |||
11. References ....................................................85 | 9.4.2. 301 Moved Permanently . . . . . . . . . . . . . . . . 123 | |||
11.1. Normative References .....................................85 | 9.4.3. 302 Found . . . . . . . . . . . . . . . . . . . . . . 123 | |||
11.2. Informative References ...................................86 | 9.4.4. 303 See Other . . . . . . . . . . . . . . . . . . . . 124 | |||
Appendix A. Differences between HTTP and MIME .....................89 | 9.4.5. 304 Not Modified . . . . . . . . . . . . . . . . . . 124 | |||
A.1. MIME-Version ..............................................89 | 9.4.6. 305 Use Proxy . . . . . . . . . . . . . . . . . . . . 125 | |||
A.2. Conversion to Canonical Form ..............................89 | 9.4.7. 306 (Unused) . . . . . . . . . . . . . . . . . . . . 125 | |||
A.3. Conversion of Date Formats ................................90 | 9.4.8. 307 Temporary Redirect . . . . . . . . . . . . . . . 125 | |||
A.4. Conversion of Content-Encoding ..........................90 | 9.4.9. 308 Permanent Redirect . . . . . . . . . . . . . . . 126 | |||
A.5. Conversion of Content-Transfer-Encoding .................90 | 9.5. Client Error 4xx . . . . . . . . . . . . . . . . . . . . 126 | |||
A.6. MHTML and Line Length Limitations .........................90 | 9.5.1. 400 Bad Request . . . . . . . . . . . . . . . . . . . 126 | |||
Appendix B. Changes from RFC 2616 .................................91 | 9.5.2. 401 Unauthorized . . . . . . . . . . . . . . . . . . 126 | |||
Appendix C. Imported ABNF .........................................93 | 9.5.3. 402 Payment Required . . . . . . . . . . . . . . . . 127 | |||
Appendix D. Collected ABNF ........................................94 | 9.5.4. 403 Forbidden . . . . . . . . . . . . . . . . . . . . 127 | |||
Index .............................................................97 | 9.5.5. 404 Not Found . . . . . . . . . . . . . . . . . . . . 127 | |||
9.5.6. 405 Method Not Allowed . . . . . . . . . . . . . . . 128 | ||||
9.5.7. 406 Not Acceptable . . . . . . . . . . . . . . . . . 128 | ||||
9.5.8. 407 Proxy Authentication Required . . . . . . . . . . 128 | ||||
9.5.9. 408 Request Timeout . . . . . . . . . . . . . . . . . 128 | ||||
9.5.10. 409 Conflict . . . . . . . . . . . . . . . . . . . . 129 | ||||
9.5.11. 410 Gone . . . . . . . . . . . . . . . . . . . . . . 129 | ||||
9.5.12. 411 Length Required . . . . . . . . . . . . . . . . . 129 | ||||
9.5.13. 412 Precondition Failed . . . . . . . . . . . . . . . 130 | ||||
9.5.14. 413 Payload Too Large . . . . . . . . . . . . . . . . 130 | ||||
9.5.15. 414 URI Too Long . . . . . . . . . . . . . . . . . . 130 | ||||
9.5.16. 415 Unsupported Media Type . . . . . . . . . . . . . 130 | ||||
9.5.17. 416 Range Not Satisfiable . . . . . . . . . . . . . . 131 | ||||
9.5.18. 417 Expectation Failed . . . . . . . . . . . . . . . 131 | ||||
9.5.19. 418 (Unused) . . . . . . . . . . . . . . . . . . . . 131 | ||||
9.5.20. 422 Unprocessable Payload . . . . . . . . . . . . . . 132 | ||||
9.5.21. 426 Upgrade Required . . . . . . . . . . . . . . . . 132 | ||||
9.6. Server Error 5xx . . . . . . . . . . . . . . . . . . . . 132 | ||||
9.6.1. 500 Internal Server Error . . . . . . . . . . . . . . 133 | ||||
9.6.2. 501 Not Implemented . . . . . . . . . . . . . . . . . 133 | ||||
9.6.3. 502 Bad Gateway . . . . . . . . . . . . . . . . . . . 133 | ||||
9.6.4. 503 Service Unavailable . . . . . . . . . . . . . . . 133 | ||||
9.6.5. 504 Gateway Timeout . . . . . . . . . . . . . . . . . 133 | ||||
9.6.6. 505 HTTP Version Not Supported . . . . . . . . . . . 133 | ||||
9.7. Status Code Extensibility . . . . . . . . . . . . . . . . 134 | ||||
9.7.1. Status Code Registry . . . . . . . . . . . . . . . . 134 | ||||
9.7.2. Considerations for New Status Codes . . . . . . . . . 134 | ||||
10. Response Header Fields . . . . . . . . . . . . . . . . . . . 135 | ||||
10.1. Control Data . . . . . . . . . . . . . . . . . . . . . . 135 | ||||
10.1.1. Origination Date . . . . . . . . . . . . . . . . . . 136 | ||||
10.1.2. Location . . . . . . . . . . . . . . . . . . . . . . 139 | ||||
10.1.3. Retry-After . . . . . . . . . . . . . . . . . . . . 140 | ||||
10.1.4. Vary . . . . . . . . . . . . . . . . . . . . . . . . 141 | ||||
10.2. Validators . . . . . . . . . . . . . . . . . . . . . . . 142 | ||||
10.2.1. Weak versus Strong . . . . . . . . . . . . . . . . . 143 | ||||
10.2.2. Last-Modified . . . . . . . . . . . . . . . . . . . 144 | ||||
10.2.3. ETag . . . . . . . . . . . . . . . . . . . . . . . . 146 | ||||
10.2.4. When to Use Entity-Tags and Last-Modified Dates . . 150 | ||||
10.3. Authentication Challenges . . . . . . . . . . . . . . . 150 | ||||
10.3.1. WWW-Authenticate . . . . . . . . . . . . . . . . . . 151 | ||||
10.3.2. Proxy-Authenticate . . . . . . . . . . . . . . . . . 152 | ||||
10.3.3. Authentication-Info . . . . . . . . . . . . . . . . 152 | ||||
10.3.4. Proxy-Authentication-Info . . . . . . . . . . . . . 153 | ||||
10.4. Response Context . . . . . . . . . . . . . . . . . . . . 154 | ||||
10.4.1. Accept-Ranges . . . . . . . . . . . . . . . . . . . 154 | ||||
10.4.2. Allow . . . . . . . . . . . . . . . . . . . . . . . 154 | ||||
10.4.3. Server . . . . . . . . . . . . . . . . . . . . . . . 155 | ||||
11. Generic Syntax . . . . . . . . . . . . . . . . . . . . . . . 156 | ||||
11.1. Whitespace . . . . . . . . . . . . . . . . . . . . . . . 156 | ||||
12. ABNF List Extension: #rule . . . . . . . . . . . . . . . . . 156 | ||||
12.1. Sender Requirements . . . . . . . . . . . . . . . . . . 156 | ||||
12.2. Recipient Requirements . . . . . . . . . . . . . . . . . 157 | ||||
13. Security Considerations . . . . . . . . . . . . . . . . . . . 158 | ||||
13.1. Establishing Authority . . . . . . . . . . . . . . . . . 158 | ||||
13.2. Risks of Intermediaries . . . . . . . . . . . . . . . . 159 | ||||
13.3. Attacks Based on File and Path Names . . . . . . . . . . 160 | ||||
13.4. Attacks Based on Command, Code, or Query Injection . . . 160 | ||||
13.5. Attacks via Protocol Element Length . . . . . . . . . . 161 | ||||
13.6. Disclosure of Personal Information . . . . . . . . . . . 161 | ||||
13.7. Privacy of Server Log Information . . . . . . . . . . . 161 | ||||
13.8. Disclosure of Sensitive Information in URIs . . . . . . 162 | ||||
13.9. Disclosure of Fragment after Redirects . . . . . . . . . 162 | ||||
13.10. Disclosure of Product Information . . . . . . . . . . . 163 | ||||
13.11. Browser Fingerprinting . . . . . . . . . . . . . . . . . 163 | ||||
13.12. Validator Retention . . . . . . . . . . . . . . . . . . 164 | ||||
13.13. Denial-of-Service Attacks Using Range . . . . . . . . . 165 | ||||
13.14. Authentication Considerations . . . . . . . . . . . . . 165 | ||||
13.14.1. Confidentiality of Credentials . . . . . . . . . . 165 | ||||
13.14.2. Credentials and Idle Clients . . . . . . . . . . . 166 | ||||
13.14.3. Protection Spaces . . . . . . . . . . . . . . . . . 166 | ||||
13.14.4. Additional Response Header Fields . . . . . . . . . 167 | ||||
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 167 | ||||
14.1. URI Scheme Registration . . . . . . . . . . . . . . . . 167 | ||||
14.2. Method Registration . . . . . . . . . . . . . . . . . . 167 | ||||
14.3. Status Code Registration . . . . . . . . . . . . . . . . 167 | ||||
14.4. Header Field Registration . . . . . . . . . . . . . . . 168 | ||||
14.5. Authentication Scheme Registration . . . . . . . . . . . 168 | ||||
14.6. Content Coding Registration . . . . . . . . . . . . . . 168 | ||||
14.7. Range Unit Registration . . . . . . . . . . . . . . . . 169 | ||||
14.8. Media Type Registration . . . . . . . . . . . . . . . . 169 | ||||
14.9. Port Registration . . . . . . . . . . . . . . . . . . . 169 | ||||
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 169 | ||||
15.1. Normative References . . . . . . . . . . . . . . . . . . 169 | ||||
15.2. Informative References . . . . . . . . . . . . . . . . . 171 | ||||
Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 177 | ||||
Appendix B. Changes from RFC 7230 . . . . . . . . . . . . . . . 181 | ||||
Appendix C. Changes from RFC 2818 . . . . . . . . . . . . . . . 182 | ||||
Appendix D. Changes from RFC 7231 . . . . . . . . . . . . . . . 182 | ||||
Appendix E. Changes from RFC 7232 . . . . . . . . . . . . . . . 182 | ||||
Appendix F. Changes from RFC 7233 . . . . . . . . . . . . . . . 182 | ||||
Appendix G. Changes from RFC 7235 . . . . . . . . . . . . . . . 182 | ||||
Appendix H. Changes from RFC 7538 . . . . . . . . . . . . . . . 183 | ||||
Appendix I. Changes from RFC 7615 . . . . . . . . . . . . . . . 183 | ||||
Appendix J. Change Log . . . . . . . . . . . . . . . . . . . . . 183 | ||||
J.1. Between RFC723x and draft 00 . . . . . . . . . . . . . . 183 | ||||
J.2. Since draft-ietf-httpbis-semantics-00 . . . . . . . . . . 183 | ||||
J.3. Since draft-ietf-httpbis-semantics-01 . . . . . . . . . . 184 | ||||
J.4. Since draft-ietf-httpbis-semantics-02 . . . . . . . . . . 185 | ||||
J.5. Since draft-ietf-httpbis-semantics-03 . . . . . . . . . . 186 | ||||
J.6. Since draft-ietf-httpbis-semantics-04 . . . . . . . . . . 187 | ||||
J.7. Since draft-ietf-httpbis-semantics-05 . . . . . . . . . . 187 | ||||
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 | ||||
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 196 | ||||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 197 | ||||
1. Introduction | 1. Introduction | |||
The Hypertext Transfer Protocol (HTTP) is a stateless application- | ||||
level request/response protocol that uses extensible semantics and | ||||
self-descriptive messages for flexible interaction with network-based | ||||
hypertext information systems. HTTP is defined by a series of | ||||
documents that collectively form the HTTP/1.1 specification: | ||||
o "HTTP Semantics" (this document) | ||||
o "HTTP Caching" [Caching] | ||||
o "HTTP/1.1 Messaging" [Messaging] | ||||
HTTP is a generic interface protocol for information systems. It is | HTTP is a generic interface protocol for information systems. It is | |||
designed to hide the details of how a service is implemented by | designed to hide the details of how a service is implemented by | |||
presenting a uniform interface to clients that is independent of the | presenting a uniform interface to clients that is independent of the | |||
types of resources provided. Likewise, servers do not need to be | types of resources provided. Likewise, servers do not need to be | |||
aware of each client's purpose: an HTTP request can be considered in | aware of each client's purpose: an HTTP request can be considered in | |||
isolation rather than being associated with a specific type of client | isolation rather than being associated with a specific type of client | |||
or a predetermined sequence of application steps. The result is a | or a predetermined sequence of application steps. The result is a | |||
protocol that can be used effectively in many different contexts and | protocol that can be used effectively in many different contexts and | |||
for which implementations can evolve independently over time. | for which implementations can evolve independently over time. | |||
skipping to change at line 232 ¶ | skipping to change at page 8, line 33 ¶ | |||
One consequence of this flexibility is that the protocol cannot be | One consequence of this flexibility is that the protocol cannot be | |||
defined in terms of what occurs behind the interface. Instead, we | defined in terms of what occurs behind the interface. Instead, we | |||
are limited to defining the syntax of communication, the intent of | are limited to defining the syntax of communication, the intent of | |||
received communication, and the expected behavior of recipients. If | received communication, and the expected behavior of recipients. If | |||
the communication is considered in isolation, then successful actions | the communication is considered in isolation, then successful actions | |||
ought to be reflected in corresponding changes to the observable | ought to be reflected in corresponding changes to the observable | |||
interface provided by servers. However, since multiple clients might | interface provided by servers. However, since multiple clients might | |||
act in parallel and perhaps at cross-purposes, we cannot require that | act in parallel and perhaps at cross-purposes, we cannot require that | |||
such changes be observable beyond the scope of a single response. | such changes be observable beyond the scope of a single response. | |||
Each Hypertext Transfer Protocol (HTTP) message is either a request | Each HTTP message is either a request or a response. A server | |||
or a response. A server listens on a connection for a request, | listens on a connection for a request, parses each message received, | |||
parses each message received, interprets the message semantics in | interprets the message semantics in relation to the identified | |||
relation to the identified request target, and responds to that | request target, and responds to that request with one or more | |||
request with one or more response messages. A client constructs | response messages. A client constructs request messages to | |||
request messages to communicate specific intentions, examines | communicate specific intentions, examines received responses to see | |||
received responses to see if the intentions were carried out, and | if the intentions were carried out, and determines how to interpret | |||
determines how to interpret the results. This document defines | the results. | |||
HTTP/1.1 request and response semantics in terms of the architecture | ||||
defined in [RFC7230]. | ||||
HTTP provides a uniform interface for interacting with a resource | HTTP provides a uniform interface for interacting with a resource | |||
(Section 2), regardless of its type, nature, or implementation, via | (Section 2.5), regardless of its type, nature, or implementation, via | |||
the manipulation and transfer of representations (Section 3). | the manipulation and transfer of representations (Section 6). | |||
HTTP semantics include the intentions defined by each request method | This document defines semantics that are common to all versions of | |||
(Section 4), extensions to those semantics that might be described in | HTTP. HTTP semantics include the intentions defined by each request | |||
request header fields (Section 5), the meaning of status codes to | method (Section 7), extensions to those semantics that might be | |||
indicate a machine-readable response (Section 6), and the meaning of | described in request header fields (Section 8), the meaning of status | |||
other control data and resource metadata that might be given in | codes to indicate a machine-readable response (Section 9), and the | |||
response header fields (Section 7). | meaning of other control data and resource metadata that might be | |||
given in response header fields (Section 10). | ||||
This document also defines representation metadata that describe how | This document also defines representation metadata that describe how | |||
a payload is intended to be interpreted by a recipient, the request | a payload is intended to be interpreted by a recipient, the request | |||
header fields that might influence content selection, and the various | header fields that might influence content selection, and the various | |||
selection algorithms that are collectively referred to as "content | selection algorithms that are collectively referred to as "content | |||
negotiation" (Section 3.4). | negotiation" (Section 6.4). | |||
This document defines HTTP/1.1 range requests, partial responses, and | This document defines HTTP range requests, partial responses, and the | |||
the multipart/byteranges media type. | multipart/byteranges media type. | |||
1.1. Conformance and Error Handling | This document obsoletes the portions of RFC 7230 that are independent | |||
of the HTTP/1.1 messaging syntax and connection management, with the | ||||
changes being summarized in Appendix B. The other parts of RFC 7230 | ||||
are obsoleted by "HTTP/1.1 Messaging" [Messaging]. This document | ||||
also obsoletes RFC 2818 (see Appendix C), RFC 7231 (see Appendix D), | ||||
RFC 7232 (see Appendix E), RFC 7233 (see Appendix F), RFC 7235 (see | ||||
Appendix G), RFC 7538 (see Appendix H), and RFC 7615 (see | ||||
Appendix I). | ||||
1.1. Requirements Notation | ||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | |||
document are to be interpreted as described in [RFC2119]. | document are to be interpreted as described in [RFC2119]. | |||
Conformance criteria and considerations regarding error handling are | Conformance criteria and considerations regarding error handling are | |||
defined in Section 2.5 of [RFC7230]. | defined in Section 3. | |||
1.2. Syntax Notation | 1.2. Syntax Notation | |||
This specification uses the Augmented Backus-Naur Form (ABNF) | This specification uses the Augmented Backus-Naur Form (ABNF) | |||
notation of [RFC5234] with a list extension, defined in Section 7 of | notation of [RFC5234], extended with the notation for case- | |||
[RFC7230], that allows for compact definition of comma-separated | sensitivity in strings defined in [RFC7405]. | |||
lists using a '#' operator (similar to how the '*' operator indicates | ||||
repetition). Appendix C describes rules imported from other | It also uses a list extension, defined in Section 12, that allows for | |||
documents. Appendix D shows the collected grammar with all list | compact definition of comma-separated lists using a '#' operator | |||
operators expanded to standard ABNF notation. | (similar to how the '*' operator indicates repetition). Appendix A | |||
shows the collected grammar with all list operators expanded to | ||||
standard ABNF notation. | ||||
As a convention, ABNF rule names prefixed with "obs-" denote | As a convention, ABNF rule names prefixed with "obs-" denote | |||
"obsolete" grammar rules that appear for historical reasons. | "obsolete" grammar rules that appear for historical reasons. | |||
The following core rules are included by reference, as defined in | The following core rules are included by reference, as defined in | |||
Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), | Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), | |||
CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double | CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double | |||
quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF | 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 | (line feed), OCTET (any 8-bit sequence of data), SP (space), and | |||
VCHAR (any visible US-ASCII character). | VCHAR (any visible US-ASCII character). | |||
Section 4.2.3 defines some generic syntactic components for header | ||||
field values. | ||||
The rules below are defined in [Messaging]: | ||||
obs-fold = <obs-fold, see [Messaging], Section 5.2> | ||||
protocol-name = <protocol-name, see [Messaging], Section 9.9> | ||||
protocol-version = <protocol-version, see [Messaging], Section 9.9> | ||||
request-target = <request-target, see [Messaging], Section 3.2> | ||||
This specification uses the terms "character", "character encoding | This specification uses the terms "character", "character encoding | |||
scheme", "charset", and "protocol element" as they are defined in | scheme", "charset", and "protocol element" as they are defined in | |||
[RFC6365]. | [RFC6365]. | |||
2. Architecture | 2. Architecture | |||
HTTP was created for the World Wide Web (WWW) architecture and has | HTTP was created for the World Wide Web (WWW) architecture and has | |||
evolved over time to support the scalability needs of a worldwide | evolved over time to support the scalability needs of a worldwide | |||
hypertext system. Much of that architecture is reflected in the | hypertext system. Much of that architecture is reflected in the | |||
terminology and syntax productions used to define HTTP. | terminology and syntax productions used to define HTTP. | |||
2.1. Client/Server Messaging | 2.1. Client/Server Messaging | |||
HTTP is a stateless request/response protocol that operates by | HTTP is a stateless request/response protocol that operates by | |||
exchanging messages (Section 3) across a reliable transport- or | exchanging messages (Section 2 of [Messaging]) across a reliable | |||
session-layer "connection" (Section 6). An HTTP "client" is a | transport- or session-layer "connection" (Section 9 of [Messaging]). | |||
program that establishes a connection to a server for the purpose of | An HTTP "client" is a program that establishes a connection to a | |||
sending one or more HTTP requests. An HTTP "server" is a program | server for the purpose of sending one or more HTTP requests. An HTTP | |||
that accepts connections in order to service HTTP requests by sending | "server" is a program that accepts connections in order to service | |||
HTTP responses. | HTTP requests by sending HTTP responses. | |||
The terms "client" and "server" refer only to the roles that these | The terms "client" and "server" refer only to the roles that these | |||
programs perform for a particular connection. The same program might | programs perform for a particular connection. The same program might | |||
act as a client on some connections and a server on others. The term | act as a client on some connections and a server on others. The term | |||
"user agent" refers to any of the various client programs that | "user agent" refers to any of the various client programs that | |||
initiate a request, including (but not limited to) browsers, spiders | initiate a request, including (but not limited to) browsers, spiders | |||
(web-based robots), command-line tools, custom applications, and | (web-based robots), command-line tools, custom applications, and | |||
mobile apps. The term "origin server" refers to the program that can | mobile apps. The term "origin server" refers to the program that can | |||
originate authoritative responses for a given target resource. The | originate authoritative responses for a given target resource. The | |||
terms "sender" and "recipient" refer to any implementation that sends | terms "sender" and "recipient" refer to any implementation that sends | |||
or receives a given message, respectively. | or receives a given message, respectively. | |||
HTTP relies upon the Uniform Resource Identifier (URI) standard | HTTP relies upon the Uniform Resource Identifier (URI) standard | |||
[RFC3986] to indicate the target resource (Section 5.1) and | [RFC3986] to indicate the target resource (Section 5.1) and | |||
relationships between resources. Messages are passed in a format | relationships between resources. | |||
similar to that used by Internet mail [RFC5322] and the Multipurpose | ||||
Internet Mail Extensions (MIME) [RFC2045] (see Appendix A of | ||||
[RFC7231] for the differences between HTTP and MIME messages). | ||||
Most HTTP communication consists of a retrieval request (GET) for a | Most HTTP communication consists of a retrieval request (GET) for a | |||
representation of some resource identified by a URI. In the simplest | representation of some resource identified by a URI. In the simplest | |||
case, this might be accomplished via a single bidirectional | case, this might be accomplished via a single bidirectional | |||
connection (===) between the user agent (UA) and the origin | connection (===) between the user agent (UA) and the origin server | |||
server (O). | (O). | |||
request > | request > | |||
UA ======================================= O | UA ======================================= O | |||
< response | < response | |||
Each major version of HTTP defines its own syntax for the inclusion | ||||
of information in messages. Nevertheless, a common abstraction is | ||||
that a message includes some form of envelope/framing, a potential | ||||
set of named header fields up front (a header section), a potential | ||||
body, and a potential set of named trailer fields. | ||||
A client sends an HTTP request to a server in the form of a request | A client sends an HTTP request to a server in the form of a request | |||
message, beginning with a request-line that includes a method, URI, | message, beginning with a method (Section 7) and URI, followed by | |||
and protocol version (Section 3.1.1), followed by header fields | header fields containing request modifiers, client information, and | |||
containing request modifiers, client information, and representation | representation metadata (Section 4), and finally a payload body (if | |||
metadata (Section 3.2), an empty line to indicate the end of the | any, Section 6.3.3). | |||
header section, and finally a message body containing the payload | ||||
body (if any, Section 3.3). | ||||
A server responds to a client's request by sending one or more HTTP | A server responds to a client's request by sending one or more HTTP | |||
response messages, each beginning with a status line that includes | response messages, each beginning with a success or error code | |||
the protocol version, a success or error code, and textual reason | (Section 9), possibly followed by header fields containing server | |||
phrase (Section 3.1.2), possibly followed by header fields containing | information, resource metadata, and representation metadata | |||
server information, resource metadata, and representation metadata | (Section 4), and finally a payload body (if any, Section 6.3.3). | |||
(Section 3.2), an empty line to indicate the end of the header | ||||
section, and finally a message body containing the payload body (if | ||||
any, Section 3.3). | ||||
A connection might be used for multiple request/response exchanges, | A connection might be used for multiple request/response exchanges. | |||
as defined in Section 6.3. | The mechanism used to correlate between request and response messages | |||
is version dependent; some versions of HTTP use implicit ordering of | ||||
messages, while others use an explicit identifier. | ||||
Responses (both final and non-final) can be sent at any time after a | ||||
request is received, even if it is not yet complete. However, | ||||
clients (including intermediaries) might abandon a request if the | ||||
response is not forthcoming within a reasonable period of time. | ||||
The following example illustrates a typical message exchange for a | The following example illustrates a typical message exchange for a | |||
GET request (Section 4.3.1 of [RFC7231]) on the URI | GET request (Section 7.3.1) on the URI "http://www.example.com/ | |||
"http://www.example.com/hello.txt": | hello.txt": | |||
Client request: | Client request: | |||
GET /hello.txt HTTP/1.1 | GET /hello.txt HTTP/1.1 | |||
User-Agent: curl/7.16.3 libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3 | User-Agent: curl/7.16.3 libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3 | |||
Host: www.example.com | Host: www.example.com | |||
Accept-Language: en, mi | Accept-Language: en, mi | |||
Server response: | Server response: | |||
skipping to change at line 386 ¶ | skipping to change at page 12, line 24 ¶ | |||
Server: Apache | Server: Apache | |||
Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT | Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT | |||
ETag: "34aa387-d-1568eb00" | ETag: "34aa387-d-1568eb00" | |||
Accept-Ranges: bytes | Accept-Ranges: bytes | |||
Content-Length: 51 | Content-Length: 51 | |||
Vary: Accept-Encoding | Vary: Accept-Encoding | |||
Content-Type: text/plain | Content-Type: text/plain | |||
Hello World! My payload includes a trailing CRLF. | Hello World! My payload includes a trailing CRLF. | |||
2.3. Intermediaries | 2.2. Intermediaries | |||
HTTP enables the use of intermediaries to satisfy requests through a | HTTP enables the use of intermediaries to satisfy requests through a | |||
chain of connections. There are three common forms of HTTP | chain of connections. There are three common forms of HTTP | |||
intermediary: proxy, gateway, and tunnel. In some cases, a single | intermediary: proxy, gateway, and tunnel. In some cases, a single | |||
intermediary might act as an origin server, proxy, gateway, or | intermediary might act as an origin server, proxy, gateway, or | |||
tunnel, switching behavior based on the nature of each request. | tunnel, switching behavior based on the nature of each request. | |||
> > > > | > > > > | |||
UA =========== A =========== B =========== C =========== O | UA =========== A =========== B =========== C =========== O | |||
< < < < | < < < < | |||
skipping to change at line 430 ¶ | skipping to change at page 13, line 20 ¶ | |||
client, usually via local configuration rules, to receive requests | client, usually via local configuration rules, to receive requests | |||
for some type(s) of absolute URI and attempt to satisfy those | for some type(s) of absolute URI and attempt to satisfy those | |||
requests via translation through the HTTP interface. Some | requests via translation through the HTTP interface. Some | |||
translations are minimal, such as for proxy requests for "http" URIs, | translations are minimal, such as for proxy requests for "http" URIs, | |||
whereas other requests might require translation to and from entirely | whereas other requests might require translation to and from entirely | |||
different application-level protocols. Proxies are often used to | different application-level protocols. Proxies are often used to | |||
group an organization's HTTP requests through a common intermediary | group an organization's HTTP requests through a common intermediary | |||
for the sake of security, annotation services, or shared caching. | for the sake of security, annotation services, or shared caching. | |||
Some proxies are designed to apply transformations to selected | Some proxies are designed to apply transformations to selected | |||
messages or payloads while they are being forwarded, as described in | messages or payloads while they are being forwarded, as described in | |||
Section 5.7.2. | Section 5.5.2. | |||
A "gateway" (a.k.a. "reverse proxy") is an intermediary that acts as | A "gateway" (a.k.a. "reverse proxy") is an intermediary that acts as | |||
an origin server for the outbound connection but translates received | an origin server for the outbound connection but translates received | |||
requests and forwards them inbound to another server or servers. | requests and forwards them inbound to another server or servers. | |||
Gateways are often used to encapsulate legacy or untrusted | Gateways are often used to encapsulate legacy or untrusted | |||
information services, to improve server performance through | information services, to improve server performance through | |||
"accelerator" caching, and to enable partitioning or load balancing | "accelerator" caching, and to enable partitioning or load balancing | |||
of HTTP services across multiple machines. | of HTTP services across multiple machines. | |||
All HTTP requirements applicable to an origin server also apply to | All HTTP requirements applicable to an origin server also apply to | |||
skipping to change at line 454 ¶ | skipping to change at page 13, line 44 ¶ | |||
However, an HTTP-to-HTTP gateway that wishes to interoperate with | However, an HTTP-to-HTTP gateway that wishes to interoperate with | |||
third-party HTTP servers ought to conform to user agent requirements | third-party HTTP servers ought to conform to user agent requirements | |||
on the gateway's inbound connection. | on the gateway's inbound connection. | |||
A "tunnel" acts as a blind relay between two connections without | A "tunnel" acts as a blind relay between two connections without | |||
changing the messages. Once active, a tunnel is not considered a | changing the messages. Once active, a tunnel is not considered a | |||
party to the HTTP communication, though the tunnel might have been | party to the HTTP communication, though the tunnel might have been | |||
initiated by an HTTP request. A tunnel ceases to exist when both | initiated by an HTTP request. A tunnel ceases to exist when both | |||
ends of the relayed connection are closed. Tunnels are used to | ends of the relayed connection are closed. Tunnels are used to | |||
extend a virtual connection through an intermediary, such as when | extend a virtual connection through an intermediary, such as when | |||
Transport Layer Security (TLS, [RFC5246]) is used to establish | Transport Layer Security (TLS, [RFC8446]) is used to establish | |||
confidential communication through a shared firewall proxy. | confidential communication through a shared firewall proxy. | |||
The above categories for intermediary only consider those acting as | The above categories for intermediary only consider those acting as | |||
participants in the HTTP communication. There are also | participants in the HTTP communication. There are also | |||
intermediaries that can act on lower layers of the network protocol | intermediaries that can act on lower layers of the network protocol | |||
stack, filtering or redirecting HTTP traffic without the knowledge or | stack, filtering or redirecting HTTP traffic without the knowledge or | |||
permission of message senders. Network intermediaries are | permission of message senders. Network intermediaries are | |||
indistinguishable (at a protocol level) from a man-in-the-middle | indistinguishable (at a protocol level) from a man-in-the-middle | |||
attack, often introducing security flaws or interoperability problems | attack, often introducing security flaws or interoperability problems | |||
due to mistakenly violating HTTP semantics. | due to mistakenly violating HTTP semantics. | |||
skipping to change at line 486 ¶ | skipping to change at page 14, line 28 ¶ | |||
HTTP is defined as a stateless protocol, meaning that each request | HTTP is defined as a stateless protocol, meaning that each request | |||
message can be understood in isolation. Many implementations depend | message can be understood in isolation. Many implementations depend | |||
on HTTP's stateless design in order to reuse proxied connections or | on HTTP's stateless design in order to reuse proxied connections or | |||
dynamically load balance requests across multiple servers. Hence, a | dynamically load balance requests across multiple servers. Hence, a | |||
server MUST NOT assume that two requests on the same connection are | server MUST NOT assume that two requests on the same connection are | |||
from the same user agent unless the connection is secured and | from the same user agent unless the connection is secured and | |||
specific to that agent. Some non-standard HTTP extensions (e.g., | specific to that agent. Some non-standard HTTP extensions (e.g., | |||
[RFC4559]) have been known to violate this requirement, resulting in | [RFC4559]) have been known to violate this requirement, resulting in | |||
security and interoperability problems. | security and interoperability problems. | |||
2.4. Caches | 2.3. Caches | |||
A "cache" is a local store of previous response messages and the | A "cache" is a local store of previous response messages and the | |||
subsystem that controls its message storage, retrieval, and deletion. | subsystem that controls its message storage, retrieval, and deletion. | |||
A cache stores cacheable responses in order to reduce the response | A cache stores cacheable responses in order to reduce the response | |||
time and network bandwidth consumption on future, equivalent | time and network bandwidth consumption on future, equivalent | |||
requests. Any client or server MAY employ a cache, though a cache | requests. Any client or server MAY employ a cache, though a cache | |||
cannot be used by a server while it is acting as a tunnel. | cannot be used by a server while it is acting as a tunnel. | |||
The effect of a cache is that the request/response chain is shortened | The effect of a cache is that the request/response chain is shortened | |||
if one of the participants along the chain has a cached response | if one of the participants along the chain has a cached response | |||
skipping to change at line 511 ¶ | skipping to change at page 15, line 5 ¶ | |||
> > | > > | |||
UA =========== A =========== B - - - - - - C - - - - - - O | UA =========== A =========== B - - - - - - C - - - - - - O | |||
< < | < < | |||
A response is "cacheable" if a cache is allowed to store a copy of | A response is "cacheable" if a cache is allowed to store a copy of | |||
the response message for use in answering subsequent requests. Even | the response message for use in answering subsequent requests. Even | |||
when a response is cacheable, there might be additional constraints | when a response is cacheable, there might be additional constraints | |||
placed by the client or by the origin server on when that cached | placed by the client or by the origin server on when that cached | |||
response can be used for a particular request. HTTP requirements for | response can be used for a particular request. HTTP requirements for | |||
cache behavior and cacheable responses are defined in Section 2 of | cache behavior and cacheable responses are defined in Section 2 of | |||
[RFC7234]. | [Caching]. | |||
There is a wide variety of architectures and configurations of caches | There is a wide variety of architectures and configurations of caches | |||
deployed across the World Wide Web and inside large organizations. | deployed across the World Wide Web and inside large organizations. | |||
These include national hierarchies of proxy caches to save | These include national hierarchies of proxy caches to save | |||
transoceanic bandwidth, collaborative systems that broadcast or | transoceanic bandwidth, collaborative systems that broadcast or | |||
multicast cache entries, archives of pre-fetched cache entries for | multicast cache entries, archives of pre-fetched cache entries for | |||
use in off-line or high-latency environments, and so on. | use in off-line or high-latency environments, and so on. | |||
2.7. Uniform Resource Identifiers | 2.4. Uniform Resource Identifiers | |||
Uniform Resource Identifiers (URIs) [RFC3986] are used throughout | Uniform Resource Identifiers (URIs) [RFC3986] are used throughout | |||
HTTP as the means for identifying resources (Section 2 of [RFC7231]). | HTTP as the means for identifying resources (Section 2.5). URI | |||
URI references are used to target requests, indicate redirects, and | references are used to target requests, indicate redirects, and | |||
define relationships. | define relationships. | |||
The definitions of "URI-reference", "absolute-URI", "relative-part", | The definitions of "URI-reference", "absolute-URI", "relative-part", | |||
"scheme", "authority", "port", "host", "path-abempty", "segment", | "authority", "port", "host", "path-abempty", "segment", and "query" | |||
"query", and "fragment" are adopted from the URI generic syntax. An | are adopted from the URI generic syntax. An "absolute-path" rule is | |||
"absolute-path" rule is defined for protocol elements that can | defined for protocol elements that can contain a non-empty path | |||
contain a non-empty path component. (This rule differs slightly from | component. (This rule differs slightly from the path-abempty rule of | |||
the path-abempty rule of RFC 3986, which allows for an empty path to | RFC 3986, which allows for an empty path to be used in references, | |||
be used in references, and path-absolute rule, which does not allow | and path-absolute rule, which does not allow paths that begin with | |||
paths that begin with "//".) A "partial-URI" rule is defined for | "//".) A "partial-URI" rule is defined for protocol elements that | |||
protocol elements that can contain a relative URI but not a fragment | can contain a relative URI but not a fragment component. | |||
component. | ||||
URI-reference = <URI-reference, see [RFC3986], Section 4.1> | URI-reference = <URI-reference, see [RFC3986], Section 4.1> | |||
absolute-URI = <absolute-URI, see [RFC3986], Section 4.3> | absolute-URI = <absolute-URI, see [RFC3986], Section 4.3> | |||
relative-part = <relative-part, see [RFC3986], Section 4.2> | relative-part = <relative-part, see [RFC3986], Section 4.2> | |||
scheme = <scheme, see [RFC3986], Section 3.1> | ||||
authority = <authority, see [RFC3986], Section 3.2> | authority = <authority, see [RFC3986], Section 3.2> | |||
uri-host = <host, see [RFC3986], Section 3.2.2> | uri-host = <host, see [RFC3986], Section 3.2.2> | |||
port = <port, see [RFC3986], Section 3.2.3> | port = <port, see [RFC3986], Section 3.2.3> | |||
path-abempty = <path-abempty, see [RFC3986], Section 3.3> | path-abempty = <path-abempty, see [RFC3986], Section 3.3> | |||
segment = <segment, see [RFC3986], Section 3.3> | segment = <segment, see [RFC3986], Section 3.3> | |||
query = <query, see [RFC3986], Section 3.4> | query = <query, see [RFC3986], Section 3.4> | |||
fragment = <fragment, see [RFC3986], Section 3.5> | ||||
absolute-path = 1*( "/" segment ) | absolute-path = 1*( "/" segment ) | |||
partial-URI = relative-part [ "?" query ] | partial-URI = relative-part [ "?" query ] | |||
Each protocol element in HTTP that allows a URI reference will | Each protocol element in HTTP that allows a URI reference will | |||
indicate in its ABNF production whether the element allows any form | indicate in its ABNF production whether the element allows any form | |||
of reference (URI-reference), only a URI in absolute form | of reference (URI-reference), only a URI in absolute form (absolute- | |||
(absolute-URI), only the path and optional query components, or some | URI), only the path and optional query components, or some | |||
combination of the above. Unless otherwise indicated, URI references | combination of the above. Unless otherwise indicated, URI references | |||
are parsed relative to the effective request URI (Section 5.5). | are parsed relative to the effective request URI (Section 5.3). | |||
2. Resources | It is RECOMMENDED that all senders and recipients support, at a | |||
minimum, URIs with lengths of 8000 octets in protocol elements. Note | ||||
that this implies some structures and on-wire representations (for | ||||
example, the request line in HTTP/1.1) will necessarily be larger in | ||||
some cases. | ||||
2.5. Resources | ||||
The target of an HTTP request is called a "resource". HTTP does not | The target of an HTTP request is called a "resource". HTTP does not | |||
limit the nature of a resource; it merely defines an interface that | limit the nature of a resource; it merely defines an interface that | |||
might be used to interact with resources. Each resource is | might be used to interact with resources. Each resource is | |||
identified by a Uniform Resource Identifier (URI), as described in | identified by a Uniform Resource Identifier (URI), as described in | |||
Section 2.7 of [RFC7230]. | Section 2.4. | |||
When a client constructs an HTTP/1.1 request message, it sends the | ||||
target URI in one of various forms, as defined in (Section 5.3 of | ||||
[RFC7230]). When a request is received, the server reconstructs an | ||||
effective request URI for the target resource (Section 5.5 of | ||||
[RFC7230]). | ||||
One design goal of HTTP is to separate resource identification from | One design goal of HTTP is to separate resource identification from | |||
request semantics, which is made possible by vesting the request | request semantics, which is made possible by vesting the request | |||
semantics in the request method (Section 4) and a few | semantics in the request method (Section 7) and a few request- | |||
request-modifying header fields (Section 5). If there is a conflict | modifying header fields (Section 8). If there is a conflict between | |||
between the method semantics and any semantic implied by the URI | the method semantics and any semantic implied by the URI itself, as | |||
itself, as described in Section 4.2.1, the method semantics take | described in Section 7.2.1, the method semantics take precedence. | |||
precedence. | ||||
IANA maintains the registry of URI Schemes [BCP115] at | ||||
<http://www.iana.org/assignments/uri-schemes/>. | ||||
This document defines the following URI schemes. | IANA maintains the registry of URI Schemes [BCP35] at | |||
<https://www.iana.org/assignments/uri-schemes/>. Although requests | ||||
might target any URI scheme, the following schemes are inherent to | ||||
HTTP servers: | ||||
+------------+------------------------------------+---------------+ | +------------+------------------------------------+---------------+ | |||
| URI Scheme | Description | Reference | | | URI Scheme | Description | Reference | | |||
+------------+------------------------------------+---------------+ | +------------+------------------------------------+---------------+ | |||
| http | Hypertext Transfer Protocol | Section 2.7.1 | | | http | Hypertext Transfer Protocol | Section 2.5.1 | | |||
| https | Hypertext Transfer Protocol Secure | Section 2.7.2 | | | https | Hypertext Transfer Protocol Secure | Section 2.5.2 | | |||
+------------+------------------------------------+---------------+ | +------------+------------------------------------+---------------+ | |||
2.7.1. http URI Scheme | 2.5.1. http URI Scheme | |||
The "http" URI scheme is hereby defined for the purpose of minting | The "http" URI scheme is hereby defined for the purpose of minting | |||
identifiers according to their association with the hierarchical | identifiers according to their association with the hierarchical | |||
namespace governed by a potential HTTP origin server listening for | namespace governed by a potential HTTP origin server listening for | |||
TCP ([RFC0793]) connections on a given port. | TCP ([RFC0793]) connections on a given port. | |||
http-URI = "http:" "//" authority path-abempty [ "?" query ] | http-URI = "http:" "//" authority path-abempty [ "?" query ] | |||
[ "#" fragment ] | ||||
The origin server for an "http" URI is identified by the authority | The origin server for an "http" URI is identified by the authority | |||
component, which includes a host identifier and optional TCP port | component, which includes a host identifier and optional TCP port | |||
([RFC3986], Section 3.2.2). The hierarchical path component and | ([RFC3986], Section 3.2.2). The hierarchical path component and | |||
optional query component serve as an identifier for a potential | optional query component serve as an identifier for a potential | |||
target resource within that origin server's name space. | target resource within that origin server's name space. | |||
A sender MUST NOT generate an "http" URI with an empty host | A sender MUST NOT generate an "http" URI with an empty host | |||
identifier. A recipient that processes such a URI reference MUST | identifier. A recipient that processes such a URI reference MUST | |||
reject it as invalid. | reject it as invalid. | |||
skipping to change at line 629 ¶ | skipping to change at page 17, line 24 ¶ | |||
subcomponent is empty or not given, TCP port 80 (the reserved port | subcomponent is empty or not given, TCP port 80 (the reserved port | |||
for WWW services) is the default. | for WWW services) is the default. | |||
Note that the presence of a URI with a given authority component does | Note that the presence of a URI with a given authority component does | |||
not imply that there is always an HTTP server listening for | not imply that there is always an HTTP server listening for | |||
connections on that host and port. Anyone can mint a URI. What the | connections on that host and port. Anyone can mint a URI. What the | |||
authority component determines is who has the right to respond | authority component determines is who has the right to respond | |||
authoritatively to requests that target the identified resource. The | authoritatively to requests that target the identified resource. The | |||
delegated nature of registered names and IP addresses creates a | delegated nature of registered names and IP addresses creates a | |||
federated namespace, based on control over the indicated host and | federated namespace, based on control over the indicated host and | |||
port, whether or not an HTTP server is present. See Section 9.1 for | port, whether or not an HTTP server is present. See Section 13.1 for | |||
security considerations related to establishing authority. | security considerations related to establishing authority. | |||
When an "http" URI is used within a context that calls for access to | When an "http" URI is used within a context that calls for access to | |||
the indicated resource, a client MAY attempt access by resolving the | the indicated resource, a client MAY attempt access by resolving the | |||
host to an IP address, establishing a TCP connection to that address | host to an IP address, establishing a TCP connection to that address | |||
on the indicated port, and sending an HTTP request message | on the indicated port, and sending an HTTP request message (Section 2 | |||
(Section 3) containing the URI's identifying data (Section 5) to the | of [Messaging]) containing the URI's identifying data to the server. | |||
server. If the server responds to that request with a non-interim | If the server responds to that request with a non-interim HTTP | |||
HTTP response message, as described in Section 6 of [RFC7231], then | response message, as described in Section 9, then that response is | |||
that response is considered an authoritative answer to the client's | considered an authoritative answer to the client's request. | |||
request. | ||||
Although HTTP is independent of the transport protocol, the "http" | Although HTTP is independent of the transport protocol, the "http" | |||
scheme is specific to TCP-based services because the name delegation | scheme is specific to TCP-based services because the name delegation | |||
process depends on TCP for establishing authority. An HTTP service | process depends on TCP for establishing authority. An HTTP service | |||
based on some other underlying connection protocol would presumably | based on some other underlying connection protocol would presumably | |||
be identified using a different URI scheme, just as the "https" | be identified using a different URI scheme, just as the "https" | |||
scheme (below) is used for resources that require an end-to-end | scheme (below) is used for resources that require an end-to-end | |||
secured connection. Other protocols might also be used to provide | secured connection. Other protocols might also be used to provide | |||
access to "http" identified resources -- it is only the authoritative | access to "http" identified resources -- it is only the authoritative | |||
interface that is specific to TCP. | interface that is specific to TCP. | |||
skipping to change at line 666 ¶ | skipping to change at page 18, line 11 ¶ | |||
authentication information, such as within command invocation | authentication information, such as within command invocation | |||
options, configuration files, or bookmark lists, even though such | options, configuration files, or bookmark lists, even though such | |||
usage might expose a user identifier or password. A sender MUST NOT | usage might expose a user identifier or password. A sender MUST NOT | |||
generate the userinfo subcomponent (and its "@" delimiter) when an | generate the userinfo subcomponent (and its "@" delimiter) when an | |||
"http" URI reference is generated within a message as a request | "http" URI reference is generated within a message as a request | |||
target or header field value. Before making use of an "http" URI | target or header field value. Before making use of an "http" URI | |||
reference received from an untrusted source, a recipient SHOULD parse | reference received from an untrusted source, a recipient SHOULD parse | |||
for userinfo and treat its presence as an error; it is likely being | for userinfo and treat its presence as an error; it is likely being | |||
used to obscure the authority for the sake of phishing attacks. | used to obscure the authority for the sake of phishing attacks. | |||
2.7.2. https URI Scheme | 2.5.2. https URI Scheme | |||
The "https" URI scheme is hereby defined for the purpose of minting | The "https" URI scheme is hereby defined for the purpose of minting | |||
identifiers according to their association with the hierarchical | identifiers according to their association with the hierarchical | |||
namespace governed by a potential HTTP origin server listening to a | namespace governed by a potential HTTP origin server listening to a | |||
given TCP port for TLS-secured connections ([RFC5246]). | given TCP port for TLS-secured connections ([RFC8446]). | |||
All of the requirements listed above for the "http" scheme are also | All of the requirements listed above for the "http" scheme are also | |||
requirements for the "https" scheme, except that TCP port 443 is the | requirements for the "https" scheme, except that TCP port 443 is the | |||
default if the port subcomponent is empty or not given, and the user | default if the port subcomponent is empty or not given, and the user | |||
agent MUST ensure that its connection to the origin server is secured | agent MUST ensure that its connection to the origin server is secured | |||
through the use of strong encryption, end-to-end, prior to sending | through the use of strong encryption, end-to-end, prior to sending | |||
the first HTTP request. | the first HTTP request. | |||
https-URI = "https:" "//" authority path-abempty [ "?" query ] | https-URI = "https:" "//" authority path-abempty [ "?" query ] | |||
[ "#" fragment ] | ||||
Note that the "https" URI scheme depends on both TLS and TCP for | Note that the "https" URI scheme depends on both TLS and TCP for | |||
establishing authority. Resources made available via the "https" | establishing authority. Resources made available via the "https" | |||
scheme have no shared identity with the "http" scheme even if their | scheme have no shared identity with the "http" scheme even if their | |||
resource identifiers indicate the same authority (the same host | resource identifiers indicate the same authority (the same host | |||
listening to the same TCP port). They are distinct namespaces and | listening to the same TCP port). They are distinct namespaces and | |||
are considered to be distinct origin servers. However, an extension | are considered to be distinct origin servers. However, an extension | |||
to HTTP that is defined to apply to entire host domains, such as the | to HTTP that is defined to apply to entire host domains, such as the | |||
Cookie protocol [RFC6265], can allow information set by one service | Cookie protocol [RFC6265], can allow information set by one service | |||
to impact communication with other services within a matching group | to impact communication with other services within a matching group | |||
of host domains. | of host domains. | |||
The process for authoritative access to an "https" identified | 2.5.2.1. Initiating HTTP Over TLS | |||
resource is defined in [RFC2818]. | ||||
2. HTTP Over TLS | ||||
Conceptually, HTTP/TLS is very simple. Simply use HTTP over TLS | Conceptually, HTTP/TLS is very simple. Simply use HTTP over TLS | |||
precisely as you would use HTTP over TCP. | precisely as you would use HTTP over TCP. | |||
2.1. Connection Initiation | ||||
The agent acting as the HTTP client should also act as the TLS | The agent acting as the HTTP client should also act as the TLS | |||
client. It should initiate a connection to the server on the | client. It should initiate a connection to the server on the | |||
appropriate port and then send the TLS ClientHello to begin the TLS | appropriate port and then send the TLS ClientHello to begin the TLS | |||
handshake. When the TLS handshake has finished. The client may then | handshake. When the TLS handshake has finished. The client may then | |||
initiate the first HTTP request. All HTTP data MUST be sent as TLS | initiate the first HTTP request. All HTTP data MUST be sent as TLS | |||
"application data". Normal HTTP behavior, including retained | "application data". Normal HTTP behavior, including retained | |||
connections should be followed. | connections should be followed. | |||
3.1. Server Identity | 2.5.2.2. Identifying HTTPS Servers | |||
In general, HTTP/TLS requests are generated by dereferencing a URI. | In general, HTTP/TLS requests are generated by dereferencing a URI. | |||
As a consequence, the hostname for the server is known to the client. | As a consequence, the hostname for the server is known to the client. | |||
If the hostname is available, the client MUST check it against the | If the hostname is available, the client MUST check it against the | |||
server's identity as presented in the server's Certificate message, | server's identity as presented in the server's Certificate message, | |||
in order to prevent man-in-the-middle attacks. | in order to prevent man-in-the-middle attacks. | |||
If the client has external information as to the expected identity of | If the client has external information as to the expected identity of | |||
the server, the hostname check MAY be omitted. (For instance, a | the server, the hostname check MAY be omitted. (For instance, a | |||
client may be connecting to a machine whose address and hostname are | client may be connecting to a machine whose address and hostname are | |||
dynamic but the client knows the certificate that the server will | dynamic but the client knows the certificate that the server will | |||
present.) In such cases, it is important to narrow the scope of | present.) In such cases, it is important to narrow the scope of | |||
acceptable certificates as much as possible in order to prevent man | acceptable certificates as much as possible in order to prevent man | |||
in the middle attacks. In special cases, it may be appropriate for | in the middle attacks. In special cases, it may be appropriate for | |||
the client to simply ignore the server's identity, but it must be | the client to simply ignore the server's identity, but it must be | |||
understood that this leaves the connection open to active attack. | understood that this leaves the connection open to active attack. | |||
If a subjectAltName extension of type dNSName is present, that MUST | If a subjectAltName extension of type dNSName is present, that MUST | |||
be used as the identity. Otherwise, the (most specific) Common Name | be used as the identity. Otherwise, the (most specific) Common Name | |||
field in the Subject field of the certificate MUST be used. Although | field in the Subject field of the certificate MUST be used. Although | |||
the use of the Common Name is existing practice, it is deprecated and | the use of the Common Name is existing practice, it is deprecated and | |||
Certification Authorities are encouraged to use the dNSName instead. | Certification Authorities are encouraged to use the dNSName instead. | |||
Matching is performed using the matching rules specified by | Matching is performed using the matching rules specified by | |||
[RFC2459]. If more than one identity of a given type is present in | [RFC5280]. If more than one identity of a given type is present in | |||
the certificate (e.g., more than one dNSName name, a match in any one | the certificate (e.g., more than one dNSName name, a match in any one | |||
of the set is considered acceptable.) Names may contain the wildcard | of the set is considered acceptable.) Names may contain the wildcard | |||
character * which is considered to match any single domain name | character * which is considered to match any single domain name | |||
component or component fragment. E.g., *.a.com matches foo.a.com but | component or component fragment. E.g., *.a.com matches foo.a.com but | |||
not bar.foo.a.com. f*.com matches foo.com but not bar.com. | not bar.foo.a.com. f*.com matches foo.com but not bar.com. | |||
In some cases, the URI is specified as an IP address rather than a | In some cases, the URI is specified as an IP address rather than a | |||
hostname. In this case, the iPAddress subjectAltName must be present | hostname. In this case, the iPAddress subjectAltName must be present | |||
in the certificate and must exactly match the IP in the URI. | in the certificate and must exactly match the IP in the URI. | |||
If the hostname does not match the identity in the certificate, user | If the hostname does not match the identity in the certificate, user | |||
oriented clients MUST either notify the user (clients MAY give the | oriented clients MUST either notify the user (clients MAY give the | |||
user the opportunity to continue with the connection in any case) or | user the opportunity to continue with the connection in any case) or | |||
terminate the connection with a bad certificate error. Automated | terminate the connection with a bad certificate error. Automated | |||
clients MUST log the error to an appropriate audit log (if available) | clients MUST log the error to an appropriate audit log (if available) | |||
and SHOULD terminate the connection (with a bad certificate error). | and SHOULD terminate the connection (with a bad certificate error). | |||
Automated clients MAY provide a configuration setting that disables | Automated clients MAY provide a configuration setting that disables | |||
this check, but MUST provide a setting which enables it. | this check, but MUST provide a setting which enables it. | |||
Note that in many cases the URI itself comes from an untrusted | Note that in many cases the URI itself comes from an untrusted | |||
source. The above-described check provides no protection against | source. The above-described check provides no protection against | |||
attacks where this source is compromised. For example, if the URI was | attacks where this source is compromised. For example, if the URI | |||
obtained by clicking on an HTML page which was itself obtained | was obtained by clicking on an HTML page which was itself obtained | |||
without using HTTP/TLS, a man in the middle could have replaced the | without using HTTP/TLS, a man in the middle could have replaced the | |||
URI. In order to prevent this form of attack, users should carefully | URI. In order to prevent this form of attack, users should carefully | |||
examine the certificate presented by the server to determine if it | examine the certificate presented by the server to determine if it | |||
meets their expectations. | meets their expectations. | |||
3.2. Client Identity | 2.5.2.3. Identifying HTTPS Clients | |||
Typically, the server has no external knowledge of what the client's | Typically, the server has no external knowledge of what the client's | |||
identity ought to be and so checks (other than that the client has a | identity ought to be and so checks (other than that the client has a | |||
certificate chain rooted in an appropriate CA) are not possible. If a | certificate chain rooted in an appropriate CA) are not possible. If | |||
server has such knowledge (typically from some source external to | a server has such knowledge (typically from some source external to | |||
HTTP or TLS) it SHOULD check the identity as described above. | HTTP or TLS) it SHOULD check the identity as described above. | |||
2.5.3. Fragment Identifiers on http(s) URI References | 2.5.3. Fragment Identifiers on http(s) URI References | |||
The optional fragment component allows for indirect identification of a | Fragment identifiers allow for indirect identification of a secondary | |||
secondary resource, independent of the URI scheme, as defined in Section | resource, independent of the URI scheme, as defined in Section 3.5 of | |||
3.5 of [RFC3986]. | [RFC3986]. Some protocol elements that refer to a URI allow | |||
inclusion of a fragment, while others do not. They are distinguished | ||||
by use of the ABNF rule for elements where fragment is allowed; | ||||
otherwise, a specific rule that excludes fragments is used (see | ||||
Section 5.1). | ||||
Note: the fragment identifier component is not part of the actual | ||||
scheme definition for a URI scheme (see Section 4.3 of [RFC3986]), | ||||
thus does not appear in the ABNF definitions for the "http" and | ||||
"https" URI schemes above. | ||||
2.5.4. http and https URI Normalization and Comparison | 2.5.4. http and https URI Normalization and Comparison | |||
Since the "http" and "https" schemes conform to the URI generic | Since the "http" and "https" schemes conform to the URI generic | |||
syntax, such URIs are normalized and compared according to the | syntax, such URIs are normalized and compared according to the | |||
algorithm defined in Section 6 of [RFC3986], using the defaults | algorithm defined in Section 6 of [RFC3986], using the defaults | |||
described above for each scheme. | described above for each scheme. | |||
If the port is equal to the default port for a scheme, the normal | If the port is equal to the default port for a scheme, the normal | |||
form is to omit the port subcomponent. When not being used in | form is to omit the port subcomponent. When not being used in | |||
absolute form as the request target of an OPTIONS request, an empty | absolute form as the request target of an OPTIONS request, an empty | |||
path component is equivalent to an absolute path of "/", so the | path component is equivalent to an absolute path of "/", so the | |||
normal form is to provide a path of "/" instead. The scheme and host | normal form is to provide a path of "/" instead. The scheme and host | |||
are case-insensitive and normally provided in lowercase; all other | are case-insensitive and normally provided in lowercase; all other | |||
components are compared in a case-sensitive manner. Characters other | components are compared in a case-sensitive manner. Characters other | |||
than those in the "reserved" set are equivalent to their | than those in the "reserved" set are equivalent to their percent- | |||
percent-encoded octets: the normal form is to not encode them (see | encoded octets: the normal form is to not encode them (see Sections | |||
Sections 2.1 and 2.2 of [RFC3986]). | 2.1 and 2.2 of [RFC3986]). | |||
For example, the following three URIs are equivalent: | For example, the following three URIs are equivalent: | |||
http://example.com:80/~smith/home.html | http://example.com:80/~smith/home.html | |||
http://EXAMPLE.com/%7Esmith/home.html | http://EXAMPLE.com/%7Esmith/home.html | |||
http://EXAMPLE.com:/%7esmith/home.html | http://EXAMPLE.com:/%7esmith/home.html | |||
X. [Conformance] | 3. Conformance | |||
2.2. Implementation Diversity | 3.1. Implementation Diversity | |||
When considering the design of HTTP, it is easy to fall into a trap | When considering the design of HTTP, it is easy to fall into a trap | |||
of thinking that all user agents are general-purpose browsers and all | of thinking that all user agents are general-purpose browsers and all | |||
origin servers are large public websites. That is not the case in | origin servers are large public websites. That is not the case in | |||
practice. Common HTTP user agents include household appliances, | practice. Common HTTP user agents include household appliances, | |||
stereos, scales, firmware update scripts, command-line programs, | stereos, scales, firmware update scripts, command-line programs, | |||
mobile apps, and communication devices in a multitude of shapes and | mobile apps, and communication devices in a multitude of shapes and | |||
sizes. Likewise, common HTTP origin servers include home automation | sizes. Likewise, common HTTP origin servers include home automation | |||
units, configurable networking components, office machines, | units, configurable networking components, office machines, | |||
autonomous robots, news feeds, traffic cameras, ad selectors, and | autonomous robots, news feeds, traffic cameras, ad selectors, and | |||
skipping to change at line 840 ¶ | skipping to change at page 21, line 45 ¶ | |||
warning for security or privacy concerns. In the few cases where | warning for security or privacy concerns. In the few cases where | |||
this specification requires reporting of errors to the user, it is | this specification requires reporting of errors to the user, it is | |||
acceptable for such reporting to only be observable in an error | acceptable for such reporting to only be observable in an error | |||
console or log file. Likewise, requirements that an automated action | console or log file. Likewise, requirements that an automated action | |||
be confirmed by the user before proceeding might be met via advance | be confirmed by the user before proceeding might be met via advance | |||
configuration choices, run-time options, or simple avoidance of the | configuration choices, run-time options, or simple avoidance of the | |||
unsafe action; confirmation does not imply any specific user | unsafe action; confirmation does not imply any specific user | |||
interface or interruption of normal processing if the user has | interface or interruption of normal processing if the user has | |||
already made that choice. | already made that choice. | |||
2.5. Conformance and Error Handling | 3.2. Role-based Requirements | |||
This specification targets conformance criteria according to the role | This specification targets conformance criteria according to the role | |||
of a participant in HTTP communication. Hence, HTTP requirements are | of a participant in HTTP communication. Hence, HTTP requirements are | |||
placed on senders, recipients, clients, servers, user agents, | placed on senders, recipients, clients, servers, user agents, | |||
intermediaries, origin servers, proxies, gateways, or caches, | intermediaries, origin servers, proxies, gateways, or caches, | |||
depending on what behavior is being constrained by the requirement. | depending on what behavior is being constrained by the requirement. | |||
Additional (social) requirements are placed on implementations, | Additional (social) requirements are placed on implementations, | |||
resource owners, and protocol element registrations when they apply | resource owners, and protocol element registrations when they apply | |||
beyond the scope of a single communication. | beyond the scope of a single communication. | |||
skipping to change at line 867 ¶ | skipping to change at page 22, line 23 ¶ | |||
Conformance includes both the syntax and semantics of protocol | Conformance includes both the syntax and semantics of protocol | |||
elements. A sender MUST NOT generate protocol elements that convey a | elements. A sender MUST NOT generate protocol elements that convey a | |||
meaning that is known by that sender to be false. A sender MUST NOT | meaning that is known by that sender to be false. A sender MUST NOT | |||
generate protocol elements that do not match the grammar defined by | generate protocol elements that do not match the grammar defined by | |||
the corresponding ABNF rules. Within a given message, a sender MUST | the corresponding ABNF rules. Within a given message, a sender MUST | |||
NOT generate protocol elements or syntax alternatives that are only | NOT generate protocol elements or syntax alternatives that are only | |||
allowed to be generated by participants in other roles (i.e., a role | allowed to be generated by participants in other roles (i.e., a role | |||
that the sender does not have for that message). | that the sender does not have for that message). | |||
3.3. Parsing Elements | ||||
When a received protocol element is parsed, the recipient MUST be | When a received protocol element is parsed, the recipient MUST be | |||
able to parse any value of reasonable length that is applicable to | able to parse any value of reasonable length that is applicable to | |||
the recipient's role and that matches the grammar defined by the | the recipient's role and that matches the grammar defined by the | |||
corresponding ABNF rules. Note, however, that some received protocol | corresponding ABNF rules. Note, however, that some received protocol | |||
elements might not be parsed. For example, an intermediary | elements might not be parsed. For example, an intermediary | |||
forwarding a message might parse a header-field into generic | forwarding a message might parse a header-field into generic field- | |||
field-name and field-value components, but then forward the header | name and field-value components, but then forward the header field | |||
field without further parsing inside the field-value. | without further parsing inside the field-value. | |||
HTTP does not have specific length limitations for many of its | HTTP does not have specific length limitations for many of its | |||
protocol elements because the lengths that might be appropriate will | protocol elements because the lengths that might be appropriate will | |||
vary widely, depending on the deployment context and purpose of the | vary widely, depending on the deployment context and purpose of the | |||
implementation. Hence, interoperability between senders and | implementation. Hence, interoperability between senders and | |||
recipients depends on shared expectations regarding what is a | recipients depends on shared expectations regarding what is a | |||
reasonable length for each protocol element. Furthermore, what is | reasonable length for each protocol element. Furthermore, what is | |||
commonly understood to be a reasonable length for some protocol | commonly understood to be a reasonable length for some protocol | |||
elements has changed over the course of the past two decades of HTTP | elements has changed over the course of the past two decades of HTTP | |||
use and is expected to continue changing in the future. | use and is expected to continue changing in the future. | |||
At a minimum, a recipient MUST be able to parse and process protocol | At a minimum, a recipient MUST be able to parse and process protocol | |||
element lengths that are at least as long as the values that it | element lengths that are at least as long as the values that it | |||
generates for those same protocol elements in other messages. For | generates for those same protocol elements in other messages. For | |||
example, an origin server that publishes very long URI references to | example, an origin server that publishes very long URI references to | |||
its own resources needs to be able to parse and process those same | its own resources needs to be able to parse and process those same | |||
references when received as a request target. | references when received as a request target. | |||
3.4. Error Handling | ||||
A recipient MUST interpret a received protocol element according to | A recipient MUST interpret a received protocol element according to | |||
the semantics defined for it by this specification, including | the semantics defined for it by this specification, including | |||
extensions to this specification, unless the recipient has determined | extensions to this specification, unless the recipient has determined | |||
(through experience or configuration) that the sender incorrectly | (through experience or configuration) that the sender incorrectly | |||
implements what is implied by those semantics. For example, an | implements what is implied by those semantics. For example, an | |||
origin server might disregard the contents of a received | origin server might disregard the contents of a received Accept- | |||
Accept-Encoding header field if inspection of the User-Agent header | Encoding header field if inspection of the User-Agent header field | |||
field indicates a specific implementation version that is known to | indicates a specific implementation version that is known to fail on | |||
fail on receipt of certain content codings. | receipt of certain content codings. | |||
Unless noted otherwise, a recipient MAY attempt to recover a usable | Unless noted otherwise, a recipient MAY attempt to recover a usable | |||
protocol element from an invalid construct. HTTP does not define | protocol element from an invalid construct. HTTP does not define | |||
specific error handling mechanisms except when they have a direct | specific error handling mechanisms except when they have a direct | |||
impact on security, since different applications of the protocol | impact on security, since different applications of the protocol | |||
require different error handling strategies. For example, a Web | require different error handling strategies. For example, a Web | |||
browser might wish to transparently recover from a response where the | browser might wish to transparently recover from a response where the | |||
Location header field doesn't parse according to the ABNF, whereas a | Location header field doesn't parse according to the ABNF, whereas a | |||
systems control client might consider any form of error recovery to | systems control client might consider any form of error recovery to | |||
be dangerous. | be dangerous. | |||
2.6. Protocol Versioning | Some requests can be automatically retried by a client in the event | |||
of an underlying connection failure, as described in Section 7.2.2. | ||||
3.5. Protocol Versioning | ||||
The HTTP version number consists of two decimal digits separated by a | The HTTP version number consists of two decimal digits separated by a | |||
"." (period or decimal point). The first digit ("major version") | "." (period or decimal point). The first digit ("major version") | |||
indicates the HTTP messaging syntax, whereas the second digit ("minor | indicates the HTTP messaging syntax, whereas the second digit ("minor | |||
version") indicates the highest minor version within that major | version") indicates the highest minor version within that major | |||
version to which the sender is conformant and able to understand for | version to which the sender is conformant and able to understand for | |||
future communication. | future communication. | |||
The protocol version as a whole indicates the sender's conformance with | The protocol version as a whole indicates the sender's conformance | |||
the set of requirements laid out in that version's corresponding | with the set of requirements laid out in that version's corresponding | |||
specification of HTTP. | specification of HTTP. For example, the version "HTTP/1.1" is | |||
defined by the combined specifications of this document, "HTTP | ||||
Caching" [Caching], and "HTTP/1.1 Messaging" [Messaging]. | ||||
The minor version advertises the sender's | The minor version advertises the sender's communication capabilities | |||
communication capabilities even when the sender is only using a | even when the sender is only using a backwards-compatible subset of | |||
backwards-compatible subset of the protocol, thereby letting the | the protocol, thereby letting the recipient know that more advanced | |||
recipient know that more advanced features can be used in response | features can be used in response (by servers) or in future requests | |||
(by servers) or in future requests (by clients). | (by clients). | |||
A client SHOULD send a request version equal to the highest version | A client SHOULD send a request version equal to the highest version | |||
to which the client is conformant and whose major version is no | to which the client is conformant and whose major version is no | |||
higher than the highest version supported by the server, if this is | higher than the highest version supported by the server, if this is | |||
known. A client MUST NOT send a version to which it is not | known. A client MUST NOT send a version to which it is not | |||
conformant. | conformant. | |||
A client MAY send a lower request version if it is known that the | A client MAY send a lower request version if it is known that the | |||
server incorrectly implements the HTTP specification, but only after | server incorrectly implements the HTTP specification, but only after | |||
the client has attempted at least one normal request and determined | the client has attempted at least one normal request and determined | |||
from the response status code or header fields (e.g., Server) that | from the response status code or header fields (e.g., Server) that | |||
the server improperly handles higher request versions. | the server improperly handles higher request versions. | |||
A server SHOULD send a response version equal to the highest version | A server SHOULD send a response version equal to the highest version | |||
to which the server is conformant that has a major version less than | to which the server is conformant that has a major version less than | |||
or equal to the one received in the request. A server MUST NOT send | or equal to the one received in the request. A server MUST NOT send | |||
a version to which it is not conformant. A server can send a 505 | a version to which it is not conformant. A server can send a 505 | |||
(HTTP Version Not Supported) response if it wishes, for any reason, | (HTTP Version Not Supported) response if it wishes, for any reason, | |||
to refuse service of the client's major protocol version. | to refuse service of the client's major protocol version. | |||
The intention of HTTP's versioning design is that the major number | HTTP's major version number is incremented when an incompatible | |||
will only be incremented if an incompatible message syntax is | message syntax is introduced. The minor number is incremented when | |||
introduced, and that the minor number will only be incremented when | ||||
changes made to the protocol have the effect of adding to the message | changes made to the protocol have the effect of adding to the message | |||
semantics or implying additional capabilities of the sender. | semantics or implying additional capabilities of the sender. | |||
However, the minor version was not incremented for the changes | ||||
introduced between [RFC2068] and [RFC2616], and this revision has | ||||
specifically avoided any such changes to the protocol. | ||||
When an HTTP message is received with a major version number that the | When an HTTP message is received with a major version number that the | |||
recipient implements, but a higher minor version number than what the | recipient implements, but a higher minor version number than what the | |||
recipient implements, the recipient SHOULD process the message as if | recipient implements, the recipient SHOULD process the message as if | |||
it were in the highest minor version within that major version to | it were in the highest minor version within that major version to | |||
which the recipient is conformant. A recipient can assume that a | which the recipient is conformant. A recipient can assume that a | |||
message with a higher minor version, when sent to a recipient that | message with a higher minor version, when sent to a recipient that | |||
has not yet indicated support for that higher version, is | has not yet indicated support for that higher version, is | |||
sufficiently backwards-compatible to be safely processed by any | sufficiently backwards-compatible to be safely processed by any | |||
implementation of the same major version. | implementation of the same major version. | |||
When a major version of HTTP does not define any minor versions, the | ||||
minor version "0" is implied and is used when referring to that | ||||
protocol within a protocol element that requires sending a minor | ||||
version. | ||||
4. Header Fields | 4. Header Fields | |||
This section defines the abstraction for message fields as field-name | ||||
and field-value pairs. | ||||
4.1. Header Field Names | 4.1. Header Field Names | |||
Header fields are key:value pairs that can be used to communicate | Header fields are key:value pairs that can be used to communicate | |||
data about the message, its payload, the target resource, or the | data about the message, its payload, the target resource, or the | |||
connection (i.e., control data). See Section 3.2 of [RFC7230] for a | connection (i.e., control data). | |||
general definition of header field syntax in HTTP messages. | ||||
The requirements for header field names are defined in [BCP90]. | The requirements for header field names are defined in [BCP90]. | |||
The field-name token labels the corresponding field-value as having | The field-name token labels the corresponding field-value as having | |||
the semantics defined by that header field. For example, the Date | the semantics defined by that header field. For example, the Date | |||
header field is defined in Section 7.1.1.2 of [RFC7231] as containing | header field is defined in Section 10.1.1.2 as containing the | |||
the origination timestamp for the message in which it appears. | origination timestamp for the message in which it appears. | |||
field-name = token | field-name = token | |||
The interpretation of a header field does not change between minor | The interpretation of a header field does not change between minor | |||
versions of the same major HTTP version, though the default behavior | versions of the same major HTTP version, though the default behavior | |||
of a recipient in the absence of such a field can change. Unless | of a recipient in the absence of such a field can change. Unless | |||
specified otherwise, header fields defined in HTTP/1.1 are defined | specified otherwise, header fields are defined for all versions of | |||
for all versions of HTTP/1.x. In particular, the Host and Connection | HTTP. In particular, the Host and Connection header fields ought to | |||
header fields ought to be implemented by all HTTP/1.x implementations | be implemented by all HTTP/1.x implementations whether or not they | |||
whether or not they advertise conformance with HTTP/1.1. | advertise conformance with HTTP/1.1. | |||
New header fields can be introduced without changing the protocol | New header fields can be introduced without changing the protocol | |||
version if their defined semantics allow them to be safely ignored by | version if their defined semantics allow them to be safely ignored by | |||
recipients that do not recognize them. Header field extensibility is | recipients that do not recognize them. Header field extensibility is | |||
discussed in Section 3.2.1. | discussed in Section 4.1.2. | |||
The "Message Headers" registry has been updated with the following | The following field names are defined by this document: | |||
permanent registrations: | ||||
+-------------------+----------+----------+-----------------+ | +---------------------------+------------+-------------------+ | |||
| Header Field Name | Protocol | Status | Reference | | | Header Field Name | Status | Reference | | |||
+-------------------+----------+----------+-----------------+ | +---------------------------+------------+-------------------+ | |||
| Accept | http | standard | Section 5.3.2 | | | Accept | standard | Section 8.4.2 | | |||
| Accept-Charset | http | standard | Section 5.3.3 | | | Accept-Charset | deprecated | Section 8.4.3 | | |||
| Accept-Encoding | http | standard | Section 5.3.4 | | | Accept-Encoding | standard | Section 8.4.4 | | |||
| Accept-Language | http | standard | Section 5.3.5 | | | Accept-Language | standard | Section 8.4.5 | | |||
| Accept-Ranges | http | standard | Section 2.3 | | | Accept-Ranges | standard | Section 10.4.1 | | |||
| Allow | http | standard | Section 7.4.1 | | | Allow | standard | Section 10.4.2 | | |||
| Authorization | http | standard | Section 4.2 | | | Authentication-Info | standard | Section 10.3.3 | | |||
| Content-Encoding | http | standard | Section 3.1.2.2 | | | Authorization | standard | Section 8.5.3 | | |||
| Content-Language | http | standard | Section 3.1.3.2 | | | Content-Encoding | standard | Section 6.2.2 | | |||
| Content-Length | http | standard | Section 3.3.2 | | | Content-Language | standard | Section 6.2.3 | | |||
| Content-Location | http | standard | Section 3.1.4.2 | | | Content-Length | standard | Section 6.2.4 | | |||
| Content-Range | http | standard | Section 4.2 | | | Content-Location | standard | Section 6.2.5 | | |||
| Content-Type | http | standard | Section 3.1.1.5 | | | Content-Range | standard | Section 6.3.4 | | |||
| Date | http | standard | Section 7.1.1.2 | | | Content-Type | standard | Section 6.2.1 | | |||
| ETag | http | standard | Section 2.3 | | | Date | standard | Section 10.1.1.2 | | |||
| Expect | http | standard | Section 5.1.1 | | | ETag | standard | Section 10.2.3 | | |||
| From | http | standard | Section 5.5.1 | | | Expect | standard | Section 8.1.1 | | |||
| Host | http | standard | Section 5.4 | | | From | standard | Section 8.6.1 | | |||
| If-Match | http | standard | Section 3.1 | | | Host | standard | Section 5.4 | | |||
| If-Modified-Since | http | standard | Section 3.3 | | | If-Match | standard | Section 8.2.3 | | |||
| If-None-Match | http | standard | Section 3.2 | | | If-Modified-Since | standard | Section 8.2.5 | | |||
| If-Range | http | standard | Section 3.2 | | | If-None-Match | standard | Section 8.2.4 | | |||
| If-Unmodified-Since | http | standard | Section 3.4 | | | If-Range | standard | Section 8.2.7 | | |||
| Last-Modified | http | standard | Section 2.2 | | | If-Unmodified-Since | standard | Section 8.2.6 | | |||
| Location | http | standard | Section 7.1.2 | | | Last-Modified | standard | Section 10.2.2 | | |||
| Max-Forwards | http | standard | Section 5.1.2 | | | Location | standard | Section 10.1.2 | | |||
| Proxy-Authenticate | http | standard | Section 4.3 | | | Max-Forwards | standard | Section 8.1.2 | | |||
| Proxy-Authorization | http | standard | Section 4.4 | | | Proxy-Authenticate | standard | Section 10.3.2 | | |||
| Range | http | standard | Section 3.1 | | | Proxy-Authentication-Info | standard | Section 10.3.4 | | |||
| Referer | http | standard | Section 5.5.2 | | | Proxy-Authorization | standard | Section 8.5.4 | | |||
| Retry-After | http | standard | Section 7.1.3 | | | Range | standard | Section 8.3 | | |||
| Server | http | standard | Section 7.4.2 | | | Referer | standard | Section 8.6.2 | | |||
| Trailer | http | standard | Section 4.4 | | | Retry-After | standard | Section 10.1.3 | | |||
| User-Agent | http | standard | Section 5.5.3 | | | Server | standard | Section 10.4.3 | | |||
| Vary | http | standard | Section 7.1.4 | | | Trailer | standard | Section 4.3.3 | | |||
| Via | http | standard | Section 5.7.1 | | | User-Agent | standard | Section 8.6.3 | | |||
| WWW-Authenticate | http | standard | Section 4.1 | | | Vary | standard | Section 10.1.4 | | |||
+-------------------+----------+----------+-----------------+ | | Via | standard | Section 5.5.1 | | |||
| WWW-Authenticate | standard | Section 10.3.1 | | ||||
+---------------------------+------------+-------------------+ | ||||
Table 1 | ||||
4.1.1. Header Field Name Registry | 4.1.1. Header Field Name Registry | |||
HTTP header fields are registered within the "Message Headers" | The "Hypertext Transfer Protocol (HTTP) Header Field Registry" | |||
registry located at | defines the namespace for HTTP header field names. | |||
<http://www.iana.org/assignments/message-headers>, as defined by | ||||
[BCP90]. | Any party can request registration of a HTTP header field. See | |||
Section 4.4 for considerations to take into account when creating a | ||||
new HTTP header field. | ||||
The "HTTP Header Field Name" registry is located at | ||||
"https://www.iana.org/assignments/http-headers/". Registration | ||||
requests can be made by following the instructions located there or | ||||
by sending an email to the "ietf-http-wg@ietf.org" mailing list. | ||||
Header field names are registered on the advice of a Designated | ||||
Expert (appointed by the IESG or their delegate). Header fields with | ||||
the status 'permanent' are Specification Required (using terminology | ||||
from [RFC8126]). | ||||
Registration requests consist of at least the following information: | ||||
o Header field name: The requested field name. It MUST conform to | ||||
the field-name syntax defined in Section 4.1, and SHOULD be | ||||
restricted to just letters, digits, hyphen ('-') and underscore | ||||
('_') characters, with the first character being a letter. | ||||
o Status: "permanent" or "provisional" | ||||
o Specification document(s): Reference to the document that | ||||
specifies the header field, preferably including a URI that can be | ||||
used to retrieve a copy of the document. An indication of the | ||||
relevant section(s) can also be included, but is not required. | ||||
The Expert(s) can define additional fields to be collected in the | ||||
registry, in consultation with the community. | ||||
Standards-defined names have a status of "permanent". Other names | ||||
can also be registered as permanent, if the Expert(s) find that they | ||||
are in use, in consultation with the community. Other names should | ||||
be registered as "provisional". | ||||
Provisional entries can be removed by the Expert(s) if -- in | ||||
consultation with the community -- the Expert(s) find that they are | ||||
not in use. The Experts can change a provisional entry's status to | ||||
permanent at any time. | ||||
Note that names can be registered by third parties (including the | ||||
Expert(s)), if the Expert(s) determines that an unregistered name is | ||||
widely deployed and not likely to be registered in a timely manner | ||||
otherwise. | ||||
4.1.2. Header Field Extensibility | 4.1.2. Header Field Extensibility | |||
Header fields are fully extensible: there is no limit on the | Header fields are fully extensible: there is no limit on the | |||
introduction of new field names, each presumably defining new | introduction of new field names, each presumably defining new | |||
semantics, nor on the number of header fields used in a given | semantics, nor on the number of header fields used in a given | |||
message. Existing fields are defined in each part of this | message. Existing fields are defined in each part of this | |||
specification and in many other specifications outside this document | specification and in many other specifications outside this document | |||
set. | set. | |||
New header fields can be defined such that, when they are understood | New header fields can be defined such that, when they are understood | |||
by a recipient, they might override or enhance the interpretation of | by a recipient, they might override or enhance the interpretation of | |||
previously defined header fields, define preconditions on request | previously defined header fields, define preconditions on request | |||
evaluation, or refine the meaning of responses. | evaluation, or refine the meaning of responses. | |||
A proxy MUST forward unrecognized header fields unless the field-name | A proxy MUST forward unrecognized header fields unless the field-name | |||
is listed in the Connection header field (Section 6.1) or the proxy | is listed in the Connection header field (Section 9.1 of [Messaging]) | |||
is specifically configured to block, or otherwise transform, such | or the proxy is specifically configured to block, or otherwise | |||
fields. Other recipients SHOULD ignore unrecognized header fields. | transform, such fields. Other recipients SHOULD ignore unrecognized | |||
These requirements allow HTTP's functionality to be enhanced without | header fields. These requirements allow HTTP's functionality to be | |||
requiring prior update of deployed intermediaries. | enhanced without requiring prior update of deployed intermediaries. | |||
All defined header fields ought to be registered with IANA in the | All defined header fields ought to be registered with IANA in the | |||
"Message Headers" registry, as described in Section 8.3 of [RFC7231]. | "HTTP Header Field Name" registry. | |||
4.2. Field Values | 4.2. Header Field Values | |||
Consequently, this specification does not use ABNF rules | This specification does not use ABNF rules to define each "Field- | |||
to define each "Field-Name: Field Value" pair, as was done in | Name: Field Value" pair, as was done in earlier editions. Instead, | |||
previous editions. Instead, this specification uses ABNF rules that | this specification uses ABNF rules that are named according to each | |||
are named according to each registered field name, wherein the rule | registered field name, wherein the rule defines the valid grammar for | |||
defines the valid grammar for that field's corresponding field values | that field's corresponding field values (i.e., after the field-value | |||
(i.e., after the field-value has been extracted from the header | has been extracted by a generic field parser). | |||
section by a generic field parser). | ||||
field-value = *( field-content / obs-fold ) | field-value = *( field-content / obs-fold ) | |||
field-content = field-vchar [ 1*( SP / HTAB ) field-vchar ] | field-content = field-vchar | |||
[ 1*( SP / HTAB / field-vchar ) field-vchar ] | ||||
field-vchar = VCHAR / obs-text | field-vchar = VCHAR / obs-text | |||
Historically, HTTP header field values could be extended over | Historically, HTTP header field values could be extended over | |||
multiple lines by preceding each extra line with at least one space | multiple lines by preceding each extra line with at least one space | |||
or horizontal tab (obs-fold). | or horizontal tab (obs-fold). [[CREF1: This document assumes that | |||
any such obs-fold has been replaced with one or more SP octets prior | ||||
to interpreting the field value, as described in Section 5.2 of | ||||
[Messaging].]] | ||||
Historically, HTTP has allowed field content with text in the | Historically, HTTP has allowed field content with text in the | |||
ISO-8859-1 charset [ISO-8859-1], supporting other charsets only | ISO-8859-1 charset [ISO-8859-1], supporting other charsets only | |||
through use of [RFC2047] encoding. In practice, most HTTP header | through use of [RFC2047] encoding. In practice, most HTTP header | |||
field values use only a subset of the US-ASCII charset [USASCII]. | field values use only a subset of the US-ASCII charset [USASCII]. | |||
Newly defined header fields SHOULD limit their field values to | Newly defined header fields SHOULD limit their field values to | |||
US-ASCII octets. A recipient SHOULD treat other octets in field | US-ASCII octets. A recipient SHOULD treat other octets in field | |||
content (obs-text) as opaque data. | content (obs-text) as opaque data. | |||
4.2.1. Field Order | 4.2.1. Header Field Order | |||
The order in which header fields with differing field names are | The order in which header fields with differing field names are | |||
received is not significant. However, it is good practice to send | received is not significant. However, it is good practice to send | |||
header fields that contain control data first, such as Host on | header fields that contain control data first, such as Host on | |||
requests and Date on responses, so that implementations can decide | requests and Date on responses, so that implementations can decide | |||
when not to handle a message as early as possible. A server MUST NOT | when not to handle a message as early as possible. A server MUST NOT | |||
apply a request to the target resource until the entire request | apply a request to the target resource until the entire request | |||
header section is received, since later header fields might include | header section is received, since later header fields might include | |||
conditionals, authentication credentials, or deliberately misleading | conditionals, authentication credentials, or deliberately misleading | |||
duplicate header fields that would impact request processing. | duplicate header fields that would impact request processing. | |||
A sender MUST NOT generate multiple header fields with the same field | Aside from the well-known exception noted below, a sender MUST NOT | |||
name in a message unless either the entire field value for that | generate multiple header fields with the same field name in a | |||
header field is defined as a comma-separated list [i.e., #(values)] | message, or append a header field when a field of the same name | |||
or the header field is a well-known exception (as noted below). | already exists in the message, unless that field's definition allows | |||
multiple field values to be recombined as a comma-separated list | ||||
[i.e., at least one alternative of the field's definition allows a | ||||
comma-separated list, such as an ABNF rule of #(values)]. | ||||
A recipient MAY combine multiple header fields with the same field | A recipient MAY combine multiple header fields with the same field | |||
name into one "field-name: field-value" pair, without changing the | name into one "field-name: field-value" pair, without changing the | |||
semantics of the message, by appending each subsequent field value to | semantics of the message, by appending each subsequent field value to | |||
the combined field value in order, separated by a comma. The order | the combined field value in order, separated by a comma. The order | |||
in which header fields with the same field name are received is | in which header fields with the same field name are received is | |||
therefore significant to the interpretation of the combined field | therefore significant to the interpretation of the combined field | |||
value; a proxy MUST NOT change the order of these field values when | value; a proxy MUST NOT change the order of these field values when | |||
forwarding a message. | forwarding a message. | |||
Note: In practice, the "Set-Cookie" header field ([RFC6265]) often | Note: In practice, the "Set-Cookie" header field ([RFC6265]) often | |||
appears multiple times in a response message and does not use the | appears multiple times in a response message and does not use the | |||
list syntax, violating the above requirements on multiple header | list syntax, violating the above requirements on multiple header | |||
fields with the same name. Since it cannot be combined into a | fields with the same name. Since it cannot be combined into a | |||
single field-value, recipients ought to handle "Set-Cookie" as a | single field-value, recipients ought to handle "Set-Cookie" as a | |||
special case while processing header fields. (See Appendix A.2.3 | special case while processing header fields. (See Appendix A.2.3 | |||
of [Kri2001] for details.) | of [Kri2001] for details.) | |||
3.2.5. Field Limits | 4.2.2. Header Field Limits | |||
HTTP does not place a predefined limit on the length of each header | HTTP does not place a predefined limit on the length of each header | |||
field or on the length of the header section as a whole, as described | field or on the length of the header section as a whole, as described | |||
in Section 2.5. Various ad hoc limitations on individual header | in Section 3. Various ad hoc limitations on individual header field | |||
field length are found in practice, often depending on the specific | length are found in practice, often depending on the specific field | |||
field semantics. | semantics. | |||
A server that receives a request header field, or set of fields, | A server that receives a request header field, or set of fields, | |||
larger than it wishes to process MUST respond with an appropriate 4xx | larger than it wishes to process MUST respond with an appropriate 4xx | |||
(Client Error) status code. Ignoring such header fields would | (Client Error) status code. Ignoring such header fields would | |||
increase the server's vulnerability to request smuggling attacks | increase the server's vulnerability to request smuggling attacks | |||
(Section 9.5). | (Section 11.2 of [Messaging]). | |||
A client MAY discard or truncate received header fields that are | A client MAY discard or truncate received header fields that are | |||
larger than the client wishes to process if the field semantics are | larger than the client wishes to process if the field semantics are | |||
such that the dropped value(s) can be safely ignored without changing | such that the dropped value(s) can be safely ignored without changing | |||
the message framing or response semantics. | the message framing or response semantics. | |||
3.2.6. Field Value Components | 4.2.3. Header Field Value Components | |||
Most HTTP header field values are defined using common syntax | Many HTTP header field values are defined using common syntax | |||
components (token, quoted-string, and comment) separated by | components, separated by whitespace or specific delimiting | |||
whitespace or specific delimiting characters. Delimiters are chosen | characters. Delimiters are chosen from the set of US-ASCII visual | |||
from the set of US-ASCII visual characters not allowed in a token | characters not allowed in a token (DQUOTE and "(),/:;<=>?@[\]{}"). | |||
(DQUOTE and "(),/:;<=>?@[\]{}"). | ||||
4.2.3.1. Tokens | ||||
Tokens are short textual identifiers that do not include whitespace | ||||
or delimiters. | ||||
token = 1*tchar | token = 1*tchar | |||
tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" | tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" | |||
/ "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" | / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" | |||
/ DIGIT / ALPHA | / DIGIT / ALPHA | |||
; any VCHAR, except delimiters | ; any VCHAR, except delimiters | |||
4.2.3.2. Quoted Strings | ||||
A string of text is parsed as a single value if it is quoted using | A string of text is parsed as a single value if it is quoted using | |||
double-quote marks. | double-quote marks. | |||
quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE | quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE | |||
qdtext = HTAB / SP /%x21 / %x23-5B / %x5D-7E / obs-text | qdtext = HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text | |||
obs-text = %x80-FF | obs-text = %x80-FF | |||
The backslash octet ("\") can be used as a single-octet quoting | The backslash octet ("\") can be used as a single-octet quoting | |||
mechanism within quoted-string and comment constructs. Recipients | mechanism within quoted-string and comment constructs. Recipients | |||
that process the value of a quoted-string MUST handle a quoted-pair | that process the value of a quoted-string MUST handle a quoted-pair | |||
as if it were replaced by the octet following the backslash. | as if it were replaced by the octet following the backslash. | |||
quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) | quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) | |||
A sender SHOULD NOT generate a quoted-pair in a quoted-string except | A sender SHOULD NOT generate a quoted-pair in a quoted-string except | |||
where necessary to quote DQUOTE and backslash octets occurring within | where necessary to quote DQUOTE and backslash octets occurring within | |||
that string. A sender SHOULD NOT generate a quoted-pair in a comment | that string. A sender SHOULD NOT generate a quoted-pair in a comment | |||
except where necessary to quote parentheses ["(" and ")"] and | except where necessary to quote parentheses ["(" and ")"] and | |||
backslash octets occurring within that comment. | backslash octets occurring within that comment. | |||
4.2.3.3. Comments | ||||
Comments can be included in some HTTP header fields by surrounding | Comments can be included in some HTTP header fields by surrounding | |||
the comment text with parentheses. Comments are only allowed in | the comment text with parentheses. Comments are only allowed in | |||
fields containing "comment" as part of their field value definition. | fields containing "comment" as part of their field value definition. | |||
comment = "(" *( ctext / quoted-pair / comment ) ")" | comment = "(" *( ctext / quoted-pair / comment ) ")" | |||
ctext = HTAB / SP / %x21-27 / %x2A-5B / %x5D-7E / obs-text | ctext = HTAB / SP / %x21-27 / %x2A-5B / %x5D-7E / obs-text | |||
parameter = token "=" ( token / quoted-string ) | 4.2.3.4. Parameters | |||
The parameter name tokens are case-insensitive. | A parameter is a name=value pair that is often defined within header | |||
Parameter values might or might not be case-sensitive, depending on | field values as a common syntax for appending auxiliary information | |||
the semantics of the parameter name. | to an item. Each parameter is usually delimited by an immediately | |||
preceding semicolon. | ||||
parameter = parameter-name "=" parameter-value | ||||
parameter-name = token | ||||
parameter-value = ( token / quoted-string ) | ||||
Parameter names are case-insensitive. Parameter values might or | ||||
might not be case-sensitive, depending on the semantics of the | ||||
parameter name. Examples of parameters and some equivalent forms can | ||||
be seen in media types (Section 6.1.1) and the Accept header field | ||||
(Section 8.4.2). | ||||
A parameter value that matches the token production can be | A parameter value that matches the token production can be | |||
transmitted either as a token or within a quoted-string. The quoted | transmitted either as a token or within a quoted-string. The quoted | |||
and unquoted values are equivalent. | and unquoted values are equivalent. | |||
Note: Unlike some similar constructs in other header fields, media | Note: Parameters do not allow whitespace (not even "bad" | |||
type parameters do not allow whitespace (even "bad" whitespace) | whitespace) around the "=" character. | |||
around the "=" character. | ||||
X.X. [Trailer Fields] | 4.3. Trailer Fields | |||
A trailer allows the sender to include additional fields at the end | 4.3.1. Purpose | |||
of a chunked message in order to supply metadata that might be | ||||
dynamically generated while the message body is sent, such as a | ||||
message integrity check, digital signature, or post-processing | ||||
status. The trailer fields are identical to header fields, except | ||||
they are sent in a chunked trailer instead of the message's header | ||||
section. | ||||
A sender MUST NOT generate a trailer that contains a field necessary | In some HTTP versions, additional metadata can be sent after the | |||
for message framing (e.g., Transfer-Encoding and Content-Length), | initial header section has been completed (during or after | |||
routing (e.g., Host), request modifiers (e.g., controls and | transmission of the payload body), such as a message integrity check, | |||
conditionals in Section 5 of [RFC7231]), authentication (e.g., see | digital signature, or post-processing status. For example, the | |||
[RFC7235] and [RFC6265]), response control data (e.g., see Section | chunked coding in HTTP/1.1 allows a trailer section after the payload | |||
7.1 of [RFC7231]), or determining how to process the payload (e.g., | body (Section 7.1.2 of [Messaging]) which can contain trailer fields: | |||
Content-Encoding, Content-Type, Content-Range, and Trailer). | field names and values that share the same syntax and namespace as | |||
header fields but are received after the header section. | ||||
When a chunked message containing a non-empty trailer is received, | Trailer fields ought to be processed and stored separately from the | |||
the recipient MAY process the fields (aside from those forbidden | fields in the header section to avoid contradicting message semantics | |||
above) as if they were appended to the message's header section. A | known at the time the header section was complete. The presence or | |||
recipient MUST ignore (or consider as an error) any fields that are | absence of certain header fields might impact choices made for the | |||
forbidden to be sent in a trailer, since processing them as if they | routing or processing of the message as a whole before the trailers | |||
were present in the header section might bypass external security | are received; those choices cannot be unmade by the later discovery | |||
filters. | of trailer fields. | |||
Unless the request includes a TE header field indicating "trailers" | 4.3.2. Limitations | |||
is acceptable, as described in Section 4.3, a server SHOULD NOT | ||||
generate trailer fields that it believes are necessary for the user | Many header fields cannot be processed outside the header section | |||
agent to receive. Without a TE containing "trailers", the server | because their evaluation is necessary prior to receiving the message | |||
ought to assume that the trailer fields might be silently discarded | body, such as fields that describe message framing, routing, | |||
along the path to the user agent. This requirement allows | authentication, request modifiers, response controls, or payload | |||
intermediaries to forward a de-chunked message to an HTTP/1.0 | format. A sender MUST NOT generate a trailer field unless the sender | |||
recipient without buffering the entire response. | knows the corresponding header field name's definition permits the | |||
field to be sent in trailers. | ||||
Trailer fields can be difficult to process by intermediaries that | ||||
forward messages from one protocol version to another. If the entire | ||||
message can be buffered in transit, some intermediaries could merge | ||||
trailer fields into the header section (as appropriate) before it is | ||||
forwarded. However, in most cases, the trailers are simply | ||||
discarded. A recipient MUST NOT merge a trailer field into a header | ||||
section unless the recipient understands the corresponding header | ||||
field definition and that definition explicitly permits and defines | ||||
how trailer field values can be safely merged. | ||||
A client can send a TE header field indicating "trailers" is | ||||
acceptable, as described in Section 7.4 of [Messaging], to inform the | ||||
server that it will not discard trailer fields. | ||||
Because of the potential for trailer fields to be discarded in | ||||
transit, a server SHOULD NOT generate trailer fields that it believes | ||||
are necessary for the user agent to receive. | ||||
4.3.3. Trailer | 4.3.3. Trailer | |||
The "Trailer" header field provides a list of field names that the | ||||
sender anticipates sending as trailer fields within that message. | ||||
This allows a recipient to prepare for receipt of the indicated | ||||
metadata before it starts processing the body. | ||||
Trailer = 1#field-name | Trailer = 1#field-name | |||
When a message includes a message body encoded with the chunked | For example, a sender might indicate that a message integrity check | |||
transfer coding and the sender desires to send metadata in the form | will be computed as the payload is being streamed and provide the | |||
of trailer fields at the end of the message, the sender SHOULD | final signature as a trailer field. This allows a recipient to | |||
generate a Trailer header field before the message body to indicate | perform the same check on the fly as the payload data is received. | |||
which fields will be present in the trailers. This allows the | ||||
recipient to prepare for receipt of that metadata before it starts | A sender that intends to generate one or more trailer fields in a | |||
processing the body, which is useful if the message is being streamed | message SHOULD generate a Trailer header field in the header section | |||
and the recipient wishes to confirm an integrity check on the fly. | of that message to indicate which fields might be present in the | |||
trailers. | ||||
4.4. Considerations for New Header Fields | 4.4. Considerations for New Header Fields | |||
Authors of specifications defining new fields are advised to keep the | Authors of specifications defining new fields are advised to choose a | |||
name as short as practical and not to prefix the name with "X-" | short but descriptive field name. Short names avoid needless data | |||
unless the header field will never be used on the Internet. (The | transmission; descriptive names avoid confusion and "squatting" on | |||
"X-" prefix idiom has been extensively misused in practice; it was | names that might have broader uses. | |||
intended to only be used as a mechanism for avoiding name collisions | ||||
inside proprietary software or intranet processing, since the prefix | ||||
would ensure that private names never collide with a newly registered | ||||
Internet name; see [BCP178] for further information). | ||||
New header field values typically have their syntax defined using | To that end, limited-use fields (such as a header confined to a | |||
ABNF ([RFC5234]), using the extension defined in Section 7 of | single application or use case) are encouraged to use a name that | |||
[RFC7230] as necessary, and are usually constrained to the range of | includes its name (or an abbreviation) as a prefix; for example, if | |||
US-ASCII characters. Header fields needing a greater range of | the Foo Application needs a Description field, it might use "Foo- | |||
characters can use an encoding such as the one defined in [RFC5987]. | Desc"; "Description" is too generic, and "Foo-Description" is | |||
needlessly long. | ||||
Header field names ought not be prefixed with "X-"; see [BCP178] for | ||||
further information. | ||||
Other prefixes are sometimes used in HTTP header field names; for | ||||
example, "Accept-" is used in many content negotiation headers. | ||||
These prefixes are only an aid to recognizing the purpose of a header | ||||
field, and do not trigger automatic processing. | ||||
Header field values typically have their syntax defined using ABNF | ||||
([RFC5234]), using the extension defined in Section 12 as necessary, | ||||
and are usually constrained to the range of US-ASCII characters. | ||||
Header fields needing a greater range of characters can use an | ||||
encoding such as the one defined in [RFC8187]. | ||||
Leading and trailing whitespace in raw field values is removed upon | Leading and trailing whitespace in raw field values is removed upon | |||
field parsing (Section 3.2.4 of [RFC7230]). Field definitions where | field parsing (Section 5.1 of [Messaging]). Field definitions where | |||
leading or trailing whitespace in values is significant will have to | leading or trailing whitespace in values is significant will have to | |||
use a container syntax such as quoted-string (Section 3.2.6 of | use a container syntax such as quoted-string (Section 4.2.3.2). | |||
[RFC7230]). | ||||
Because commas (",") are used as a generic delimiter between | Because commas (",") are used as a generic delimiter between field- | |||
field-values, they need to be treated with care if they are allowed | values, they need to be treated with care if they are allowed in the | |||
in the field-value. Typically, components that might contain a comma | field-value. Typically, components that might contain a comma are | |||
are protected with double-quotes using the quoted-string ABNF | protected with double-quotes using the quoted-string ABNF production. | |||
production. | ||||
For example, a textual date and a URI (either of which might contain | For example, a textual date and a URI (either of which might contain | |||
a comma) could be safely carried in field-values like these: | a comma) could be safely carried in field-values like these: | |||
Example-URI-Field: "http://example.com/a.html,foo", | Example-URI-Field: "http://example.com/a.html,foo", | |||
"http://without-a-comma.example.com/" | "http://without-a-comma.example.com/" | |||
Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005" | Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005" | |||
Note that double-quote delimiters almost always are used with the | Note that double-quote delimiters almost always are used with the | |||
quoted-string production; using a different syntax inside | quoted-string production; using a different syntax inside double- | |||
double-quotes will likely cause unnecessary confusion. | quotes will likely cause unnecessary confusion. | |||
Many header fields use a format including (case-insensitively) named | Many header fields (such as Content-Type, defined in Section 6.2.1) | |||
parameters (for instance, Content-Type, defined in Section 3.1.1.5). | use a common syntax for parameters that allows both unquoted (token) | |||
Allowing both unquoted (token) and quoted (quoted-string) syntax for | and quoted (quoted-string) syntax for a parameter value | |||
the parameter value enables recipients to use existing parser | (Section 4.2.3.4). Use of common syntax allows recipients to reuse | |||
components. When allowing both forms, the meaning of a parameter | existing parser components. When allowing both forms, the meaning of | |||
value ought to be independent of the syntax used for it (for an | a parameter value ought to be the same whether it was received as a | |||
example, see the notes on parameter handling for media types in | token or a quoted string. | |||
Section 3.1.1.1). | ||||
Authors of specifications defining new header fields are advised to | Authors of specifications defining new header fields are advised to | |||
consider documenting: | consider documenting: | |||
o Whether the field is a single value or whether it can be a list | o Whether the field is a single value or whether it can be a list | |||
(delimited by commas; see Section 3.2 of [RFC7230]). | (delimited by commas; see Section 4.2). | |||
If it does not use the list syntax, document how to treat messages | If it does not use the list syntax, document how to treat messages | |||
where the field occurs multiple times (a sensible default would be | where the field occurs multiple times (a sensible default would be | |||
to ignore the field, but this might not always be the right | to ignore the field, but this might not always be the right | |||
choice). | choice). | |||
Note that intermediaries and software libraries might combine | Note that intermediaries and software libraries might combine | |||
multiple header field instances into a single one, despite the | multiple header field instances into a single one, despite the | |||
field's definition not allowing the list syntax. A robust format | field's definition not allowing the list syntax. A robust format | |||
enables recipients to discover these situations (good example: | enables recipients to discover these situations (good example: | |||
skipping to change at line 1340 ¶ | skipping to change at page 35, line 17 ¶ | |||
particular request method, etc. | particular request method, etc. | |||
o Whether the field should be stored by origin servers that | o Whether the field should be stored by origin servers that | |||
understand it upon a PUT request. | understand it upon a PUT request. | |||
o Whether the field semantics are further refined by the context, | o Whether the field semantics are further refined by the context, | |||
such as by existing request methods or status codes. | such as by existing request methods or status codes. | |||
o Whether it is appropriate to list the field-name in the Connection | o 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 | header field (i.e., if the header field is to be hop-by-hop; see | |||
Section 6.1 of [RFC7230]). | Section 9.1 of [Messaging]). | |||
o Under what conditions intermediaries are allowed to insert, | o Under what conditions intermediaries are allowed to insert, | |||
delete, or modify the field's value. | delete, or modify the field's value. | |||
o Whether it is appropriate to list the field-name in a Vary | o Whether it is appropriate to list the field-name in a Vary | |||
response header field (e.g., when the request header field is used | response header field (e.g., when the request header field is used | |||
by an origin server's content selection algorithm; see | by an origin server's content selection algorithm; see | |||
Section 7.1.4). | Section 10.1.4). | |||
o Whether the header field is useful or allowable in trailers (see | o Whether the header field is useful or allowable in trailers (see | |||
Section 4.1 of [RFC7230]). | Section 7.1 of [Messaging]). | |||
o Whether the header field ought to be preserved across redirects. | o Whether the header field ought to be preserved across redirects. | |||
o Whether it introduces any additional security considerations, such | o Whether it introduces any additional security considerations, such | |||
as disclosure of privacy-related data. | as disclosure of privacy-related data. | |||
5. Message Routing | 5. Message Routing | |||
HTTP request message routing is determined by each client based on | HTTP request message routing is determined by each client based on | |||
the target resource, the client's proxy configuration, and | the target resource, the client's proxy configuration, and | |||
establishment or reuse of an inbound connection. The corresponding | establishment or reuse of an inbound connection. The corresponding | |||
response routing follows the same connection chain back to the | response routing follows the same connection chain back to the | |||
client. | client. | |||
5.1. Identifying a Target Resource | 5.1. Identifying a Target Resource | |||
HTTP is used in a wide variety of applications, ranging from | HTTP is used in a wide variety of applications, ranging from general- | |||
general-purpose computers to home appliances. In some cases, | purpose computers to home appliances. In some cases, communication | |||
communication options are hard-coded in a client's configuration. | options are hard-coded in a client's configuration. However, most | |||
However, most HTTP clients rely on the same resource identification | HTTP clients rely on the same resource identification mechanism and | |||
mechanism and configuration techniques as general-purpose Web | configuration techniques as general-purpose Web browsers. | |||
browsers. | ||||
HTTP communication is initiated by a user agent for some purpose. | HTTP communication is initiated by a user agent for some purpose. | |||
The purpose is a combination of request semantics, which are defined | The purpose is a combination of request semantics and a target | |||
in [RFC7231], and a target resource upon which to apply those | resource upon which to apply those semantics. A URI reference | |||
semantics. A URI reference (Section 2.7) is typically used as an | (Section 2.4) is typically used as an identifier for the "target | |||
identifier for the "target resource", which a user agent would | resource", which a user agent would resolve to its absolute form in | |||
resolve to its absolute form in order to obtain the "target URI". | order to obtain the "target URI". The target URI excludes the | |||
The target URI excludes the reference's fragment component, if any, | reference's fragment component, if any, since fragment identifiers | |||
since fragment identifiers are reserved for client-side processing | are reserved for client-side processing ([RFC3986], Section 3.5). | |||
([RFC3986], Section 3.5). | ||||
5.2. Connecting Inbound | 5.2. Routing Inbound | |||
Once the target URI is determined, a client needs to decide whether a | Once the target URI is determined, a client needs to decide whether a | |||
network request is necessary to accomplish the desired semantics and, | network request is necessary to accomplish the desired semantics and, | |||
if so, where that request is to be directed. | if so, where that request is to be directed. | |||
If the client has a cache [RFC7234] and the request can be satisfied | If the client has a cache [Caching] and the request can be satisfied | |||
by it, then the request is usually directed there first. | by it, then the request is usually directed there first. | |||
If the request is not satisfied by a cache, then a typical client | If the request is not satisfied by a cache, then a typical client | |||
will check its configuration to determine whether a proxy is to be | will check its configuration to determine whether a proxy is to be | |||
used to satisfy the request. Proxy configuration is implementation- | used to satisfy the request. Proxy configuration is implementation- | |||
dependent, but is often based on URI prefix matching, selective | dependent, but is often based on URI prefix matching, selective | |||
authority matching, or both, and the proxy itself is usually | authority matching, or both, and the proxy itself is usually | |||
identified by an "http" or "https" URI. If a proxy is applicable, | identified by an "http" or "https" URI. If a proxy is applicable, | |||
the client connects inbound by establishing (or reusing) a connection | the client connects inbound by establishing (or reusing) a connection | |||
to that proxy. | to that proxy. | |||
If no proxy is applicable, a typical client will invoke a handler | If no proxy is applicable, a typical client will invoke a handler | |||
routine, usually specific to the target URI's scheme, to connect | routine, usually specific to the target URI's scheme, to connect | |||
directly to an authority for the target resource. How that is | directly to an authority for the target resource. How that is | |||
accomplished is dependent on the target URI scheme and defined by its | accomplished is dependent on the target URI scheme and defined by its | |||
associated specification, similar to how this specification defines | associated specification, similar to how this specification defines | |||
origin server access for resolution of the "http" (Section 2.7.1) and | origin server access for resolution of the "http" (Section 2.5.1) and | |||
"https" (Section 2.7.2) schemes. | "https" (Section 2.5.2) schemes. | |||
HTTP requirements regarding connection management are defined in | HTTP requirements regarding connection management are defined in | |||
Section 6. | Section 9 of [Messaging]. | |||
5.5. Effective Request URI | 5.3. Effective Request URI | |||
Once an inbound connection is obtained, the client sends an HTTP | Once an inbound connection is obtained, the client sends an HTTP | |||
request message (Section 3) with a request-target derived from the | request message (Section 2 of [Messaging]). | |||
target URI. | ||||
Since the request-target often contains only part of the user agent's | Depending on the nature of the request, the client's target URI might | |||
target URI, a server reconstructs the intended target as an | be split into components and transmitted (or implied) within various | |||
"effective request URI" to properly service the request. This | parts of a request message. These parts are recombined by each | |||
reconstruction involves both the server's local configuration and | recipient, in accordance with their local configuration and incoming | |||
information communicated in the request-target, Host header field, | connection context, to form an "effective request URI" for | |||
and connection context. | identifying the intended target resource with respect to that server. | |||
Section 3.3 of [Messaging] defines how a server determines the | ||||
effective request URI for an HTTP/1.1 request. | ||||
For a user agent, the effective request URI is the target URI. | For a user agent, the effective request URI is the target URI. | |||
Once the effective request URI has been constructed, an origin server | Once the effective request URI has been constructed, an origin server | |||
needs to decide whether or not to provide service for that URI via | needs to decide whether or not to provide service for that URI via | |||
the connection in which the request was received. For example, the | the connection in which the request was received. For example, the | |||
request might have been misdirected, deliberately or accidentally, | request might have been misdirected, deliberately or accidentally, | |||
such that the information within a received request-target or Host | such that the information within a received request-target or Host | |||
header field differs from the host or port upon which the connection | header field differs from the host or port upon which the connection | |||
has been made. If the connection is from a trusted gateway, that | has been made. If the connection is from a trusted gateway, that | |||
inconsistency might be expected; otherwise, it might indicate an | inconsistency might be expected; otherwise, it might indicate an | |||
attempt to bypass security filters, trick the server into delivering | attempt to bypass security filters, trick the server into delivering | |||
non-public content, or poison a cache. See Section 9 for security | non-public content, or poison a cache. See Section 13 for security | |||
considerations regarding message routing. | considerations regarding message routing. | |||
5.4. Host | 5.4. Host | |||
The "Host" header field in a request provides the host and port | The "Host" header field in a request provides the host and port | |||
information from the target URI, enabling the origin server to | information from the target URI, enabling the origin server to | |||
distinguish among resources while servicing requests for multiple | distinguish among resources while servicing requests for multiple | |||
host names on a single IP address. | host names on a single IP address. | |||
Host = uri-host [ ":" port ] ; Section 2.7.1 | Host = uri-host [ ":" port ] ; Section 2.4 | |||
A client MUST send a Host header field in all HTTP/1.1 request | A client MUST send a Host header field in all HTTP/1.1 request | |||
messages. If the target URI includes an authority component, then a | messages. If the target URI includes an authority component, then a | |||
client MUST send a field-value for Host that is identical to that | client MUST send a field-value for Host that is identical to that | |||
authority component, excluding any userinfo subcomponent and its "@" | authority component, excluding any userinfo subcomponent and its "@" | |||
delimiter (Section 2.7.1). If the authority component is missing or | delimiter (Section 2.5.1). If the authority component is missing or | |||
undefined for the target URI, then a client MUST send a Host header | undefined for the target URI, then a client MUST send a Host header | |||
field with an empty field-value. | field with an empty field-value. | |||
Since the Host field-value is critical information for handling a | Since the Host field-value is critical information for handling a | |||
request, a user agent SHOULD generate Host as the first header field | request, a user agent SHOULD generate Host as the first header field | |||
following the request-line. | following the request-line. | |||
For example, a GET request to the origin server for | For example, a GET request to the origin server for | |||
<http://www.example.org/pub/WWW/> would begin with: | <http://www.example.org/pub/WWW/> would begin with: | |||
GET /pub/WWW/ HTTP/1.1 | GET /pub/WWW/ HTTP/1.1 | |||
Host: www.example.org | Host: www.example.org | |||
A client MUST send a Host header field in an HTTP/1.1 request even if | A client MUST send a Host header field in an HTTP/1.1 request even if | |||
the request-target is in the absolute-form, since this allows the | the request-target is in the absolute-form, since this allows the | |||
Host information to be forwarded through ancient HTTP/1.0 proxies | Host information to be forwarded through ancient HTTP/1.0 proxies | |||
that might not have implemented Host. | that might not have implemented Host. | |||
When a proxy receives a request with an absolute-form of | When a proxy receives a request with an absolute-form of request- | |||
request-target, the proxy MUST ignore the received Host header field | target, the proxy MUST ignore the received Host header field (if any) | |||
(if any) and instead replace it with the host information of the | and instead replace it with the host information of the request- | |||
request-target. A proxy that forwards such a request MUST generate a | target. A proxy that forwards such a request MUST generate a new | |||
new Host field-value based on the received request-target rather than | Host field-value based on the received request-target rather than | |||
forward the received Host field-value. | forward the received Host field-value. | |||
Since the Host header field acts as an application-level routing | Since the Host header field acts as an application-level routing | |||
mechanism, it is a frequent target for malware seeking to poison a | mechanism, it is a frequent target for malware seeking to poison a | |||
shared cache or redirect a request to an unintended server. An | shared cache or redirect a request to an unintended server. An | |||
interception proxy is particularly vulnerable if it relies on the | interception proxy is particularly vulnerable if it relies on the | |||
Host field-value for redirecting requests to internal servers, or for | Host field-value for redirecting requests to internal servers, or for | |||
use as a cache key in a shared cache, without first verifying that | use as a cache key in a shared cache, without first verifying that | |||
the intercepted connection is targeting a valid IP address for that | the intercepted connection is targeting a valid IP address for that | |||
host. | host. | |||
A server MUST respond with a 400 (Bad Request) status code to any | A server MUST respond with a 400 (Bad Request) status code to any | |||
HTTP/1.1 request message that lacks a Host header field and to any | HTTP/1.1 request message that lacks a Host header field and to any | |||
request message that contains more than one Host header field or a | request message that contains more than one Host header field or a | |||
Host header field with an invalid field-value. | Host header field with an invalid field-value. | |||
5.7. Message Forwarding | 5.5. Message Forwarding | |||
As described in Section 2.3, intermediaries can serve a variety of | As described in Section 2.2, intermediaries can serve a variety of | |||
roles in the processing of HTTP requests and responses. Some | roles in the processing of HTTP requests and responses. Some | |||
intermediaries are used to improve performance or availability. | intermediaries are used to improve performance or availability. | |||
Others are used for access control or to filter content. Since an | Others are used for access control or to filter content. Since an | |||
HTTP stream has characteristics similar to a pipe-and-filter | HTTP stream has characteristics similar to a pipe-and-filter | |||
architecture, there are no inherent limits to the extent an | architecture, there are no inherent limits to the extent an | |||
intermediary can enhance (or interfere) with either direction of the | intermediary can enhance (or interfere) with either direction of the | |||
stream. | stream. | |||
An intermediary not acting as a tunnel MUST implement the Connection | An intermediary not acting as a tunnel MUST implement the Connection | |||
header field, as specified in Section 6.1, and exclude fields from | header field, as specified in Section 9.1 of [Messaging], and exclude | |||
being forwarded that are only intended for the incoming connection. | fields from being forwarded that are only intended for the incoming | |||
connection. | ||||
An intermediary MUST NOT forward a message to itself unless it is | An intermediary MUST NOT forward a message to itself unless it is | |||
protected from an infinite request loop. In general, an intermediary | protected from an infinite request loop. In general, an intermediary | |||
ought to recognize its own server names, including any aliases, local | ought to recognize its own server names, including any aliases, local | |||
variations, or literal IP addresses, and respond to such requests | variations, or literal IP addresses, and respond to such requests | |||
directly. | directly. | |||
An HTTP message can be parsed as a stream for incremental processing | An HTTP message can be parsed as a stream for incremental processing | |||
or forwarding downstream. However, recipients cannot rely on | or forwarding downstream. However, recipients cannot rely on | |||
incremental delivery of partial messages, since some implementations | incremental delivery of partial messages, since some implementations | |||
will buffer or delay message forwarding for the sake of network | will buffer or delay message forwarding for the sake of network | |||
efficiency, security checks, or payload transformations. | efficiency, security checks, or payload transformations. | |||
5.7.1. Via | 5.5.1. Via | |||
The "Via" header field indicates the presence of intermediate | The "Via" header field indicates the presence of intermediate | |||
protocols and recipients between the user agent and the server (on | protocols and recipients between the user agent and the server (on | |||
requests) or between the origin server and the client (on responses), | requests) or between the origin server and the client (on responses), | |||
similar to the "Received" header field in email (Section 3.6.7 of | similar to the "Received" header field in email (Section 3.6.7 of | |||
[RFC5322]). Via can be used for tracking message forwards, avoiding | [RFC5322]). Via can be used for tracking message forwards, avoiding | |||
request loops, and identifying the protocol capabilities of senders | request loops, and identifying the protocol capabilities of senders | |||
along the request/response chain. | along the request/response chain. | |||
Via = 1#( received-protocol RWS received-by [ RWS comment ] ) | Via = 1#( received-protocol RWS received-by [ RWS comment ] ) | |||
received-protocol = [ protocol-name "/" ] protocol-version | received-protocol = [ protocol-name "/" ] protocol-version | |||
; see Section 6.7 | ; see [Messaging], Section 9.9 | |||
received-by = ( uri-host [ ":" port ] ) / pseudonym | received-by = ( uri-host [ ":" port ] ) / pseudonym | |||
pseudonym = token | pseudonym = token | |||
Multiple Via field values represent each proxy or gateway that has | Multiple Via field values represent each proxy or gateway that has | |||
forwarded the message. Each intermediary appends its own information | forwarded the message. Each intermediary appends its own information | |||
about how the message was received, such that the end result is | about how the message was received, such that the end result is | |||
ordered according to the sequence of forwarding recipients. | ordered according to the sequence of forwarding recipients. | |||
A proxy MUST send an appropriate Via header field, as described | A proxy MUST send an appropriate Via header field, as described | |||
below, in each message that it forwards. An HTTP-to-HTTP gateway | below, in each message that it forwards. An HTTP-to-HTTP gateway | |||
MUST send an appropriate Via header field in each inbound request | MUST send an appropriate Via header field in each inbound request | |||
message and MAY send a Via header field in forwarded response | message and MAY send a Via header field in forwarded response | |||
messages. | messages. | |||
For each intermediary, the received-protocol indicates the protocol | For each intermediary, the received-protocol indicates the protocol | |||
and protocol version used by the upstream sender of the message. | and protocol version used by the upstream sender of the message. | |||
Hence, the Via field value records the advertised protocol | Hence, the Via field value records the advertised protocol | |||
capabilities of the request/response chain such that they remain | capabilities of the request/response chain such that they remain | |||
visible to downstream recipients; this can be useful for determining | visible to downstream recipients; this can be useful for determining | |||
what backwards-incompatible features might be safe to use in | what backwards-incompatible features might be safe to use in | |||
response, or within a later request, as described in Section 2.6. | response, or within a later request, as described in Section 3.5. | |||
For brevity, the protocol-name is omitted when the received protocol | For brevity, the protocol-name is omitted when the received protocol | |||
is HTTP. | is HTTP. | |||
The received-by portion of the field value is normally the host and | The received-by portion of the field value is normally the host and | |||
optional port number of a recipient server or client that | optional port number of a recipient server or client that | |||
subsequently forwarded the message. However, if the real host is | subsequently forwarded the message. However, if the real host is | |||
considered to be sensitive information, a sender MAY replace it with | considered to be sensitive information, a sender MAY replace it with | |||
a pseudonym. If a port is not provided, a recipient MAY interpret | a pseudonym. If a port is not provided, a recipient MAY interpret | |||
that as meaning it was received on the default TCP port, if any, for | that as meaning it was received on the default TCP port, if any, for | |||
the received-protocol. | the received-protocol. | |||
skipping to change at line 1603 ¶ | skipping to change at page 40, line 38 ¶ | |||
could be collapsed to | could be collapsed to | |||
Via: 1.0 ricky, 1.1 mertz, 1.0 lucy | Via: 1.0 ricky, 1.1 mertz, 1.0 lucy | |||
A sender SHOULD NOT combine multiple entries unless they are all | A sender SHOULD NOT combine multiple entries unless they are all | |||
under the same organizational control and the hosts have already been | under the same organizational control and the hosts have already been | |||
replaced by pseudonyms. A sender MUST NOT combine entries that have | replaced by pseudonyms. A sender MUST NOT combine entries that have | |||
different received-protocol values. | different received-protocol values. | |||
5.7.2. Transformations | 5.5.2. Transformations | |||
Some intermediaries include features for transforming messages and | Some intermediaries include features for transforming messages and | |||
their payloads. A proxy might, for example, convert between image | their payloads. A proxy might, for example, convert between image | |||
formats in order to save cache space or to reduce the amount of | formats in order to save cache space or to reduce the amount of | |||
traffic on a slow link. However, operational problems might occur | traffic on a slow link. However, operational problems might occur | |||
when these transformations are applied to payloads intended for | when these transformations are applied to payloads intended for | |||
critical applications, such as medical imaging or scientific data | critical applications, such as medical imaging or scientific data | |||
analysis, particularly when integrity checks or digital signatures | analysis, particularly when integrity checks or digital signatures | |||
are used to ensure that the payload received is identical to the | are used to ensure that the payload received is identical to the | |||
original. | original. | |||
skipping to change at line 1639 ¶ | skipping to change at page 41, line 26 ¶ | |||
name it received when forwarding the request. A proxy MUST NOT | name it received when forwarding the request. A proxy MUST NOT | |||
change the host name if the request-target contains a fully qualified | change the host name if the request-target contains a fully qualified | |||
domain name. | domain name. | |||
A proxy MUST NOT modify the "absolute-path" and "query" parts of the | A proxy MUST NOT modify the "absolute-path" and "query" parts of the | |||
received request-target when forwarding it to the next inbound | received request-target when forwarding it to the next inbound | |||
server, except as noted above to replace an empty path with "/" or | server, except as noted above to replace an empty path with "/" or | |||
"*". | "*". | |||
A proxy MAY modify the message body through application or removal of | A proxy MAY modify the message body through application or removal of | |||
a transfer coding (Section 4). | a transfer coding (Section 7 of [Messaging]). | |||
A proxy MUST NOT transform the payload (Section 3.3 of [RFC7231]) of | A proxy MUST NOT transform the payload (Section 6.3) of a message | |||
a message that contains a no-transform cache-control directive | that contains a no-transform cache-control response directive | |||
(Section 5.2 of [RFC7234]). | (Section 5.2 of [Caching]). | |||
A proxy MAY transform the payload of a message that does not contain | A proxy MAY transform the payload of a message that does not contain | |||
a no-transform cache-control directive. A proxy that transforms a | a no-transform cache-control directive. A proxy that transforms the | |||
payload MUST add a Warning header field with the warn-code of 214 | payload of a 200 (OK) response can inform downstream recipients that | |||
("Transformation Applied") if one is not already in the message (see | a transformation has been applied by changing the response status | |||
Section 5.5 of [RFC7234]). A proxy that transforms the payload of a | code to 203 (Non-Authoritative Information) (Section 9.3.4). | |||
200 (OK) response can further inform downstream recipients that a | ||||
transformation has been applied by changing the response status code | ||||
to 203 (Non-Authoritative Information) (Section 6.3.4 of [RFC7231]). | ||||
A proxy SHOULD NOT modify header fields that provide information | A proxy SHOULD NOT modify header fields that provide information | |||
about the endpoints of the communication chain, the resource state, | about the endpoints of the communication chain, the resource state, | |||
or the selected representation (other than the payload) unless the | or the selected representation (other than the payload) unless the | |||
field's definition specifically allows such modification or the | field's definition specifically allows such modification or the | |||
modification is deemed necessary for privacy or security. | modification is deemed necessary for privacy or security. | |||
3. Representations | 6. Representations | |||
Considering that a resource could be anything, and that the uniform | Considering that a resource could be anything, and that the uniform | |||
interface provided by HTTP is similar to a window through which one | interface provided by HTTP is similar to a window through which one | |||
can observe and act upon such a thing only through the communication | can observe and act upon such a thing only through the communication | |||
of messages to some independent actor on the other side, an | of messages to some independent actor on the other side, an | |||
abstraction is needed to represent ("take the place of") the current | abstraction is needed to represent ("take the place of") the current | |||
or desired state of that thing in our communications. That | or desired state of that thing in our communications. That | |||
abstraction is called a representation [REST]. | abstraction is called a representation [REST]. | |||
For the purposes of HTTP, a "representation" is information that is | For the purposes of HTTP, a "representation" is information that is | |||
skipping to change at line 1682 ¶ | skipping to change at page 42, line 19 ¶ | |||
resource, in a format that can be readily communicated via the | resource, in a format that can be readily communicated via the | |||
protocol, and that consists of a set of representation metadata and a | protocol, and that consists of a set of representation metadata and a | |||
potentially unbounded stream of representation data. | potentially unbounded stream of representation data. | |||
An origin server might be provided with, or be capable of generating, | An origin server might be provided with, or be capable of generating, | |||
multiple representations that are each intended to reflect the | multiple representations that are each intended to reflect the | |||
current state of a target resource. In such cases, some algorithm is | current state of a target resource. In such cases, some algorithm is | |||
used by the origin server to select one of those representations as | used by the origin server to select one of those representations as | |||
most applicable to a given request, usually based on content | most applicable to a given request, usually based on content | |||
negotiation. This "selected representation" is used to provide the | negotiation. This "selected representation" is used to provide the | |||
data and metadata for evaluating conditional requests [RFC7232] and | data and metadata for evaluating conditional requests (Section 8.2) | |||
constructing the payload for 200 (OK) and 304 (Not Modified) | and constructing the payload for 200 (OK) and 304 (Not Modified) | |||
responses to GET (Section 4.3.1). | responses to GET (Section 7.3.1). | |||
3.2. Representation Data | 6.1. Representation Data | |||
The representation data associated with an HTTP message is either | The representation data associated with an HTTP message is either | |||
provided as the payload body of the message or referred to by the | provided as the payload body of the message or referred to by the | |||
message semantics and the effective request URI. The representation | message semantics and the effective request URI. The representation | |||
data is in a format and encoding defined by the representation | data is in a format and encoding defined by the representation | |||
metadata header fields. | metadata header fields. | |||
The data type of the representation data is determined via the header | The data type of the representation data is determined via the header | |||
fields Content-Type and Content-Encoding. These define a two-layer, | fields Content-Type and Content-Encoding. These define a two-layer, | |||
ordered encoding model: | ordered encoding model: | |||
representation-data := Content-Encoding( Content-Type( bits ) ) | representation-data := Content-Encoding( Content-Type( bits ) ) | |||
3.1.1.1. Media Type | 6.1.1. Media Type | |||
HTTP uses Internet media types [RFC2046] in the Content-Type | HTTP uses media types [RFC2046] in the Content-Type (Section 6.2.1) | |||
(Section 3.1.1.5) and Accept (Section 5.3.2) header fields in order | and Accept (Section 8.4.2) header fields in order to provide open and | |||
to provide open and extensible data typing and type negotiation. | extensible data typing and type negotiation. Media types define both | |||
Media types define both a data format and various processing models: | a data format and various processing models: how to process that data | |||
how to process that data in accordance with each context in which it | in accordance with each context in which it is received. | |||
is received. | ||||
media-type = type "/" subtype *( OWS ";" OWS parameter ) | media-type = type "/" subtype *( OWS ";" OWS parameter ) | |||
type = token | type = token | |||
subtype = token | subtype = token | |||
The type/subtype MAY be followed by parameters in the form of | The type and subtype tokens are case-insensitive. | |||
name=value pairs. | ||||
The type, subtype, and parameter name tokens are case-insensitive. | The type/subtype MAY be followed by semicolon-delimited parameters | |||
Parameter values might or might not be case-sensitive, depending on | (Section 4.2.3.4) in the form of name=value pairs. The presence or | |||
the semantics of the parameter name. The presence or absence of a | absence of a parameter might be significant to the processing of a | |||
parameter might be significant to the processing of a media-type, | media type, depending on its definition within the media type | |||
depending on its definition within the media type registry. | registry. Parameter values might or might not be case-sensitive, | |||
depending on the semantics of the parameter name. | ||||
For example, the following | For example, the following media types are equivalent in describing | |||
examples are all equivalent, but the first is preferred for | HTML text data encoded in the UTF-8 character encoding scheme, but | |||
consistency: | the first is preferred for consistency (the "charset" parameter value | |||
is defined as being case-insensitive in [RFC2046], Section 4.1.2): | ||||
text/html;charset=utf-8 | text/html;charset=utf-8 | |||
text/html;charset=UTF-8 | ||||
Text/HTML;Charset="utf-8" | 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 according to | Media types ought to be registered with IANA according to the | |||
the procedures defined in [BCP13]. | procedures defined in [BCP13]. | |||
3.1.1.2. Charset | 6.1.1.1. Charset | |||
HTTP uses charset names to indicate or negotiate the character | HTTP uses charset names to indicate or negotiate the character | |||
encoding scheme of a textual representation [RFC6365]. A charset is | encoding scheme of a textual representation [RFC6365]. A charset is | |||
identified by a case-insensitive token. | identified by a case-insensitive token. | |||
charset = token | charset = token | |||
Charset names ought to be registered in the IANA "Character Sets" | Charset names ought to be registered in the IANA "Character Sets" | |||
registry (<http://www.iana.org/assignments/character-sets>) according | registry (<https://www.iana.org/assignments/character-sets>) | |||
to the procedures defined in [RFC2978]. | according to the procedures defined in Section 2 of [RFC2978]. | |||
3.1.1.3. Canonicalization and Text Defaults | Note: In theory, charset names are defined by the "mime-charset" | |||
ABNF rule defined in Section 2.3 of [RFC2978] (as corrected in | ||||
[Err1912]). That rule allows two characters that are not included | ||||
in "token" ("{" and "}"), but no charset name registered at the | ||||
time of this writing includes braces (see [Err5433]). | ||||
Internet media types are registered with a canonical form in order to | 6.1.1.2. Canonicalization and Text Defaults | |||
be interoperable among systems with varying native encoding formats. | ||||
Media types are registered with a canonical form in order to be | ||||
interoperable among systems with varying native encoding formats. | ||||
Representations selected or transferred via HTTP ought to be in | Representations selected or transferred via HTTP ought to be in | |||
canonical form, for many of the same reasons described by the | canonical form, for many of the same reasons described by the | |||
Multipurpose Internet Mail Extensions (MIME) [RFC2045]. However, the | Multipurpose Internet Mail Extensions (MIME) [RFC2045]. However, the | |||
performance characteristics of email deployments (i.e., store and | performance characteristics of email deployments (i.e., store and | |||
forward messages to peers) are significantly different from those | forward messages to peers) are significantly different from those | |||
common to HTTP and the Web (server-based information services). | common to HTTP and the Web (server-based information services). | |||
Furthermore, MIME's constraints for the sake of compatibility with | Furthermore, MIME's constraints for the sake of compatibility with | |||
older mail transfer protocols do not apply to HTTP (see Appendix A). | older mail transfer protocols do not apply to HTTP (see Appendix B of | |||
[Messaging]). | ||||
MIME's canonical form requires that media subtypes of the "text" type | MIME's canonical form requires that media subtypes of the "text" type | |||
use CRLF as the text line break. HTTP allows the transfer of text | use CRLF as the text line break. HTTP allows the transfer of text | |||
media with plain CR or LF alone representing a line break, when such | media with plain CR or LF alone representing a line break, when such | |||
line breaks are consistent for an entire representation. An HTTP | line breaks are consistent for an entire representation. An HTTP | |||
sender MAY generate, and a recipient MUST be able to parse, line | sender MAY generate, and a recipient MUST be able to parse, line | |||
breaks in text media that consist of CRLF, bare CR, or bare LF. In | breaks in text media that consist of CRLF, bare CR, or bare LF. In | |||
addition, text media in HTTP is not limited to charsets that use | addition, text media in HTTP is not limited to charsets that use | |||
octets 13 and 10 for CR and LF, respectively. This flexibility | octets 13 and 10 for CR and LF, respectively. This flexibility | |||
regarding line breaks applies only to text within a representation | regarding line breaks applies only to text within a representation | |||
that has been assigned a "text" media type; it does not apply to | that has been assigned a "text" media type; it does not apply to | |||
"multipart" types or HTTP elements outside the payload body (e.g., | "multipart" types or HTTP elements outside the payload body (e.g., | |||
header fields). | header fields). | |||
If a representation is encoded with a content-coding, the underlying | If a representation is encoded with a content-coding, the underlying | |||
data ought to be in a form defined above prior to being encoded. | data ought to be in a form defined above prior to being encoded. | |||
3.1.1.4. Multipart Types | 6.1.1.3. Multipart Types | |||
MIME provides for a number of "multipart" types -- encapsulations of | MIME provides for a number of "multipart" types -- encapsulations of | |||
one or more representations within a single message body. All | one or more representations within a single message body. All | |||
multipart types share a common syntax, as defined in Section 5.1.1 of | multipart types share a common syntax, as defined in Section 5.1.1 of | |||
[RFC2046], and include a boundary parameter as part of the media type | [RFC2046], and include a boundary parameter as part of the media type | |||
value. The message body is itself a protocol element; a sender MUST | value. The message body is itself a protocol element; a sender MUST | |||
generate only CRLF to represent line breaks between body parts. | generate only CRLF to represent line breaks between body parts. | |||
HTTP message framing does not use the multipart boundary as an | HTTP message framing does not use the multipart boundary as an | |||
indicator of message body length, though it might be used by | indicator of message body length, though it might be used by | |||
implementations that generate or process the payload. For example, | implementations that generate or process the payload. For example, | |||
the "multipart/form-data" type is often used for carrying form data | the "multipart/form-data" type is often used for carrying form data | |||
in a request, as described in [RFC2388], and the "multipart/ | in a request, as described in [RFC7578], and the "multipart/ | |||
byteranges" type is defined by this specification for use in some 206 | byteranges" type is defined by this specification for use in some 206 | |||
(Partial Content) responses [RFC7233]. | (Partial Content) responses (see Section 9.3.7). | |||
3.1.2.1. Content Codings | 6.1.2. Content Codings | |||
Content coding values indicate an encoding transformation that has | Content coding values indicate an encoding transformation that has | |||
been or can be applied to a representation. Content codings are | been or can be applied to a representation. Content codings are | |||
primarily used to allow a representation to be compressed or | primarily used to allow a representation to be compressed or | |||
otherwise usefully transformed without losing the identity of its | otherwise usefully transformed without losing the identity of its | |||
underlying media type and without loss of information. Frequently, | underlying media type and without loss of information. Frequently, | |||
the representation is stored in coded form, transmitted directly, and | the representation is stored in coded form, transmitted directly, and | |||
only decoded by the final recipient. | only decoded by the final recipient. | |||
content-coding = token | content-coding = token | |||
All content-coding values are case-insensitive and ought to be | Content-coding values are used in the Accept-Encoding (Section 8.4.4) | |||
registered within the "HTTP Content Coding Registry", as defined in | and Content-Encoding (Section 6.2.2) header fields. | |||
Section 8.4. They are used in the Accept-Encoding (Section 5.3.4) | ||||
and Content-Encoding (Section 3.1.2.2) header fields. | ||||
The following content-coding values are defined by this | The following content-coding values are defined by this | |||
specification: | specification: | |||
compress (and x-compress): See Section 4.2.1 of [RFC7230]. | +------------+------------------------------------------+-----------+ | |||
| Name | Description | Reference | | ||||
deflate: See Section 4.2.2 of [RFC7230]. | +------------+------------------------------------------+-----------+ | |||
| compress | UNIX "compress" data format [Welch] | Section 6 | | ||||
gzip (and x-gzip): See Section 4.2.3 of [RFC7230]. | | | | .1.2.1 | | |||
| deflate | "deflate" compressed data ([RFC1951]) | Section 6 | | ||||
+------------+--------------------------------------+---------------+ | | | inside the "zlib" data format | .1.2.2 | | |||
| Name | Description | Reference | | | | ([RFC1950]) | | | |||
+------------+--------------------------------------+---------------+ | | gzip | GZIP file format [RFC1952] | Section 6 | | |||
| compress | UNIX "compress" data format [Welch] | Section 4.2.1 | | | | | .1.2.3 | | |||
| deflate | "deflate" compressed data | Section 4.2.2 | | | identity | Reserved (synonym for "no encoding" in | Section 8 | | |||
| | ([RFC1951]) inside the "zlib" data | | | | | Accept-Encoding) | .4.4 | | |||
| | format ([RFC1950]) | | | | x-compress | Deprecated (alias for compress) | Section 6 | | |||
| gzip | GZIP file format [RFC1952] | Section 4.2.3 | | | | | .1.2.1 | | |||
| identity | Reserved (synonym for "no encoding" in | Section 5.3.4 | | | x-gzip | Deprecated (alias for gzip) | Section 6 | | |||
| | Accept-Encoding) | | | | | | .1.2.3 | | |||
| x-compress | Deprecated (alias for compress) | Section 4.2.1 | | +------------+------------------------------------------+-----------+ | |||
| x-gzip | Deprecated (alias for gzip) | Section 4.2.3 | | ||||
+------------+--------------------------------------+---------------+ | ||||
4.2. Compression Codings | ||||
The codings defined below can be used to compress the payload of a | Table 2 | |||
message. | ||||
4.2.1. Compress Coding | 6.1.2.1. Compress Coding | |||
The "compress" coding is an adaptive Lempel-Ziv-Welch (LZW) coding | The "compress" coding is an adaptive Lempel-Ziv-Welch (LZW) coding | |||
[Welch] that is commonly produced by the UNIX file compression | [Welch] that is commonly produced by the UNIX file compression | |||
program "compress". A recipient SHOULD consider "x-compress" to be | program "compress". A recipient SHOULD consider "x-compress" to be | |||
equivalent to "compress". | equivalent to "compress". | |||
4.2.2. Deflate Coding | 6.1.2.2. Deflate Coding | |||
The "deflate" coding is a "zlib" data format [RFC1950] containing a | The "deflate" coding is a "zlib" data format [RFC1950] containing a | |||
"deflate" compressed data stream [RFC1951] that uses a combination of | "deflate" compressed data stream [RFC1951] that uses a combination of | |||
the Lempel-Ziv (LZ77) compression algorithm and Huffman coding. | the Lempel-Ziv (LZ77) compression algorithm and Huffman coding. | |||
Note: Some non-conformant implementations send the "deflate" | Note: Some non-conformant implementations send the "deflate" | |||
compressed data without the zlib wrapper. | compressed data without the zlib wrapper. | |||
4.2.3. Gzip Coding | 6.1.2.3. Gzip Coding | |||
The "gzip" coding is an LZ77 coding with a 32-bit Cyclic Redundancy | The "gzip" coding is an LZ77 coding with a 32-bit Cyclic Redundancy | |||
Check (CRC) that is commonly produced by the gzip file compression | Check (CRC) that is commonly produced by the gzip file compression | |||
program [RFC1952]. A recipient SHOULD consider "x-gzip" to be | program [RFC1952]. A recipient SHOULD consider "x-gzip" to be | |||
equivalent to "gzip". | equivalent to "gzip". | |||
8.4. Content Coding Registry | 6.1.2.4. Content Coding Extensibility | |||
The "HTTP Content Coding Registry" defines the namespace for content | Additional content codings, outside the scope of this specification, | |||
coding names (Section 4.2 of [RFC7230]). The content coding registry | have been specified for use in HTTP. All such content codings ought | |||
is maintained at <http://www.iana.org/assignments/http-parameters>. | to be registered within the "HTTP Content Coding Registry". | |||
8.4.1. Procedure | 6.1.2.4.1. Content Coding Registry | |||
The "HTTP Content Coding Registry", maintained by IANA at | ||||
<https://www.iana.org/assignments/http-parameters/>, registers | ||||
content-coding names. | ||||
Content coding registrations MUST include the following fields: | Content coding registrations MUST include the following fields: | |||
o Name | o Name | |||
o Description | o Description | |||
o Pointer to specification text | o Pointer to specification text | |||
Names of content codings MUST NOT overlap with names of transfer | Names of content codings MUST NOT overlap with names of transfer | |||
codings (Section 4 of [RFC7230]), unless the encoding transformation | codings (Section 7 of [Messaging]), unless the encoding | |||
is identical (as is the case for the compression codings defined in | transformation is identical (as is the case for the compression | |||
Section 4.2 of [RFC7230]). | codings defined in Section 6.1.2). | |||
Values to be added to this namespace require IETF Review (see Section | Values to be added to this namespace require IETF Review (see | |||
4.1 of [RFC5226]) and MUST conform to the purpose of content coding | Section 4.8 of [RFC8126]) and MUST conform to the purpose of content | |||
defined in this section. | coding defined in Section 6.1.2. | |||
3.1.3.1. Language Tags | 6.1.3. Language Tags | |||
A language tag, as defined in [RFC5646], identifies a natural | A language tag, as defined in [RFC5646], identifies a natural | |||
language spoken, written, or otherwise conveyed by human beings for | language spoken, written, or otherwise conveyed by human beings for | |||
communication of information to other human beings. Computer | communication of information to other human beings. Computer | |||
languages are explicitly excluded. | languages are explicitly excluded. | |||
HTTP uses language tags within the Accept-Language and | HTTP uses language tags within the Accept-Language and Content- | |||
Content-Language header fields. Accept-Language uses the broader | Language header fields. Accept-Language uses the broader language- | |||
language-range production defined in Section 5.3.5, whereas | range production defined in Section 8.4.5, whereas Content-Language | |||
Content-Language uses the language-tag production defined below. | uses the language-tag production defined below. | |||
language-tag = <Language-Tag, see [RFC5646], Section 2.1> | language-tag = <Language-Tag, see [RFC5646], Section 2.1> | |||
A language tag is a sequence of one or more case-insensitive subtags, | A language tag is a sequence of one or more case-insensitive subtags, | |||
each separated by a hyphen character ("-", %x2D). In most cases, a | each separated by a hyphen character ("-", %x2D). In most cases, a | |||
language tag consists of a primary language subtag that identifies a | language tag consists of a primary language subtag that identifies a | |||
broad family of related languages (e.g., "en" = English), which is | broad family of related languages (e.g., "en" = English), which is | |||
optionally followed by a series of subtags that refine or narrow that | optionally followed by a series of subtags that refine or narrow that | |||
language's range (e.g., "en-CA" = the variety of English as | language's range (e.g., "en-CA" = the variety of English as | |||
communicated in Canada). Whitespace is not allowed within a language | communicated in Canada). Whitespace is not allowed within a language | |||
tag. Example tags include: | tag. Example tags include: | |||
fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN | fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN | |||
See [RFC5646] for further information. | See [RFC5646] for further information. | |||
2. Range Units | 6.1.4. Range Units | |||
A representation can be partitioned into subranges according to | Representation data can be partitioned into subranges when there are | |||
various structural units, depending on the structure inherent in the | addressable structural units inherent to that data's content coding | |||
representation's media type. This "range unit" is used in the | or media type. For example, octet (a.k.a., byte) boundaries are a | |||
Accept-Ranges (Section 2.3) response header field to advertise | structural unit common to all representation data, allowing | |||
support for range requests, the Range (Section 3.1) request header | partitions of the data to be identified as a range of bytes at some | |||
field to delineate the parts of a representation that are requested, | offset from the start or end of that data. | |||
and the Content-Range (Section 4.2) payload header field to describe | ||||
which part of a representation is being transferred. | ||||
range-unit = bytes-unit / other-range-unit | This general notion of a "range unit" is used in the Accept-Ranges | |||
(Section 10.4.1) response header field to advertise support for range | ||||
requests, the Range (Section 8.3) request header field to delineate | ||||
the parts of a representation that are requested, and the Content- | ||||
Range (Section 6.3.4) payload header field to describe which part of | ||||
a representation is being transferred. | ||||
+-------------+---------------------------------------+-------------+ | range-unit = token | |||
| Range Unit | Description | Reference | | ||||
| Name | | | | ||||
+-------------+---------------------------------------+-------------+ | ||||
| bytes | a range of octets | Section 2.1 | | ||||
| none | reserved as keyword, indicating no | Section 2.3 | | ||||
| | ranges are supported | | | ||||
+-------------+---------------------------------------+-------------+ | ||||
2.1. Byte Ranges | The following range unit names are defined by this document: | |||
Since representation data is transferred in payloads as a sequence of | +------------+-----------------------------------------+------------+ | |||
octets, a byte range is a meaningful substructure for any | | Range Unit | Description | Reference | | |||
representation transferable over HTTP (Section 3 of [RFC7231]). The | | Name | | | | |||
"bytes" range unit is defined for expressing subranges of the data's | +------------+-----------------------------------------+------------+ | |||
octet sequence. | | bytes | a range of octets | Section 6. | | |||
| | | 1.4.2 | | ||||
| none | reserved as keyword to indicate range | Section 10 | | ||||
| | requests are not supported | .4.1 | | ||||
+------------+-----------------------------------------+------------+ | ||||
bytes-unit = "bytes" | Table 3 | |||
A byte-range request can specify a single range of bytes or a set of | 6.1.4.1. Range Specifiers | |||
ranges within a single representation. | ||||
byte-ranges-specifier = bytes-unit "=" byte-range-set | Ranges are expressed in terms of a range unit paired with a set of | |||
byte-range-set = 1#( byte-range-spec / suffix-byte-range-spec ) | range specifiers. The range unit name determines what kinds of | |||
byte-range-spec = first-byte-pos "-" [ last-byte-pos ] | range-spec are applicable to its own specifiers. Hence, the | |||
first-byte-pos = 1*DIGIT | following gramar is generic: each range unit is expected to specify | |||
last-byte-pos = 1*DIGIT | requirements on when int-range, suffix-range, and other-range are | |||
allowed. | ||||
The first-byte-pos value in a byte-range-spec gives the byte-offset | A range request can specify a single range or a set of ranges within | |||
of the first byte in a range. The last-byte-pos value gives the | a single representation. | |||
byte-offset of the last byte in the range; that is, the byte | ||||
positions specified are inclusive. Byte offsets start at zero. | ||||
Examples of byte-ranges-specifier values: | ranges-specifier = range-unit "=" range-set | |||
range-set = 1#range-spec | ||||
range-spec = int-range | ||||
/ suffix-range | ||||
/ other-range | ||||
An int-range is a range expressed as two non-negative integers or as | ||||
one non-negative integer through to the end of the representation | ||||
data. The range unit specifies what the integers mean (e.g., they | ||||
might indicate unit offsets from the beginning, inclusive numbered | ||||
parts, etc.). | ||||
int-range = first-pos "-" [ last-pos ] | ||||
first-pos = 1*DIGIT | ||||
last-pos = 1*DIGIT | ||||
An int-range is invalid if the last-pos value is present and less | ||||
than the first-pos. | ||||
A suffix-range is a range expressed as a suffix of the representation | ||||
data with the provided non-negative integer maximum length (in range | ||||
units). In other words, the last N units of the representation data. | ||||
suffix-range = "-" suffix-length | ||||
suffix-length = 1*DIGIT | ||||
To provide for extensibility, the other-range rule is a mostly | ||||
unconstrained grammar that allows application-specific or future | ||||
range units to define additional range specifiers. | ||||
other-range = 1*( %x21-2B / %x2D-7E ) | ||||
; 1*(VCHAR excluding comma) | ||||
6.1.4.2. Byte Ranges | ||||
The "bytes" range unit is used to express subranges of a | ||||
representation data's octet sequence. Each byte range is expressed | ||||
as an integer range at some offset, relative to either the beginning | ||||
(int-range) or end (suffix-range) of the representation data. Byte | ||||
ranges do not use the other-range specifier. | ||||
The first-pos value in a bytes int-range gives the offset of the | ||||
first byte in a range. The last-pos value gives the offset of the | ||||
last byte in the range; that is, the byte positions specified are | ||||
inclusive. Byte offsets start at zero. | ||||
If the representation data has a content coding applied, each byte | ||||
range is calculated with respect to the encoded sequence of bytes, | ||||
not the sequence of underlying bytes that would be obtained after | ||||
decoding. | ||||
Examples of bytes range specifiers: | ||||
o The first 500 bytes (byte offsets 0-499, inclusive): | o The first 500 bytes (byte offsets 0-499, inclusive): | |||
bytes=0-499 | bytes=0-499 | |||
o The second 500 bytes (byte offsets 500-999, inclusive): | o The second 500 bytes (byte offsets 500-999, inclusive): | |||
bytes=500-999 | bytes=500-999 | |||
A byte-range-spec is invalid if the last-byte-pos value is present | ||||
and less than the first-byte-pos. | ||||
A client can limit the number of bytes requested without knowing the | A client can limit the number of bytes requested without knowing the | |||
size of the selected representation. If the last-byte-pos value is | size of the selected representation. If the last-pos value is | |||
absent, or if the value is greater than or equal to the current | absent, or if the value is greater than or equal to the current | |||
length of the representation data, the byte range is interpreted as | length of the representation data, the byte range is interpreted as | |||
the remainder of the representation (i.e., the server replaces the | the remainder of the representation (i.e., the server replaces the | |||
value of last-byte-pos with a value that is one less than the current | value of last-pos with a value that is one less than the current | |||
length of the selected representation). | length of the selected representation). | |||
A client can request the last N bytes of the selected representation | A client can request the last N bytes of the selected representation | |||
using a suffix-byte-range-spec. | using a suffix-range. If the selected representation is shorter than | |||
the specified suffix-length, the entire representation is used. | ||||
suffix-byte-range-spec = "-" suffix-length | ||||
suffix-length = 1*DIGIT | ||||
If the selected representation is shorter than the specified | ||||
suffix-length, the entire representation is used. | ||||
Additional examples, assuming a representation of length 10000: | Additional examples, assuming a representation of length 10000: | |||
o The final 500 bytes (byte offsets 9500-9999, inclusive): | o The final 500 bytes (byte offsets 9500-9999, inclusive): | |||
bytes=-500 | bytes=-500 | |||
Or: | Or: | |||
bytes=9500- | bytes=9500- | |||
o The first and last bytes only (bytes 0 and 9999): | o The first and last bytes only (bytes 0 and 9999): | |||
bytes=0-0,-1 | bytes=0-0,-1 | |||
o The first, middle, and last 1000 bytes: | ||||
bytes= 0-999, 4500-5499, -1000 | ||||
o Other valid (but not canonical) specifications of the second 500 | o Other valid (but not canonical) specifications of the second 500 | |||
bytes (byte offsets 500-999, inclusive): | bytes (byte offsets 500-999, inclusive): | |||
bytes=500-600,601-999 | bytes=500-600,601-999 | |||
bytes=500-700,601-999 | bytes=500-700,601-999 | |||
If a valid byte-range-set includes at least one byte-range-spec with | If a valid bytes range-set includes at least one range-spec with a | |||
a first-byte-pos that is less than the current length of the | first-pos that is less than the current length of the representation, | |||
representation, or at least one suffix-byte-range-spec with a | or at least one suffix-range with a non-zero suffix-length, then the | |||
non-zero suffix-length, then the byte-range-set is satisfiable. | bytes range-set is satisfiable. Otherwise, the bytes range-set is | |||
Otherwise, the byte-range-set is unsatisfiable. | unsatisfiable. | |||
In the byte-range syntax, first-byte-pos, last-byte-pos, and | In the byte-range syntax, first-pos, last-pos, and suffix-length are | |||
suffix-length are expressed as decimal number of octets. Since there | expressed as decimal number of octets. Since there is no predefined | |||
is no predefined limit to the length of a payload, recipients MUST | limit to the length of a payload, recipients MUST anticipate | |||
anticipate potentially large decimal numerals and prevent parsing | potentially large decimal numerals and prevent parsing errors due to | |||
errors due to integer conversion overflows. | integer conversion overflows. | |||
2.2. Other Range Units | 6.1.4.3. Other Range Units | |||
Range units are intended to be extensible. New range units ought to | Other range units, such as format-specific boundaries like pages, | |||
be registered with IANA, as defined in Section 5.1. | sections, records, rows, or time, are potentially usable in HTTP for | |||
application-specific purposes, but are not commonly used in practice. | ||||
Implementors of alternative range units ought to consider how they | ||||
would work with content codings and general-purpose intermediaries. | ||||
other-range-unit = token | Range units are intended to be extensible. New range units ought to | |||
be registered with IANA, as defined in Section 6.1.4.4. | ||||
5.1. Range Unit Registry | 6.1.4.4. Range Unit Registry | |||
The "HTTP Range Unit Registry" defines the namespace for the range | The "HTTP Range Unit Registry" defines the namespace for the range | |||
unit names and refers to their corresponding specifications. The | unit names and refers to their corresponding specifications. It is | |||
registry has been created and is now maintained at | maintained at <https://www.iana.org/assignments/http-parameters>. | |||
<http://www.iana.org/assignments/http-parameters>. | ||||
5.1.1. Procedure | ||||
Registration of an HTTP Range Unit MUST include the following fields: | Registration of an HTTP Range Unit MUST include the following fields: | |||
o Name | o Name | |||
o Description | o Description | |||
o Pointer to specification text | o Pointer to specification text | |||
Values to be added to this namespace require IETF Review (see | Values to be added to this namespace require IETF Review (see | |||
[RFC5226], Section 4.1). | [RFC8126], Section 4.8). | |||
3.1. Representation Metadata | 6.2. Representation Metadata | |||
Representation header fields provide metadata about the | Representation header fields provide metadata about the | |||
representation. When a message includes a payload body, the | representation. When a message includes a payload body, the | |||
representation header fields describe how to interpret the | representation header fields describe how to interpret the | |||
representation data enclosed in the payload body. In a response to a | representation data enclosed in the payload body. In a response to a | |||
HEAD request, the representation header fields describe the | HEAD request, the representation header fields describe the | |||
representation data that would have been enclosed in the payload body | representation data that would have been enclosed in the payload body | |||
if the same request had been a GET. | if the same request had been a GET. | |||
The following header fields convey representation metadata: | The following header fields convey representation metadata: | |||
+-------------------+-----------------+ | +-------------------+---------------+ | |||
| Header Field Name | Defined in... | | | Header Field Name | Defined in... | | |||
+-------------------+-----------------+ | +-------------------+---------------+ | |||
| Content-Type | Section 3.1.1.5 | | | Content-Type | Section 6.2.1 | | |||
| Content-Encoding | Section 3.1.2.2 | | | Content-Encoding | Section 6.2.2 | | |||
| Content-Language | Section 3.1.3.2 | | | Content-Language | Section 6.2.3 | | |||
| Content-Location | Section 3.1.4.2 | | | Content-Length | Section 6.2.4 | | |||
+-------------------+-----------------+ | | Content-Location | Section 6.2.5 | | |||
+-------------------+---------------+ | ||||
3.1.1. Processing Representation Data | ||||
3.1.1.5. Content-Type | 6.2.1. Content-Type | |||
The "Content-Type" header field indicates the media type of the | The "Content-Type" header field indicates the media type of the | |||
associated representation: either the representation enclosed in the | associated representation: either the representation enclosed in the | |||
message payload or the selected representation, as determined by the | message payload or the selected representation, as determined by the | |||
message semantics. The indicated media type defines both the data | message semantics. The indicated media type defines both the data | |||
format and how that data is intended to be processed by a recipient, | format and how that data is intended to be processed by a recipient, | |||
within the scope of the received message semantics, after any content | within the scope of the received message semantics, after any content | |||
codings indicated by Content-Encoding are decoded. | codings indicated by Content-Encoding are decoded. | |||
Content-Type = media-type | Content-Type = media-type | |||
Media types are defined in Section 3.1.1.1. An example of the field | Media types are defined in Section 6.1.1. An example of the field is | |||
is | ||||
Content-Type: text/html; charset=ISO-8859-4 | Content-Type: text/html; charset=ISO-8859-4 | |||
A sender that generates a message containing a payload body SHOULD | A sender that generates a message containing a payload body SHOULD | |||
generate a Content-Type header field in that message unless the | generate a Content-Type header field in that message unless the | |||
intended media type of the enclosed representation is unknown to the | intended media type of the enclosed representation is unknown to the | |||
sender. If a Content-Type header field is not present, the recipient | sender. If a Content-Type header field is not present, the recipient | |||
MAY either assume a media type of "application/octet-stream" | MAY either assume a media type of "application/octet-stream" | |||
([RFC2046], Section 4.5.1) or examine the data to determine its type. | ([RFC2046], Section 4.5.1) or examine the data to determine its type. | |||
In practice, resource owners do not always properly configure their | In practice, resource owners do not always properly configure their | |||
origin server to provide the correct Content-Type for a given | origin server to provide the correct Content-Type for a given | |||
representation, with the result that some clients will examine a | representation. Some user agents examine a payload's content and, in | |||
payload's content and override the specified type. Clients that do | certain cases, override the received type (for example, see | |||
so risk drawing incorrect conclusions, which might expose additional | [Sniffing]). This "MIME sniffing" risks drawing incorrect | |||
conclusions about the data, which might expose the user to additional | ||||
security risks (e.g., "privilege escalation"). Furthermore, it is | security risks (e.g., "privilege escalation"). Furthermore, it is | |||
impossible to determine the sender's intent by examining the data | impossible to determine the sender's intended processing model by | |||
format: many data formats match multiple media types that differ only | examining the data format: many data formats match multiple media | |||
in processing semantics. Implementers are encouraged to provide a | types that differ only in processing semantics. Implementers are | |||
means of disabling such "content sniffing" when it is used. | encouraged to provide a means to disable such sniffing. | |||
3.1.2. Encoding for Compression or Integrity | ||||
3.1.2.2. Content-Encoding | 6.2.2. Content-Encoding | |||
The "Content-Encoding" header field indicates what content codings | The "Content-Encoding" header field indicates what content codings | |||
have been applied to the representation, beyond those inherent in the | have been applied to the representation, beyond those inherent in the | |||
media type, and thus what decoding mechanisms have to be applied in | media type, and thus what decoding mechanisms have to be applied in | |||
order to obtain data in the media type referenced by the Content-Type | order to obtain data in the media type referenced by the Content-Type | |||
header field. Content-Encoding is primarily used to allow a | header field. Content-Encoding is primarily used to allow a | |||
representation's data to be compressed without losing the identity of | representation's data to be compressed without losing the identity of | |||
its underlying media type. | its underlying media type. | |||
Content-Encoding = 1#content-coding | Content-Encoding = 1#content-coding | |||
skipping to change at line 2130 ¶ | skipping to change at page 52, line 43 ¶ | |||
Content-Encoding: gzip | Content-Encoding: gzip | |||
If one or more encodings have been applied to a representation, the | If one or more encodings have been applied to a representation, the | |||
sender that applied the encodings MUST generate a Content-Encoding | sender that applied the encodings MUST generate a Content-Encoding | |||
header field that lists the content codings in the order in which | header field that lists the content codings in the order in which | |||
they were applied. Additional information about the encoding | they were applied. Additional information about the encoding | |||
parameters can be provided by other header fields not defined by this | parameters can be provided by other header fields not defined by this | |||
specification. | specification. | |||
Unlike Transfer-Encoding (Section 3.3.1 of [RFC7230]), the codings | Unlike Transfer-Encoding (Section 6.1 of [Messaging]), the codings | |||
listed in Content-Encoding are a characteristic of the | listed in Content-Encoding are a characteristic of the | |||
representation; the representation is defined in terms of the coded | representation; the representation is defined in terms of the coded | |||
form, and all other metadata about the representation is about the | form, and all other metadata about the representation is about the | |||
coded form unless otherwise noted in the metadata definition. | coded form unless otherwise noted in the metadata definition. | |||
Typically, the representation is only decoded just prior to rendering | Typically, the representation is only decoded just prior to rendering | |||
or analogous usage. | or analogous usage. | |||
If the media type includes an inherent encoding, such as a data | If the media type includes an inherent encoding, such as a data | |||
format that is always compressed, then that encoding would not be | format that is always compressed, then that encoding would not be | |||
restated in Content-Encoding even if it happens to be the same | restated in Content-Encoding even if it happens to be the same | |||
skipping to change at line 2154 ¶ | skipping to change at page 53, line 21 ¶ | |||
choose to publish the same data as multiple representations that | choose to publish the same data as multiple representations that | |||
differ only in whether the coding is defined as part of Content-Type | differ only in whether the coding is defined as part of Content-Type | |||
or Content-Encoding, since some user agents will behave differently | or Content-Encoding, since some user agents will behave differently | |||
in their handling of each response (e.g., open a "Save as ..." dialog | in their handling of each response (e.g., open a "Save as ..." dialog | |||
instead of automatic decompression and rendering of content). | instead of automatic decompression and rendering of content). | |||
An origin server MAY respond with a status code of 415 (Unsupported | An origin server MAY respond with a status code of 415 (Unsupported | |||
Media Type) if a representation in the request message has a content | Media Type) if a representation in the request message has a content | |||
coding that is not acceptable. | coding that is not acceptable. | |||
3.1.3. Audience Language | 6.2.3. Content-Language | |||
3.1.3.2. Content-Language | ||||
The "Content-Language" header field describes the natural language(s) | The "Content-Language" header field describes the natural language(s) | |||
of the intended audience for the representation. Note that this | of the intended audience for the representation. Note that this | |||
might not be equivalent to all the languages used within the | might not be equivalent to all the languages used within the | |||
representation. | representation. | |||
Content-Language = 1#language-tag | Content-Language = 1#language-tag | |||
Language tags are defined in Section 3.1.3.1. The primary purpose of | Language tags are defined in Section 6.1.3. The primary purpose of | |||
Content-Language is to allow a user to identify and differentiate | Content-Language is to allow a user to identify and differentiate | |||
representations according to the users' own preferred language. | representations according to the users' own preferred language. | |||
Thus, if the content is intended only for a Danish-literate audience, | Thus, if the content is intended only for a Danish-literate audience, | |||
the appropriate field is | the appropriate field is | |||
Content-Language: da | Content-Language: da | |||
If no Content-Language is specified, the default is that the content | If no Content-Language is specified, the default is that the content | |||
is intended for all language audiences. This might mean that the | is intended for all language audiences. This might mean that the | |||
sender does not consider it to be specific to any natural language, | sender does not consider it to be specific to any natural language, | |||
skipping to change at line 2195 ¶ | skipping to change at page 54, line 11 ¶ | |||
However, just because multiple languages are present within a | However, just because multiple languages are present within a | |||
representation does not mean that it is intended for multiple | representation does not mean that it is intended for multiple | |||
linguistic audiences. An example would be a beginner's language | linguistic audiences. An example would be a beginner's language | |||
primer, such as "A First Lesson in Latin", which is clearly intended | primer, such as "A First Lesson in Latin", which is clearly intended | |||
to be used by an English-literate audience. In this case, the | to be used by an English-literate audience. In this case, the | |||
Content-Language would properly only include "en". | Content-Language would properly only include "en". | |||
Content-Language MAY be applied to any media type -- it is not | Content-Language MAY be applied to any media type -- it is not | |||
limited to textual documents. | limited to textual documents. | |||
3.3.2. Content-Length | 6.2.4. Content-Length | |||
[[CREF2: The "Content-Length" header field indicates the number of | ||||
data octets (body length) for the representation. In some cases, | ||||
Content-Length is used to define or estimate message framing. ]] | ||||
Content-Length = 1*DIGIT | Content-Length = 1*DIGIT | |||
An example is | An example is | |||
Content-Length: 3495 | Content-Length: 3495 | |||
A sender MUST NOT send a Content-Length header field in any message | A sender MUST NOT send a Content-Length header field in any message | |||
that contains a Transfer-Encoding header field. | that contains a Transfer-Encoding header field. | |||
A user agent SHOULD send a Content-Length in a request message when | A user agent SHOULD send a Content-Length in a request message when | |||
no Transfer-Encoding is sent and the request method defines a meaning | no Transfer-Encoding is sent and the request method defines a meaning | |||
for an enclosed payload body. For example, a Content-Length header | for an enclosed payload body. For example, a Content-Length header | |||
field is normally sent in a POST request even when the value is 0 | field is normally sent in a POST request even when the value is 0 | |||
(indicating an empty payload body). A user agent SHOULD NOT send a | (indicating an empty payload body). A user agent SHOULD NOT send a | |||
Content-Length header field when the request message does not contain | Content-Length header field when the request message does not contain | |||
a payload body and the method semantics do not anticipate such a | a payload body and the method semantics do not anticipate such a | |||
body. | body. | |||
A server MAY send a Content-Length header field in a response to a | A server MAY send a Content-Length header field in a response to a | |||
HEAD request (Section 4.3.2 of [RFC7231]); a server MUST NOT send | HEAD request (Section 7.3.2); a server MUST NOT send Content-Length | |||
Content-Length in such a response unless its field-value equals the | in such a response unless its field-value equals the decimal number | |||
decimal number of octets that would have been sent in the payload | of octets that would have been sent in the payload body of a response | |||
body of a response if the same request had used the GET method. | if the same request had used the GET method. | |||
A server MAY send a Content-Length header field in a 304 (Not | A server MAY send a Content-Length header field in a 304 (Not | |||
Modified) response to a conditional GET request (Section 4.1 of | Modified) response to a conditional GET request (Section 9.4.5); a | |||
[RFC7232]); a server MUST NOT send Content-Length in such a response | server MUST NOT send Content-Length in such a response unless its | |||
unless its field-value equals the decimal number of octets that would | field-value equals the decimal number of octets that would have been | |||
have been sent in the payload body of a 200 (OK) response to the same | sent in the payload body of a 200 (OK) response to the same request. | |||
request. | ||||
A server MUST NOT send a Content-Length header field in any response | A server MUST NOT send a Content-Length header field in any response | |||
with a status code of 1xx (Informational) or 204 (No Content). A | with a status code of 1xx (Informational) or 204 (No Content). A | |||
server MUST NOT send a Content-Length header field in any 2xx | server MUST NOT send a Content-Length header field in any 2xx | |||
(Successful) response to a CONNECT request (Section 4.3.6 of | (Successful) response to a CONNECT request (Section 7.3.6). | |||
[RFC7231]). | ||||
Aside from the cases defined above, in the absence of | Aside from the cases defined above, in the absence of Transfer- | |||
Transfer-Encoding, an origin server SHOULD send a Content-Length | Encoding, an origin server SHOULD send a Content-Length header field | |||
header field when the payload body size is known prior to sending the | when the payload body size is known prior to sending the complete | |||
complete header section. This will allow downstream recipients to | header section. This will allow downstream recipients to measure | |||
measure transfer progress, know when a received message is complete, | transfer progress, know when a received message is complete, and | |||
and potentially reuse the connection for additional requests. | potentially reuse the connection for additional requests. | |||
Any Content-Length field value greater than or equal to zero is | Any Content-Length field value greater than or equal to zero is | |||
valid. Since there is no predefined limit to the length of a | valid. Since there is no predefined limit to the length of a | |||
payload, a recipient MUST anticipate potentially large decimal | payload, a recipient MUST anticipate potentially large decimal | |||
numerals and prevent parsing errors due to integer conversion | numerals and prevent parsing errors due to integer conversion | |||
overflows (Section 9.3). | overflows (Section 13.5). | |||
If a message is received that has multiple Content-Length header | If a message is received that has multiple Content-Length header | |||
fields with field-values consisting of the same decimal value, or a | fields with field-values consisting of the same decimal value, or a | |||
single Content-Length header field with a field value containing a | single Content-Length header field with a field value containing a | |||
list of identical decimal values (e.g., "Content-Length: 42, 42"), | list of identical decimal values (e.g., "Content-Length: 42, 42"), | |||
indicating that duplicate Content-Length header fields have been | indicating that duplicate Content-Length header fields have been | |||
generated or combined by an upstream message processor, then the | generated or combined by an upstream message processor, then the | |||
recipient MUST either reject the message as invalid or replace the | recipient MUST either reject the message as invalid or replace the | |||
duplicated field-values with a single valid Content-Length field | duplicated field-values with a single valid Content-Length field | |||
containing that decimal value prior to determining the message body | containing that decimal value prior to determining the message body | |||
length or forwarding the message. | length or forwarding the message. | |||
3.1.4. Identification | 6.2.5. Content-Location | |||
3.1.4.2. Content-Location | ||||
The "Content-Location" header field references a URI that can be used | The "Content-Location" header field references a URI that can be used | |||
as an identifier for a specific resource corresponding to the | as an identifier for a specific resource corresponding to the | |||
representation in this message's payload. In other words, if one | representation in this message's payload. In other words, if one | |||
were to perform a GET request on this URI at the time of this | were to perform a GET request on this URI at the time of this | |||
message's generation, then a 200 (OK) response would contain the same | message's generation, then a 200 (OK) response would contain the same | |||
representation that is enclosed as payload in this message. | representation that is enclosed as payload in this message. | |||
Content-Location = absolute-URI / partial-URI | Content-Location = absolute-URI / partial-URI | |||
The Content-Location value is not a replacement for the effective | The Content-Location value is not a replacement for the effective | |||
Request URI (Section 5.5 of [RFC7230]). It is representation | Request URI (Section 5.3). It is representation metadata. It has | |||
metadata. It has the same syntax and semantics as the header field | the same syntax and semantics as the header field of the same name | |||
of the same name defined for MIME body parts in Section 4 of | defined for MIME body parts in Section 4 of [RFC2557]. However, its | |||
[RFC2557]. However, its appearance in an HTTP message has some | appearance in an HTTP message has some special implications for HTTP | |||
special implications for HTTP recipients. | recipients. | |||
If Content-Location is included in a 2xx (Successful) response | If Content-Location is included in a 2xx (Successful) response | |||
message and its value refers (after conversion to absolute form) to a | message and its value refers (after conversion to absolute form) to a | |||
URI that is the same as the effective request URI, then the recipient | URI that is the same as the effective request URI, then the recipient | |||
MAY consider the payload to be a current representation of that | MAY consider the payload to be a current representation of that | |||
resource at the time indicated by the message origination date. For | 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 | a GET (Section 7.3.1) or HEAD (Section 7.3.2) request, this is the | |||
same as the default semantics when no Content-Location is provided by | same as the default semantics when no Content-Location is provided by | |||
the server. For a state-changing request like PUT (Section 4.3.4) or | the server. For a state-changing request like PUT (Section 7.3.4) or | |||
POST (Section 4.3.3), it implies that the server's response contains | POST (Section 7.3.3), it implies that the server's response contains | |||
the new representation of that resource, thereby distinguishing it | the new representation of that resource, thereby distinguishing it | |||
from representations that might only report about the action (e.g., | from representations that might only report about the action (e.g., | |||
"It worked!"). This allows authoring applications to update their | "It worked!"). This allows authoring applications to update their | |||
local copies without the need for a subsequent GET request. | local copies without the need for a subsequent GET request. | |||
If Content-Location is included in a 2xx (Successful) response | If Content-Location is included in a 2xx (Successful) response | |||
message and its field-value refers to a URI that differs from the | message and its field-value refers to a URI that differs from the | |||
effective request URI, then the origin server claims that the URI is | effective request URI, then the origin server claims that the URI is | |||
an identifier for a different resource corresponding to the enclosed | an identifier for a different resource corresponding to the enclosed | |||
representation. Such a claim can only be trusted if both identifiers | representation. Such a claim can only be trusted if both identifiers | |||
share the same resource owner, which cannot be programmatically | share the same resource owner, which cannot be programmatically | |||
determined via HTTP. | determined via HTTP. | |||
o For a response to a GET or HEAD request, this is an indication | o For a response to a GET or HEAD request, this is an indication | |||
that the effective request URI refers to a resource that is | that the effective request URI refers to a resource that is | |||
subject to content negotiation and the Content-Location | subject to content negotiation and the Content-Location field- | |||
field-value is a more specific identifier for the selected | value is a more specific identifier for the selected | |||
representation. | representation. | |||
o For a 201 (Created) response to a state-changing method, a | o For a 201 (Created) response to a state-changing method, a | |||
Content-Location field-value that is identical to the Location | Content-Location field-value that is identical to the Location | |||
field-value indicates that this payload is a current | field-value indicates that this payload is a current | |||
representation of the newly created resource. | representation of the newly created resource. | |||
o Otherwise, such a Content-Location indicates that this payload is | o Otherwise, such a Content-Location indicates that this payload is | |||
a representation reporting on the requested action's status and | a representation reporting on the requested action's status and | |||
that the same report is available (for future access with GET) at | that the same report is available (for future access with GET) at | |||
skipping to change at line 2344 ¶ | skipping to change at page 57, line 16 ¶ | |||
For example, if a client makes a PUT request on a negotiated resource | For example, if a client makes a PUT request on a negotiated resource | |||
and the origin server accepts that PUT (without redirection), then | and the origin server accepts that PUT (without redirection), then | |||
the new state of that resource is expected to be consistent with the | the new state of that resource is expected to be consistent with the | |||
one representation supplied in that PUT; the Content-Location cannot | one representation supplied in that PUT; the Content-Location cannot | |||
be used as a form of reverse content selection identifier to update | be used as a form of reverse content selection identifier to update | |||
only one of the negotiated representations. If the user agent had | only one of the negotiated representations. If the user agent had | |||
wanted the latter semantics, it would have applied the PUT directly | wanted the latter semantics, it would have applied the PUT directly | |||
to the Content-Location URI. | to the Content-Location URI. | |||
3.3. Payload Semantics | 6.3. Payload | |||
Some HTTP messages transfer a complete or partial representation as | Some HTTP messages transfer a complete or partial representation as | |||
the message "payload". In some cases, a payload might contain only | the message "payload". In some cases, a payload might contain only | |||
the associated representation's header fields (e.g., responses to | the associated representation's header fields (e.g., responses to | |||
HEAD) or only some part(s) of the representation data (e.g., the 206 | HEAD) or only some part(s) of the representation data (e.g., the 206 | |||
(Partial Content) status code). | (Partial Content) status code). | |||
Header fields that specifically describe the payload, rather than the | Header fields that specifically describe the payload, rather than the | |||
associated representation, are referred to as "payload header | associated representation, are referred to as "payload header | |||
fields". Payload header fields are defined in other parts of this | fields". Payload header fields are defined in other parts of this | |||
specification, due to their impact on message parsing. | specification, due to their impact on message parsing. | |||
+-------------------+----------------------------+ | +-------------------+----------------------------+ | |||
| Header Field Name | Defined in... | | | Header Field Name | Defined in... | | |||
+-------------------+----------------------------+ | +-------------------+----------------------------+ | |||
| Content-Length | Section 3.3.2 of [RFC7230] | | | Content-Range | Section 6.3.4 | | |||
| Content-Range | Section 4.2 of [RFC7233] | | | Trailer | Section 4.3.3 | | |||
| Trailer | Section 4.4 of [RFC7230] | | | Transfer-Encoding | Section 6.1 of [Messaging] | | |||
| Transfer-Encoding | Section 3.3.1 of [RFC7230] | | ||||
+-------------------+----------------------------+ | +-------------------+----------------------------+ | |||
X.X.X. [Purpose] | 6.3.1. Purpose | |||
The purpose of a payload in a request is defined by the method | The purpose of a payload in a request is defined by the method | |||
semantics. For example, a representation in the payload of a PUT | semantics. For example, a representation in the payload of a PUT | |||
request (Section 4.3.4) represents the desired state of the target | request (Section 7.3.4) represents the desired state of the target | |||
resource if the request is successfully applied, whereas a | resource if the request is successfully applied, whereas a | |||
representation in the payload of a POST request (Section 4.3.3) | representation in the payload of a POST request (Section 7.3.3) | |||
represents information to be processed by the target resource. | represents information to be processed by the target resource. | |||
In a response, the payload's purpose is defined by both the request | 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 | 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 | 200 (OK) response to GET (Section 7.3.1) represents the current state | |||
of the target resource, as observed at the time of the message | of the target resource, as observed at the time of the message | |||
origination date (Section 7.1.1.2), whereas the payload of the same | origination date (Section 10.1.1.2), whereas the payload of the same | |||
status code in a response to POST might represent either the | status code in a response to POST might represent either the | |||
processing result or the new state of the target resource after | processing result or the new state of the target resource after | |||
applying the processing. Response messages with an error status code | applying the processing. Response messages with an error status code | |||
usually contain a payload that represents the error condition, such | usually contain a payload that represents the error condition, such | |||
that it describes the error state and what next steps are suggested | that it describes the error state and what next steps are suggested | |||
for resolving it. | for resolving it. | |||
3.1.4.1. Identifying a Representation | 6.3.2. Identification | |||
When a complete or partial representation is transferred in a message | When a complete or partial representation is transferred in a message | |||
payload, it is often desirable for the sender to supply, or the | payload, it is often desirable for the sender to supply, or the | |||
recipient to determine, an identifier for a resource corresponding to | recipient to determine, an identifier for a resource corresponding to | |||
that representation. | that representation. | |||
For a request message: | For a request message: | |||
o If the request has a Content-Location header field, then the | o If the request has a Content-Location header field, then the | |||
sender asserts that the payload is a representation of the | sender asserts that the payload is a representation of the | |||
skipping to change at line 2411 ¶ | skipping to change at page 58, line 34 ¶ | |||
might still be useful for revision history links. | might still be useful for revision history links. | |||
o Otherwise, the payload is unidentified. | o Otherwise, the payload is unidentified. | |||
For a response message, the following rules are applied in order | For a response message, the following rules are applied in order | |||
until a match is found: | until a match is found: | |||
1. If the request method is GET or HEAD and the response status code | 1. 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 | is 200 (OK), 204 (No Content), 206 (Partial Content), or 304 (Not | |||
Modified), the payload is a representation of the resource | Modified), the payload is a representation of the resource | |||
identified by the effective request URI (Section 5.5 of | identified by the effective request URI (Section 5.3). | |||
[RFC7230]). | ||||
2. If the request method is GET or HEAD and the response status code | 2. If the request method is GET or HEAD and the response status code | |||
is 203 (Non-Authoritative Information), the payload is a | is 203 (Non-Authoritative Information), the payload is a | |||
potentially modified or enhanced representation of the target | potentially modified or enhanced representation of the target | |||
resource as provided by an intermediary. | resource as provided by an intermediary. | |||
3. If the response has a Content-Location header field and its | 3. If the response has a Content-Location header field and its | |||
field-value is a reference to the same URI as the effective | field-value is a reference to the same URI as the effective | |||
request URI, the payload is a representation of the resource | request URI, the payload is a representation of the resource | |||
identified by the effective request URI. | identified by the effective request URI. | |||
skipping to change at line 2436 ¶ | skipping to change at page 59, line 11 ¶ | |||
request URI, then the sender asserts that the payload is a | request URI, then the sender asserts that the payload is a | |||
representation of the resource identified by the Content-Location | representation of the resource identified by the Content-Location | |||
field-value. However, such an assertion cannot be trusted unless | field-value. However, such an assertion cannot be trusted unless | |||
it can be verified by other means (not defined by this | it can be verified by other means (not defined by this | |||
specification). | specification). | |||
5. Otherwise, the payload is unidentified. | 5. Otherwise, the payload is unidentified. | |||
6.3.3. Payload Body | 6.3.3. Payload Body | |||
Responses to the HEAD request method (Section 4.3.2 | The payload body contains the data of a request or response. This is | |||
of [RFC7231]) never include a message body because the associated | distinct from the message body (e.g., Section 6 of [Messaging]), | |||
response header fields (e.g., Transfer-Encoding, Content-Length, | which is how the payload body is transferred "on the wire", and might | |||
etc.), if present, indicate only what their values would have been if | be encoded, depending on the HTTP version in use. | |||
the request method had been GET (Section 4.3.1 of [RFC7231]). | ||||
It is also distinct from a request or response's representation data | ||||
(Section 6.1), which can be inferred from protocol operation, rather | ||||
than necessarily appearing "on the wire." | ||||
The presence of a payload body in a request depends on whether the | ||||
request method used defines semantics for it. | ||||
The presence of a payload body in a response depends on both the | ||||
request method to which it is responding and the response status code | ||||
(Section 9). | ||||
Responses to the HEAD request method (Section 7.3.2) never include a | ||||
payload body because the associated response header fields indicate | ||||
only what their values would have been if the request method had been | ||||
GET (Section 7.3.1). | ||||
2xx (Successful) responses to a CONNECT request method | 2xx (Successful) responses to a CONNECT request method | |||
(Section 4.3.6 of [RFC7231]) switch to tunnel mode instead of | (Section 7.3.6) switch the connection to tunnel mode instead of | |||
having a message body. | having a payload body. | |||
All 1xx (Informational), 204 (No Content), and 304 (Not Modified) | All 1xx (Informational), 204 (No Content), and 304 (Not Modified) | |||
responses do not include a message body. | responses do not include a payload body. | |||
All other responses do include a message body, although the body | All other responses do include a payload body, although that body | |||
might be of zero length. | might be of zero length. | |||
4.2. Content-Range | 6.3.4. Content-Range | |||
The "Content-Range" header field is sent in a single part 206 | The "Content-Range" header field is sent in a single part 206 | |||
(Partial Content) response to indicate the partial range of the | (Partial Content) response to indicate the partial range of the | |||
selected representation enclosed as the message payload, sent in each | selected representation enclosed as the message payload, sent in each | |||
part of a multipart 206 response to indicate the range enclosed | part of a multipart 206 response to indicate the range enclosed | |||
within each body part, and sent in 416 (Range Not Satisfiable) | within each body part, and sent in 416 (Range Not Satisfiable) | |||
responses to provide information about the selected representation. | responses to provide information about the selected representation. | |||
Content-Range = byte-content-range | Content-Range = range-unit SP | |||
/ other-content-range | ( range-resp / unsatisfied-range ) | |||
byte-content-range = bytes-unit SP | ||||
( byte-range-resp / unsatisfied-range ) | ||||
byte-range-resp = byte-range "/" ( complete-length / "*" ) | range-resp = incl-range "/" ( complete-length / "*" ) | |||
byte-range = first-byte-pos "-" last-byte-pos | incl-range = first-pos "-" last-pos | |||
unsatisfied-range = "*/" complete-length | unsatisfied-range = "*/" complete-length | |||
complete-length = 1*DIGIT | complete-length = 1*DIGIT | |||
other-content-range = other-range-unit SP other-range-resp | ||||
other-range-resp = *CHAR | ||||
If a 206 (Partial Content) response contains a Content-Range header | If a 206 (Partial Content) response contains a Content-Range header | |||
field with a range unit (Section 2) that the recipient does not | field with a range unit (Section 6.1.4) that the recipient does not | |||
understand, the recipient MUST NOT attempt to recombine it with a | understand, the recipient MUST NOT attempt to recombine it with a | |||
stored representation. A proxy that receives such a message SHOULD | stored representation. A proxy that receives such a message SHOULD | |||
forward it downstream. | forward it downstream. | |||
For byte ranges, a sender SHOULD indicate the complete length of the | For byte ranges, a sender SHOULD indicate the complete length of the | |||
representation from which the range has been extracted, unless the | representation from which the range has been extracted, unless the | |||
complete length is unknown or difficult to determine. An asterisk | complete length is unknown or difficult to determine. An asterisk | |||
character ("*") in place of the complete-length indicates that the | character ("*") in place of the complete-length indicates that the | |||
representation length was unknown when the header field was | representation length was unknown when the header field was | |||
generated. | generated. | |||
skipping to change at line 2499 ¶ | skipping to change at page 60, line 37 ¶ | |||
The following example illustrates when the complete length of the | The following example illustrates when the complete length of the | |||
selected representation is known by the sender to be 1234 bytes: | selected representation is known by the sender to be 1234 bytes: | |||
Content-Range: bytes 42-1233/1234 | Content-Range: bytes 42-1233/1234 | |||
and this second example illustrates when the complete length is | and this second example illustrates when the complete length is | |||
unknown: | unknown: | |||
Content-Range: bytes 42-1233/* | Content-Range: bytes 42-1233/* | |||
A Content-Range field value is invalid if it contains a | A Content-Range field value is invalid if it contains a range-resp | |||
byte-range-resp that has a last-byte-pos value less than its | that has a last-pos value less than its first-pos value, or a | |||
first-byte-pos value, or a complete-length value less than or equal | complete-length value less than or equal to its last-pos value. The | |||
to its last-byte-pos value. The recipient of an invalid | recipient of an invalid Content-Range MUST NOT attempt to recombine | |||
Content-Range MUST NOT attempt to recombine the received content with | the received content with a stored representation. | |||
a stored representation. | ||||
A server generating a 416 (Range Not Satisfiable) response to a | A server generating a 416 (Range Not Satisfiable) response to a byte- | |||
byte-range request SHOULD send a Content-Range header field with an | range request SHOULD send a Content-Range header field with an | |||
unsatisfied-range value, as in the following example: | unsatisfied-range value, as in the following example: | |||
Content-Range: bytes */1234 | Content-Range: bytes */1234 | |||
The complete-length in a 416 response indicates the current length of | The complete-length in a 416 response indicates the current length of | |||
the selected representation. | the selected representation. | |||
The Content-Range header field has no meaning for status codes that | The Content-Range header field has no meaning for status codes that | |||
do not explicitly describe its semantic. For this specification, | do not explicitly describe its semantic. For this specification, | |||
only the 206 (Partial Content) and 416 (Range Not Satisfiable) status | only the 206 (Partial Content) and 416 (Range Not Satisfiable) status | |||
skipping to change at line 2539 ¶ | skipping to change at page 61, line 29 ¶ | |||
Content-Range: bytes 500-999/1234 | Content-Range: bytes 500-999/1234 | |||
o All except for the first 500 bytes: | o All except for the first 500 bytes: | |||
Content-Range: bytes 500-1233/1234 | Content-Range: bytes 500-1233/1234 | |||
o The last 500 bytes: | o The last 500 bytes: | |||
Content-Range: bytes 734-1233/1234 | Content-Range: bytes 734-1233/1234 | |||
Appendix A. Internet Media Type multipart/byteranges | 6.3.5. Media Type multipart/byteranges | |||
When a 206 (Partial Content) response message includes the content of | When a 206 (Partial Content) response message includes the content of | |||
multiple ranges, they are transmitted as body parts in a multipart | multiple ranges, they are transmitted as body parts in a multipart | |||
message body ([RFC2046], Section 5.1) with the media type of | message body ([RFC2046], Section 5.1) with the media type of | |||
"multipart/byteranges". | "multipart/byteranges". | |||
The multipart/byteranges media type includes one or more body parts, | The multipart/byteranges media type includes one or more body parts, | |||
each with its own Content-Type and Content-Range fields. The | each with its own Content-Type and Content-Range fields. The | |||
required boundary parameter specifies the boundary string used to | required boundary parameter specifies the boundary string used to | |||
separate each body part. | separate each body part. | |||
skipping to change at line 2587 ¶ | skipping to change at page 62, line 36 ¶ | |||
Content-Range: exampleunit 1.2-4.3/25 | Content-Range: exampleunit 1.2-4.3/25 | |||
...the first range... | ...the first range... | |||
--THIS_STRING_SEPARATES | --THIS_STRING_SEPARATES | |||
Content-Type: video/example | Content-Type: video/example | |||
Content-Range: exampleunit 11.2-14.3/25 | Content-Range: exampleunit 11.2-14.3/25 | |||
...the second range | ...the second range | |||
--THIS_STRING_SEPARATES-- | --THIS_STRING_SEPARATES-- | |||
5.4.1. Internet Media Type multipart/byteranges | The following information serves as the registration form for the | |||
multipart/byteranges media type. | ||||
This document serves as the specification for the Internet media type | ||||
"multipart/byteranges". The following has been registered with IANA. | ||||
Type name: multipart | Type name: multipart | |||
Subtype name: byteranges | Subtype name: byteranges | |||
Required parameters: boundary | Required parameters: boundary | |||
Optional parameters: N/A | Optional parameters: N/A | |||
Encoding considerations: only "7bit", "8bit", or "binary" are | Encoding considerations: only "7bit", "8bit", or "binary" are | |||
permitted | permitted | |||
Security considerations: see Section 6 | Security considerations: see Section 13 | |||
Interoperability considerations: N/A | Interoperability considerations: N/A | |||
Published specification: This specification (see Section 6.3.5). | ||||
Published specification: This specification (see Appendix A). | ||||
Applications that use this media type: HTTP components supporting | Applications that use this media type: HTTP components supporting | |||
multiple ranges in a single request. | multiple ranges in a single request. | |||
Fragment identifier considerations: N/A | Fragment identifier considerations: N/A | |||
Additional information: | Additional information: | |||
Deprecated alias names for this type: N/A | Deprecated alias names for this type: N/A | |||
Magic number(s): N/A | Magic number(s): N/A | |||
File extension(s): N/A | File extension(s): N/A | |||
Macintosh file type code(s): N/A | Macintosh file type code(s): N/A | |||
Person and email address to contact for further information: See | Person and email address to contact for further information: See Aut | |||
Authors' Addresses section. | hors' Addresses section. | |||
Intended usage: COMMON | Intended usage: COMMON | |||
Restrictions on usage: N/A | Restrictions on usage: N/A | |||
Author: See Authors' Addresses section. | Author: See Authors' Addresses section. | |||
Change controller: IESG | Change controller: IESG | |||
3.4. Content Negotiation | 6.4. Content Negotiation | |||
When responses convey payload information, whether indicating a | When responses convey payload information, whether indicating a | |||
success or an error, the origin server often has different ways of | success or an error, the origin server often has different ways of | |||
representing that information; for example, in different formats, | representing that information; for example, in different formats, | |||
languages, or encodings. Likewise, different users or user agents | languages, or encodings. Likewise, different users or user agents | |||
might have differing capabilities, characteristics, or preferences | might have differing capabilities, characteristics, or preferences | |||
that could influence which representation, among those available, | that could influence which representation, among those available, | |||
would be best to deliver. For this reason, HTTP provides mechanisms | would be best to deliver. For this reason, HTTP provides mechanisms | |||
for content negotiation. | for content negotiation. | |||
skipping to change at line 2668 ¶ | skipping to change at page 64, line 18 ¶ | |||
practicality. | practicality. | |||
Note that, in all cases, HTTP is not aware of the resource semantics. | Note that, in all cases, HTTP is not aware of the resource semantics. | |||
The consistency with which an origin server responds to requests, | The consistency with which an origin server responds to requests, | |||
over time and over the varying dimensions of content negotiation, and | over time and over the varying dimensions of content negotiation, and | |||
thus the "sameness" of a resource's observed representations over | thus the "sameness" of a resource's observed representations over | |||
time, is determined entirely by whatever entity or algorithm selects | time, is determined entirely by whatever entity or algorithm selects | |||
or generates those responses. HTTP pays no attention to the man | or generates those responses. HTTP pays no attention to the man | |||
behind the curtain. | behind the curtain. | |||
3.4.1. Proactive Negotiation | 6.4.1. Proactive Negotiation | |||
When content negotiation preferences are sent by the user agent in a | When content negotiation preferences are sent by the user agent in a | |||
request to encourage an algorithm located at the server to select the | request to encourage an algorithm located at the server to select the | |||
preferred representation, it is called proactive negotiation (a.k.a., | preferred representation, it is called proactive negotiation (a.k.a., | |||
server-driven negotiation). Selection is based on the available | server-driven negotiation). Selection is based on the available | |||
representations for a response (the dimensions over which it might | representations for a response (the dimensions over which it might | |||
vary, such as language, content-coding, etc.) compared to various | vary, such as language, content-coding, etc.) compared to various | |||
information supplied in the request, including both the explicit | information supplied in the request, including both the explicit | |||
negotiation fields of Section 5.3 and implicit characteristics, such | negotiation fields of Section 8.4 and implicit characteristics, such | |||
as the client's network address or parts of the User-Agent field. | as the client's network address or parts of the User-Agent field. | |||
Proactive negotiation is advantageous when the algorithm for | Proactive negotiation is advantageous when the algorithm for | |||
selecting from among the available representations is difficult to | selecting from among the available representations is difficult to | |||
describe to a user agent, or when the server desires to send its | describe to a user agent, or when the server desires to send its | |||
"best guess" to the user agent along with the first response (hoping | "best guess" to the user agent along with the first response (hoping | |||
to avoid the round trip delay of a subsequent request if the "best | to avoid the round trip delay of a subsequent request if the "best | |||
guess" is good enough for the user). In order to improve the | guess" is good enough for the user). In order to improve the | |||
server's guess, a user agent MAY send request header fields that | server's guess, a user agent MAY send request header fields that | |||
describe its preferences. | describe its preferences. | |||
skipping to change at line 2713 ¶ | skipping to change at page 65, line 16 ¶ | |||
algorithms for generating responses to a request; and, | algorithms for generating responses to a request; and, | |||
o It limits the reusability of responses for shared caching. | o It limits the reusability of responses for shared caching. | |||
A user agent cannot rely on proactive negotiation preferences being | A user agent cannot rely on proactive negotiation preferences being | |||
consistently honored, since the origin server might not implement | consistently honored, since the origin server might not implement | |||
proactive negotiation for the requested resource or might decide that | proactive negotiation for the requested resource or might decide that | |||
sending a response that doesn't conform to the user agent's | sending a response that doesn't conform to the user agent's | |||
preferences is better than sending a 406 (Not Acceptable) response. | preferences is better than sending a 406 (Not Acceptable) response. | |||
A Vary header field (Section 7.1.4) is often sent in a response | A Vary header field (Section 10.1.4) is often sent in a response | |||
subject to proactive negotiation to indicate what parts of the | subject to proactive negotiation to indicate what parts of the | |||
request information were used in the selection algorithm. | request information were used in the selection algorithm. | |||
3.4.2. Reactive Negotiation | 6.4.2. Reactive Negotiation | |||
With reactive negotiation (a.k.a., agent-driven negotiation), | With reactive negotiation (a.k.a., agent-driven negotiation), | |||
selection of the best response representation (regardless of the | selection of the best response representation (regardless of the | |||
status code) is performed by the user agent after receiving an | status code) is performed by the user agent after receiving an | |||
initial response from the origin server that contains a list of | initial response from the origin server that contains a list of | |||
resources for alternative representations. If the user agent is not | resources for alternative representations. If the user agent is not | |||
satisfied by the initial response representation, it can perform a | satisfied by the initial response representation, it can perform a | |||
GET request on one or more of the alternative resources, selected | GET request on one or more of the alternative resources, selected | |||
based on metadata included in the list, to obtain a different form of | based on metadata included in the list, to obtain a different form of | |||
representation for that response. Selection of alternatives might be | representation for that response. Selection of alternatives might be | |||
skipping to change at line 2762 ¶ | skipping to change at page 66, line 16 ¶ | |||
caches are used to distribute server load and reduce network usage. | caches are used to distribute server load and reduce network usage. | |||
Reactive negotiation suffers from the disadvantages of transmitting a | Reactive negotiation suffers from the disadvantages of transmitting a | |||
list of alternatives to the user agent, which degrades user-perceived | list of alternatives to the user agent, which degrades user-perceived | |||
latency if transmitted in the header section, and needing a second | latency if transmitted in the header section, and needing a second | |||
request to obtain an alternate representation. Furthermore, this | request to obtain an alternate representation. Furthermore, this | |||
specification does not define a mechanism for supporting automatic | specification does not define a mechanism for supporting automatic | |||
selection, though it does not prevent such a mechanism from being | selection, though it does not prevent such a mechanism from being | |||
developed as an extension. | developed as an extension. | |||
4. Request Methods | 7. Request Methods | |||
4.1. Overview | 7.1. Overview | |||
The request method token is the primary source of request semantics; | The request method token is the primary source of request semantics; | |||
it indicates the purpose for which the client has made this request | it indicates the purpose for which the client has made this request | |||
and what is expected by the client as a successful result. | and what is expected by the client as a successful result. | |||
The request method's semantics might be further specialized by the | The request method's semantics might be further specialized by the | |||
semantics of some header fields when present in a request (Section 5) | semantics of some header fields when present in a request (Section 8) | |||
if those additional semantics do not conflict with the method. For | if those additional semantics do not conflict with the method. For | |||
example, a client can send conditional request header fields | example, a client can send conditional request header fields | |||
(Section 5.2) to make the requested action conditional on the current | (Section 8.2) to make the requested action conditional on the current | |||
state of the target resource ([RFC7232]). | state of the target resource. | |||
method = token | method = token | |||
HTTP was originally designed to be usable as an interface to | HTTP was originally designed to be usable as an interface to | |||
distributed object systems. The request method was envisioned as | distributed object systems. The request method was envisioned as | |||
applying semantics to a target resource in much the same way as | applying semantics to a target resource in much the same way as | |||
invoking a defined method on an identified object would apply | invoking a defined method on an identified object would apply | |||
semantics. The method token is case-sensitive because it might be | semantics. | |||
used as a gateway to object-based systems with case-sensitive method | ||||
names. | The method token is case-sensitive because it might be used as a | |||
gateway to object-based systems with case-sensitive method names. By | ||||
convention, standardized methods are defined in all-uppercase US- | ||||
ASCII letters. | ||||
Unlike distributed objects, the standardized request methods in HTTP | Unlike distributed objects, the standardized request methods in HTTP | |||
are not resource-specific, since uniform interfaces provide for | are not resource-specific, since uniform interfaces provide for | |||
better visibility and reuse in network-based systems [REST]. Once | better visibility and reuse in network-based systems [REST]. Once | |||
defined, a standardized method ought to have the same semantics when | defined, a standardized method ought to have the same semantics when | |||
applied to any resource, though each resource determines for itself | applied to any resource, though each resource determines for itself | |||
whether those semantics are implemented or allowed. | whether those semantics are implemented or allowed. | |||
This specification defines a number of standardized methods that are | This specification defines a number of standardized methods that are | |||
commonly used in HTTP, as outlined by the following table. By | commonly used in HTTP, as outlined by the following table. | |||
convention, standardized methods are defined in all-uppercase | ||||
US-ASCII letters. | ||||
+---------+-------------------------------------------------+-------+ | +---------+-------------------------------------------------+-------+ | |||
| Method | Description | Sec. | | | Method | Description | Sec. | | |||
+---------+-------------------------------------------------+-------+ | +---------+-------------------------------------------------+-------+ | |||
| GET | Transfer a current representation of the target | 4.3.1 | | | GET | Transfer a current representation of the target | 7.3.1 | | |||
| | resource. | | | | | resource. | | | |||
| HEAD | Same as GET, but only transfer the status line | 4.3.2 | | | HEAD | Same as GET, but only transfer the status line | 7.3.2 | | |||
| | and header section. | | | | | and header section. | | | |||
| POST | Perform resource-specific processing on the | 4.3.3 | | | POST | Perform resource-specific processing on the | 7.3.3 | | |||
| | request payload. | | | | | request payload. | | | |||
| PUT | Replace all current representations of the | 4.3.4 | | | PUT | Replace all current representations of the | 7.3.4 | | |||
| | target resource with the request payload. | | | | | target resource with the request payload. | | | |||
| DELETE | Remove all current representations of the | 4.3.5 | | | DELETE | Remove all current representations of the | 7.3.5 | | |||
| | target resource. | | | | | target resource. | | | |||
| CONNECT | Establish a tunnel to the server identified by | 4.3.6 | | | CONNECT | Establish a tunnel to the server identified by | 7.3.6 | | |||
| | the target resource. | | | | | the target resource. | | | |||
| OPTIONS | Describe the communication options for the | 4.3.7 | | | OPTIONS | Describe the communication options for the | 7.3.7 | | |||
| | target resource. | | | | | target resource. | | | |||
| TRACE | Perform a message loop-back test along the path | 4.3.8 | | | TRACE | Perform a message loop-back test along the path | 7.3.8 | | |||
| | to the target resource. | | | | | to the target resource. | | | |||
+---------+-------------------------------------------------+-------+ | +---------+-------------------------------------------------+-------+ | |||
Table 4 | ||||
All general-purpose servers MUST support the methods GET and HEAD. | All general-purpose servers MUST support the methods GET and HEAD. | |||
All other methods are OPTIONAL. | All other methods are OPTIONAL. | |||
The set of methods allowed by a target resource can be listed in an | The set of methods allowed by a target resource can be listed in an | |||
Allow header field (Section 7.4.1). However, the set of allowed | Allow header field (Section 10.4.2). However, the set of allowed | |||
methods can change dynamically. When a request method is received | methods can change dynamically. When a request method is received | |||
that is unrecognized or not implemented by an origin server, the | that is unrecognized or not implemented by an origin server, the | |||
origin server SHOULD respond with the 501 (Not Implemented) status | origin server SHOULD respond with the 501 (Not Implemented) status | |||
code. When a request method is received that is known by an origin | code. When a request method is received that is known by an origin | |||
server but not allowed for the target resource, the origin server | server but not allowed for the target resource, the origin server | |||
SHOULD respond with the 405 (Method Not Allowed) status code. | SHOULD respond with the 405 (Method Not Allowed) status code. | |||
4.2. Common Method Properties | 7.2. Common Method Properties | |||
+---------+------+------------+----------------+ | ||||
| Method | Safe | Idempotent | Reference | | ||||
+---------+------+------------+----------------+ | ||||
| CONNECT | no | no | Section 7.3.6 | | ||||
| DELETE | no | yes | Section 7.3.5 | | ||||
| GET | yes | yes | Section 7.3.1 | | ||||
| HEAD | yes | yes | Section 7.3.2 | | ||||
| OPTIONS | yes | yes | Section 7.3.7 | | ||||
| POST | no | no | Section 7.3.3 | | ||||
| PUT | no | yes | Section 7.3.4 | | ||||
| TRACE | yes | yes | Section 7.3.8 | | ||||
+---------+------+------------+----------------+ | ||||
+---------+------+------------+---------------+ | Table 5 | |||
| 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 | | ||||
+---------+------+------------+---------------+ | ||||
4.2.1. Safe Methods | 7.2.1. Safe Methods | |||
Request methods are considered "safe" if their defined semantics are | Request methods are considered "safe" if their defined semantics are | |||
essentially read-only; i.e., the client does not request, and does | essentially read-only; i.e., the client does not request, and does | |||
not expect, any state change on the origin server as a result of | not expect, any state change on the origin server as a result of | |||
applying a safe method to a target resource. Likewise, reasonable | applying a safe method to a target resource. Likewise, reasonable | |||
use of a safe method is not expected to cause any harm, loss of | use of a safe method is not expected to cause any harm, loss of | |||
property, or unusual burden on the origin server. | property, or unusual burden on the origin server. | |||
This definition of safe methods does not prevent an implementation | This definition of safe methods does not prevent an implementation | |||
from including behavior that is potentially harmful, that is not | from including behavior that is potentially harmful, that is not | |||
skipping to change at line 2895 ¶ | skipping to change at page 69, line 22 ¶ | |||
consistent with the request method semantics. For example, it is | consistent with the request method semantics. For example, it is | |||
common for Web-based content editing software to use actions within | common for Web-based content editing software to use actions within | |||
query parameters, such as "page?do=delete". If the purpose of such a | query parameters, such as "page?do=delete". If the purpose of such a | |||
resource is to perform an unsafe action, then the resource owner MUST | resource is to perform an unsafe action, then the resource owner MUST | |||
disable or disallow that action when it is accessed using a safe | disable or disallow that action when it is accessed using a safe | |||
request method. Failure to do so will result in unfortunate side | request method. Failure to do so will result in unfortunate side | |||
effects when automated processes perform a GET on every URI reference | effects when automated processes perform a GET on every URI reference | |||
for the sake of link maintenance, pre-fetching, building a search | for the sake of link maintenance, pre-fetching, building a search | |||
index, etc. | index, etc. | |||
4.2.2. Idempotent Methods | 7.2.2. Idempotent Methods | |||
A request method is considered "idempotent" if the intended effect on | A request method is considered "idempotent" if the intended effect on | |||
the server of multiple identical requests with that method is the | the server of multiple identical requests with that method is the | |||
same as the effect for a single such request. Of the request methods | same as the effect for a single such request. Of the request methods | |||
defined by this specification, PUT, DELETE, and safe request methods | defined by this specification, PUT, DELETE, and safe request methods | |||
are idempotent. | are idempotent. | |||
Like the definition of safe, the idempotent property only applies to | Like the definition of safe, the idempotent property only applies to | |||
what has been requested by the user; a server is free to log each | what has been requested by the user; a server is free to log each | |||
request separately, retain a revision control history, or implement | request separately, retain a revision control history, or implement | |||
skipping to change at line 2917 ¶ | skipping to change at page 69, line 44 ¶ | |||
Idempotent methods are distinguished because the request can be | Idempotent methods are distinguished because the request can be | |||
repeated automatically if a communication failure occurs before the | repeated automatically if a communication failure occurs before the | |||
client is able to read the server's response. For example, if a | client is able to read the server's response. For example, if a | |||
client sends a PUT request and the underlying connection is closed | client sends a PUT request and the underlying connection is closed | |||
before any response is received, then the client can establish a new | before any response is received, then the client can establish a new | |||
connection and retry the idempotent request. It knows that repeating | connection and retry the idempotent request. It knows that repeating | |||
the request will have the same intended effect, even if the original | the request will have the same intended effect, even if the original | |||
request succeeded, though the response might differ. | request succeeded, though the response might differ. | |||
A user agent MUST NOT automatically retry a request with a non- | A client SHOULD NOT automatically retry a request with a non- | |||
idempotent method unless it has some means to know that the request | idempotent method unless it has some means to know that the request | |||
semantics are actually idempotent, regardless of the method, or some | semantics are actually idempotent, regardless of the method, or some | |||
means to detect that the original request was never applied. | means to detect that the original request was never applied. | |||
For example, a user agent that knows (through design or | For example, a user agent that knows (through design or | |||
configuration) that a POST request to a given resource is safe can | configuration) that a POST request to a given resource is safe can | |||
repeat that request automatically. Likewise, a user agent designed | repeat that request automatically. Likewise, a user agent designed | |||
specifically to operate on a version control repository might be able | specifically to operate on a version control repository might be able | |||
to recover from partial failure conditions by checking the target | to recover from partial failure conditions by checking the target | |||
resource revision(s) after a failed connection, reverting or fixing | resource revision(s) after a failed connection, reverting or fixing | |||
any changes that were partially applied, and then automatically | any changes that were partially applied, and then automatically | |||
retrying the requests that failed. | retrying the requests that failed. | |||
Some clients use weaker signals to initiate automatic retries. For | ||||
example, when a POST request is sent, but the underlying transport | ||||
connection is closed before any part of the response is received. | ||||
Although this is commonly implemented, it is not recommended. | ||||
A proxy MUST NOT automatically retry non-idempotent requests. A | A proxy MUST NOT automatically retry non-idempotent requests. A | |||
client SHOULD NOT automatically retry a failed automatic retry. | client SHOULD NOT automatically retry a failed automatic retry. | |||
7.2.3. Methods and Caching | 7.2.3. Methods and Caching | |||
Request methods can be defined as "cacheable" to indicate that | For a cache to store and use a response, the associated method needs | |||
responses to them are allowed to be stored for future reuse; for | to explicitly allow caching, and detail under what conditions a | |||
specific requirements see [RFC7234]. In general, safe methods that | response can be used to satisfy subsequent requests; a method | |||
do not depend on a current or authoritative response are defined as | definition which does not do so cannot be cached. For additional | |||
cacheable; this specification defines GET, HEAD, and POST as | requirements see [Caching]. | |||
cacheable, although the overwhelming majority of cache | ||||
implementations only support GET and HEAD. | ||||
4.3. Method Definitions | This specification defines caching semantics for GET, HEAD, and POST, | |||
although the overwhelming majority of cache implementations only | ||||
support GET and HEAD. | ||||
4.3.1. GET | 7.3. Method Definitions | |||
7.3.1. GET | ||||
The GET method requests transfer of a current selected representation | The GET method requests transfer of a current selected representation | |||
for the target resource. GET is the primary mechanism of information | for the target resource. GET is the primary mechanism of information | |||
retrieval and the focus of almost all performance optimizations. | retrieval and the focus of almost all performance optimizations. | |||
Hence, when people speak of retrieving some identifiable information | Hence, when people speak of retrieving some identifiable information | |||
via HTTP, they are generally referring to making a GET request. | via HTTP, they are generally referring to making a GET request. | |||
It is tempting to think of resource identifiers as remote file system | It is tempting to think of resource identifiers as remote file system | |||
pathnames and of representations as being a copy of the contents of | pathnames and of representations as being a copy of the contents of | |||
such files. In fact, that is how many resources are implemented (see | such files. In fact, that is how many resources are implemented (see | |||
Section 9.1 for related security considerations). However, there are | Section 13.3 for related security considerations). However, there | |||
no such limitations in practice. The HTTP interface for a resource | are no such limitations in practice. The HTTP interface for a | |||
is just as likely to be implemented as a tree of content objects, a | resource is just as likely to be implemented as a tree of content | |||
programmatic view on various database records, or a gateway to other | objects, a programmatic view on various database records, or a | |||
information systems. Even when the URI mapping mechanism is tied to | gateway to other information systems. Even when the URI mapping | |||
a file system, an origin server might be configured to execute the | mechanism is tied to a file system, an origin server might be | |||
files with the request as input and send the output as the | configured to execute the files with the request as input and send | |||
representation rather than transfer the files directly. Regardless, | the output as the representation rather than transfer the files | |||
only the origin server needs to know how each of its resource | directly. Regardless, only the origin server needs to know how each | |||
identifiers corresponds to an implementation and how each | of its resource identifiers corresponds to an implementation and how | |||
implementation manages to select and send a current representation of | each implementation manages to select and send a current | |||
the target resource in a response to GET. | representation of the target resource in a response to GET. | |||
A client can alter the semantics of GET to be a "range request", | A client can alter the semantics of GET to be a "range request", | |||
requesting transfer of only some part(s) of the selected | requesting transfer of only some part(s) of the selected | |||
representation, by sending a Range header field in the request | representation, by sending a Range header field in the request | |||
([RFC7233]). | (Section 8.3). | |||
A payload within a GET request message has no defined semantics; | The GET method is specifically intended to reflect the quality of | |||
sending a payload body on a GET request might cause some existing | "sameness" identified by the request URI as if it were referenced as | |||
implementations to reject the request. | an ordinary hypertext link. A client SHOULD NOT generate a body in a | |||
GET request. A payload received in a GET request has no defined | ||||
semantics, cannot alter the meaning or target of the request, and | ||||
might lead some implementations to reject the request and close the | ||||
connection because of its potential as a request smuggling attack | ||||
(Section 11.2 of [Messaging]). | ||||
The response to a GET request is cacheable; a cache MAY use it to | The response to a GET request is cacheable; a cache MAY use it to | |||
satisfy subsequent GET and HEAD requests unless otherwise indicated | satisfy subsequent GET and HEAD requests unless otherwise indicated | |||
by the Cache-Control header field (Section 5.2 of [RFC7234]). | by the Cache-Control header field (Section 5.2 of [Caching]). A | |||
cache that receives a payload in a GET request is likely to ignore | ||||
that payload and cache regardless of the payload contents. | ||||
4.3.2. HEAD | 7.3.2. HEAD | |||
The HEAD method is identical to GET except that the server MUST NOT | 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 | 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 | 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 | 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 | the request had been a GET, except that the payload header fields | |||
(Section 3.3) MAY be omitted. This method can be used for obtaining | (Section 6.3) MAY be omitted. This method can be used for obtaining | |||
metadata about the selected representation without transferring the | metadata about the selected representation without transferring the | |||
representation data and is often used for testing hypertext links for | representation data and is often used for testing hypertext links for | |||
validity, accessibility, and recent modification. | validity, accessibility, and recent modification. | |||
A payload within a HEAD request message has no defined semantics; | A payload within a HEAD request message has no defined semantics; | |||
sending a payload body on a HEAD request might cause some existing | sending a payload body on a HEAD request might cause some existing | |||
implementations to reject the request. | implementations to reject the request. | |||
The response to a HEAD request is cacheable; a cache MAY use it to | The response to a HEAD request is cacheable; a cache MAY use it to | |||
satisfy subsequent HEAD requests unless otherwise indicated by the | satisfy subsequent HEAD requests unless otherwise indicated by the | |||
Cache-Control header field (Section 5.2 of [RFC7234]). A HEAD | Cache-Control header field (Section 5.2 of [Caching]). A HEAD | |||
response might also have an effect on previously cached responses to | response might also have an effect on previously cached responses to | |||
GET; see Section 4.3.5 of [RFC7234]. | GET; see Section 4.3.5 of [Caching]. | |||
4.3.3. POST | 7.3.3. POST | |||
The POST method requests that the target resource process the | The POST method requests that the target resource process the | |||
representation enclosed in the request according to the resource's | representation enclosed in the request according to the resource's | |||
own specific semantics. For example, POST is used for the following | own specific semantics. For example, POST is used for the following | |||
functions (among others): | functions (among others): | |||
o Providing a block of data, such as the fields entered into an HTML | o Providing a block of data, such as the fields entered into an HTML | |||
form, to a data-handling process; | form, to a data-handling process; | |||
o Posting a message to a bulletin board, newsgroup, mailing list, | o Posting a message to a bulletin board, newsgroup, mailing list, | |||
skipping to change at line 3034 ¶ | skipping to change at page 72, line 34 ¶ | |||
appropriate status code depending on the result of processing the | appropriate status code depending on the result of processing the | |||
POST request; almost all of the status codes defined by this | POST request; almost all of the status codes defined by this | |||
specification might be received in a response to POST (the exceptions | specification might be received in a response to POST (the exceptions | |||
being 206 (Partial Content), 304 (Not Modified), and 416 (Range Not | being 206 (Partial Content), 304 (Not Modified), and 416 (Range Not | |||
Satisfiable)). | Satisfiable)). | |||
If one or more resources has been created on the origin server as a | If one or more resources has been created on the origin server as a | |||
result of successfully processing a POST request, the origin server | result of successfully processing a POST request, the origin server | |||
SHOULD send a 201 (Created) response containing a Location header | SHOULD send a 201 (Created) response containing a Location header | |||
field that provides an identifier for the primary resource created | field that provides an identifier for the primary resource created | |||
(Section 7.1.2) and a representation that describes the status of the | (Section 10.1.2) and a representation that describes the status of | |||
request while referring to the new resource(s). | the request while referring to the new resource(s). | |||
Responses to POST requests are only cacheable when they include | Responses to POST requests are only cacheable when they include | |||
explicit freshness information (see Section 4.2.1 of [RFC7234]). | explicit freshness information (see Section 4.2.1 of [Caching]) and a | |||
However, POST caching is not widely implemented. For cases where an | ||||
origin server wishes 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 and a | ||||
Content-Location header field that has the same value as the POST's | Content-Location header field that has the same value as the POST's | |||
effective request URI (Section 3.1.4.2). | effective request URI (Section 6.2.5). A cached POST response can be | |||
reused to satisfy a later GET or HEAD request, but not a POST | ||||
request, since POST is required to be written through to the origin | ||||
server, because it is unsafe; see Section 4 of [Caching]. | ||||
If the result of processing a POST would be equivalent to a | If the result of processing a POST would be equivalent to a | |||
representation of an existing resource, an origin server MAY redirect | representation of an existing resource, an origin server MAY redirect | |||
the user agent to that resource by sending a 303 (See Other) response | the user agent to that resource by sending a 303 (See Other) response | |||
with the existing resource's identifier in the Location field. This | with the existing resource's identifier in the Location field. This | |||
has the benefits of providing the user agent a resource identifier | has the benefits of providing the user agent a resource identifier | |||
and transferring the representation via a method more amenable to | and transferring the representation via a method more amenable to | |||
shared caching, though at the cost of an extra request if the user | shared caching, though at the cost of an extra request if the user | |||
agent does not already have the representation cached. | agent does not already have the representation cached. | |||
4.3.4. PUT | 7.3.4. PUT | |||
The PUT method requests that the state of the target resource be | The PUT method requests that the state of the target resource be | |||
created or replaced with the state defined by the representation | created or replaced with the state defined by the representation | |||
enclosed in the request message payload. A successful PUT of a given | enclosed in the request message payload. A successful PUT of a given | |||
representation would suggest that a subsequent GET on that same | representation would suggest that a subsequent GET on that same | |||
target resource will result in an equivalent representation being | target resource will result in an equivalent representation being | |||
sent in a 200 (OK) response. However, there is no guarantee that | sent in a 200 (OK) response. However, there is no guarantee that | |||
such a state change will be observable, since the target resource | such a state change will be observable, since the target resource | |||
might be acted upon by other user agents in parallel, or might be | might be acted upon by other user agents in parallel, or might be | |||
subject to dynamic processing by the origin server, before any | subject to dynamic processing by the origin server, before any | |||
skipping to change at line 3122 ¶ | skipping to change at page 74, line 24 ¶ | |||
agent request and the semantics of the origin server response. It | agent request and the semantics of the origin server response. It | |||
does not define what a resource might be, in any sense of that word, | does not define what a resource might be, in any sense of that word, | |||
beyond the interface provided via HTTP. It does not define how | beyond the interface provided via HTTP. It does not define how | |||
resource state is "stored", nor how such storage might change as a | resource state is "stored", nor how such storage might change as a | |||
result of a change in resource state, nor how the origin server | result of a change in resource state, nor how the origin server | |||
translates resource state into representations. Generally speaking, | translates resource state into representations. Generally speaking, | |||
all implementation details behind the resource interface are | all implementation details behind the resource interface are | |||
intentionally hidden by the server. | intentionally hidden by the server. | |||
An origin server MUST NOT send a validator header field | An origin server MUST NOT send a validator header field | |||
(Section 7.2), such as an ETag or Last-Modified field, in a | (Section 10.2), such as an ETag or Last-Modified field, in a | |||
successful response to PUT unless the request's representation data | successful response to PUT unless the request's representation data | |||
was saved without any transformation applied to the body (i.e., the | was saved without any transformation applied to the body (i.e., the | |||
resource's new representation data is identical to the representation | resource's new representation data is identical to the representation | |||
data received in the PUT request) and the validator field value | data received in the PUT request) and the validator field value | |||
reflects the new representation. This requirement allows a user | reflects the new representation. This requirement allows a user | |||
agent to know when the representation body it has in memory remains | agent to know when the representation body it has in memory remains | |||
current as a result of the PUT, thus not in need of being retrieved | current as a result of the PUT, thus not in need of being retrieved | |||
again from the origin server, and that the new validator(s) received | again from the origin server, and that the new validator(s) received | |||
in the response can be used for future conditional requests in order | in the response can be used for future conditional requests in order | |||
to prevent accidental overwrites (Section 5.2). | to prevent accidental overwrites (Section 8.2). | |||
The fundamental difference between the POST and PUT methods is | The fundamental difference between the POST and PUT methods is | |||
highlighted by the different intent for the enclosed representation. | highlighted by the different intent for the enclosed representation. | |||
The target resource in a POST request is intended to handle the | The target resource in a POST request is intended to handle the | |||
enclosed representation according to the resource's own semantics, | enclosed representation according to the resource's own semantics, | |||
whereas the enclosed representation in a PUT request is defined as | whereas the enclosed representation in a PUT request is defined as | |||
replacing the state of the target resource. Hence, the intent of PUT | replacing the state of the target resource. Hence, the intent of PUT | |||
is idempotent and visible to intermediaries, even though the exact | is idempotent and visible to intermediaries, even though the exact | |||
effect is only known by the origin server. | effect is only known by the origin server. | |||
skipping to change at line 3166 ¶ | skipping to change at page 75, line 20 ¶ | |||
identifying "the current version" (a resource) that is separate from | identifying "the current version" (a resource) that is separate from | |||
the URIs identifying each particular version (different resources | the URIs identifying each particular version (different resources | |||
that at one point shared the same state as the current version | that at one point shared the same state as the current version | |||
resource). A successful PUT request on "the current version" URI | resource). A successful PUT request on "the current version" URI | |||
might therefore create a new version resource in addition to changing | might therefore create a new version resource in addition to changing | |||
the state of the target resource, and might also cause links to be | the state of the target resource, and might also cause links to be | |||
added between the related resources. | added between the related resources. | |||
An origin server that allows PUT on a given target resource MUST send | An origin server that allows PUT on a given target resource MUST send | |||
a 400 (Bad Request) response to a PUT request that contains a | a 400 (Bad Request) response to a PUT request that contains a | |||
Content-Range header field (Section 4.2 of [RFC7233]), since the | Content-Range header field (Section 6.3.4), since the payload is | |||
payload is likely to be partial content that has been mistakenly PUT | likely to be partial content that has been mistakenly PUT as a full | |||
as a full representation. Partial content updates are possible by | representation. Partial content updates are possible by targeting a | |||
targeting a separately identified resource with state that overlaps a | separately identified resource with state that overlaps a portion of | |||
portion of the larger resource, or by using a different method that | the larger resource, or by using a different method that has been | |||
has been specifically defined for partial updates (for example, the | specifically defined for partial updates (for example, the PATCH | |||
PATCH method defined in [RFC5789]). | method defined in [RFC5789]). | |||
Responses to the PUT method are not cacheable. If a successful PUT | Responses to the PUT method are not cacheable. If a successful PUT | |||
request passes through a cache that has one or more stored responses | request passes through a cache that has one or more stored responses | |||
for the effective request URI, those stored responses will be | for the effective request URI, those stored responses will be | |||
invalidated (see Section 4.4 of [RFC7234]). | invalidated (see Section 4.4 of [Caching]). | |||
4.3.5. DELETE | 7.3.5. DELETE | |||
The DELETE method requests that the origin server remove the | The DELETE method requests that the origin server remove the | |||
association between the target resource and its current | association between the target resource and its current | |||
functionality. In effect, this method is similar to the rm command | functionality. In effect, this method is similar to the rm command | |||
in UNIX: it expresses a deletion operation on the URI mapping of the | in UNIX: it expresses a deletion operation on the URI mapping of the | |||
origin server rather than an expectation that the previously | origin server rather than an expectation that the previously | |||
associated information be deleted. | associated information be deleted. | |||
If the target resource has one or more current representations, they | If the target resource has one or more current representations, they | |||
might or might not be destroyed by the origin server, and the | might or might not be destroyed by the origin server, and the | |||
skipping to change at line 3212 ¶ | skipping to change at page 76, line 18 ¶ | |||
previously created using a PUT request, or identified via the | previously created using a PUT request, or identified via the | |||
Location header field after a 201 (Created) response to a POST | Location header field after a 201 (Created) response to a POST | |||
request, might allow a corresponding DELETE request to undo those | request, might allow a corresponding DELETE request to undo those | |||
actions. Similarly, custom user agent implementations that implement | actions. Similarly, custom user agent implementations that implement | |||
an authoring function, such as revision control clients using HTTP | an authoring function, such as revision control clients using HTTP | |||
for remote operations, might use DELETE based on an assumption that | for remote operations, might use DELETE based on an assumption that | |||
the server's URI space has been crafted to correspond to a version | the server's URI space has been crafted to correspond to a version | |||
repository. | repository. | |||
If a DELETE method is successfully applied, the origin server SHOULD | If a DELETE method is successfully applied, the origin server SHOULD | |||
send a 202 (Accepted) status code if the action will likely succeed | send | |||
but has not yet been enacted, a 204 (No Content) status code if the | ||||
action has been enacted and no further information is to be supplied, | o a 202 (Accepted) status code if the action will likely succeed but | |||
or a 200 (OK) status code if the action has been enacted and the | has not yet been enacted, | |||
response message includes a representation describing the status. | ||||
o a 204 (No Content) status code if the action has been enacted and | ||||
no further information is to be supplied, or | ||||
o a 200 (OK) status code if the action has been enacted and the | ||||
response message includes a representation describing the status. | ||||
A payload within a DELETE request message has no defined semantics; | A payload within a DELETE request message has no defined semantics; | |||
sending a payload body on a DELETE request might cause some existing | sending a payload body on a DELETE request might cause some existing | |||
implementations to reject the request. | implementations to reject the request. | |||
Responses to the DELETE method are not cacheable. If a DELETE | Responses to the DELETE method are not cacheable. If a successful | |||
request passes through a cache that has one or more stored responses | DELETE request passes through a cache that has one or more stored | |||
for the effective request URI, those stored responses will be | responses for the effective request URI, those stored responses will | |||
invalidated (see Section 4.4 of [RFC7234]). | be invalidated (see Section 4.4 of [Caching]). | |||
4.3.6. CONNECT | 7.3.6. CONNECT | |||
The CONNECT method requests that the recipient establish a tunnel to | The CONNECT method requests that the recipient establish a tunnel to | |||
the destination origin server identified by the request-target and, | the destination origin server identified by the request-target and, | |||
if successful, thereafter restrict its behavior to blind forwarding | if successful, thereafter restrict its behavior to blind forwarding | |||
of packets, in both directions, until the tunnel is closed. Tunnels | of packets, in both directions, until the tunnel is closed. Tunnels | |||
are commonly used to create an end-to-end virtual connection, through | are commonly used to create an end-to-end virtual connection, through | |||
one or more proxies, which can then be secured using TLS (Transport | one or more proxies, which can then be secured using TLS (Transport | |||
Layer Security, [RFC5246]). | Layer Security, [RFC8446]). | |||
CONNECT is intended only for use in requests to a proxy. An origin | CONNECT is intended only for use in requests to a proxy. An origin | |||
server that receives a CONNECT request for itself MAY respond with a | server that receives a CONNECT request for itself MAY respond with a | |||
2xx (Successful) status code to indicate that a connection is | 2xx (Successful) status code to indicate that a connection is | |||
established. However, most origin servers do not implement CONNECT. | established. However, most origin servers do not implement CONNECT. | |||
A client sending a CONNECT request MUST send the authority form of | A client sending a CONNECT request MUST send the authority form of | |||
request-target (Section 5.3 of [RFC7230]); i.e., the request-target | request-target (Section 3.2 of [Messaging]); i.e., the request-target | |||
consists of only the host name and port number of the tunnel | consists of only the host name and port number of the tunnel | |||
destination, separated by a colon. For example, | destination, separated by a colon. For example, | |||
CONNECT server.example.com:80 HTTP/1.1 | CONNECT server.example.com:80 HTTP/1.1 | |||
Host: server.example.com:80 | Host: server.example.com:80 | |||
The recipient proxy can establish a tunnel either by directly | The recipient proxy can establish a tunnel either by directly | |||
connecting to the request-target or, if configured to use another | connecting to the request-target or, if configured to use another | |||
proxy, by forwarding the CONNECT request to the next inbound proxy. | proxy, by forwarding the CONNECT request to the next inbound proxy. | |||
Any 2xx (Successful) response indicates that the sender (and all | Any 2xx (Successful) response indicates that the sender (and all | |||
skipping to change at line 3294 ¶ | skipping to change at page 78, line 11 ¶ | |||
fields in a 2xx (Successful) response to CONNECT. A client MUST | fields in a 2xx (Successful) response to CONNECT. A client MUST | |||
ignore any Content-Length or Transfer-Encoding header fields received | ignore any Content-Length or Transfer-Encoding header fields received | |||
in a successful response to CONNECT. | in a successful response to CONNECT. | |||
A payload within a CONNECT request message has no defined semantics; | A payload within a CONNECT request message has no defined semantics; | |||
sending a payload body on a CONNECT request might cause some existing | sending a payload body on a CONNECT request might cause some existing | |||
implementations to reject the request. | implementations to reject the request. | |||
Responses to the CONNECT method are not cacheable. | Responses to the CONNECT method are not cacheable. | |||
4.3.7. OPTIONS | 7.3.7. OPTIONS | |||
The OPTIONS method requests information about the communication | The OPTIONS method requests information about the communication | |||
options available for the target resource, at either the origin | options available for the target resource, at either the origin | |||
server or an intervening intermediary. This method allows a client | server or an intervening intermediary. This method allows a client | |||
to determine the options and/or requirements associated with a | to determine the options and/or requirements associated with a | |||
resource, or the capabilities of a server, without implying a | resource, or the capabilities of a server, without implying a | |||
resource action. | resource action. | |||
An OPTIONS request with an asterisk ("*") as the request-target | An OPTIONS request with an asterisk ("*") as the request-target | |||
(Section 5.3 of [RFC7230]) applies to the server in general rather | (Section 3.2 of [Messaging]) applies to the server in general rather | |||
than to a specific resource. Since a server's communication options | than to a specific resource. Since a server's communication options | |||
typically depend on the resource, the "*" request is only useful as a | typically depend on the resource, the "*" request is only useful as a | |||
"ping" or "no-op" type of method; it does nothing beyond allowing the | "ping" or "no-op" type of method; it does nothing beyond allowing the | |||
client to test the capabilities of the server. For example, this can | client to test the capabilities of the server. For example, this can | |||
be used to test a proxy for HTTP/1.1 conformance (or lack thereof). | 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 | If the request-target is not an asterisk, the OPTIONS request applies | |||
to the options that are available when communicating with the target | to the options that are available when communicating with the target | |||
resource. | resource. | |||
A server generating a successful response to OPTIONS SHOULD send any | A server generating a successful response to OPTIONS SHOULD send any | |||
header fields that might indicate optional features implemented by | header fields that might indicate optional features implemented by | |||
the server and applicable to the target resource (e.g., Allow), | the server and applicable to the target resource (e.g., Allow), | |||
including potential extensions not defined by this specification. | including potential extensions not defined by this specification. | |||
The response payload, if any, might also describe the communication | The response payload, if any, might also describe the communication | |||
options in a machine or human-readable representation. A standard | options in a machine or human-readable representation. A standard | |||
format for such a representation is not defined by this | format for such a representation is not defined by this | |||
specification, but might be defined by future extensions to HTTP. A | specification, but might be defined by future extensions to HTTP. | |||
server MUST generate a Content-Length field with a value of "0" if no | ||||
payload body is to be sent in the response. | ||||
A client MAY send a Max-Forwards header field in an OPTIONS request | A client MAY send a Max-Forwards header field in an OPTIONS request | |||
to target a specific recipient in the request chain (see | to target a specific recipient in the request chain (see | |||
Section 5.1.2). A proxy MUST NOT generate a Max-Forwards header | Section 8.1.2). A proxy MUST NOT generate a Max-Forwards header | |||
field while forwarding a request unless that request was received | field while forwarding a request unless that request was received | |||
with a Max-Forwards field. | with a Max-Forwards field. | |||
A client that generates an OPTIONS request containing a payload body | A client that generates an OPTIONS request containing a payload body | |||
MUST send a valid Content-Type header field describing the | MUST send a valid Content-Type header field describing the | |||
representation media type. Although this specification does not | representation media type. Note that this specification does not | |||
define any use for such a payload, future extensions to HTTP might | define any use for such a payload. | |||
use the OPTIONS body to make more detailed queries about the target | ||||
resource. | ||||
Responses to the OPTIONS method are not cacheable. | Responses to the OPTIONS method are not cacheable. | |||
4.3.8. TRACE | 7.3.8. TRACE | |||
The TRACE method requests a remote, application-level loop-back of | The TRACE method requests a remote, application-level loop-back of | |||
the request message. The final recipient of the request SHOULD | the request message. The final recipient of the request SHOULD | |||
reflect the message received, excluding some fields described below, | reflect the message received, excluding some fields described below, | |||
back to the client as the message body of a 200 (OK) response with a | back to the client as the message body of a 200 (OK) response with a | |||
Content-Type of "message/http" (Section 8.3.1 of [RFC7230]). The | Content-Type of "message/http" (Section 10.1 of [Messaging]). The | |||
final recipient is either the origin server or the first server to | final recipient is either the origin server or the first server to | |||
receive a Max-Forwards value of zero (0) in the request | receive a Max-Forwards value of zero (0) in the request | |||
(Section 5.1.2). | (Section 8.1.2). | |||
A client MUST NOT generate header fields in a TRACE request | A client MUST NOT generate header fields in a TRACE request | |||
containing sensitive data that might be disclosed by the response. | containing sensitive data that might be disclosed by the response. | |||
For example, it would be foolish for a user agent to send stored user | For example, it would be foolish for a user agent to send stored user | |||
credentials [RFC7235] or cookies [RFC6265] in a TRACE request. The | credentials Section 8.5 or cookies [RFC6265] in a TRACE request. The | |||
final recipient of the request SHOULD exclude any request header | final recipient of the request SHOULD exclude any request header | |||
fields that are likely to contain sensitive data when that recipient | fields that are likely to contain sensitive data when that recipient | |||
generates the response body. | generates the response body. | |||
TRACE allows the client to see what is being received at the other | TRACE allows the client to see what is being received at the other | |||
end of the request chain and use that data for testing or diagnostic | end of the request chain and use that data for testing or diagnostic | |||
information. The value of the Via header field (Section 5.7.1 of | information. The value of the Via header field (Section 5.5.1) is of | |||
[RFC7230]) is of particular interest, since it acts as a trace of the | particular interest, since it acts as a trace of the request chain. | |||
request chain. Use of the Max-Forwards header field allows the | Use of the Max-Forwards header field allows the client to limit the | |||
client to limit the length of the request chain, which is useful for | length of the request chain, which is useful for testing a chain of | |||
testing a chain of proxies forwarding messages in an infinite loop. | proxies forwarding messages in an infinite loop. | |||
A client MUST NOT send a message body in a TRACE request. | A client MUST NOT send a message body in a TRACE request. | |||
Responses to the TRACE method are not cacheable. | Responses to the TRACE method are not cacheable. | |||
X.X. [Method Extensibility] | 7.4. Method Extensibility | |||
Additional methods, outside the scope of this specification, have | Additional methods, outside the scope of this specification, have | |||
been standardized for use in HTTP. All such methods ought to be | been specified for use in HTTP. All such methods ought to be | |||
registered within the "Hypertext Transfer Protocol (HTTP) Method | registered within the "Hypertext Transfer Protocol (HTTP) Method | |||
Registry" maintained by IANA, as defined in Section 8.1. | Registry". | |||
8.1. Method Registry | ||||
The "Hypertext Transfer Protocol (HTTP) Method Registry" defines the | 7.4.1. Method Registry | |||
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 | The "Hypertext Transfer Protocol (HTTP) Method Registry", maintained | |||
by IANA at <https://www.iana.org/assignments/http-methods>, registers | ||||
method names. | ||||
HTTP method registrations MUST include the following fields: | HTTP method registrations MUST include the following fields: | |||
o Method Name (see Section 4) | o Method Name (see Section 7) | |||
o Safe ("yes" or "no", see Section 7.2.1) | ||||
o Safe ("yes" or "no", see Section 4.2.1) | ||||
o Idempotent ("yes" or "no", see Section 4.2.2) | o Idempotent ("yes" or "no", see Section 7.2.2) | |||
o Pointer to specification text | o Pointer to specification text | |||
Values to be added to this namespace require IETF Review (see | Values to be added to this namespace require IETF Review (see | |||
[RFC5226], Section 4.1). | [RFC8126], Section 4.8). | |||
8.1.2. Considerations for New Methods | 7.4.2. Considerations for New Methods | |||
Standardized methods are generic; that is, they are potentially | Standardized methods are generic; that is, they are potentially | |||
applicable to any resource, not just one particular media type, kind | applicable to any resource, not just one particular media type, kind | |||
of resource, or application. As such, it is preferred that new | of resource, or application. As such, it is preferred that new | |||
methods be registered in a document that isn't specific to a single | methods be registered in a document that isn't specific to a single | |||
application or data format, since orthogonal technologies deserve | application or data format, since orthogonal technologies deserve | |||
orthogonal specification. | orthogonal specification. | |||
Since message parsing (Section 3.3 of [RFC7230]) needs to be | Since message parsing (Section 6 of [Messaging]) needs to be | |||
independent of method semantics (aside from responses to HEAD), | independent of method semantics (aside from responses to HEAD), | |||
definitions of new methods cannot change the parsing algorithm or | definitions of new methods cannot change the parsing algorithm or | |||
prohibit the presence of a message body on either the request or the | prohibit the presence of a message body on either the request or the | |||
response message. Definitions of new methods can specify that only a | response message. Definitions of new methods can specify that only a | |||
zero-length message body is allowed by requiring a Content-Length | zero-length message body is allowed by requiring a Content-Length | |||
header field with a value of "0". | header field with a value of "0". | |||
A new method definition needs to indicate whether it is safe | A new method definition needs to indicate whether it is safe | |||
(Section 4.2.1), idempotent (Section 4.2.2), cacheable | (Section 7.2.1), idempotent (Section 7.2.2), cacheable | |||
(Section 4.2.3), what semantics are to be associated with the payload | (Section 7.2.3), what semantics are to be associated with the payload | |||
body if any is present in the request and what refinements the method | body if any is present in the request and what refinements the method | |||
makes to header field or status code semantics. If the new method is | makes to header field or status code semantics. If the new method is | |||
cacheable, its definition ought to describe how, and under what | cacheable, its definition ought to describe how, and under what | |||
conditions, a cache can store a response and use it to satisfy a | conditions, a cache can store a response and use it to satisfy a | |||
subsequent request. The new method ought to describe whether it can | subsequent request. The new method ought to describe whether it can | |||
be made conditional (Section 5.2) and, if so, how a server responds | be made conditional (Section 8.2) and, if so, how a server responds | |||
when the condition is false. Likewise, if the new method might have | when the condition is false. Likewise, if the new method might have | |||
some use for partial response semantics ([RFC7233]), it ought to | some use for partial response semantics (Section 8.3), it ought to | |||
document this, too. | document this, too. | |||
Note: Avoid defining a method name that starts with "M-", since | Note: Avoid defining a method name that starts with "M-", since | |||
that prefix might be misinterpreted as having the semantics | that prefix might be misinterpreted as having the semantics | |||
assigned to it by [RFC2774]. | assigned to it by [RFC2774]. | |||
5. Request Header Fields | 8. Request Header Fields | |||
A client sends request header fields to provide more information | A client sends request header fields to provide more information | |||
about the request context, make the request conditional based on the | about the request context, make the request conditional based on the | |||
target resource state, suggest preferred formats for the response, | target resource state, suggest preferred formats for the response, | |||
supply authentication credentials, or modify the expected request | supply authentication credentials, or modify the expected request | |||
processing. These fields act as request modifiers, similar to the | processing. These fields act as request modifiers, similar to the | |||
parameters on a programming language method invocation. | parameters on a programming language method invocation. | |||
5.1. Controls | 8.1. Controls | |||
Controls are request header fields that direct specific handling of | Controls are request header fields that direct specific handling of | |||
the request. | the request. | |||
+-------------------+--------------------------+ | +-------------------+----------------------------+ | |||
| Header Field Name | Defined in... | | | Header Field Name | Defined in... | | |||
+-------------------+--------------------------+ | +-------------------+----------------------------+ | |||
| Cache-Control | Section 5.2 of [RFC7234] | | | Cache-Control | Section 5.2 of [Caching] | | |||
| Expect | Section 5.1.1 | | | Expect | Section 8.1.1 | | |||
| Host | Section 5.4 of [RFC7230] | | | Host | Section 5.4 | | |||
| Max-Forwards | Section 5.1.2 | | | Max-Forwards | Section 8.1.2 | | |||
| Pragma | Section 5.4 of [RFC7234] | | | Pragma | Section 5.4 of [Caching] | | |||
| Range | Section 3.1 of [RFC7233] | | | TE | Section 7.4 of [Messaging] | | |||
| TE | Section 4.3 of [RFC7230] | | +-------------------+----------------------------+ | |||
+-------------------+--------------------------+ | ||||
5.1.1. Expect | 8.1.1. Expect | |||
The "Expect" header field in a request indicates a certain set of | The "Expect" header field in a request indicates a certain set of | |||
behaviors (expectations) that need to be supported by the server in | behaviors (expectations) that need to be supported by the server in | |||
order to properly handle this request. The only such expectation | order to properly handle this request. The only such expectation | |||
defined by this specification is 100-continue. | defined by this specification is 100-continue. | |||
Expect = "100-continue" | Expect = "100-continue" | |||
The Expect field-value is case-insensitive. | The Expect field-value is case-insensitive. | |||
A server that receives an Expect field-value other than 100-continue | A server that receives an Expect field-value other than 100-continue | |||
MAY respond with a 417 (Expectation Failed) status code to indicate | MAY respond with a 417 (Expectation Failed) status code to indicate | |||
that the unexpected expectation cannot be met. | that the unexpected expectation cannot be met. | |||
A 100-continue expectation informs recipients that the client is | A 100-continue expectation informs recipients that the client is | |||
about to send a (presumably large) message body in this request and | about to send a (presumably large) message body in this request and | |||
wishes to receive a 100 (Continue) interim response if the | wishes to receive a 100 (Continue) interim response if the request- | |||
request-line and header fields are not sufficient to cause an | line and header fields are not sufficient to cause an immediate | |||
immediate success, redirect, or error response. This allows the | success, redirect, or error response. This allows the client to wait | |||
client to wait for an indication that it is worthwhile to send the | for an indication that it is worthwhile to send the message body | |||
message body before actually doing so, which can improve efficiency | before actually doing so, which can improve efficiency when the | |||
when the message body is huge or when the client anticipates that an | message body is huge or when the client anticipates that an error is | |||
error is likely (e.g., when sending a state-changing method, for the | likely (e.g., when sending a state-changing method, for the first | |||
first time, without previously verified authentication credentials). | time, without previously verified authentication credentials). | |||
For example, a request that begins with | For example, a request that begins with | |||
PUT /somewhere/fun HTTP/1.1 | PUT /somewhere/fun HTTP/1.1 | |||
Host: origin.example.com | Host: origin.example.com | |||
Content-Type: video/h264 | Content-Type: video/h264 | |||
Content-Length: 1234567890987 | Content-Length: 1234567890987 | |||
Expect: 100-continue | Expect: 100-continue | |||
allows the origin server to immediately respond with an error | allows the origin server to immediately respond with an error | |||
message, such as 401 (Unauthorized) or 405 (Method Not Allowed), | message, such as 401 (Unauthorized) or 405 (Method Not Allowed), | |||
before the client starts filling the pipes with an unnecessary data | before the client starts filling the pipes with an unnecessary data | |||
transfer. | transfer. | |||
skipping to change at line 3537 ¶ | skipping to change at page 83, line 6 ¶ | |||
o A server MAY omit sending a 100 (Continue) response if it has | o A server MAY omit sending a 100 (Continue) response if it has | |||
already received some or all of the message body for the | already received some or all of the message body for the | |||
corresponding request, or if the framing indicates that there is | corresponding request, or if the framing indicates that there is | |||
no message body. | no message body. | |||
o A server that sends a 100 (Continue) response MUST ultimately send | o A server that sends a 100 (Continue) response MUST ultimately send | |||
a final status code, once the message body is received and | a final status code, once the message body is received and | |||
processed, unless the connection is closed prematurely. | processed, unless the connection is closed prematurely. | |||
o A server that responds with a final status code before reading the | o A server that responds with a final status code before reading the | |||
entire message body SHOULD indicate in that response whether it | entire request payload body SHOULD indicate whether it intends to | |||
intends to close the connection or continue reading and discarding | close the connection (see Section 9.7 of [Messaging]) or continue | |||
the request message (see Section 6.6 of [RFC7230]). | reading the payload body. | |||
An origin server MUST, upon receiving an HTTP/1.1 (or later) | An origin server MUST, upon receiving an HTTP/1.1 (or later) request- | |||
request-line and a complete header section that contains a | line and a complete header section that contains a 100-continue | |||
100-continue expectation and indicates a request message body will | expectation and indicates a request message body will follow, either | |||
follow, either send an immediate response with a final status code, | send an immediate response with a final status code, if that status | |||
if that status can be determined by examining just the request-line | can be determined by examining just the request-line and header | |||
and header fields, or send an immediate 100 (Continue) response to | fields, or send an immediate 100 (Continue) response to encourage the | |||
encourage the client to send the request's message body. The origin | client to send the request's message body. The origin server MUST | |||
server MUST NOT wait for the message body before sending the 100 | NOT wait for the message body before sending the 100 (Continue) | |||
(Continue) response. | response. | |||
A proxy MUST, upon receiving an HTTP/1.1 (or later) request-line and | A proxy MUST, upon receiving an HTTP/1.1 (or later) request-line and | |||
a complete header section that contains a 100-continue expectation | a complete header section that contains a 100-continue expectation | |||
and indicates a request message body will follow, either send an | and indicates a request message body will follow, either send an | |||
immediate response with a final status code, if that status can be | immediate response with a final status code, if that status can be | |||
determined by examining just the request-line and header fields, or | determined by examining just the request-line and header fields, or | |||
begin forwarding the request toward the origin server by sending a | begin forwarding the request toward the origin server by sending a | |||
corresponding request-line and header section to the next inbound | corresponding request-line and header section to the next inbound | |||
server. If the proxy believes (from configuration or past | server. If the proxy believes (from configuration or past | |||
interaction) that the next inbound server only supports HTTP/1.0, the | interaction) that the next inbound server only supports HTTP/1.0, the | |||
skipping to change at line 3573 ¶ | skipping to change at page 83, line 42 ¶ | |||
Note: The Expect header field was added after the original | Note: The Expect header field was added after the original | |||
publication of HTTP/1.1 [RFC2068] as both the means to request an | publication of HTTP/1.1 [RFC2068] as both the means to request an | |||
interim 100 (Continue) response and the general mechanism for | interim 100 (Continue) response and the general mechanism for | |||
indicating must-understand extensions. However, the extension | indicating must-understand extensions. However, the extension | |||
mechanism has not been used by clients and the must-understand | mechanism has not been used by clients and the must-understand | |||
requirements have not been implemented by many servers, rendering | requirements have not been implemented by many servers, rendering | |||
the extension mechanism useless. This specification has removed | the extension mechanism useless. This specification has removed | |||
the extension mechanism in order to simplify the definition and | the extension mechanism in order to simplify the definition and | |||
processing of 100-continue. | processing of 100-continue. | |||
5.1.2. Max-Forwards | 8.1.2. Max-Forwards | |||
The "Max-Forwards" header field provides a mechanism with the TRACE | The "Max-Forwards" header field provides a mechanism with the TRACE | |||
(Section 4.3.8) and OPTIONS (Section 4.3.7) request methods to limit | (Section 7.3.8) and OPTIONS (Section 7.3.7) request methods to limit | |||
the number of times that the request is forwarded by proxies. This | the number of times that the request is forwarded by proxies. This | |||
can be useful when the client is attempting to trace a request that | can be useful when the client is attempting to trace a request that | |||
appears to be failing or looping mid-chain. | appears to be failing or looping mid-chain. | |||
Max-Forwards = 1*DIGIT | Max-Forwards = 1*DIGIT | |||
The Max-Forwards value is a decimal integer indicating the remaining | The Max-Forwards value is a decimal integer indicating the remaining | |||
number of times this request message can be forwarded. | number of times this request message can be forwarded. | |||
Each intermediary that receives a TRACE or OPTIONS request containing | Each intermediary that receives a TRACE or OPTIONS request containing | |||
skipping to change at line 3599 ¶ | skipping to change at page 84, line 21 ¶ | |||
intermediary MUST NOT forward the request; instead, the intermediary | intermediary MUST NOT forward the request; instead, the intermediary | |||
MUST respond as the final recipient. If the received Max-Forwards | MUST respond as the final recipient. If the received Max-Forwards | |||
value is greater than zero, the intermediary MUST generate an updated | value is greater than zero, the intermediary MUST generate an updated | |||
Max-Forwards field in the forwarded message with a field-value that | 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) | is the lesser of a) the received value decremented by one (1) or b) | |||
the recipient's maximum supported value for Max-Forwards. | the recipient's maximum supported value for Max-Forwards. | |||
A recipient MAY ignore a Max-Forwards header field received with any | A recipient MAY ignore a Max-Forwards header field received with any | |||
other request methods. | other request methods. | |||
5.2. Conditionals | 8.2. Preconditions | |||
Conditional requests are HTTP requests [RFC7231] that include one or | ||||
more header fields indicating a precondition to be tested before | ||||
applying the method semantics to the target resource. This document | ||||
defines the HTTP/1.1 conditional request mechanisms in terms of the | ||||
architecture, syntax notation, and conformance criteria defined in | ||||
[RFC7230]. | ||||
3. Precondition Header Fields | ||||
This section defines the syntax and semantics of HTTP/1.1 header | A conditional request is an HTTP request with one or more request | |||
fields for applying preconditions on requests. Section 5 defines | header fields that indicate a precondition to be tested before | |||
when the preconditions are applied. Section 6 defines the order of | applying the request method to the target resource. Section 8.2.1 | |||
evaluation when more than one precondition is present. | defines when preconditions are applied. Section 8.2.2 defines the | |||
order of evaluation when more than one precondition is present. | ||||
Conditional GET requests are the most efficient mechanism for HTTP | Conditional GET requests are the most efficient mechanism for HTTP | |||
cache updates [RFC7234]. Conditionals can also be applied to | cache updates [Caching]. Conditionals can also be applied to state- | |||
state-changing methods, such as PUT and DELETE, to prevent the "lost | changing methods, such as PUT and DELETE, to prevent the "lost | |||
update" problem: one client accidentally overwriting the work of | update" problem: one client accidentally overwriting the work of | |||
another client that has been acting in parallel. | another client that has been acting in parallel. | |||
Conditional request preconditions are based on the state of the | Conditional request preconditions are based on the state of the | |||
target resource as a whole (its current value set) or the state as | target resource as a whole (its current value set) or the state as | |||
observed in a previously obtained representation (one value in that | observed in a previously obtained representation (one value in that | |||
set). A resource might have multiple current representations, each | set). A resource might have multiple current representations, each | |||
with its own observable state. The conditional request mechanisms | with its own observable state. The conditional request mechanisms | |||
assume that the mapping of requests to a "selected representation" | assume that the mapping of requests to a "selected representation" | |||
(Section 3 of [RFC7231]) will be consistent over time if the server | (Section 6) will be consistent over time if the server intends to | |||
intends to take advantage of conditionals. Regardless, if the | take advantage of conditionals. Regardless, if the mapping is | |||
mapping is inconsistent and the server is unable to select the | inconsistent and the server is unable to select the appropriate | |||
appropriate representation, then no harm will result when the | representation, then no harm will result when the precondition | |||
precondition evaluates to false. | evaluates to false. | |||
The conditional request preconditions defined by this specification | ||||
(Section 3) are evaluated when applicable to the recipient | ||||
(Section 5) according to their order of precedence (Section 6). | ||||
The HTTP conditional request header fields [RFC7232] allow a client | The following request header fields allow a client to place a | |||
to place a precondition on the state of the target resource, so that | precondition on the state of the target resource, so that the action | |||
the action corresponding to the method semantics will not be applied | corresponding to the method semantics will not be applied if the | |||
if the precondition evaluates to false. Each precondition defined by | precondition evaluates to false. Each precondition defined by this | |||
this specification consists of a comparison between a set of | specification consists of a comparison between a set of validators | |||
validators obtained from prior representations of the target resource | obtained from prior representations of the target resource to the | |||
to the current state of validators for the selected representation | current state of validators for the selected representation | |||
(Section 7.2). Hence, these preconditions evaluate whether the state | (Section 10.2). Hence, these preconditions evaluate whether the | |||
of the target resource has changed since a given state known by the | state of the target resource has changed since a given state known by | |||
client. The effect of such an evaluation depends on the method | the client. The effect of such an evaluation depends on the method | |||
semantics and choice of conditional, as defined in Section 5 of | semantics and choice of conditional, as defined in Section 8.2.1. | |||
[RFC7232]. | ||||
+---------------------+--------------------------+ | +---------------------+---------------+ | |||
| Header Field Name | Defined in... | | | Header Field Name | Defined in... | | |||
+---------------------+--------------------------+ | +---------------------+---------------+ | |||
| If-Match | Section 3.1 of [RFC7232] | | | If-Match | Section 8.2.3 | | |||
| If-None-Match | Section 3.2 of [RFC7232] | | | If-None-Match | Section 8.2.4 | | |||
| If-Modified-Since | Section 3.3 of [RFC7232] | | | If-Modified-Since | Section 8.2.5 | | |||
| If-Unmodified-Since | Section 3.4 of [RFC7232] | | | If-Unmodified-Since | Section 8.2.6 | | |||
| If-Range | Section 3.2 of [RFC7233] | | | If-Range | Section 8.2.7 | | |||
+---------------------+--------------------------+ | +---------------------+---------------+ | |||
5. Evaluation | 8.2.1. Evaluation | |||
Except when excluded below, a recipient cache or origin server MUST | Except when excluded below, a recipient cache or origin server MUST | |||
evaluate received request preconditions after it has successfully | evaluate received request preconditions after it has successfully | |||
performed its normal request checks and just before it would perform | performed its normal request checks and just before it would perform | |||
the action associated with the request method. A server MUST ignore | the action associated with the request method. A server MUST ignore | |||
all received preconditions if its response to the same request | all received preconditions if its response to the same request | |||
without those conditions would have been a status code other than a | without those conditions would have been a status code other than a | |||
2xx (Successful) or 412 (Precondition Failed). In other words, | 2xx (Successful) or 412 (Precondition Failed). In other words, | |||
redirects and failures take precedence over the evaluation of | redirects and failures take precedence over the evaluation of | |||
preconditions in conditional requests. | preconditions in conditional requests. | |||
skipping to change at line 3683 ¶ | skipping to change at page 85, line 43 ¶ | |||
cannot act as a cache for requests on the target resource MUST NOT | cannot act as a cache for requests on the target resource MUST NOT | |||
evaluate the conditional request header fields defined by this | evaluate the conditional request header fields defined by this | |||
specification, and it MUST forward them if the request is forwarded, | specification, and it MUST forward them if the request is forwarded, | |||
since the generating client intends that they be evaluated by a | since the generating client intends that they be evaluated by a | |||
server that can provide a current representation. Likewise, a server | server that can provide a current representation. Likewise, a server | |||
MUST ignore the conditional request header fields defined by this | MUST ignore the conditional request header fields defined by this | |||
specification when received with a request method that does not | specification when received with a request method that does not | |||
involve the selection or modification of a selected representation, | involve the selection or modification of a selected representation, | |||
such as CONNECT, OPTIONS, or TRACE. | such as CONNECT, OPTIONS, or TRACE. | |||
Note that protocol extensions can modify the conditions under which | ||||
revalidation is triggered. For example, the "immutable" cache | ||||
directive (defined by [RFC8246]) instructs caches to forgo | ||||
revalidation of fresh responses even when requested by the client. | ||||
Conditional request header fields that are defined by extensions to | Conditional request header fields that are defined by extensions to | |||
HTTP might place conditions on all recipients, on the state of the | HTTP might place conditions on all recipients, on the state of the | |||
target resource in general, or on a group of resources. For | target resource in general, or on a group of resources. For | |||
instance, the "If" header field in WebDAV can make a request | instance, the "If" header field in WebDAV can make a request | |||
conditional on various aspects of multiple resources, such as locks, | conditional on various aspects of multiple resources, such as locks, | |||
if the recipient understands and implements that field ([RFC4918], | if the recipient understands and implements that field ([RFC4918], | |||
Section 10.4). | Section 10.4). | |||
Although conditional request header fields are defined as being | Although conditional request header fields are defined as being | |||
usable with the HEAD method (to keep HEAD's semantics consistent with | usable with the HEAD method (to keep HEAD's semantics consistent with | |||
those of GET), there is no point in sending a conditional HEAD | those of GET), there is no point in sending a conditional HEAD | |||
because a successful response is around the same size as a 304 (Not | because a successful response is around the same size as a 304 (Not | |||
Modified) response and more useful than a 412 (Precondition Failed) | Modified) response and more useful than a 412 (Precondition Failed) | |||
response. | response. | |||
6. Precedence | 8.2.2. Precedence | |||
When more than one conditional request header field is present in a | When more than one conditional request header field is present in a | |||
request, the order in which the fields are evaluated becomes | request, the order in which the fields are evaluated becomes | |||
important. In practice, the fields defined in this document are | important. In practice, the fields defined in this document are | |||
consistently implemented in a single, logical order, since "lost | consistently implemented in a single, logical order, since "lost | |||
update" preconditions have more strict requirements than cache | update" preconditions have more strict requirements than cache | |||
validation, a validated cache is more efficient than a partial | validation, a validated cache is more efficient than a partial | |||
response, and entity tags are presumed to be more accurate than date | response, and entity tags are presumed to be more accurate than date | |||
validators. | validators. | |||
A recipient cache or origin server MUST evaluate the request | A recipient cache or origin server MUST evaluate the request | |||
preconditions defined by this specification in the following order: | preconditions defined by this specification in the following order: | |||
1. When recipient is the origin server and If-Match is present, | 1. When recipient is the origin server and If-Match is present, | |||
evaluate the If-Match precondition: | evaluate the If-Match precondition: | |||
* if true, continue to step 3 | * if true, continue to step 3 | |||
* if false, respond 412 (Precondition Failed) unless it can be | * if false, respond 412 (Precondition Failed) unless it can be | |||
determined that the state-changing request has already | determined that the state-changing request has already | |||
succeeded (see Section 3.1) | succeeded (see Section 8.2.3) | |||
2. When recipient is the origin server, If-Match is not present, and | 2. When recipient is the origin server, If-Match is not present, and | |||
If-Unmodified-Since is present, evaluate the If-Unmodified-Since | If-Unmodified-Since is present, evaluate the If-Unmodified-Since | |||
precondition: | precondition: | |||
* if true, continue to step 3 | * if true, continue to step 3 | |||
* if false, respond 412 (Precondition Failed) unless it can be | * if false, respond 412 (Precondition Failed) unless it can be | |||
determined that the state-changing request has already | determined that the state-changing request has already | |||
succeeded (see Section 3.4) | succeeded (see Section 8.2.6) | |||
3. When If-None-Match is present, evaluate the If-None-Match | 3. When If-None-Match is present, evaluate the If-None-Match | |||
precondition: | precondition: | |||
* if true, continue to step 5 | * if true, continue to step 5 | |||
* if false for GET/HEAD, respond 304 (Not Modified) | * if false for GET/HEAD, respond 304 (Not Modified) | |||
* if false for other methods, respond 412 (Precondition Failed) | * if false for other methods, respond 412 (Precondition Failed) | |||
skipping to change at line 3753 ¶ | skipping to change at page 87, line 30 ¶ | |||
* if true, continue to step 5 | * if true, continue to step 5 | |||
* if false, respond 304 (Not Modified) | * if false, respond 304 (Not Modified) | |||
5. When the method is GET and both Range and If-Range are present, | 5. When the method is GET and both Range and If-Range are present, | |||
evaluate the If-Range precondition: | evaluate the If-Range precondition: | |||
* if the validator matches and the Range specification is | * if the validator matches and the Range specification is | |||
applicable to the selected representation, respond 206 | applicable to the selected representation, respond 206 | |||
(Partial Content) [RFC7233] | (Partial Content) | |||
6. Otherwise, | 6. Otherwise, | |||
* all conditions are met, so perform the requested action and | * all conditions are met, so perform the requested action and | |||
respond according to its success or failure. | respond according to its success or failure. | |||
Any extension to HTTP/1.1 that defines additional conditional request | Any extension to HTTP/1.1 that defines additional conditional request | |||
header fields ought to define its own expectations regarding the | header fields ought to define its own expectations regarding the | |||
order for evaluating such fields in relation to those defined in this | order for evaluating such fields in relation to those defined in this | |||
document and other conditionals that might be found in practice. | document and other conditionals that might be found in practice. | |||
3.1. If-Match | 8.2.3. If-Match | |||
The "If-Match" header field makes the request method conditional on | The "If-Match" header field makes the request method conditional on | |||
the recipient origin server either having at least one current | the recipient origin server either having at least one current | |||
representation of the target resource, when the field-value is "*", | representation of the target resource, when the field-value is "*", | |||
or having a current representation of the target resource that has an | or having a current representation of the target resource that has an | |||
entity-tag matching a member of the list of entity-tags provided in | entity-tag matching a member of the list of entity-tags provided in | |||
the field-value. | the field-value. | |||
An origin server MUST use the strong comparison function when | An origin server MUST use the strong comparison function when | |||
comparing entity-tags for If-Match (Section 2.3.2), since the client | comparing entity-tags for If-Match (Section 10.2.3.2), since the | |||
intends this precondition to prevent the method from being applied if | client intends this precondition to prevent the method from being | |||
there have been any changes to the representation data. | applied if there have been any changes to the representation data. | |||
If-Match = "*" / 1#entity-tag | If-Match = "*" / 1#entity-tag | |||
Examples: | Examples: | |||
If-Match: "xyzzy" | If-Match: "xyzzy" | |||
If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" | If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" | |||
If-Match: * | If-Match: * | |||
If-Match is most often used with state-changing methods (e.g., POST, | If-Match is most often used with state-changing methods (e.g., POST, | |||
PUT, DELETE) to prevent accidental overwrites when multiple user | PUT, DELETE) to prevent accidental overwrites when multiple user | |||
agents might be acting in parallel on the same resource (i.e., to | agents might be acting in parallel on the same resource (i.e., to | |||
prevent the "lost update" problem). It can also be used with safe | prevent the "lost update" problem). It can also be used with safe | |||
methods to abort a request if the selected representation does not | methods to abort a request if the selected representation does not | |||
match one already stored (or partially stored) from a prior request. | match one already stored (or partially stored) from a prior request. | |||
An origin server that receives an If-Match header field MUST evaluate | An origin server that receives an If-Match header field MUST evaluate | |||
the condition prior to performing the method (Section 5). If the | the condition prior to performing the method (Section 8.2.1). If the | |||
field-value is "*", the condition is false if the origin server does | field-value is "*", the condition is false if the origin server does | |||
not have a current representation for the target resource. If the | not have a current representation for the target resource. If the | |||
field-value is a list of entity-tags, the condition is false if none | field-value is a list of entity-tags, the condition is false if none | |||
of the listed tags match the entity-tag of the selected | of the listed tags match the entity-tag of the selected | |||
representation. | representation. | |||
An origin server MUST NOT perform the requested method if a received | An origin server MUST NOT perform the requested method if a received | |||
If-Match condition evaluates to false; instead, the origin server | If-Match condition evaluates to false; instead, the origin server | |||
MUST respond with either a) the 412 (Precondition Failed) status code | MUST respond with either a) the 412 (Precondition Failed) status code | |||
or b) one of the 2xx (Successful) status codes if the origin server | or b) one of the 2xx (Successful) status codes if the origin server | |||
skipping to change at line 3819 ¶ | skipping to change at page 89, line 15 ¶ | |||
succeeded, but the user agent might not be aware of it, perhaps | succeeded, but the user agent might not be aware of it, perhaps | |||
because the prior response was lost or a compatible change was made | because the prior response was lost or a compatible change was made | |||
by some other user agent). In the latter case, the origin server | by some other user agent). In the latter case, the origin server | |||
MUST NOT send a validator header field in the response unless it can | MUST NOT send a validator header field in the response unless it can | |||
verify that the request is a duplicate of an immediately prior change | verify that the request is a duplicate of an immediately prior change | |||
made by the same user agent. | made by the same user agent. | |||
The If-Match header field can be ignored by caches and intermediaries | The If-Match header field can be ignored by caches and intermediaries | |||
because it is not applicable to a stored response. | because it is not applicable to a stored response. | |||
3.2. If-None-Match | 8.2.4. If-None-Match | |||
The "If-None-Match" header field makes the request method conditional | The "If-None-Match" header field makes the request method conditional | |||
on a recipient cache or origin server either not having any current | on a recipient cache or origin server either not having any current | |||
representation of the target resource, when the field-value is "*", | representation of the target resource, when the field-value is "*", | |||
or having a selected representation with an entity-tag that does not | or having a selected representation with an entity-tag that does not | |||
match any of those listed in the field-value. | match any of those listed in the field-value. | |||
A recipient MUST use the weak comparison function when comparing | A recipient MUST use the weak comparison function when comparing | |||
entity-tags for If-None-Match (Section 2.3.2), since weak entity-tags | entity-tags for If-None-Match (Section 10.2.3.2), since weak entity- | |||
can be used for cache validation even if there have been changes to | tags can be used for cache validation even if there have been changes | |||
the representation data. | to the representation data. | |||
If-None-Match = "*" / 1#entity-tag | If-None-Match = "*" / 1#entity-tag | |||
Examples: | Examples: | |||
If-None-Match: "xyzzy" | If-None-Match: "xyzzy" | |||
If-None-Match: W/"xyzzy" | If-None-Match: W/"xyzzy" | |||
If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" | If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" | |||
If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" | If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" | |||
If-None-Match: * | If-None-Match: * | |||
skipping to change at line 3855 ¶ | skipping to change at page 89, line 51 ¶ | |||
stored responses that have entity-tags, the client SHOULD generate an | stored responses that have entity-tags, the client SHOULD generate an | |||
If-None-Match header field containing a list of those entity-tags | If-None-Match header field containing a list of those entity-tags | |||
when making a GET request; this allows recipient servers to send a | when making a GET request; this allows recipient servers to send a | |||
304 (Not Modified) response to indicate when one of those stored | 304 (Not Modified) response to indicate when one of those stored | |||
responses matches the selected representation. | responses matches the selected representation. | |||
If-None-Match can also be used with a value of "*" to prevent an | If-None-Match can also be used with a value of "*" to prevent an | |||
unsafe request method (e.g., PUT) from inadvertently modifying an | unsafe request method (e.g., PUT) from inadvertently modifying an | |||
existing representation of the target resource when the client | existing representation of the target resource when the client | |||
believes that the resource does not have a current representation | believes that the resource does not have a current representation | |||
(Section 4.2.1 of [RFC7231]). This is a variation on the "lost | (Section 7.2.1). This is a variation on the "lost update" problem | |||
update" problem that might arise if more than one client attempts to | that might arise if more than one client attempts to create an | |||
create an initial representation for the target resource. | initial representation for the target resource. | |||
An origin server that receives an If-None-Match header field MUST | An origin server that receives an If-None-Match header field MUST | |||
evaluate the condition prior to performing the method (Section 5). | evaluate the condition prior to performing the method | |||
If the field-value is "*", the condition is false if the origin | (Section 8.2.1). If the field-value is "*", the condition is false | |||
server has a current representation for the target resource. If the | if the origin server has a current representation for the target | |||
field-value is a list of entity-tags, the condition is false if one | resource. If the field-value is a list of entity-tags, the condition | |||
of the listed tags match the entity-tag of the selected | is false if one of the listed tags match the entity-tag of the | |||
representation. | selected representation. | |||
An origin server MUST NOT perform the requested method if the | An origin server MUST NOT perform the requested method if the | |||
condition evaluates to false; instead, the origin server MUST respond | condition evaluates to false; instead, the origin server MUST respond | |||
with either a) the 304 (Not Modified) status code if the request | with either a) the 304 (Not Modified) status code if the request | |||
method is GET or HEAD or b) the 412 (Precondition Failed) status code | method is GET or HEAD or b) the 412 (Precondition Failed) status code | |||
for all other request methods. | for all other request methods. | |||
Requirements on cache handling of a received If-None-Match header | Requirements on cache handling of a received If-None-Match header | |||
field are defined in Section 4.3.2 of [RFC7234]. | field are defined in Section 4.3.2 of [Caching]. | |||
3.3. If-Modified-Since | 8.2.5. If-Modified-Since | |||
The "If-Modified-Since" header field makes a GET or HEAD request | The "If-Modified-Since" header field makes a GET or HEAD request | |||
method conditional on the selected representation's modification date | method conditional on the selected representation's modification date | |||
being more recent than the date provided in the field-value. | being more recent than the date provided in the field-value. | |||
Transfer of the selected representation's data is avoided if that | Transfer of the selected representation's data is avoided if that | |||
data has not changed. | data has not changed. | |||
If-Modified-Since = HTTP-date | If-Modified-Since = HTTP-date | |||
An example of the field is: | An example of the field is: | |||
If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT | If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT | |||
A recipient MUST ignore If-Modified-Since if the request contains an | A recipient MUST ignore If-Modified-Since if the request contains an | |||
If-None-Match header field; the condition in If-None-Match is | If-None-Match header field; the condition in If-None-Match is | |||
considered to be a more accurate replacement for the condition in | considered to be a more accurate replacement for the condition in If- | |||
If-Modified-Since, and the two are only combined for the sake of | Modified-Since, and the two are only combined for the sake of | |||
interoperating with older intermediaries that might not implement | interoperating with older intermediaries that might not implement If- | |||
If-None-Match. | None-Match. | |||
A recipient MUST ignore the If-Modified-Since header field if the | A recipient MUST ignore the If-Modified-Since header field if the | |||
received field-value is not a valid HTTP-date, or if the request | received field-value is not a valid HTTP-date, or if the request | |||
method is neither GET nor HEAD. | method is neither GET nor HEAD. | |||
A recipient MUST interpret an If-Modified-Since field-value's | A recipient MUST interpret an If-Modified-Since field-value's | |||
timestamp in terms of the origin server's clock. | timestamp in terms of the origin server's clock. | |||
If-Modified-Since is typically used for two distinct purposes: 1) to | If-Modified-Since is typically used for two distinct purposes: 1) to | |||
allow efficient updates of a cached representation that does not have | allow efficient updates of a cached representation that does not have | |||
an entity-tag and 2) to limit the scope of a web traversal to | an entity-tag and 2) to limit the scope of a web traversal to | |||
resources that have recently changed. | resources that have recently changed. | |||
When used for cache updates, a cache will typically use the value of | When used for cache updates, a cache will typically use the value of | |||
the cached message's Last-Modified field to generate the field value | the cached message's Last-Modified field to generate the field value | |||
of If-Modified-Since. This behavior is most interoperable for cases | of If-Modified-Since. This behavior is most interoperable for cases | |||
where clocks are poorly synchronized or when the server has chosen to | where clocks are poorly synchronized or when the server has chosen to | |||
only honor exact timestamp matches (due to a problem with | only honor exact timestamp matches (due to a problem with Last- | |||
Last-Modified dates that appear to go "back in time" when the origin | Modified dates that appear to go "back in time" when the origin | |||
server's clock is corrected or a representation is restored from an | server's clock is corrected or a representation is restored from an | |||
archived backup). However, caches occasionally generate the field | archived backup). However, caches occasionally generate the field | |||
value based on other data, such as the Date header field of the | value based on other data, such as the Date header field of the | |||
cached message or the local clock time that the message was received, | cached message or the local clock time that the message was received, | |||
particularly when the cached message does not contain a Last-Modified | particularly when the cached message does not contain a Last-Modified | |||
field. | field. | |||
When used for limiting the scope of retrieval to a recent time | When used for limiting the scope of retrieval to a recent time | |||
window, a user agent will generate an If-Modified-Since field value | window, a user agent will generate an If-Modified-Since field value | |||
based on either its own local clock or a Date header field received | based on either its own local clock or a Date header field received | |||
from the server in a prior response. Origin servers that choose an | from the server in a prior response. Origin servers that choose an | |||
exact timestamp match based on the selected representation's | exact timestamp match based on the selected representation's Last- | |||
Last-Modified field will not be able to help the user agent limit its | Modified field will not be able to help the user agent limit its data | |||
data transfers to only those changed during the specified window. | transfers to only those changed during the specified window. | |||
An origin server that receives an If-Modified-Since header field | An origin server that receives an If-Modified-Since header field | |||
SHOULD evaluate the condition prior to performing the method | SHOULD evaluate the condition prior to performing the method | |||
(Section 5). The origin server SHOULD NOT perform the requested | (Section 8.2.1). The origin server SHOULD NOT perform the requested | |||
method if the selected representation's last modification date is | method if the selected representation's last modification date is | |||
earlier than or equal to the date provided in the field-value; | earlier than or equal to the date provided in the field-value; | |||
instead, the origin server SHOULD generate a 304 (Not Modified) | instead, the origin server SHOULD generate a 304 (Not Modified) | |||
response, including only those metadata that are useful for | response, including only those metadata that are useful for | |||
identifying or updating a previously cached response. | identifying or updating a previously cached response. | |||
Requirements on cache handling of a received If-Modified-Since header | Requirements on cache handling of a received If-Modified-Since header | |||
field are defined in Section 4.3.2 of [RFC7234]. | field are defined in Section 4.3.2 of [Caching]. | |||
3.4. If-Unmodified-Since | 8.2.6. If-Unmodified-Since | |||
The "If-Unmodified-Since" header field makes the request method | The "If-Unmodified-Since" header field makes the request method | |||
conditional on the selected representation's last modification date | conditional on the selected representation's last modification date | |||
being earlier than or equal to the date provided in the field-value. | being earlier than or equal to the date provided in the field-value. | |||
This field accomplishes the same purpose as If-Match for cases where | This field accomplishes the same purpose as If-Match for cases where | |||
the user agent does not have an entity-tag for the representation. | the user agent does not have an entity-tag for the representation. | |||
If-Unmodified-Since = HTTP-date | If-Unmodified-Since = HTTP-date | |||
An example of the field is: | An example of the field is: | |||
If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT | If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT | |||
A recipient MUST ignore If-Unmodified-Since if the request contains | A recipient MUST ignore If-Unmodified-Since if the request contains | |||
an If-Match header field; the condition in If-Match is considered to | an If-Match header field; the condition in If-Match is considered to | |||
be a more accurate replacement for the condition in | be a more accurate replacement for the condition in If-Unmodified- | |||
If-Unmodified-Since, and the two are only combined for the sake of | Since, and the two are only combined for the sake of interoperating | |||
interoperating with older intermediaries that might not implement | with older intermediaries that might not implement If-Match. | |||
If-Match. | ||||
A recipient MUST ignore the If-Unmodified-Since header field if the | A recipient MUST ignore the If-Unmodified-Since header field if the | |||
received field-value is not a valid HTTP-date. | received field-value is not a valid HTTP-date. | |||
A recipient MUST interpret an If-Unmodified-Since field-value's | A recipient MUST interpret an If-Unmodified-Since field-value's | |||
timestamp in terms of the origin server's clock. | timestamp in terms of the origin server's clock. | |||
If-Unmodified-Since is most often used with state-changing methods | If-Unmodified-Since is most often used with state-changing methods | |||
(e.g., POST, PUT, DELETE) to prevent accidental overwrites when | (e.g., POST, PUT, DELETE) to prevent accidental overwrites when | |||
multiple user agents might be acting in parallel on a resource that | multiple user agents might be acting in parallel on a resource that | |||
does not supply entity-tags with its representations (i.e., to | does not supply entity-tags with its representations (i.e., to | |||
prevent the "lost update" problem). It can also be used with safe | prevent the "lost update" problem). It can also be used with safe | |||
methods to abort a request if the selected representation does not | methods to abort a request if the selected representation does not | |||
match one already stored (or partially stored) from a prior request. | match one already stored (or partially stored) from a prior request. | |||
An origin server that receives an If-Unmodified-Since header field | An origin server that receives an If-Unmodified-Since header field | |||
MUST evaluate the condition prior to performing the method | MUST evaluate the condition prior to performing the method | |||
(Section 5). The origin server MUST NOT perform the requested method | (Section 8.2.1). The origin server MUST NOT perform the requested | |||
if the selected representation's last modification date is more | method if the selected representation's last modification date is | |||
recent than the date provided in the field-value; instead the origin | more recent than the date provided in the field-value; instead the | |||
server MUST respond with either a) the 412 (Precondition Failed) | origin server MUST respond with either a) the 412 (Precondition | |||
status code or b) one of the 2xx (Successful) status codes if the | Failed) status code or b) one of the 2xx (Successful) status codes if | |||
origin server has verified that a state change is being requested and | the origin server has verified that a state change is being requested | |||
the final state is already reflected in the current state of the | and the final state is already reflected in the current state of the | |||
target resource (i.e., the change requested by the user agent has | target resource (i.e., the change requested by the user agent has | |||
already succeeded, but the user agent might not be aware of that | already succeeded, but the user agent might not be aware of that | |||
because the prior response message was lost or a compatible change | because the prior response message was lost or a compatible change | |||
was made by some other user agent). In the latter case, the origin | was made by some other user agent). In the latter case, the origin | |||
server MUST NOT send a validator header field in the response unless | server MUST NOT send a validator header field in the response unless | |||
it can verify that the request is a duplicate of an immediately prior | it can verify that the request is a duplicate of an immediately prior | |||
change made by the same user agent. | change made by the same user agent. | |||
The If-Unmodified-Since header field can be ignored by caches and | The If-Unmodified-Since header field can be ignored by caches and | |||
intermediaries because it is not applicable to a stored response. | intermediaries because it is not applicable to a stored response. | |||
3.5. If-Range | 8.2.7. If-Range | |||
The "If-Range" header field provides a special conditional request | The "If-Range" header field provides a special conditional request | |||
mechanism that is similar to the If-Match and If-Unmodified-Since | mechanism that is similar to the If-Match and If-Unmodified-Since | |||
header fields but that instructs the recipient to ignore the Range | header fields but that instructs the recipient to ignore the Range | |||
header field if the validator doesn't match, resulting in transfer of | header field if the validator doesn't match, resulting in transfer of | |||
the new selected representation instead of a 412 (Precondition | the new selected representation instead of a 412 (Precondition | |||
Failed) response. If-Range is defined in Section 3.2 of [RFC7233]. | Failed) response. | |||
If a client has a partial copy of a representation and wishes to have | If a client has a partial copy of a representation and wishes to have | |||
an up-to-date copy of the entire representation, it could use the | an up-to-date copy of the entire representation, it could use the | |||
Range header field with a conditional GET (using either or both of | Range header field with a conditional GET (using either or both of | |||
If-Unmodified-Since and If-Match.) However, if the precondition | If-Unmodified-Since and If-Match.) However, if the precondition | |||
fails because the representation has been modified, the client would | fails because the representation has been modified, the client would | |||
then have to make a second request to obtain the entire current | then have to make a second request to obtain the entire current | |||
representation. | representation. | |||
The "If-Range" header field allows a client to "short-circuit" the | The "If-Range" header field allows a client to "short-circuit" the | |||
second request. Informally, its meaning is as follows: if the | second request. Informally, its meaning is as follows: if the | |||
representation is unchanged, send me the part(s) that I am requesting | representation is unchanged, send me the part(s) that I am requesting | |||
in Range; otherwise, send me the entire representation. | in Range; otherwise, send me the entire representation. | |||
If-Range = entity-tag / HTTP-date | If-Range = entity-tag / HTTP-date | |||
A client MUST NOT generate an If-Range header field in a request that | A client MUST NOT generate an If-Range header field in a request that | |||
does not contain a Range header field. A server MUST ignore an | does not contain a Range header field. A server MUST ignore an If- | |||
If-Range header field received in a request that does not contain a | Range header field received in a request that does not contain a | |||
Range header field. An origin server MUST ignore an If-Range header | Range header field. An origin server MUST ignore an If-Range header | |||
field received in a request for a target resource that does not | field received in a request for a target resource that does not | |||
support Range requests. | support Range requests. | |||
A client MUST NOT generate an If-Range header field containing an | A client MUST NOT generate an If-Range header field containing an | |||
entity-tag that is marked as weak. A client MUST NOT generate an | entity-tag that is marked as weak. A client MUST NOT generate an If- | |||
If-Range header field containing an HTTP-date unless the client has | Range header field containing an HTTP-date unless the client has no | |||
no entity-tag for the corresponding representation and the date is a | entity-tag for the corresponding representation and the date is a | |||
strong validator in the sense defined by Section 2.2.2 of [RFC7232]. | strong validator in the sense defined by Section 10.2.2.2. | |||
A server that evaluates an If-Range precondition MUST use the strong | A server that evaluates an If-Range precondition MUST use the strong | |||
comparison function when comparing entity-tags (Section 2.3.2 of | comparison function when comparing entity-tags (Section 10.2.3.2) and | |||
[RFC7232]) and MUST evaluate the condition as false if an HTTP-date | MUST evaluate the condition as false if an HTTP-date validator is | |||
validator is provided that is not a strong validator in the sense | provided that is not a strong validator in the sense defined by | |||
defined by Section 2.2.2 of [RFC7232]. A valid entity-tag can be | Section 10.2.2.2. A valid entity-tag can be distinguished from a | |||
distinguished from a valid HTTP-date by examining the first two | valid HTTP-date by examining the first two characters for a DQUOTE. | |||
characters for a DQUOTE. | ||||
If the validator given in the If-Range header field matches the | If the validator given in the If-Range header field matches the | |||
current validator for the selected representation of the target | current validator for the selected representation of the target | |||
resource, then the server SHOULD process the Range header field as | resource, then the server SHOULD process the Range header field as | |||
requested. If the validator does not match, the server MUST ignore | requested. If the validator does not match, the server MUST ignore | |||
the Range header field. Note that this comparison by exact match, | the Range header field. Note that this comparison by exact match, | |||
including when the validator is an HTTP-date, differs from the | including when the validator is an HTTP-date, differs from the | |||
"earlier than or equal to" comparison used when evaluating an | "earlier than or equal to" comparison used when evaluating an If- | |||
If-Unmodified-Since conditional. | Unmodified-Since conditional. | |||
3.1. Range | 8.3. Range | |||
The "Range" header field on a GET request modifies the method | The "Range" header field on a GET request modifies the method | |||
semantics to request transfer of only one or more subranges of the | semantics to request transfer of only one or more subranges of the | |||
selected representation data, rather than the entire selected | selected representation data, rather than the entire selected | |||
representation data. | representation data. | |||
Range = byte-ranges-specifier / other-ranges-specifier | Range = ranges-specifier | |||
other-ranges-specifier = other-range-unit "=" other-range-set | ||||
other-range-set = 1*VCHAR | ||||
Hypertext Transfer Protocol (HTTP) clients often encounter | Clients often encounter interrupted data transfers as a result of | |||
interrupted data transfers as a result of canceled requests or | canceled requests or dropped connections. When a client has stored a | |||
dropped connections. When a client has stored a partial | partial representation, it is desirable to request the remainder of | |||
representation, it is desirable to request the remainder of that | that representation in a subsequent request rather than transfer the | |||
representation in a subsequent request rather than transfer the | ||||
entire representation. Likewise, devices with limited local storage | entire representation. Likewise, devices with limited local storage | |||
might benefit from being able to request only a subset of a larger | might benefit from being able to request only a subset of a larger | |||
representation, such as a single page of a very large document, or | representation, such as a single page of a very large document, or | |||
the dimensions of an embedded image. | the dimensions of an embedded image. | |||
Range requests are an OPTIONAL | Range requests are an OPTIONAL feature of HTTP, designed so that | |||
feature of HTTP, designed so that recipients not implementing this | recipients not implementing this feature (or not supporting it for | |||
feature (or not supporting it for the target resource) can respond as | the target resource) can respond as if it is a normal GET request | |||
if it is a normal GET request without impacting interoperability. | without impacting interoperability. Partial responses are indicated | |||
Partial responses are indicated by a distinct status code to not be | by a distinct status code to not be mistaken for full responses by | |||
mistaken for full responses by caches that might not implement the | caches that might not implement the feature. | |||
feature. | ||||
A server MAY ignore the Range header field. However, origin servers | A server MAY ignore the Range header field. However, origin servers | |||
and intermediate caches ought to support byte ranges when possible, | and intermediate caches ought to support byte ranges when possible, | |||
since Range supports efficient recovery from partially failed | since they support efficient recovery from partially failed transfers | |||
transfers and partial retrieval of large representations. A server | and partial retrieval of large representations. A server MUST ignore | |||
MUST ignore a Range header field received with a request method other | a Range header field received with a request method other than GET. | |||
than GET. | ||||
Although the range request mechanism is designed to allow for | Although the range request mechanism is designed to allow for | |||
extensible range types, this specification only defines requests for | extensible range types, this specification only defines requests for | |||
byte ranges. | byte ranges. | |||
An origin server MUST ignore a Range header field that contains a | An origin server MUST ignore a Range header field that contains a | |||
range unit it does not understand. A proxy MAY discard a Range | range unit it does not understand. A proxy MAY discard a Range | |||
header field that contains a range unit it does not understand. | header field that contains a range unit it does not understand. | |||
A server that supports range requests MAY ignore or reject a Range | A server that supports range requests MAY ignore or reject a Range | |||
header field that consists of more than two overlapping ranges, or a | header field that consists of more than two overlapping ranges, or a | |||
set of many small ranges that are not listed in ascending order, | set of many small ranges that are not listed in ascending order, | |||
since both are indications of either a broken client or a deliberate | since both are indications of either a broken client or a deliberate | |||
denial-of-service attack (Section 6.1). A client SHOULD NOT request | denial-of-service attack (Section 13.13). A client SHOULD NOT | |||
multiple ranges that are inherently less efficient to process and | request multiple ranges that are inherently less efficient to process | |||
transfer than a single range that encompasses the same data. | and transfer than a single range that encompasses the same data. | |||
A client that is requesting multiple ranges SHOULD list those ranges | A client that is requesting multiple ranges SHOULD list those ranges | |||
in ascending order (the order in which they would typically be | in ascending order (the order in which they would typically be | |||
received in a complete representation) unless there is a specific | received in a complete representation) unless there is a specific | |||
need to request a later part earlier. For example, a user agent | need to request a later part earlier. For example, a user agent | |||
processing a large representation with an internal catalog of parts | processing a large representation with an internal catalog of parts | |||
might need to request later parts first, particularly if the | might need to request later parts first, particularly if the | |||
representation consists of pages stored in reverse order and the user | representation consists of pages stored in reverse order and the user | |||
agent wishes to transfer one page at a time. | agent wishes to transfer one page at a time. | |||
The Range header field is evaluated after evaluating the precondition | The Range header field is evaluated after evaluating the precondition | |||
header fields defined in [RFC7232], and only if the result in absence | header fields defined in Section 8.2, and only if the result in | |||
of the Range header field would be a 200 (OK) response. In other | absence of the Range header field would be a 200 (OK) response. In | |||
words, Range is ignored when a conditional GET would result in a 304 | other words, Range is ignored when a conditional GET would result in | |||
(Not Modified) response. | a 304 (Not Modified) response. | |||
The If-Range header field (Section 3.2) can be used as a precondition | The If-Range header field (Section 8.2.7) can be used as a | |||
to applying the Range header field. | precondition to applying the Range header field. | |||
If all of the preconditions are true, the server supports the Range | If all of the preconditions are true, the server supports the Range | |||
header field for the target resource, and the specified range(s) are | header field for the target resource, and the specified range(s) are | |||
valid and satisfiable (as defined in Section 2.1), the server SHOULD | valid and satisfiable (as defined in Section 6.1.4.2), the server | |||
send a 206 (Partial Content) response with a payload containing one | SHOULD send a 206 (Partial Content) response with a payload | |||
or more partial representations that correspond to the satisfiable | containing one or more partial representations that correspond to the | |||
ranges requested, as defined in Section 4. | satisfiable ranges requested. | |||
If all of the preconditions are true, the server supports the Range | If all of the preconditions are true, the server supports the Range | |||
header field for the target resource, and the specified range(s) are | header field for the target resource, and the specified range(s) are | |||
invalid or unsatisfiable, the server SHOULD send a 416 (Range Not | invalid or unsatisfiable, the server SHOULD send a 416 (Range Not | |||
Satisfiable) response. | Satisfiable) response. | |||
5.3. Content Negotiation | 8.4. Content Negotiation | |||
The following request header fields are sent by a user agent to | The following request header fields are sent by a user agent to | |||
engage in proactive negotiation of the response content, as defined | engage in proactive negotiation of the response content, as defined | |||
in Section 3.4.1. The preferences sent in these fields apply to any | in Section 6.4.1. The preferences sent in these fields apply to any | |||
content in the response, including representations of the target | content in the response, including representations of the target | |||
resource, representations of error or processing status, and | resource, representations of error or processing status, and | |||
potentially even the miscellaneous text strings that might appear | potentially even the miscellaneous text strings that might appear | |||
within the protocol. | within the protocol. | |||
+-------------------+---------------+ | +-------------------+---------------+ | |||
| Header Field Name | Defined in... | | | Header Field Name | Defined in... | | |||
+-------------------+---------------+ | +-------------------+---------------+ | |||
| Accept | Section 5.3.2 | | | Accept | Section 8.4.2 | | |||
| Accept-Charset | Section 5.3.3 | | | Accept-Charset | Section 8.4.3 | | |||
| Accept-Encoding | Section 5.3.4 | | | Accept-Encoding | Section 8.4.4 | | |||
| Accept-Language | Section 5.3.5 | | | Accept-Language | Section 8.4.5 | | |||
+-------------------+---------------+ | +-------------------+---------------+ | |||
For each of these header fields, a request that does not contain it | ||||
implies that the user agent has no preference on that axis of | ||||
negotiation. If the header field is present in a request and none of | ||||
the available representations for the response can be considered | ||||
acceptable according to it, the origin server can either honor the | ||||
header field by sending a 406 (Not Acceptable) response or disregard | ||||
the header field by treating the response as if it is not subject to | ||||
content negotiation for that request header field. This does not | ||||
imply, however, that the client will be able to use the | ||||
representation. | ||||
Note: Sending these header fields makes it easier for a server to | ||||
identify an individual by virtue of the user agent's request | ||||
characteristics (Section 13.11). | ||||
Each of these header fields defines a wildcard value (often, "*") to | ||||
select unspecified values. If no wildcard is present, all values not | ||||
explicitly mentioned in the field are considered "not acceptable" to | ||||
the client. | ||||
Note: In practice, using wildcards in content negotiation has limited | ||||
practical value, because it is seldom useful to say, for example, "I | ||||
prefer image/* more or less than (some other specific value)". | ||||
Clients can explicitly request a 406 (Not Acceptable) response if a | ||||
more preferred format is not available by sending Accept: */*;q=0, | ||||
but they still need to be able to handle a different response, since | ||||
the server is allowed to ignore their preference. | ||||
8.4.1. Quality Values | 8.4.1. Quality Values | |||
Many of the request header fields for proactive negotiation use a | Many of the request header fields for proactive negotiation use a | |||
common parameter, named "q" (case-insensitive), to assign a relative | common parameter, named "q" (case-insensitive), to assign a relative | |||
"weight" to the preference for that associated kind of content. This | "weight" to the preference for that associated kind of content. This | |||
weight is referred to as a "quality value" (or "qvalue") because the | weight is referred to as a "quality value" (or "qvalue") because the | |||
same parameter name is often used within server configurations to | same parameter name is often used within server configurations to | |||
assign a weight to the relative quality of the various | assign a weight to the relative quality of the various | |||
representations that can be selected for a resource. | representations that can be selected for a resource. | |||
skipping to change at line 4175 ¶ | skipping to change at page 97, line 18 ¶ | |||
the default weight is 1. | the default weight is 1. | |||
weight = OWS ";" OWS "q=" qvalue | weight = OWS ";" OWS "q=" qvalue | |||
qvalue = ( "0" [ "." 0*3DIGIT ] ) | qvalue = ( "0" [ "." 0*3DIGIT ] ) | |||
/ ( "1" [ "." 0*3("0") ] ) | / ( "1" [ "." 0*3("0") ] ) | |||
A sender of qvalue MUST NOT generate more than three digits after the | A sender of qvalue MUST NOT generate more than three digits after the | |||
decimal point. User configuration of these values ought to be | decimal point. User configuration of these values ought to be | |||
limited in the same fashion. | limited in the same fashion. | |||
5.3.2. Accept | 8.4.2. Accept | |||
The "Accept" header field can be used by user agents to specify | The "Accept" header field can be used by user agents to specify their | |||
response media types that are acceptable. Accept header fields can | preferences regarding response media types. For example, Accept | |||
be used to indicate that the request is specifically limited to a | header fields can be used to indicate that the request is | |||
small set of desired types, as in the case of a request for an | specifically limited to a small set of desired types, as in the case | |||
in-line image. | of a request for an in-line image. | |||
Accept = #( media-range [ accept-params ] ) | Accept = #( media-range [ accept-params ] ) | |||
media-range = ( "*/*" | media-range = ( "*/*" | |||
/ ( type "/" "*" ) | / ( type "/" "*" ) | |||
/ ( type "/" subtype ) | / ( type "/" subtype ) | |||
) *( OWS ";" OWS parameter ) | ) *( OWS ";" OWS parameter ) | |||
accept-params = weight *( accept-ext ) | accept-params = weight *( accept-ext ) | |||
accept-ext = OWS ";" OWS token [ "=" ( token / quoted-string ) ] | accept-ext = OWS ";" OWS token [ "=" ( token / quoted-string ) ] | |||
The asterisk "*" character is used to group media types into ranges, | The asterisk "*" character is used to group media types into ranges, | |||
with "*/*" indicating all media types and "type/*" indicating all | with "*/*" indicating all media types and "type/*" indicating all | |||
subtypes of that type. The media-range can include media type | subtypes of that type. The media-range can include media type | |||
parameters that are applicable to that range. | parameters that are applicable to that range. | |||
Each media-range might be followed by zero or more applicable media | Each media-range might be followed by zero or more applicable media | |||
type parameters (e.g., charset), an optional "q" parameter for | type parameters (e.g., charset), an optional "q" parameter for | |||
indicating a relative weight (Section 5.3.1), and then zero or more | indicating a relative weight (Section 8.4.1), and then zero or more | |||
extension parameters. The "q" parameter is necessary if any | extension parameters. The "q" parameter is necessary if any | |||
extensions (accept-ext) are present, since it acts as a separator | extensions (accept-ext) are present, since it acts as a separator | |||
between the two parameter sets. | between the two parameter sets. | |||
Note: Use of the "q" parameter name to separate media type | Note: Use of the "q" parameter name to separate media type | |||
parameters from Accept extension parameters is due to historical | parameters from Accept extension parameters is due to historical | |||
practice. Although this prevents any media type parameter named | practice. Although this prevents any media type parameter named | |||
"q" from being used with a media range, such an event is believed | "q" from being used with a media range, such an event is believed | |||
to be unlikely given the lack of any "q" parameters in the IANA | to be unlikely given the lack of any "q" parameters in the IANA | |||
media type registry and the rare usage of any media type | media type registry and the rare usage of any media type | |||
parameters in Accept. Future media types are discouraged from | parameters in Accept. Future media types are discouraged from | |||
registering any parameter named "q". | registering any parameter named "q". | |||
The example | The example | |||
Accept: audio/*; q=0.2, audio/basic | Accept: audio/*; q=0.2, audio/basic | |||
is interpreted as "I prefer audio/basic, but send me any audio type | is interpreted as "I prefer audio/basic, but send me any audio type | |||
if it is the best available after an 80% markdown in quality". | if it is the best available after an 80% markdown in quality". | |||
A request without any Accept header field implies that the user agent | ||||
will accept any media type in response. If the header field is | ||||
present in a request and none of the available representations for | ||||
the response have a media type that is listed as acceptable, the | ||||
origin server can either honor the header field by sending a 406 (Not | ||||
Acceptable) response or disregard the header field by treating the | ||||
response as if it is not subject to content negotiation. | ||||
A more elaborate example is | A more elaborate example is | |||
Accept: text/plain; q=0.5, text/html, | Accept: text/plain; q=0.5, text/html, | |||
text/x-dvi; q=0.8, text/x-c | text/x-dvi; q=0.8, text/x-c | |||
Verbally, this would be interpreted as "text/html and text/x-c are | Verbally, this would be interpreted as "text/html and text/x-c are | |||
the equally preferred media types, but if they do not exist, then | the equally preferred media types, but if they do not exist, then | |||
send the text/x-dvi representation, and if that does not exist, send | send the text/x-dvi representation, and if that does not exist, send | |||
the text/plain representation". | the text/plain representation". | |||
skipping to change at line 4279 ¶ | skipping to change at page 99, line 21 ¶ | |||
| image/jpeg | 0.5 | | | image/jpeg | 0.5 | | |||
| text/html;level=2 | 0.4 | | | text/html;level=2 | 0.4 | | |||
| text/html;level=3 | 0.7 | | | text/html;level=3 | 0.7 | | |||
+-------------------+---------------+ | +-------------------+---------------+ | |||
Note: A user agent might be provided with a default set of quality | Note: A user agent might be provided with a default set of quality | |||
values for certain media ranges. However, unless the user agent is a | values for certain media ranges. However, unless the user agent is a | |||
closed system that cannot interact with other rendering agents, this | closed system that cannot interact with other rendering agents, this | |||
default set ought to be configurable by the user. | default set ought to be configurable by the user. | |||
5.3.3. Accept-Charset | 8.4.3. Accept-Charset | |||
The "Accept-Charset" header field can be sent by a user agent to | The "Accept-Charset" header field can be sent by a user agent to | |||
indicate what charsets are acceptable in textual response content. | indicate its preferences for charsets in textual response content. | |||
This field allows user agents capable of understanding more | For example, this field allows user agents capable of understanding | |||
comprehensive or special-purpose charsets to signal that capability | more comprehensive or special-purpose charsets to signal that | |||
to an origin server that is capable of representing information in | capability to an origin server that is capable of representing | |||
those charsets. | information in those charsets. | |||
Accept-Charset = 1#( ( charset / "*" ) [ weight ] ) | Accept-Charset = 1#( ( charset / "*" ) [ weight ] ) | |||
Charset names are defined in Section 3.1.1.2. A user agent MAY | Charset names are defined in Section 6.1.1.1. A user agent MAY | |||
associate a quality value with each charset to indicate the user's | associate a quality value with each charset to indicate the user's | |||
relative preference for that charset, as defined in Section 5.3.1. | relative preference for that charset, as defined in Section 8.4.1. | |||
An example is | An example is | |||
Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 | Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 | |||
The special value "*", if present in the Accept-Charset field, | The special value "*", if present in the Accept-Charset field, | |||
matches every charset that is not mentioned elsewhere in the | matches every charset that is not mentioned elsewhere in the Accept- | |||
Accept-Charset field. If no "*" is present in an Accept-Charset | Charset field. | |||
field, then any charsets not explicitly mentioned in the field are | ||||
considered "not acceptable" to the client. | ||||
A request without any Accept-Charset header field implies that the | ||||
user agent will accept any charset in response. Most general-purpose | ||||
user agents do not send Accept-Charset, unless specifically | ||||
configured to do so, because a detailed list of supported charsets | ||||
makes it easier for a server to identify an individual by virtue of | ||||
the user agent's request characteristics (Section 9.7). | ||||
If an Accept-Charset header field is present in a request and none of | Note: Accept-Charset is deprecated because UTF-8 has become nearly | |||
the available representations for the response has a charset that is | ubiquitous and sending a detailed list of user-preferred charsets | |||
listed as acceptable, the origin server can either honor the header | wastes bandwidth, increases latency, and makes passive fingerprinting | |||
field, by sending a 406 (Not Acceptable) response, or disregard the | far too easy (Section 13.11). Most general-purpose user agents do | |||
header field by treating the resource as if it is not subject to | not send Accept-Charset, unless specifically configured to do so. | |||
content negotiation. | ||||
5.3.4. Accept-Encoding | 8.4.4. Accept-Encoding | |||
The "Accept-Encoding" header field can be used by user agents to | The "Accept-Encoding" header field can be used by user agents to | |||
indicate what response content-codings (Section 3.1.2.1) are | indicate their preferences regarding response content-codings | |||
acceptable in the response. An "identity" token is used as a synonym | (Section 6.1.2). An "identity" token is used as a synonym for "no | |||
for "no encoding" in order to communicate when no encoding is | encoding" in order to communicate when no encoding is preferred. | |||
preferred. | ||||
Accept-Encoding = #( codings [ weight ] ) | Accept-Encoding = #( codings [ weight ] ) | |||
codings = content-coding / "identity" / "*" | codings = content-coding / "identity" / "*" | |||
Each codings value MAY be given an associated quality value | Each codings value MAY be given an associated quality value | |||
representing the preference for that encoding, as defined in | representing the preference for that encoding, as defined in | |||
Section 5.3.1. The asterisk "*" symbol in an Accept-Encoding field | Section 8.4.1. The asterisk "*" symbol in an Accept-Encoding field | |||
matches any available content-coding not explicitly listed in the | matches any available content-coding not explicitly listed in the | |||
header field. | header field. | |||
For example, | For example, | |||
Accept-Encoding: compress, gzip | Accept-Encoding: compress, gzip | |||
Accept-Encoding: | Accept-Encoding: | |||
Accept-Encoding: * | Accept-Encoding: * | |||
Accept-Encoding: compress;q=0.5, gzip;q=1.0 | Accept-Encoding: compress;q=0.5, gzip;q=1.0 | |||
Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 | Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 | |||
A request without an Accept-Encoding header field implies that the | ||||
user agent has no preferences regarding content-codings. Although | ||||
this allows the server to use any content-coding in a response, it | ||||
does not imply that the user agent will be able to correctly process | ||||
all encodings. | ||||
A server tests whether a content-coding for a given representation is | A server tests whether a content-coding for a given representation is | |||
acceptable using these rules: | acceptable using these rules: | |||
1. If no Accept-Encoding field is in the request, any content-coding | 1. If no Accept-Encoding field is in the request, any content-coding | |||
is considered acceptable by the user agent. | is considered acceptable by the user agent. | |||
2. If the representation has no content-coding, then it is | 2. If the representation has no content-coding, then it is | |||
acceptable by default unless specifically excluded by the | acceptable by default unless specifically excluded by the Accept- | |||
Accept-Encoding field stating either "identity;q=0" or "*;q=0" | Encoding field stating either "identity;q=0" or "*;q=0" without a | |||
without a more specific entry for "identity". | more specific entry for "identity". | |||
3. If the representation's content-coding is one of the | 3. If the representation's content-coding is one of the content- | |||
content-codings listed in the Accept-Encoding field, then it is | codings listed in the Accept-Encoding field, then it is | |||
acceptable unless it is accompanied by a qvalue of 0. (As | acceptable unless it is accompanied by a qvalue of 0. (As | |||
defined in Section 5.3.1, a qvalue of 0 means "not acceptable".) | defined in Section 8.4.1, a qvalue of 0 means "not acceptable".) | |||
4. If multiple content-codings are acceptable, then the acceptable | 4. If multiple content-codings are acceptable, then the acceptable | |||
content-coding with the highest non-zero qvalue is preferred. | content-coding with the highest non-zero qvalue is preferred. | |||
An Accept-Encoding header field with a combined field-value that is | An Accept-Encoding header field with a combined field-value that is | |||
empty implies that the user agent does not want any content-coding in | empty implies that the user agent does not want any content-coding in | |||
response. If an Accept-Encoding header field is present in a request | response. If an Accept-Encoding header field is present in a request | |||
and none of the available representations for the response have a | and none of the available representations for the response have a | |||
content-coding that is listed as acceptable, the origin server SHOULD | content-coding that is listed as acceptable, the origin server SHOULD | |||
send a response without any content-coding. | send a response without any content-coding. | |||
Note: Most HTTP/1.0 applications do not recognize or obey qvalues | Note: Most HTTP/1.0 applications do not recognize or obey qvalues | |||
associated with content-codings. This means that qvalues might | associated with content-codings. This means that qvalues might | |||
not work and are not permitted with x-gzip or x-compress. | not work and are not permitted with x-gzip or x-compress. | |||
5.3.5. Accept-Language | 8.4.5. Accept-Language | |||
The "Accept-Language" header field can be used by user agents to | The "Accept-Language" header field can be used by user agents to | |||
indicate the set of natural languages that are preferred in the | indicate the set of natural languages that are preferred in the | |||
response. Language tags are defined in Section 3.1.3.1. | response. Language tags are defined in Section 6.1.3. | |||
Accept-Language = 1#( language-range [ weight ] ) | Accept-Language = 1#( language-range [ weight ] ) | |||
language-range = | language-range = | |||
<language-range, see [RFC4647], Section 2.1> | <language-range, see [RFC4647], Section 2.1> | |||
Each language-range can be given an associated quality value | Each language-range can be given an associated quality value | |||
representing an estimate of the user's preference for the languages | representing an estimate of the user's preference for the languages | |||
specified by that range, as defined in Section 5.3.1. For example, | specified by that range, as defined in Section 8.4.1. For example, | |||
Accept-Language: da, en-gb;q=0.8, en;q=0.7 | Accept-Language: da, en-gb;q=0.8, en;q=0.7 | |||
would mean: "I prefer Danish, but will accept British English and | would mean: "I prefer Danish, but will accept British English and | |||
other types of English". | other types of English". | |||
A request without any Accept-Language header field implies that the | ||||
user agent will accept any language in response. If the header field | ||||
is present in a request and none of the available representations for | ||||
the response have a matching language tag, the origin server can | ||||
either disregard the header field by treating the response as if it | ||||
is not subject to content negotiation or honor the header field by | ||||
sending a 406 (Not Acceptable) response. However, the latter is not | ||||
encouraged, as doing so can prevent users from accessing content that | ||||
they might be able to use (with translation software, for example). | ||||
Note that some recipients treat the order in which language tags are | Note that some recipients treat the order in which language tags are | |||
listed as an indication of descending priority, particularly for tags | listed as an indication of descending priority, particularly for tags | |||
that are assigned equal quality values (no value is the same as q=1). | that are assigned equal quality values (no value is the same as q=1). | |||
However, this behavior cannot be relied upon. For consistency and to | However, this behavior cannot be relied upon. For consistency and to | |||
maximize interoperability, many user agents assign each language tag | maximize interoperability, many user agents assign each language tag | |||
a unique quality value while also listing them in order of decreasing | a unique quality value while also listing them in order of decreasing | |||
quality. Additional discussion of language priority lists can be | quality. Additional discussion of language priority lists can be | |||
found in Section 2.3 of [RFC4647]. | found in Section 2.3 of [RFC4647]. | |||
For matching, Section 3 of [RFC4647] defines several matching | For matching, Section 3 of [RFC4647] defines several matching | |||
schemes. Implementations can offer the most appropriate matching | schemes. Implementations can offer |