rfc9110.original | rfc9110.txt | |||
---|---|---|---|---|
HTTP Working Group R. Fielding, Ed. | Internet Engineering Task Force (IETF) R. Fielding, Ed. | |||
Internet-Draft Adobe | Request for Comments: 9110 Adobe | |||
Obsoletes: 2818, 7230, 7231, 7232, 7233, 7235, M. Nottingham, Ed. | STD: 97 M. Nottingham, Ed. | |||
7538, 7615, 7694 (if approved) Fastly | Obsoletes: 2818, 7230, 7231, 7232, 7233, 7235, Fastly | |||
Updates: 3864 (if approved) J. Reschke, Ed. | 7538, 7615, 7694 J. Reschke, Ed. | |||
Intended status: Standards Track greenbytes | Updates: 3864 greenbytes | |||
Expires: 14 March 2022 10 September 2021 | Category: Standards Track February 2022 | |||
ISSN: 2070-1721 | ||||
HTTP Semantics | HTTP Semantics | |||
draft-ietf-httpbis-semantics-19 | ||||
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 describes the overall architecture of HTTP, | systems. This document describes the overall architecture of HTTP, | |||
establishes common terminology, and defines aspects of the protocol | establishes common terminology, and defines aspects of the protocol | |||
that are shared by all versions. In this definition are core | that are shared by all versions. In this definition are core | |||
protocol elements, extensibility mechanisms, and the "http" and | protocol elements, extensibility mechanisms, and the "http" and | |||
"https" Uniform Resource Identifier (URI) schemes. | "https" Uniform Resource Identifier (URI) schemes. | |||
This document updates RFC 3864 and obsoletes RFC 2818, RFC 7231, RFC | This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, | |||
7232, RFC 7233, RFC 7235, RFC 7538, RFC 7615, RFC 7694, and portions | 7233, 7235, 7538, 7615, 7694, and portions of 7230. | |||
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 C.20. | ||||
Status of This Memo | Status of This Memo | |||
This Internet-Draft is submitted in full conformance with the | This is an Internet Standards Track document. | |||
provisions of BCP 78 and BCP 79. | ||||
Internet-Drafts are working documents of the Internet Engineering | ||||
Task Force (IETF). Note that other groups may also distribute | ||||
working documents as Internet-Drafts. The list of current Internet- | ||||
Drafts is at https://datatracker.ietf.org/drafts/current/. | ||||
Internet-Drafts are draft documents valid for a maximum of six months | This document is a product of the Internet Engineering Task Force | |||
and may be updated, replaced, or obsoleted by other documents at any | (IETF). It represents the consensus of the IETF community. It has | |||
time. It is inappropriate to use Internet-Drafts as reference | received public review and has been approved for publication by the | |||
material or to cite them other than as "work in progress." | Internet Engineering Steering Group (IESG). Further information on | |||
Internet Standards is available in Section 2 of RFC 7841. | ||||
This Internet-Draft will expire on 14 March 2022. | Information about the current status of this document, any errata, | |||
and how to provide feedback on it may be obtained at | ||||
https://www.rfc-editor.org/info/rfc9110. | ||||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2021 IETF Trust and the persons identified as the | Copyright (c) 2022 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 (https://trustee.ietf.org/ | Provisions Relating to IETF Documents | |||
license-info) in effect on the date of publication of this document. | (https://trustee.ietf.org/license-info) in effect on the date of | |||
Please review these documents carefully, as they describe your rights | publication of this document. Please review these documents | |||
and restrictions with respect to this document. Code Components | carefully, as they describe your rights and restrictions with respect | |||
extracted from this document must include Simplified BSD License text | to this document. Code Components extracted from this document must | |||
as described in Section 4.e of the Trust Legal Provisions and are | include Revised BSD License text as described in Section 4.e of the | |||
provided without warranty as described in the Simplified BSD License. | Trust Legal Provisions and are provided without warranty as described | |||
in the Revised 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 | |||
material may not have granted the IETF Trust the right to allow | material may not have granted the IETF Trust the right to allow | |||
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 . . . . . . . . . . . . . . . . . . . . . . . . 9 | 1. Introduction | |||
1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 9 | 1.1. Purpose | |||
1.2. History and Evolution . . . . . . . . . . . . . . . . . . 10 | 1.2. History and Evolution | |||
1.3. Core Semantics . . . . . . . . . . . . . . . . . . . . . 11 | 1.3. Core Semantics | |||
1.4. Specifications Obsoleted by this Document . . . . . . . . 11 | 1.4. Specifications Obsoleted by This Document | |||
2. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 12 | 2. Conformance | |||
2.1. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 12 | 2.1. Syntax Notation | |||
2.2. Requirements Notation . . . . . . . . . . . . . . . . . . 13 | 2.2. Requirements Notation | |||
2.3. Length Requirements . . . . . . . . . . . . . . . . . . . 14 | 2.3. Length Requirements | |||
2.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 15 | 2.4. Error Handling | |||
2.5. Protocol Version . . . . . . . . . . . . . . . . . . . . 15 | 2.5. Protocol Version | |||
3. Terminology and Core Concepts . . . . . . . . . . . . . . . . 16 | 3. Terminology and Core Concepts | |||
3.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 16 | 3.1. Resources | |||
3.2. Representations . . . . . . . . . . . . . . . . . . . . . 17 | 3.2. Representations | |||
3.3. Connections, Clients and Servers . . . . . . . . . . . . 17 | 3.3. Connections, Clients, and Servers | |||
3.4. Messages . . . . . . . . . . . . . . . . . . . . . . . . 18 | 3.4. Messages | |||
3.5. User Agents . . . . . . . . . . . . . . . . . . . . . . . 18 | 3.5. User Agents | |||
3.6. Origin Server . . . . . . . . . . . . . . . . . . . . . . 19 | 3.6. Origin Server | |||
3.7. Intermediaries . . . . . . . . . . . . . . . . . . . . . 20 | 3.7. Intermediaries | |||
3.8. Caches . . . . . . . . . . . . . . . . . . . . . . . . . 22 | 3.8. Caches | |||
3.9. Example Message Exchange . . . . . . . . . . . . . . . . 23 | 3.9. Example Message Exchange | |||
4. Identifiers in HTTP . . . . . . . . . . . . . . . . . . . . . 23 | 4. Identifiers in HTTP | |||
4.1. URI References . . . . . . . . . . . . . . . . . . . . . 23 | 4.1. URI References | |||
4.2. HTTP-Related URI Schemes . . . . . . . . . . . . . . . . 24 | 4.2. HTTP-Related URI Schemes | |||
4.2.1. http URI Scheme . . . . . . . . . . . . . . . . . . . 25 | 4.2.1. http URI Scheme | |||
4.2.2. https URI Scheme . . . . . . . . . . . . . . . . . . 25 | 4.2.2. https URI Scheme | |||
4.2.3. http(s) Normalization and Comparison . . . . . . . . 26 | 4.2.3. http(s) Normalization and Comparison | |||
4.2.4. Deprecation of userinfo in http(s) URIs . . . . . . . 27 | 4.2.4. Deprecation of userinfo in http(s) URIs | |||
4.2.5. http(s) References with Fragment Identifiers . . . . 28 | 4.2.5. http(s) References with Fragment Identifiers | |||
4.3. Authoritative Access . . . . . . . . . . . . . . . . . . 28 | 4.3. Authoritative Access | |||
4.3.1. URI Origin . . . . . . . . . . . . . . . . . . . . . 28 | 4.3.1. URI Origin | |||
4.3.2. http origins . . . . . . . . . . . . . . . . . . . . 29 | 4.3.2. http Origins | |||
4.3.3. https origins . . . . . . . . . . . . . . . . . . . . 30 | 4.3.3. https Origins | |||
4.3.4. https certificate verification . . . . . . . . . . . 31 | 4.3.4. https Certificate Verification | |||
4.3.5. IP-ID reference identity . . . . . . . . . . . . . . 32 | 4.3.5. IP-ID Reference Identity | |||
5. Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 | 5. Fields | |||
5.1. Field Names . . . . . . . . . . . . . . . . . . . . . . . 33 | 5.1. Field Names | |||
5.2. Field Lines and Combined Field Value . . . . . . . . . . 33 | 5.2. Field Lines and Combined Field Value | |||
5.3. Field Order . . . . . . . . . . . . . . . . . . . . . . . 34 | 5.3. Field Order | |||
5.4. Field Limits . . . . . . . . . . . . . . . . . . . . . . 35 | 5.4. Field Limits | |||
5.5. Field Values . . . . . . . . . . . . . . . . . . . . . . 35 | 5.5. Field Values | |||
5.6. Common Rules for Defining Field Values . . . . . . . . . 37 | 5.6. Common Rules for Defining Field Values | |||
5.6.1. Lists (#rule ABNF Extension) . . . . . . . . . . . . 37 | 5.6.1. Lists (#rule ABNF Extension) | |||
5.6.1.1. Sender Requirements . . . . . . . . . . . . . . . 37 | 5.6.1.1. Sender Requirements | |||
5.6.1.2. Recipient Requirements . . . . . . . . . . . . . 38 | 5.6.1.2. Recipient Requirements | |||
5.6.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 38 | 5.6.2. Tokens | |||
5.6.3. Whitespace . . . . . . . . . . . . . . . . . . . . . 39 | 5.6.3. Whitespace | |||
5.6.4. Quoted Strings . . . . . . . . . . . . . . . . . . . 39 | 5.6.4. Quoted Strings | |||
5.6.5. Comments . . . . . . . . . . . . . . . . . . . . . . 40 | 5.6.5. Comments | |||
5.6.6. Parameters . . . . . . . . . . . . . . . . . . . . . 40 | 5.6.6. Parameters | |||
5.6.7. Date/Time Formats . . . . . . . . . . . . . . . . . . 41 | 5.6.7. Date/Time Formats | |||
6. Message Abstraction . . . . . . . . . . . . . . . . . . . . . 43 | 6. Message Abstraction | |||
6.1. Framing and Completeness . . . . . . . . . . . . . . . . 44 | 6.1. Framing and Completeness | |||
6.2. Control Data . . . . . . . . . . . . . . . . . . . . . . 45 | 6.2. Control Data | |||
6.3. Header Fields . . . . . . . . . . . . . . . . . . . . . . 46 | 6.3. Header Fields | |||
6.4. Content . . . . . . . . . . . . . . . . . . . . . . . . . 46 | 6.4. Content | |||
6.4.1. Content Semantics . . . . . . . . . . . . . . . . . . 46 | 6.4.1. Content Semantics | |||
6.4.2. Identifying Content . . . . . . . . . . . . . . . . . 47 | 6.4.2. Identifying Content | |||
6.5. Trailer Fields . . . . . . . . . . . . . . . . . . . . . 49 | 6.5. Trailer Fields | |||
6.5.1. Limitations on use of Trailers . . . . . . . . . . . 49 | 6.5.1. Limitations on Use of Trailers | |||
6.5.2. Processing Trailer Fields . . . . . . . . . . . . . . 50 | 6.5.2. Processing Trailer Fields | |||
6.6. Message Metadata . . . . . . . . . . . . . . . . . . . . 50 | 6.6. Message Metadata | |||
6.6.1. Date . . . . . . . . . . . . . . . . . . . . . . . . 51 | 6.6.1. Date | |||
6.6.2. Trailer . . . . . . . . . . . . . . . . . . . . . . . 52 | 6.6.2. Trailer | |||
7. Routing HTTP Messages . . . . . . . . . . . . . . . . . . . . 52 | 7. Routing HTTP Messages | |||
7.1. Determining the Target Resource . . . . . . . . . . . . . 52 | 7.1. Determining the Target Resource | |||
7.2. Host and :authority . . . . . . . . . . . . . . . . . . . 53 | 7.2. Host and :authority | |||
7.3. Routing Inbound Requests . . . . . . . . . . . . . . . . 54 | 7.3. Routing Inbound Requests | |||
7.3.1. To a Cache . . . . . . . . . . . . . . . . . . . . . 54 | 7.3.1. To a Cache | |||
7.3.2. To a Proxy . . . . . . . . . . . . . . . . . . . . . 54 | 7.3.2. To a Proxy | |||
7.3.3. To the Origin . . . . . . . . . . . . . . . . . . . . 54 | 7.3.3. To the Origin | |||
7.4. Rejecting Misdirected Requests . . . . . . . . . . . . . 55 | 7.4. Rejecting Misdirected Requests | |||
7.5. Response Correlation . . . . . . . . . . . . . . . . . . 55 | 7.5. Response Correlation | |||
7.6. Message Forwarding . . . . . . . . . . . . . . . . . . . 56 | 7.6. Message Forwarding | |||
7.6.1. Connection . . . . . . . . . . . . . . . . . . . . . 56 | 7.6.1. Connection | |||
7.6.2. Max-Forwards . . . . . . . . . . . . . . . . . . . . 58 | 7.6.2. Max-Forwards | |||
7.6.3. Via . . . . . . . . . . . . . . . . . . . . . . . . . 59 | 7.6.3. Via | |||
7.7. Message Transformations . . . . . . . . . . . . . . . . . 60 | 7.7. Message Transformations | |||
7.8. Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . 61 | 7.8. Upgrade | |||
8. Representation Data and Metadata . . . . . . . . . . . . . . 64 | 8. Representation Data and Metadata | |||
8.1. Representation Data . . . . . . . . . . . . . . . . . . . 64 | 8.1. Representation Data | |||
8.2. Representation Metadata . . . . . . . . . . . . . . . . . 64 | 8.2. Representation Metadata | |||
8.3. Content-Type . . . . . . . . . . . . . . . . . . . . . . 64 | 8.3. Content-Type | |||
8.3.1. Media Type . . . . . . . . . . . . . . . . . . . . . 65 | 8.3.1. Media Type | |||
8.3.2. Charset . . . . . . . . . . . . . . . . . . . . . . . 66 | 8.3.2. Charset | |||
8.3.3. Multipart Types . . . . . . . . . . . . . . . . . . . 66 | 8.3.3. Multipart Types | |||
8.4. Content-Encoding . . . . . . . . . . . . . . . . . . . . 67 | 8.4. Content-Encoding | |||
8.4.1. Content Codings . . . . . . . . . . . . . . . . . . . 68 | 8.4.1. Content Codings | |||
8.4.1.1. Compress Coding . . . . . . . . . . . . . . . . . 68 | 8.4.1.1. Compress Coding | |||
8.4.1.2. Deflate Coding . . . . . . . . . . . . . . . . . 68 | 8.4.1.2. Deflate Coding | |||
8.4.1.3. Gzip Coding . . . . . . . . . . . . . . . . . . . 69 | 8.4.1.3. Gzip Coding | |||
8.5. Content-Language . . . . . . . . . . . . . . . . . . . . 69 | 8.5. Content-Language | |||
8.5.1. Language Tags . . . . . . . . . . . . . . . . . . . . 70 | 8.5.1. Language Tags | |||
8.6. Content-Length . . . . . . . . . . . . . . . . . . . . . 70 | 8.6. Content-Length | |||
8.7. Content-Location . . . . . . . . . . . . . . . . . . . . 72 | 8.7. Content-Location | |||
8.8. Validator Fields . . . . . . . . . . . . . . . . . . . . 74 | 8.8. Validator Fields | |||
8.8.1. Weak versus Strong . . . . . . . . . . . . . . . . . 74 | 8.8.1. Weak versus Strong | |||
8.8.2. Last-Modified . . . . . . . . . . . . . . . . . . . . 76 | 8.8.2. Last-Modified | |||
8.8.2.1. Generation . . . . . . . . . . . . . . . . . . . 76 | 8.8.2.1. Generation | |||
8.8.2.2. Comparison . . . . . . . . . . . . . . . . . . . 77 | 8.8.2.2. Comparison | |||
8.8.3. ETag . . . . . . . . . . . . . . . . . . . . . . . . 78 | 8.8.3. ETag | |||
8.8.3.1. Generation . . . . . . . . . . . . . . . . . . . 79 | 8.8.3.1. Generation | |||
8.8.3.2. Comparison . . . . . . . . . . . . . . . . . . . 80 | 8.8.3.2. Comparison | |||
8.8.3.3. Example: Entity-Tags Varying on Content-Negotiated | 8.8.3.3. Example: Entity Tags Varying on Content-Negotiated | |||
Resources . . . . . . . . . . . . . . . . . . . . . 80 | Resources | |||
9. Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 | 9. Methods | |||
9.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 81 | 9.1. Overview | |||
9.2. Common Method Properties . . . . . . . . . . . . . . . . 84 | 9.2. Common Method Properties | |||
9.2.1. Safe Methods . . . . . . . . . . . . . . . . . . . . 84 | 9.2.1. Safe Methods | |||
9.2.2. Idempotent Methods . . . . . . . . . . . . . . . . . 85 | 9.2.2. Idempotent Methods | |||
9.2.3. Methods and Caching . . . . . . . . . . . . . . . . . 86 | 9.2.3. Methods and Caching | |||
9.3. Method Definitions . . . . . . . . . . . . . . . . . . . 86 | 9.3. Method Definitions | |||
9.3.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 86 | 9.3.1. GET | |||
9.3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 87 | 9.3.2. HEAD | |||
9.3.3. POST . . . . . . . . . . . . . . . . . . . . . . . . 88 | 9.3.3. POST | |||
9.3.4. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 89 | 9.3.4. PUT | |||
9.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 92 | 9.3.5. DELETE | |||
9.3.6. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 94 | 9.3.6. CONNECT | |||
9.3.7. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 95 | 9.3.7. OPTIONS | |||
9.3.8. TRACE . . . . . . . . . . . . . . . . . . . . . . . . 96 | 9.3.8. TRACE | |||
10. Message Context . . . . . . . . . . . . . . . . . . . . . . . 97 | 10. Message Context | |||
10.1. Request Context Fields . . . . . . . . . . . . . . . . . 97 | 10.1. Request Context Fields | |||
10.1.1. Expect . . . . . . . . . . . . . . . . . . . . . . . 97 | 10.1.1. Expect | |||
10.1.2. From . . . . . . . . . . . . . . . . . . . . . . . . 99 | 10.1.2. From | |||
10.1.3. Referer . . . . . . . . . . . . . . . . . . . . . . 100 | 10.1.3. Referer | |||
10.1.4. TE . . . . . . . . . . . . . . . . . . . . . . . . . 101 | 10.1.4. TE | |||
10.1.5. User-Agent . . . . . . . . . . . . . . . . . . . . . 102 | 10.1.5. User-Agent | |||
10.2. Response Context Fields . . . . . . . . . . . . . . . . 103 | 10.2. Response Context Fields | |||
10.2.1. Allow . . . . . . . . . . . . . . . . . . . . . . . 103 | 10.2.1. Allow | |||
10.2.2. Location . . . . . . . . . . . . . . . . . . . . . . 104 | 10.2.2. Location | |||
10.2.3. Retry-After . . . . . . . . . . . . . . . . . . . . 105 | 10.2.3. Retry-After | |||
10.2.4. Server . . . . . . . . . . . . . . . . . . . . . . . 106 | 10.2.4. Server | |||
11. HTTP Authentication . . . . . . . . . . . . . . . . . . . . . 106 | 11. HTTP Authentication | |||
11.1. Authentication Scheme . . . . . . . . . . . . . . . . . 106 | 11.1. Authentication Scheme | |||
11.2. Authentication Parameters . . . . . . . . . . . . . . . 107 | 11.2. Authentication Parameters | |||
11.3. Challenge and Response . . . . . . . . . . . . . . . . . 107 | 11.3. Challenge and Response | |||
11.4. Credentials . . . . . . . . . . . . . . . . . . . . . . 108 | 11.4. Credentials | |||
11.5. Establishing a Protection Space (Realm) . . . . . . . . 109 | 11.5. Establishing a Protection Space (Realm) | |||
11.6. Authenticating Users to Origin Servers . . . . . . . . . 110 | 11.6. Authenticating Users to Origin Servers | |||
11.6.1. WWW-Authenticate . . . . . . . . . . . . . . . . . . 110 | 11.6.1. WWW-Authenticate | |||
11.6.2. Authorization . . . . . . . . . . . . . . . . . . . 111 | 11.6.2. Authorization | |||
11.6.3. Authentication-Info . . . . . . . . . . . . . . . . 111 | 11.6.3. Authentication-Info | |||
11.7. Authenticating Clients to Proxies . . . . . . . . . . . 112 | 11.7. Authenticating Clients to Proxies | |||
11.7.1. Proxy-Authenticate . . . . . . . . . . . . . . . . . 112 | 11.7.1. Proxy-Authenticate | |||
11.7.2. Proxy-Authorization . . . . . . . . . . . . . . . . 112 | 11.7.2. Proxy-Authorization | |||
11.7.3. Proxy-Authentication-Info . . . . . . . . . . . . . 113 | 11.7.3. Proxy-Authentication-Info | |||
12. Content Negotiation . . . . . . . . . . . . . . . . . . . . . 113 | 12. Content Negotiation | |||
12.1. Proactive Negotiation . . . . . . . . . . . . . . . . . 114 | 12.1. Proactive Negotiation | |||
12.2. Reactive Negotiation . . . . . . . . . . . . . . . . . . 115 | 12.2. Reactive Negotiation | |||
12.3. Request Content Negotiation . . . . . . . . . . . . . . 116 | 12.3. Request Content Negotiation | |||
12.4. Content Negotiation Field Features . . . . . . . . . . . 116 | 12.4. Content Negotiation Field Features | |||
12.4.1. Absence . . . . . . . . . . . . . . . . . . . . . . 116 | 12.4.1. Absence | |||
12.4.2. Quality Values . . . . . . . . . . . . . . . . . . . 117 | 12.4.2. Quality Values | |||
12.4.3. Wildcard Values . . . . . . . . . . . . . . . . . . 117 | 12.4.3. Wildcard Values | |||
12.5. Content Negotiation Fields . . . . . . . . . . . . . . . 118 | 12.5. Content Negotiation Fields | |||
12.5.1. Accept . . . . . . . . . . . . . . . . . . . . . . . 118 | 12.5.1. Accept | |||
12.5.2. Accept-Charset . . . . . . . . . . . . . . . . . . . 120 | 12.5.2. Accept-Charset | |||
12.5.3. Accept-Encoding . . . . . . . . . . . . . . . . . . 121 | 12.5.3. Accept-Encoding | |||
12.5.4. Accept-Language . . . . . . . . . . . . . . . . . . 123 | 12.5.4. Accept-Language | |||
12.5.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . 124 | 12.5.5. Vary | |||
13. Conditional Requests . . . . . . . . . . . . . . . . . . . . 125 | 13. Conditional Requests | |||
13.1. Preconditions . . . . . . . . . . . . . . . . . . . . . 125 | 13.1. Preconditions | |||
13.1.1. If-Match . . . . . . . . . . . . . . . . . . . . . . 126 | 13.1.1. If-Match | |||
13.1.2. If-None-Match . . . . . . . . . . . . . . . . . . . 128 | 13.1.2. If-None-Match | |||
13.1.3. If-Modified-Since . . . . . . . . . . . . . . . . . 130 | 13.1.3. If-Modified-Since | |||
13.1.4. If-Unmodified-Since . . . . . . . . . . . . . . . . 132 | 13.1.4. If-Unmodified-Since | |||
13.1.5. If-Range . . . . . . . . . . . . . . . . . . . . . . 133 | 13.1.5. If-Range | |||
13.2. Evaluation of Preconditions . . . . . . . . . . . . . . 135 | 13.2. Evaluation of Preconditions | |||
13.2.1. When to Evaluate . . . . . . . . . . . . . . . . . . 135 | 13.2.1. When to Evaluate | |||
13.2.2. Precedence of Preconditions . . . . . . . . . . . . 136 | 13.2.2. Precedence of Preconditions | |||
14. Range Requests . . . . . . . . . . . . . . . . . . . . . . . 137 | 14. Range Requests | |||
14.1. Range Units . . . . . . . . . . . . . . . . . . . . . . 138 | 14.1. Range Units | |||
14.1.1. Range Specifiers . . . . . . . . . . . . . . . . . . 138 | 14.1.1. Range Specifiers | |||
14.1.2. Byte Ranges . . . . . . . . . . . . . . . . . . . . 139 | 14.1.2. Byte Ranges | |||
14.2. Range . . . . . . . . . . . . . . . . . . . . . . . . . 141 | 14.2. Range | |||
14.3. Accept-Ranges . . . . . . . . . . . . . . . . . . . . . 142 | 14.3. Accept-Ranges | |||
14.4. Content-Range . . . . . . . . . . . . . . . . . . . . . 143 | 14.4. Content-Range | |||
14.5. Partial PUT . . . . . . . . . . . . . . . . . . . . . . 145 | 14.5. Partial PUT | |||
14.6. Media Type multipart/byteranges . . . . . . . . . . . . 146 | 14.6. Media Type multipart/byteranges | |||
15. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . 148 | 15. Status Codes | |||
15.1. Overview of Status Codes . . . . . . . . . . . . . . . . 149 | 15.1. Overview of Status Codes | |||
15.2. Informational 1xx . . . . . . . . . . . . . . . . . . . 149 | 15.2. Informational 1xx | |||
15.2.1. 100 Continue . . . . . . . . . . . . . . . . . . . . 150 | 15.2.1. 100 Continue | |||
15.2.2. 101 Switching Protocols . . . . . . . . . . . . . . 150 | 15.2.2. 101 Switching Protocols | |||
15.3. Successful 2xx . . . . . . . . . . . . . . . . . . . . . 150 | 15.3. Successful 2xx | |||
15.3.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . 150 | 15.3.1. 200 OK | |||
15.3.2. 201 Created . . . . . . . . . . . . . . . . . . . . 152 | 15.3.2. 201 Created | |||
15.3.3. 202 Accepted . . . . . . . . . . . . . . . . . . . . 152 | 15.3.3. 202 Accepted | |||
15.3.4. 203 Non-Authoritative Information . . . . . . . . . 152 | 15.3.4. 203 Non-Authoritative Information | |||
15.3.5. 204 No Content . . . . . . . . . . . . . . . . . . . 153 | 15.3.5. 204 No Content | |||
15.3.6. 205 Reset Content . . . . . . . . . . . . . . . . . 153 | 15.3.6. 205 Reset Content | |||
15.3.7. 206 Partial Content . . . . . . . . . . . . . . . . 154 | 15.3.7. 206 Partial Content | |||
15.3.7.1. Single Part . . . . . . . . . . . . . . . . . . 155 | 15.3.7.1. Single Part | |||
15.3.7.2. Multiple Parts . . . . . . . . . . . . . . . . . 155 | 15.3.7.2. Multiple Parts | |||
15.3.7.3. Combining Parts . . . . . . . . . . . . . . . . 157 | 15.3.7.3. Combining Parts | |||
15.4. Redirection 3xx . . . . . . . . . . . . . . . . . . . . 157 | 15.4. Redirection 3xx | |||
15.4.1. 300 Multiple Choices . . . . . . . . . . . . . . . . 159 | 15.4.1. 300 Multiple Choices | |||
15.4.2. 301 Moved Permanently . . . . . . . . . . . . . . . 160 | 15.4.2. 301 Moved Permanently | |||
15.4.3. 302 Found . . . . . . . . . . . . . . . . . . . . . 161 | 15.4.3. 302 Found | |||
15.4.4. 303 See Other . . . . . . . . . . . . . . . . . . . 161 | 15.4.4. 303 See Other | |||
15.4.5. 304 Not Modified . . . . . . . . . . . . . . . . . . 162 | 15.4.5. 304 Not Modified | |||
15.4.6. 305 Use Proxy . . . . . . . . . . . . . . . . . . . 163 | 15.4.6. 305 Use Proxy | |||
15.4.7. 306 (Unused) . . . . . . . . . . . . . . . . . . . . 163 | 15.4.7. 306 (Unused) | |||
15.4.8. 307 Temporary Redirect . . . . . . . . . . . . . . . 163 | 15.4.8. 307 Temporary Redirect | |||
15.4.9. 308 Permanent Redirect . . . . . . . . . . . . . . . 163 | 15.4.9. 308 Permanent Redirect | |||
15.5. Client Error 4xx . . . . . . . . . . . . . . . . . . . . 164 | 15.5. Client Error 4xx | |||
15.5.1. 400 Bad Request . . . . . . . . . . . . . . . . . . 164 | 15.5.1. 400 Bad Request | |||
15.5.2. 401 Unauthorized . . . . . . . . . . . . . . . . . . 164 | 15.5.2. 401 Unauthorized | |||
15.5.3. 402 Payment Required . . . . . . . . . . . . . . . . 165 | 15.5.3. 402 Payment Required | |||
15.5.4. 403 Forbidden . . . . . . . . . . . . . . . . . . . 165 | 15.5.4. 403 Forbidden | |||
15.5.5. 404 Not Found . . . . . . . . . . . . . . . . . . . 165 | 15.5.5. 404 Not Found | |||
15.5.6. 405 Method Not Allowed . . . . . . . . . . . . . . . 165 | 15.5.6. 405 Method Not Allowed | |||
15.5.7. 406 Not Acceptable . . . . . . . . . . . . . . . . . 166 | 15.5.7. 406 Not Acceptable | |||
15.5.8. 407 Proxy Authentication Required . . . . . . . . . 166 | 15.5.8. 407 Proxy Authentication Required | |||
15.5.9. 408 Request Timeout . . . . . . . . . . . . . . . . 166 | 15.5.9. 408 Request Timeout | |||
15.5.10. 409 Conflict . . . . . . . . . . . . . . . . . . . . 166 | 15.5.10. 409 Conflict | |||
15.5.11. 410 Gone . . . . . . . . . . . . . . . . . . . . . . 167 | 15.5.11. 410 Gone | |||
15.5.12. 411 Length Required . . . . . . . . . . . . . . . . 167 | 15.5.12. 411 Length Required | |||
15.5.13. 412 Precondition Failed . . . . . . . . . . . . . . 167 | 15.5.13. 412 Precondition Failed | |||
15.5.14. 413 Content Too Large . . . . . . . . . . . . . . . 168 | 15.5.14. 413 Content Too Large | |||
15.5.15. 414 URI Too Long . . . . . . . . . . . . . . . . . . 168 | 15.5.15. 414 URI Too Long | |||
15.5.16. 415 Unsupported Media Type . . . . . . . . . . . . . 168 | 15.5.16. 415 Unsupported Media Type | |||
15.5.17. 416 Range Not Satisfiable . . . . . . . . . . . . . 169 | 15.5.17. 416 Range Not Satisfiable | |||
15.5.18. 417 Expectation Failed . . . . . . . . . . . . . . . 169 | 15.5.18. 417 Expectation Failed | |||
15.5.19. 418 (Unused) . . . . . . . . . . . . . . . . . . . . 169 | 15.5.19. 418 (Unused) | |||
15.5.20. 421 Misdirected Request . . . . . . . . . . . . . . 170 | 15.5.20. 421 Misdirected Request | |||
15.5.21. 422 Unprocessable Content . . . . . . . . . . . . . 170 | 15.5.21. 422 Unprocessable Content | |||
15.5.22. 426 Upgrade Required . . . . . . . . . . . . . . . . 170 | 15.5.22. 426 Upgrade Required | |||
15.6. Server Error 5xx . . . . . . . . . . . . . . . . . . . . 171 | 15.6. Server Error 5xx | |||
15.6.1. 500 Internal Server Error . . . . . . . . . . . . . 171 | 15.6.1. 500 Internal Server Error | |||
15.6.2. 501 Not Implemented . . . . . . . . . . . . . . . . 171 | 15.6.2. 501 Not Implemented | |||
15.6.3. 502 Bad Gateway . . . . . . . . . . . . . . . . . . 171 | 15.6.3. 502 Bad Gateway | |||
15.6.4. 503 Service Unavailable . . . . . . . . . . . . . . 172 | 15.6.4. 503 Service Unavailable | |||
15.6.5. 504 Gateway Timeout . . . . . . . . . . . . . . . . 172 | 15.6.5. 504 Gateway Timeout | |||
15.6.6. 505 HTTP Version Not Supported . . . . . . . . . . . 172 | 15.6.6. 505 HTTP Version Not Supported | |||
16. Extending HTTP . . . . . . . . . . . . . . . . . . . . . . . 172 | 16. Extending HTTP | |||
16.1. Method Extensibility . . . . . . . . . . . . . . . . . . 173 | 16.1. Method Extensibility | |||
16.1.1. Method Registry . . . . . . . . . . . . . . . . . . 173 | 16.1.1. Method Registry | |||
16.1.2. Considerations for New Methods . . . . . . . . . . . 173 | 16.1.2. Considerations for New Methods | |||
16.2. Status Code Extensibility . . . . . . . . . . . . . . . 174 | 16.2. Status Code Extensibility | |||
16.2.1. Status Code Registry . . . . . . . . . . . . . . . . 174 | 16.2.1. Status Code Registry | |||
16.2.2. Considerations for New Status Codes . . . . . . . . 175 | 16.2.2. Considerations for New Status Codes | |||
16.3. Field Extensibility . . . . . . . . . . . . . . . . . . 176 | 16.3. Field Extensibility | |||
16.3.1. Field Name Registry . . . . . . . . . . . . . . . . 176 | 16.3.1. Field Name Registry | |||
16.3.2. Considerations for New Fields . . . . . . . . . . . 177 | 16.3.2. Considerations for New Fields | |||
16.3.2.1. Considerations for New Field Names . . . . . . . 178 | 16.3.2.1. Considerations for New Field Names | |||
16.3.2.2. Considerations for New Field Values . . . . . . 179 | 16.3.2.2. Considerations for New Field Values | |||
16.4. Authentication Scheme Extensibility | ||||
16.4. Authentication Scheme Extensibility . . . . . . . . . . 180 | 16.4.1. Authentication Scheme Registry | |||
16.4.1. Authentication Scheme Registry . . . . . . . . . . . 180 | 16.4.2. Considerations for New Authentication Schemes | |||
16.4.2. Considerations for New Authentication Schemes . . . 180 | 16.5. Range Unit Extensibility | |||
16.5. Range Unit Extensibility . . . . . . . . . . . . . . . . 182 | 16.5.1. Range Unit Registry | |||
16.5.1. Range Unit Registry . . . . . . . . . . . . . . . . 182 | 16.5.2. Considerations for New Range Units | |||
16.5.2. Considerations for New Range Units . . . . . . . . . 182 | 16.6. Content Coding Extensibility | |||
16.6. Content Coding Extensibility . . . . . . . . . . . . . . 182 | 16.6.1. Content Coding Registry | |||
16.6.1. Content Coding Registry . . . . . . . . . . . . . . 182 | 16.6.2. Considerations for New Content Codings | |||
16.6.2. Considerations for New Content Codings . . . . . . . 183 | 16.7. Upgrade Token Registry | |||
16.7. Upgrade Token Registry . . . . . . . . . . . . . . . . . 183 | 17. Security Considerations | |||
17. Security Considerations . . . . . . . . . . . . . . . . . . . 184 | 17.1. Establishing Authority | |||
17.1. Establishing Authority . . . . . . . . . . . . . . . . . 184 | 17.2. Risks of Intermediaries | |||
17.2. Risks of Intermediaries . . . . . . . . . . . . . . . . 185 | 17.3. Attacks Based on File and Path Names | |||
17.3. Attacks Based on File and Path Names . . . . . . . . . . 186 | 17.4. Attacks Based on Command, Code, or Query Injection | |||
17.4. Attacks Based on Command, Code, or Query Injection . . . 186 | 17.5. Attacks via Protocol Element Length | |||
17.5. Attacks via Protocol Element Length . . . . . . . . . . 187 | 17.6. Attacks Using Shared-Dictionary Compression | |||
17.6. Attacks using Shared-dictionary Compression . . . . . . 188 | 17.7. Disclosure of Personal Information | |||
17.7. Disclosure of Personal Information . . . . . . . . . . . 188 | 17.8. Privacy of Server Log Information | |||
17.8. Privacy of Server Log Information . . . . . . . . . . . 188 | 17.9. Disclosure of Sensitive Information in URIs | |||
17.9. Disclosure of Sensitive Information in URIs . . . . . . 189 | 17.10. Application Handling of Field Names | |||
17.10. Application Handling of Field Names . . . . . . . . . . 189 | 17.11. Disclosure of Fragment after Redirects | |||
17.11. Disclosure of Fragment after Redirects . . . . . . . . . 190 | 17.12. Disclosure of Product Information | |||
17.12. Disclosure of Product Information . . . . . . . . . . . 191 | 17.13. Browser Fingerprinting | |||
17.13. Browser Fingerprinting . . . . . . . . . . . . . . . . . 191 | 17.14. Validator Retention | |||
17.14. Validator Retention . . . . . . . . . . . . . . . . . . 192 | 17.15. Denial-of-Service Attacks Using Range | |||
17.15. Denial-of-Service Attacks Using Range . . . . . . . . . 192 | 17.16. Authentication Considerations | |||
17.16. Authentication Considerations . . . . . . . . . . . . . 193 | 17.16.1. Confidentiality of Credentials | |||
17.16.1. Confidentiality of Credentials . . . . . . . . . . 193 | 17.16.2. Credentials and Idle Clients | |||
17.16.2. Credentials and Idle Clients . . . . . . . . . . . 193 | 17.16.3. Protection Spaces | |||
17.16.3. Protection Spaces . . . . . . . . . . . . . . . . . 194 | 17.16.4. Additional Response Fields | |||
17.16.4. Additional Response Fields . . . . . . . . . . . . 194 | 18. IANA Considerations | |||
18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 194 | 18.1. URI Scheme Registration | |||
18.1. URI Scheme Registration . . . . . . . . . . . . . . . . 195 | 18.2. Method Registration | |||
18.2. Method Registration . . . . . . . . . . . . . . . . . . 195 | 18.3. Status Code Registration | |||
18.3. Status Code Registration . . . . . . . . . . . . . . . . 195 | 18.4. Field Name Registration | |||
18.4. Field Name Registration . . . . . . . . . . . . . . . . 198 | 18.5. Authentication Scheme Registration | |||
18.5. Authentication Scheme Registration . . . . . . . . . . . 200 | 18.6. Content Coding Registration | |||
18.6. Content Coding Registration . . . . . . . . . . . . . . 201 | 18.7. Range Unit Registration | |||
18.7. Range Unit Registration . . . . . . . . . . . . . . . . 201 | 18.8. Media Type Registration | |||
18.8. Media Type Registration . . . . . . . . . . . . . . . . 202 | 18.9. Port Registration | |||
18.9. Port Registration . . . . . . . . . . . . . . . . . . . 202 | 18.10. Upgrade Token Registration | |||
18.10. Upgrade Token Registration . . . . . . . . . . . . . . . 202 | 19. References | |||
19. References . . . . . . . . . . . . . . . . . . . . . . . . . 202 | 19.1. Normative References | |||
19.1. Normative References . . . . . . . . . . . . . . . . . . 202 | 19.2. Informative References | |||
19.2. Informative References . . . . . . . . . . . . . . . . . 204 | Appendix A. Collected ABNF | |||
Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 211 | Appendix B. Changes from Previous RFCs | |||
Appendix B. Changes from previous RFCs . . . . . . . . . . . . . 215 | B.1. Changes from RFC 2818 | |||
B.1. Changes from RFC 2818 . . . . . . . . . . . . . . . . . . 215 | B.2. Changes from RFC 7230 | |||
B.2. Changes from RFC 7230 . . . . . . . . . . . . . . . . . . 215 | B.3. Changes from RFC 7231 | |||
B.3. Changes from RFC 7231 . . . . . . . . . . . . . . . . . . 216 | B.4. Changes from RFC 7232 | |||
B.4. Changes from RFC 7232 . . . . . . . . . . . . . . . . . . 218 | B.5. Changes from RFC 7233 | |||
B.5. Changes from RFC 7233 . . . . . . . . . . . . . . . . . . 219 | B.6. Changes from RFC 7235 | |||
B.6. Changes from RFC 7235 . . . . . . . . . . . . . . . . . . 219 | B.7. Changes from RFC 7538 | |||
B.7. Changes from RFC 7538 . . . . . . . . . . . . . . . . . . 219 | B.8. Changes from RFC 7615 | |||
B.8. Changes from RFC 7615 . . . . . . . . . . . . . . . . . . 219 | B.9. Changes from RFC 7694 | |||
B.9. Changes from RFC 7694 . . . . . . . . . . . . . . . . . . 219 | Acknowledgements | |||
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 219 | Index | |||
C.1. Between RFC723x and draft 00 . . . . . . . . . . . . . . 219 | Authors' Addresses | |||
C.2. Since draft-ietf-httpbis-semantics-00 . . . . . . . . . . 220 | ||||
C.3. Since draft-ietf-httpbis-semantics-01 . . . . . . . . . . 220 | ||||
C.4. Since draft-ietf-httpbis-semantics-02 . . . . . . . . . . 222 | ||||
C.5. Since draft-ietf-httpbis-semantics-03 . . . . . . . . . . 223 | ||||
C.6. Since draft-ietf-httpbis-semantics-04 . . . . . . . . . . 223 | ||||
C.7. Since draft-ietf-httpbis-semantics-05 . . . . . . . . . . 224 | ||||
C.8. Since draft-ietf-httpbis-semantics-06 . . . . . . . . . . 225 | ||||
C.9. Since draft-ietf-httpbis-semantics-07 . . . . . . . . . . 227 | ||||
C.10. Since draft-ietf-httpbis-semantics-08 . . . . . . . . . . 228 | ||||
C.11. Since draft-ietf-httpbis-semantics-09 . . . . . . . . . . 229 | ||||
C.12. Since draft-ietf-httpbis-semantics-10 . . . . . . . . . . 229 | ||||
C.13. Since draft-ietf-httpbis-semantics-11 . . . . . . . . . . 231 | ||||
C.14. Since draft-ietf-httpbis-semantics-12 . . . . . . . . . . 231 | ||||
C.15. Since draft-ietf-httpbis-semantics-13 . . . . . . . . . . 233 | ||||
C.16. Since draft-ietf-httpbis-semantics-14 . . . . . . . . . . 234 | ||||
C.17. Since draft-ietf-httpbis-semantics-15 . . . . . . . . . . 236 | ||||
C.18. Since draft-ietf-httpbis-semantics-16 . . . . . . . . . . 237 | ||||
C.19. Since draft-ietf-httpbis-semantics-17 . . . . . . . . . . 237 | ||||
C.20. Since draft-ietf-httpbis-semantics-18 . . . . . . . . . . 239 | ||||
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 240 | ||||
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 | ||||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 252 | ||||
1. Introduction | 1. Introduction | |||
1.1. Purpose | 1.1. Purpose | |||
The Hypertext Transfer Protocol (HTTP) is a family of stateless, | The Hypertext Transfer Protocol (HTTP) is a family of stateless, | |||
application-level, request/response protocols that share a generic | application-level, request/response protocols that share a generic | |||
interface, extensible semantics, and self-descriptive messages to | interface, extensible semantics, and self-descriptive messages to | |||
enable flexible interaction with network-based hypertext information | enable flexible interaction with network-based hypertext information | |||
systems. | systems. | |||
skipping to change at page 10, line 43 ¶ | skipping to change at line 430 ¶ | |||
and HTTP/1.0 (see [HTTP/1.0]). | and HTTP/1.0 (see [HTTP/1.0]). | |||
HTTP/1.1 was designed to refine the protocol's features while | HTTP/1.1 was designed to refine the protocol's features while | |||
retaining compatibility with the existing text-based messaging | retaining compatibility with the existing text-based messaging | |||
syntax, improving its interoperability, scalability, and robustness | syntax, improving its interoperability, scalability, and robustness | |||
across the Internet. This included length-based data delimiters for | across the Internet. This included length-based data delimiters for | |||
both fixed and dynamic (chunked) content, a consistent framework for | both fixed and dynamic (chunked) content, a consistent framework for | |||
content negotiation, opaque validators for conditional requests, | content negotiation, opaque validators for conditional requests, | |||
cache controls for better cache consistency, range requests for | cache controls for better cache consistency, range requests for | |||
partial updates, and default persistent connections. HTTP/1.1 was | partial updates, and default persistent connections. HTTP/1.1 was | |||
introduced in 1995 and published on the standards track in 1997 | introduced in 1995 and published on the Standards Track in 1997 | |||
[RFC2068], revised in 1999 [RFC2616], and revised again in 2014 | [RFC2068], revised in 1999 [RFC2616], and revised again in 2014 | |||
([RFC7230] - [RFC7235]). | ([RFC7230] through [RFC7235]). | |||
HTTP/2 ([HTTP/2]) introduced a multiplexed session layer on top of | HTTP/2 ([HTTP/2]) introduced a multiplexed session layer on top of | |||
the existing TLS and TCP protocols for exchanging concurrent HTTP | the existing TLS and TCP protocols for exchanging concurrent HTTP | |||
messages with efficient field compression and server push. HTTP/3 | messages with efficient field compression and server push. HTTP/3 | |||
([HTTP/3]) provides greater independence for concurrent messages by | ([HTTP/3]) provides greater independence for concurrent messages by | |||
using QUIC as a secure multiplexed transport over UDP instead of TCP. | using QUIC as a secure multiplexed transport over UDP instead of TCP. | |||
All three major versions of HTTP rely on the semantics defined by | All three major versions of HTTP rely on the semantics defined by | |||
this document. They have not obsoleted each other because each one | this document. They have not obsoleted each other because each one | |||
has specific benefits and limitations depending on the context of | has specific benefits and limitations depending on the context of | |||
skipping to change at page 11, line 19 ¶ | skipping to change at line 454 ¶ | |||
transport and messaging syntax for their particular context. | transport and messaging syntax for their particular context. | |||
This revision of HTTP separates the definition of semantics (this | This revision of HTTP separates the definition of semantics (this | |||
document) and caching ([CACHING]) from the current HTTP/1.1 messaging | document) and caching ([CACHING]) from the current HTTP/1.1 messaging | |||
syntax ([HTTP/1.1]) to allow each major protocol version to progress | syntax ([HTTP/1.1]) to allow each major protocol version to progress | |||
independently while referring to the same core semantics. | independently while referring to the same core semantics. | |||
1.3. Core Semantics | 1.3. Core Semantics | |||
HTTP provides a uniform interface for interacting with a resource | HTTP provides a uniform interface for interacting with a resource | |||
(Section 3.1) - regardless of its type, nature, or implementation - | (Section 3.1) -- regardless of its type, nature, or implementation -- | |||
by sending messages that manipulate or transfer representations | by sending messages that manipulate or transfer representations | |||
(Section 3.2). | (Section 3.2). | |||
Each message is either a request or a response. A client constructs | Each message is either a request or a response. A client constructs | |||
request messages that communicate its intentions and routes those | request messages that communicate its intentions and routes those | |||
messages toward an identified origin server. A server listens for | messages toward an identified origin server. A server listens for | |||
requests, parses each message received, interprets the message | requests, parses each message received, interprets the message | |||
semantics in relation to the identified target resource, and responds | semantics in relation to the identified target resource, and responds | |||
to that request with one or more response messages. The client | to that request with one or more response messages. The client | |||
examines received responses to see if its intentions were carried | examines received responses to see if its intentions were carried | |||
skipping to change at page 11, line 42 ¶ | skipping to change at line 477 ¶ | |||
HTTP semantics include the intentions defined by each request method | HTTP semantics include the intentions defined by each request method | |||
(Section 9), extensions to those semantics that might be described in | (Section 9), extensions to those semantics that might be described in | |||
request header fields, status codes that describe the response | request header fields, status codes that describe the response | |||
(Section 15), and other control data and resource metadata that might | (Section 15), and other control data and resource metadata that might | |||
be given in response fields. | be given in response fields. | |||
Semantics also include representation metadata that describe how | Semantics also include representation metadata that describe how | |||
content is intended to be interpreted by a recipient, request header | content is intended to be interpreted by a recipient, request header | |||
fields that might influence content selection, and the various | 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 12). | negotiation" (Section 12). | |||
1.4. Specifications Obsoleted by this Document | ||||
This document obsoletes the following specifications: | 1.4. Specifications Obsoleted by This Document | |||
+============================================+===========+=========+ | +============================================+===========+=====+ | |||
| Title | Reference | Changes | | | Title | Reference | See | | |||
+============================================+===========+=========+ | +============================================+===========+=====+ | |||
| HTTP Over TLS | [RFC2818] | B.1 | | | HTTP Over TLS | [RFC2818] | B.1 | | |||
+--------------------------------------------+-----------+---------+ | +--------------------------------------------+-----------+-----+ | |||
| HTTP/1.1 Message Syntax and Routing [*] | [RFC7230] | B.2 | | | HTTP/1.1 Message Syntax and Routing [*] | [RFC7230] | B.2 | | |||
+--------------------------------------------+-----------+---------+ | +--------------------------------------------+-----------+-----+ | |||
| HTTP/1.1 Semantics and Content | [RFC7231] | B.3 | | | HTTP/1.1 Semantics and Content | [RFC7231] | B.3 | | |||
+--------------------------------------------+-----------+---------+ | +--------------------------------------------+-----------+-----+ | |||
| HTTP/1.1 Conditional Requests | [RFC7232] | B.4 | | | HTTP/1.1 Conditional Requests | [RFC7232] | B.4 | | |||
+--------------------------------------------+-----------+---------+ | +--------------------------------------------+-----------+-----+ | |||
| HTTP/1.1 Range Requests | [RFC7233] | B.5 | | | HTTP/1.1 Range Requests | [RFC7233] | B.5 | | |||
+--------------------------------------------+-----------+---------+ | +--------------------------------------------+-----------+-----+ | |||
| HTTP/1.1 Authentication | [RFC7235] | B.6 | | | HTTP/1.1 Authentication | [RFC7235] | B.6 | | |||
+--------------------------------------------+-----------+---------+ | +--------------------------------------------+-----------+-----+ | |||
| HTTP Status Code 308 (Permanent Redirect) | [RFC7538] | B.7 | | | HTTP Status Code 308 (Permanent Redirect) | [RFC7538] | B.7 | | |||
+--------------------------------------------+-----------+---------+ | +--------------------------------------------+-----------+-----+ | |||
| HTTP Authentication-Info and Proxy- | [RFC7615] | B.8 | | | HTTP Authentication-Info and Proxy- | [RFC7615] | B.8 | | |||
| Authentication-Info Response Header Fields | | | | | Authentication-Info Response Header Fields | | | | |||
+--------------------------------------------+-----------+---------+ | +--------------------------------------------+-----------+-----+ | |||
| HTTP Client-Initiated Content-Encoding | [RFC7694] | B.9 | | | HTTP Client-Initiated Content-Encoding | [RFC7694] | B.9 | | |||
+--------------------------------------------+-----------+---------+ | +--------------------------------------------+-----------+-----+ | |||
Table 1 | Table 1 | |||
[*] This document only obsoletes the portions of RFC 7230 that are | [*] This document only obsoletes the portions of RFC 7230 that are | |||
independent of the HTTP/1.1 messaging syntax and connection | independent of the HTTP/1.1 messaging syntax and connection | |||
management; the remaining bits of RFC 7230 are obsoleted by | management; the remaining bits of RFC 7230 are obsoleted by | |||
"HTTP/1.1" [HTTP/1.1]. | "HTTP/1.1" [HTTP/1.1]. | |||
2. Conformance | 2. Conformance | |||
2.1. Syntax Notation | 2.1. Syntax Notation | |||
This specification uses the Augmented Backus-Naur Form (ABNF) | This specification uses the Augmented Backus-Naur Form (ABNF) | |||
notation of [RFC5234], extended with the notation for case- | notation of [RFC5234], extended with the notation for case- | |||
sensitivity in strings defined in [RFC7405]. | sensitivity in strings defined in [RFC7405]. | |||
It also uses a list extension, defined in Section 5.6.1, that allows | It also uses a list extension, defined in Section 5.6.1, that allows | |||
for compact definition of comma-separated lists using a "#" operator | for compact definition of comma-separated lists using a "#" operator | |||
(similar to how the "*" operator indicates repetition). Appendix A | (similar to how the "*" operator indicates repetition). Appendix A | |||
shows the collected grammar with all list operators expanded to | shows the collected grammar with all list operators expanded to | |||
standard ABNF notation. | standard ABNF notation. | |||
As a convention, ABNF rule names prefixed with "obs-" denote | As a convention, ABNF rule names prefixed with "obs-" denote obsolete | |||
"obsolete" grammar rules that appear for historical reasons. | 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 5.6 defines some generic syntactic components for field | Section 5.6 defines some generic syntactic components for field | |||
values. | values. | |||
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.2. Requirements Notation | 2.2. 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", "NOT RECOMMENDED", "MAY", and | "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | |||
"OPTIONAL" in this document are to be interpreted as described in BCP | "OPTIONAL" in this document are to be interpreted as described in | |||
14 [RFC2119] [RFC8174] when, and only when, they appear in all | BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all | |||
capitals, as shown here. | capitals, as shown here. | |||
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, requirements are | of a participant in HTTP communication. Hence, 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 requirements are placed on implementations, resource | Additional requirements are placed on implementations, resource | |||
owners, and protocol element registrations when they apply beyond the | owners, and protocol element registrations when they apply beyond the | |||
scope of a single communication. | scope of a single communication. | |||
skipping to change at page 15, line 33 ¶ | skipping to change at line 652 ¶ | |||
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. | |||
Some requests can be automatically retried by a client in the event | Some requests can be automatically retried by a client in the event | |||
of an underlying connection failure, as described in Section 9.2.2. | of an underlying connection failure, as described in Section 9.2.2. | |||
2.5. Protocol Version | 2.5. Protocol Version | |||
HTTP's version number consists of two decimal digits separated by a | HTTP's 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 messaging syntax, whereas the second digit ("minor | indicates the 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 (able to understand for | version to which the sender is conformant (able to understand for | |||
future communication). | future communication). | |||
While HTTP's core semantics don't change between protocol versions, | While HTTP's core semantics don't change between protocol versions, | |||
the expression of them "on the wire" can change, and so the HTTP | their expression "on the wire" can change, and so the HTTP version | |||
version number changes when incompatible changes are made to the wire | number changes when incompatible changes are made to the wire format. | |||
format. Additionally, HTTP allows incremental, backwards-compatible | Additionally, HTTP allows incremental, backwards-compatible changes | |||
changes to be made to the protocol without changing its version | to be made to the protocol without changing its version through the | |||
through the use of defined extension points (Section 16). | use of defined extension points (Section 16). | |||
The protocol version as a whole indicates the sender's conformance | The protocol version as a whole indicates the sender's conformance | |||
with 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. For example, the version "HTTP/1.1" is | specification(s). For example, the version "HTTP/1.1" is defined by | |||
defined by the combined specifications of this document, "HTTP | the combined specifications of this document, "HTTP Caching" | |||
Caching" [CACHING], and "HTTP/1.1" [HTTP/1.1]. | [CACHING], and "HTTP/1.1" [HTTP/1.1]. | |||
HTTP's major version number is incremented when an incompatible | HTTP's major version number is incremented when an incompatible | |||
message syntax is introduced. The minor number is incremented when | message syntax is introduced. The minor number is 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. | |||
The minor version advertises the sender's communication capabilities | The minor version advertises the sender's communication capabilities | |||
even when the sender is only using a backwards-compatible subset of | even when the sender is only using a backwards-compatible subset of | |||
the protocol, thereby letting the recipient know that more advanced | the protocol, thereby letting the recipient know that more advanced | |||
features can be used in response (by servers) or in future requests | features can be used in response (by servers) or in future requests | |||
skipping to change at page 16, line 29 ¶ | skipping to change at line 695 ¶ | |||
3. Terminology and Core Concepts | 3. Terminology and Core Concepts | |||
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 used to define HTTP. | terminology used to define HTTP. | |||
3.1. Resources | 3.1. 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. Most resources are | might be used to interact with resources. Most resources are | |||
identified by a Uniform Resource Identifier (URI), as described in | identified by a Uniform Resource Identifier (URI), as described in | |||
Section 4. | Section 4. | |||
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 9) and a few request- | semantics in the request method (Section 9) and a few request- | |||
modifying header fields. A resource cannot treat a request in a | modifying header fields. A resource cannot treat a request in a | |||
manner inconsistent with the semantics of the method of the request. | manner inconsistent with the semantics of the method of the request. | |||
skipping to change at page 17, line 7 ¶ | skipping to change at line 717 ¶ | |||
are not safe, a client can expect the resource to avoid actions that | are not safe, a client can expect the resource to avoid actions that | |||
are unsafe when processing a request with a safe method (see | are unsafe when processing a request with a safe method (see | |||
Section 9.2.1). | Section 9.2.1). | |||
HTTP relies upon the Uniform Resource Identifier (URI) standard [URI] | HTTP relies upon the Uniform Resource Identifier (URI) standard [URI] | |||
to indicate the target resource (Section 7.1) and relationships | to indicate the target resource (Section 7.1) and relationships | |||
between resources. | between resources. | |||
3.2. Representations | 3.2. Representations | |||
A _representation_ is information that is intended to reflect a past, | A "representation" is information that is intended to reflect a past, | |||
current, or desired state of a given resource, in a format that can | current, or desired state of a given resource, in a format that can | |||
be readily communicated via the protocol. A representation consists | be readily communicated via the protocol. A representation consists | |||
of a set of representation metadata and a potentially unbounded | of a set of representation metadata and a potentially unbounded | |||
stream of representation data (Section 8). | stream of representation data (Section 8). | |||
HTTP allows "information hiding" behind its uniform interface by | HTTP allows "information hiding" behind its uniform interface by | |||
defining communication with respect to a transferable representation | defining communication with respect to a transferable representation | |||
of the resource state, rather than transferring the resource itself. | of the resource state, rather than transferring the resource itself. | |||
This allows the resource identified by a URI to be anything, | This allows the resource identified by a URI to be anything, | |||
including temporal functions like "the current weather in Laguna | including temporal functions like "the current weather in Laguna | |||
skipping to change at page 17, line 35 ¶ | skipping to change at line 745 ¶ | |||
or desired state of that thing in our communications. When a | or desired state of that thing in our communications. When a | |||
representation is hypertext, it can provide both a representation of | representation is hypertext, it can provide both a representation of | |||
the resource state and processing instructions that help guide the | the resource state and processing instructions that help guide the | |||
recipient's future interactions. | recipient's future interactions. | |||
A target resource might be provided with, or be capable of | A target resource might be provided with, or be capable of | |||
generating, multiple representations that are each intended to | generating, multiple representations that are each intended to | |||
reflect the resource's current state. An algorithm, usually based on | reflect the resource's current state. An algorithm, usually based on | |||
content negotiation (Section 12), would be used to select one of | content negotiation (Section 12), would be used to select one of | |||
those representations as being most applicable to a given request. | those representations as being most applicable to a given request. | |||
This _selected representation_ provides the data and metadata for | This "selected representation" provides the data and metadata for | |||
evaluating conditional requests (Section 13) and constructing the | evaluating conditional requests (Section 13) and constructing the | |||
content for 200 (OK), 206 (Partial Content), and 304 (Not Modified) | content for 200 (OK), 206 (Partial Content), and 304 (Not Modified) | |||
responses to GET (Section 9.3.1). | responses to GET (Section 9.3.1). | |||
3.3. Connections, Clients and Servers | 3.3. Connections, Clients, and Servers | |||
HTTP is a client/server protocol that operates over a reliable | HTTP is a client/server protocol that operates over a reliable | |||
transport- or session-layer _connection_. | transport- or session-layer "connection". | |||
An HTTP _client_ is a program that establishes a connection to a | An HTTP "client" is a program that establishes a connection to a | |||
server for the purpose of sending one or more HTTP requests. An HTTP | server for the purpose of sending one or more HTTP requests. An HTTP | |||
_server_ is a program that accepts connections in order to service | "server" is a program that accepts connections in order to service | |||
HTTP requests by sending 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. | act as a client on some connections and a server on others. | |||
HTTP is defined as a stateless protocol, meaning that each request | HTTP is defined as a stateless protocol, meaning that each request | |||
message's semantics can be understood in isolation, and that the | message's semantics can be understood in isolation, and that the | |||
relationship between connections and messages on them has no impact | relationship between connections and messages on them has no impact | |||
on the interpretation of those messages. For example, a CONNECT | on the interpretation of those messages. For example, a CONNECT | |||
request (Section 9.3.6) or a request with the Upgrade header field | request (Section 9.3.6) or a request with the Upgrade header field | |||
(Section 7.8) can occur at any time, not just in the first message on | (Section 7.8) can occur at any time, not just in the first message on | |||
a connection. Many implementations depend on HTTP's stateless design | a connection. Many implementations depend on HTTP's stateless design | |||
skipping to change at page 18, line 24 ¶ | skipping to change at line 783 ¶ | |||
As a result, a server MUST NOT assume that two requests on the same | As a result, a server MUST NOT assume that two requests on the same | |||
connection are from the same user agent unless the connection is | connection are from the same user agent unless the connection is | |||
secured and specific to that agent. Some non-standard HTTP | secured and specific to that agent. Some non-standard HTTP | |||
extensions (e.g., [RFC4559]) have been known to violate this | extensions (e.g., [RFC4559]) have been known to violate this | |||
requirement, resulting in security and interoperability problems. | requirement, resulting in security and interoperability problems. | |||
3.4. Messages | 3.4. Messages | |||
HTTP is a stateless request/response protocol for exchanging | HTTP is a stateless request/response protocol for exchanging | |||
_messages_ across a connection. The terms _sender_ and _recipient_ | "messages" across a connection. The terms "sender" and "recipient" | |||
refer to any implementation that sends or receives a given message, | refer to any implementation that sends or receives a given message, | |||
respectively. | respectively. | |||
A client sends requests to a server in the form of a _request_ | A client sends requests to a server in the form of a "request" | |||
message with a method (Section 9) and request target (Section 7.1). | message with a method (Section 9) and request target (Section 7.1). | |||
The request might also contain header fields (Section 6.3) for | The request might also contain header fields (Section 6.3) for | |||
request modifiers, client information, and representation metadata, | request modifiers, client information, and representation metadata, | |||
content (Section 6.4) intended for processing in accordance with the | content (Section 6.4) intended for processing in accordance with the | |||
method, and trailer fields (Section 6.5) to communicate information | method, and trailer fields (Section 6.5) to communicate information | |||
collected while sending the content. | collected while sending the content. | |||
A server responds to a client's request by sending one or more | A server responds to a client's request by sending one or more | |||
_response_ messages, each including a status code (Section 15). The | "response" messages, each including a status code (Section 15). The | |||
response might also contain header fields for server information, | response might also contain header fields for server information, | |||
resource metadata, and representation metadata, content to be | resource metadata, and representation metadata, content to be | |||
interpreted in accordance with the status code, and trailer fields to | interpreted in accordance with the status code, and trailer fields to | |||
communicate information collected while sending the content. | communicate information collected while sending the content. | |||
3.5. User Agents | 3.5. User Agents | |||
The term _user agent_ refers to any of the various client programs | The term "user agent" refers to any of the various client programs | |||
that initiate a request. | that initiate a request. | |||
The most familiar form of user agent is the general-purpose Web | The most familiar form of user agent is the general-purpose Web | |||
browser, but that's only a small percentage of implementations. | browser, but that's only a small percentage of implementations. | |||
Other common user agents include spiders (web-traversing robots), | Other common user agents include spiders (web-traversing robots), | |||
command-line tools, billboard screens, household appliances, scales, | command-line tools, billboard screens, household appliances, scales, | |||
light bulbs, firmware update scripts, mobile apps, and communication | light bulbs, firmware update scripts, mobile apps, and communication | |||
devices in a multitude of shapes and sizes. | devices in a multitude of shapes and sizes. | |||
Being a user agent does not imply that there is a human user directly | Being a user agent does not imply that there is a human user directly | |||
skipping to change at page 19, line 34 ¶ | skipping to change at line 836 ¶ | |||
reporting of errors to the user, it is acceptable for such reporting | reporting of errors to the user, it is acceptable for such reporting | |||
to only be observable in an error console or log file. Likewise, | to only be observable in an error console or log file. Likewise, | |||
requirements that an automated action be confirmed by the user before | requirements that an automated action be confirmed by the user before | |||
proceeding might be met via advance configuration choices, run-time | proceeding might be met via advance configuration choices, run-time | |||
options, or simple avoidance of the unsafe action; confirmation does | options, or simple avoidance of the unsafe action; confirmation does | |||
not imply any specific user interface or interruption of normal | not imply any specific user interface or interruption of normal | |||
processing if the user has already made that choice. | processing if the user has already made that choice. | |||
3.6. Origin Server | 3.6. Origin Server | |||
The term _origin server_ refers to a program that can originate | The term "origin server" refers to a program that can originate | |||
authoritative responses for a given target resource. | authoritative responses for a given target resource. | |||
The most familiar form of origin server are large public websites. | The most familiar form of origin server are large public websites. | |||
However, like user agents being equated with browsers, it is easy to | However, like user agents being equated with browsers, it is easy to | |||
be misled into thinking that all origin servers are alike. Common | be misled into thinking that all origin servers are alike. Common | |||
origin servers also include home automation units, configurable | origin servers also include home automation units, configurable | |||
networking components, office machines, autonomous robots, news | networking components, office machines, autonomous robots, news | |||
feeds, traffic cameras, real-time ad selectors, and video-on-demand | feeds, traffic cameras, real-time ad selectors, and video-on-demand | |||
platforms. | platforms. | |||
skipping to change at page 20, line 15 ¶ | skipping to change at line 863 ¶ | |||
request > | request > | |||
UA ======================================= O | UA ======================================= O | |||
< response | < response | |||
Figure 1 | Figure 1 | |||
3.7. Intermediaries | 3.7. 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 | |||
< < < < | < < < < | |||
Figure 2 | Figure 2 | |||
The figure above shows three intermediaries (A, B, and C) between the | The figure above shows three intermediaries (A, B, and C) between the | |||
skipping to change at page 20, line 39 ¶ | skipping to change at line 887 ¶ | |||
with the nearest, non-tunnel neighbor, only to the endpoints of the | with the nearest, non-tunnel neighbor, only to the endpoints of the | |||
chain, or to all connections along the chain. Although the diagram | chain, or to all connections along the chain. Although the diagram | |||
is linear, each participant might be engaged in multiple, | is linear, each participant might be engaged in multiple, | |||
simultaneous communications. For example, B might be receiving | simultaneous communications. For example, B might be receiving | |||
requests from many clients other than A, and/or forwarding requests | requests from many clients other than A, and/or forwarding requests | |||
to servers other than C, at the same time that it is handling A's | to servers other than C, at the same time that it is handling A's | |||
request. Likewise, later requests might be sent through a different | request. Likewise, later requests might be sent through a different | |||
path of connections, often based on dynamic configuration for load | path of connections, often based on dynamic configuration for load | |||
balancing. | balancing. | |||
The terms _upstream_ and _downstream_ are used to describe | The terms "upstream" and "downstream" are used to describe | |||
directional requirements in relation to the message flow: all | directional requirements in relation to the message flow: all | |||
messages flow from upstream to downstream. The terms "inbound" and | messages flow from upstream to downstream. The terms "inbound" and | |||
"outbound" are used to describe directional requirements in relation | "outbound" are used to describe directional requirements in relation | |||
to the request route: _inbound_ means toward the origin server and | to the request route: inbound means "toward the origin server", | |||
_outbound_ means toward the user agent. | whereas outbound means "toward the user agent". | |||
A _proxy_ is a message-forwarding agent that is chosen by the client, | A "proxy" is a message-forwarding agent that is chosen by the client, | |||
usually via local configuration rules, to receive requests for some | usually via local configuration rules, to receive requests for some | |||
type(s) of absolute URI and attempt to satisfy those requests via | type(s) of absolute URI and attempt to satisfy those requests via | |||
translation through the HTTP interface. Some translations are | translation through the HTTP interface. Some translations are | |||
minimal, such as for proxy requests for "http" URIs, whereas other | minimal, such as for proxy requests for "http" URIs, whereas other | |||
requests might require translation to and from entirely different | requests might require translation to and from entirely different | |||
application-level protocols. Proxies are often used to group an | application-level protocols. Proxies are often used to group an | |||
organization's HTTP requests through a common intermediary for the | organization's HTTP requests through a common intermediary for the | |||
sake of security services, annotation services, or shared caching. | sake of security services, 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 content while they are being forwarded, as described in | messages or content while they are being forwarded, as described in | |||
Section 7.7. | Section 7.7. | |||
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 | |||
the outbound communication of a gateway. A gateway communicates with | the outbound communication of a gateway. A gateway communicates with | |||
inbound servers using any protocol that it desires, including private | inbound servers using any protocol that it desires, including private | |||
extensions to HTTP that are outside the scope of this specification. | extensions to HTTP that are outside the scope of this specification. | |||
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 needs to conform to user agent requirements | third-party HTTP servers needs 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, [TLS13]) is used to establish | Transport Layer Security (TLS, [TLS13]) 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 an on-path attacker, | indistinguishable (at a protocol level) from an on-path attacker, | |||
often introducing security flaws or interoperability problems due to | often introducing security flaws or interoperability problems due to | |||
mistakenly violating HTTP semantics. | mistakenly violating HTTP semantics. | |||
For example, an _interception proxy_ [RFC3040] (also commonly known | For example, an "interception proxy" [RFC3040] (also commonly known | |||
as a _transparent proxy_ [RFC1919]) differs from an HTTP proxy | as a "transparent proxy" [RFC1919]) differs from an HTTP proxy | |||
because it is not chosen by the client. Instead, an interception | because it is not chosen by the client. Instead, an interception | |||
proxy filters or redirects outgoing TCP port 80 packets (and | proxy filters or redirects outgoing TCP port 80 packets (and | |||
occasionally other common port traffic). Interception proxies are | occasionally other common port traffic). Interception proxies are | |||
commonly found on public network access points, as a means of | commonly found on public network access points, as a means of | |||
enforcing account subscription prior to allowing use of non-local | enforcing account subscription prior to allowing use of non-local | |||
Internet services, and within corporate firewalls to enforce network | Internet services, and within corporate firewalls to enforce network | |||
usage policies. | usage policies. | |||
3.8. Caches | 3.8. 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 while acting as a tunnel. | cannot be used while 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 | |||
applicable to that request. The following illustrates the resulting | applicable to that request. The following illustrates the resulting | |||
chain if B has a cached copy of an earlier response from O (via C) | chain if B has a cached copy of an earlier response from O (via C) | |||
for a request that has not been cached by UA or A. | for a request that has not been cached by UA or A. | |||
> > | > > | |||
UA =========== A =========== B - - - - - - C - - - - - - O | UA =========== A =========== B - - - - - - C - - - - - - O | |||
< < | < < | |||
Figure 3 | Figure 3 | |||
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 [CACHING]. | cache behavior and cacheable responses are defined in [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 bandwidth | These include national hierarchies of proxy caches to save bandwidth | |||
and reduce latency, Content Delivery Networks that use gateway | and reduce latency, content delivery networks that use gateway | |||
caching to optimise regional and global distribution of popular | caching to optimize regional and global distribution of popular | |||
sites, collaborative systems that broadcast or multicast cache | sites, collaborative systems that broadcast or multicast cache | |||
entries, archives of pre-fetched cache entries for use in off-line or | entries, archives of pre-fetched cache entries for use in off-line or | |||
high-latency environments, and so on. | high-latency environments, and so on. | |||
3.9. Example Message Exchange | 3.9. Example Message Exchange | |||
The following example illustrates a typical HTTP/1.1 message exchange | The following example illustrates a typical HTTP/1.1 message exchange | |||
for a GET request (Section 9.3.1) on the URI "http://www.example.com/ | for a GET request (Section 9.3.1) on the URI "http://www.example.com/ | |||
hello.txt": | hello.txt": | |||
skipping to change at page 25, line 34 ¶ | skipping to change at line 1107 ¶ | |||
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. The origin determines who has the | for WWW services) is the default. The origin determines who has the | |||
right to respond authoritatively to requests that target the | right to respond authoritatively to requests that target the | |||
identified resource, as defined in Section 4.3.2. | identified resource, as defined in Section 4.3.2. | |||
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. | |||
The hierarchical path component and optional query component identify | The hierarchical path component and optional query component identify | |||
the target resource within that origin server's name space. | the target resource within that origin server's namespace. | |||
4.2.2. https URI Scheme | 4.2.2. https URI Scheme | |||
The "https" URI scheme is hereby defined for minting identifiers | The "https" URI scheme is hereby defined for minting identifiers | |||
within the hierarchical namespace governed by a potential origin | within the hierarchical namespace governed by a potential origin | |||
server listening for TCP connections on a given port and capable of | server listening for TCP connections on a given port and capable of | |||
establishing a TLS ([TLS13]) connection that has been secured for | establishing a TLS ([TLS13]) connection that has been secured for | |||
HTTP communication. In this context, _secured_ specifically means | HTTP communication. In this context, "secured" specifically means | |||
that the server has been authenticated as acting on behalf of the | that the server has been authenticated as acting on behalf of the | |||
identified authority and all HTTP communication with that server has | identified authority and all HTTP communication with that server has | |||
confidentiality and integrity protection that is acceptable to both | confidentiality and integrity protection that is acceptable to both | |||
client and server. | client and server. | |||
https-URI = "https" "://" authority path-abempty [ "?" query ] | https-URI = "https" "://" authority path-abempty [ "?" query ] | |||
The origin server for an "https" URI is identified by the authority | The origin server for an "https" URI is identified by the authority | |||
component, which includes a host identifier ([URI], Section 3.2.2) | component, which includes a host identifier ([URI], Section 3.2.2) | |||
and optional port number ([URI], Section 3.2.3). If the port | and optional port number ([URI], Section 3.2.3). If the port | |||
subcomponent is empty or not given, TCP port 443 (the reserved port | subcomponent is empty or not given, TCP port 443 (the reserved port | |||
for HTTP over TLS) is the default. The origin determines who has the | for HTTP over TLS) is the default. The origin determines who has the | |||
right to respond authoritatively to requests that target the | right to respond authoritatively to requests that target the | |||
identified resource, as defined in Section 4.3.3. | identified resource, as defined in Section 4.3.3. | |||
A sender MUST NOT generate an "https" URI with an empty host | A sender MUST NOT generate an "https" 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. | |||
The hierarchical path component and optional query component identify | The hierarchical path component and optional query component identify | |||
the target resource within that origin server's name space. | the target resource within that origin server's namespace. | |||
A client MUST ensure that its HTTP requests for an "https" resource | A client MUST ensure that its HTTP requests for an "https" resource | |||
are secured, prior to being communicated, and that it only accepts | are secured, prior to being communicated, and that it only accepts | |||
secured responses to those requests. Note that the definition of | secured responses to those requests. Note that the definition of | |||
what cryptographic mechanisms are acceptable to client and server are | what cryptographic mechanisms are acceptable to client and server are | |||
usually negotiated and can change over time. | usually negotiated and can change over time. | |||
Resources made available via the "https" scheme have no shared | Resources made available via the "https" scheme have no shared | |||
identity with the "http" scheme. They are distinct origins with | identity with the "http" scheme. They are distinct origins with | |||
separate namespaces. However, extensions to HTTP that are defined as | separate namespaces. However, extensions to HTTP that are defined as | |||
applying to all origins with the same host, such as the Cookie | applying to all origins with the same host, such as the Cookie | |||
protocol [COOKIE], allow information set by one service to impact | protocol [COOKIE], allow information set by one service to impact | |||
communication with other services within a matching group of host | communication with other services within a matching group of host | |||
domains. Such extensions ought to be designed with great care to | domains. Such extensions ought to be designed with great care to | |||
prevent information obtained from a secured connection being | prevent information obtained from a secured connection being | |||
inadvertently exchanged within an unsecured context. | inadvertently exchanged within an unsecured context. | |||
4.2.3. http(s) Normalization and Comparison | 4.2.3. http(s) Normalization and Comparison | |||
The "http" and "https" URI are normalized and compared according to | URIs with an "http" or "https" scheme are normalized and compared | |||
the methods defined in Section 6 of [URI], using the defaults | according to the methods defined in Section 6 of [URI], using the | |||
described above for each scheme. | defaults described above for each scheme. | |||
HTTP does not require use of a specific method for determining | HTTP does not require the use of a specific method for determining | |||
equivalence. For example, a cache key might be compared as a simple | equivalence. For example, a cache key might be compared as a simple | |||
string, after syntax-based normalization, or after scheme-based | string, after syntax-based normalization, or after scheme-based | |||
normalization. | normalization. | |||
Scheme-based normalization (Section 6.2.3 of [URI]) of "http" and | Scheme-based normalization (Section 6.2.3 of [URI]) of "http" and | |||
"https" URIs involves the following additional rules: | "https" URIs involves the following additional rules: | |||
* 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. | form is to omit the port subcomponent. | |||
skipping to change at page 28, line 38 ¶ | skipping to change at line 1249 ¶ | |||
Section 4.3.1 defines the concept of an origin as an aid to such | Section 4.3.1 defines the concept of an origin as an aid to such | |||
uses, and the subsequent subsections explain how to establish that a | uses, and the subsequent subsections explain how to establish that a | |||
peer has the authority to represent an origin. | peer has the authority to represent an origin. | |||
See Section 17.1 for security considerations related to establishing | See Section 17.1 for security considerations related to establishing | |||
authority. | authority. | |||
4.3.1. URI Origin | 4.3.1. URI Origin | |||
The _origin_ for a given URI is the triple of scheme, host, and port | The "origin" for a given URI is the triple of scheme, host, and port | |||
after normalizing the scheme and host to lowercase and normalizing | after normalizing the scheme and host to lowercase and normalizing | |||
the port to remove any leading zeros. If port is elided from the | the port to remove any leading zeros. If port is elided from the | |||
URI, the default port for that scheme is used. For example, the URI | URI, the default port for that scheme is used. For example, the URI | |||
https://Example.Com/happy.js | https://Example.Com/happy.js | |||
would have the origin | would have the origin | |||
{ "https", "example.com", "443" } | { "https", "example.com", "443" } | |||
which can also be described as the normalized URI prefix with port | which can also be described as the normalized URI prefix with port | |||
always present: | always present: | |||
https://example.com:443 | https://example.com:443 | |||
Each origin defines its own namespace and controls how identifiers | Each origin defines its own namespace and controls how identifiers | |||
within that namespace are mapped to resources. In turn, how the | within that namespace are mapped to resources. In turn, how the | |||
origin responds to valid requests, consistently over time, determines | origin responds to valid requests, consistently over time, determines | |||
the semantics that users will associate with a URI, and the | the semantics that users will associate with a URI, and the | |||
usefulness of those semantics is what ultimately transforms these | usefulness of those semantics is what ultimately transforms these | |||
mechanisms into a "resource" for users to reference and access in the | mechanisms into a resource for users to reference and access in the | |||
future. | future. | |||
Two origins are distinct if they differ in scheme, host, or port. | Two origins are distinct if they differ in scheme, host, or port. | |||
Even when it can be verified that the same entity controls two | Even when it can be verified that the same entity controls two | |||
distinct origins, the two namespaces under those origins are distinct | distinct origins, the two namespaces under those origins are distinct | |||
unless explicitly aliased by a server authoritative for that origin. | unless explicitly aliased by a server authoritative for that origin. | |||
Origin is also used within HTML and related Web protocols, beyond the | Origin is also used within HTML and related Web protocols, beyond the | |||
scope of this document, as described in [RFC6454]. | scope of this document, as described in [RFC6454]. | |||
4.3.2. http origins | 4.3.2. http Origins | |||
Although HTTP is independent of the transport protocol, the "http" | Although HTTP is independent of the transport protocol, the "http" | |||
scheme (Section 4.2.1) is specific to associating authority with | scheme (Section 4.2.1) is specific to associating authority with | |||
whomever controls the origin server listening for TCP connections on | whomever controls the origin server listening for TCP connections on | |||
the indicated port of whatever host is identified within the | the indicated port of whatever host is identified within the | |||
authority component. This is a very weak sense of authority because | authority component. This is a very weak sense of authority because | |||
it depends on both client-specific name resolution mechanisms and | it depends on both client-specific name resolution mechanisms and | |||
communication that might not be secured from an on-path attacker. | communication that might not be secured from an on-path attacker. | |||
Nevertheless, it is a sufficient minimum for binding "http" | Nevertheless, it is a sufficient minimum for binding "http" | |||
identifiers to an origin server for consistent resolution within a | identifiers to an origin server for consistent resolution within a | |||
skipping to change at page 30, line 13 ¶ | skipping to change at line 1319 ¶ | |||
considered an authoritative answer to the client's request. | considered an authoritative answer to the client's request. | |||
Note, however, that the above is not the only means for obtaining an | Note, however, that the above is not the only means for obtaining an | |||
authoritative response, nor does it imply that an authoritative | authoritative response, nor does it imply that an authoritative | |||
response is always necessary (see [CACHING]). For example, the Alt- | response is always necessary (see [CACHING]). For example, the Alt- | |||
Svc header field [ALTSVC] allows an origin server to identify other | Svc header field [ALTSVC] allows an origin server to identify other | |||
services that are also authoritative for that origin. Access to | services that are also authoritative for that origin. Access to | |||
"http" identified resources might also be provided by protocols | "http" identified resources might also be provided by protocols | |||
outside the scope of this document. | outside the scope of this document. | |||
4.3.3. https origins | 4.3.3. https Origins | |||
The "https" scheme (Section 4.2.2) associates authority based on the | The "https" scheme (Section 4.2.2) associates authority based on the | |||
ability of a server to use the private key corresponding to a | ability of a server to use the private key corresponding to a | |||
certificate that the client considers to be trustworthy for the | certificate that the client considers to be trustworthy for the | |||
identified origin server. The client usually relies upon a chain of | identified origin server. The client usually relies upon a chain of | |||
trust, conveyed from some prearranged or configured trust anchor, to | trust, conveyed from some prearranged or configured trust anchor, to | |||
deem a certificate trustworthy (Section 4.3.4). | deem a certificate trustworthy (Section 4.3.4). | |||
In HTTP/1.1 and earlier, a client will only attribute authority to a | In HTTP/1.1 and earlier, a client will only attribute authority to a | |||
server when they are communicating over a successfully established | server when they are communicating over a successfully established | |||
skipping to change at page 30, line 43 ¶ | skipping to change at line 1349 ¶ | |||
client will make a DNS query to check that the origin's host contains | client will make a DNS query to check that the origin's host contains | |||
the same server IP address as the established connection. This | the same server IP address as the established connection. This | |||
restriction can be removed by the origin server sending an equivalent | restriction can be removed by the origin server sending an equivalent | |||
ORIGIN frame [RFC8336]. | ORIGIN frame [RFC8336]. | |||
The request target's host and port value are passed within each HTTP | The request target's host and port value are passed within each HTTP | |||
request, identifying the origin and distinguishing it from other | request, identifying the origin and distinguishing it from other | |||
namespaces that might be controlled by the same server (Section 7.2). | namespaces that might be controlled by the same server (Section 7.2). | |||
It is the origin's responsibility to ensure that any services | It is the origin's responsibility to ensure that any services | |||
provided with control over its certificate's private key are equally | provided with control over its certificate's private key are equally | |||
responsible for managing the corresponding "https" namespaces, or at | responsible for managing the corresponding "https" namespaces or at | |||
least prepared to reject requests that appear to have been | least prepared to reject requests that appear to have been | |||
misdirected (Section 7.4). | misdirected (Section 7.4). | |||
An origin server might be unwilling to process requests for certain | An origin server might be unwilling to process requests for certain | |||
target URIs even when they have the authority to do so. For example, | target URIs even when they have the authority to do so. For example, | |||
when a host operates distinct services on different ports (e.g., 443 | when a host operates distinct services on different ports (e.g., 443 | |||
and 8000), checking the target URI at the origin server is necessary | and 8000), checking the target URI at the origin server is necessary | |||
(even after the connection has been secured) because a network | (even after the connection has been secured) because a network | |||
attacker might cause connections for one port to be received at some | attacker might cause connections for one port to be received at some | |||
other port. Failing to check the target URI might allow such an | other port. Failing to check the target URI might allow such an | |||
skipping to change at page 31, line 33 ¶ | skipping to change at line 1388 ¶ | |||
target URI (Section 7.1). | target URI (Section 7.1). | |||
If the server responds to such a request with a non-interim HTTP | If the server responds to such a request with a non-interim HTTP | |||
response message, as described in Section 15, then that response is | response message, as described in Section 15, then that response is | |||
considered an authoritative answer to the client's request. | considered an authoritative answer to the client's request. | |||
Note, however, that the above is not the only means for obtaining an | Note, however, that the above is not the only means for obtaining an | |||
authoritative response, nor does it imply that an authoritative | authoritative response, nor does it imply that an authoritative | |||
response is always necessary (see [CACHING]). | response is always necessary (see [CACHING]). | |||
4.3.4. https certificate verification | 4.3.4. https Certificate Verification | |||
To establish a secured connection to dereference a URI, a client MUST | To establish a secured connection to dereference a URI, a client MUST | |||
verify that the service's identity is an acceptable match for the | verify that the service's identity is an acceptable match for the | |||
URI's origin server. Certificate verification is used to prevent | URI's origin server. Certificate verification is used to prevent | |||
server impersonation by an on-path attacker or by an attacker that | server impersonation by an on-path attacker or by an attacker that | |||
controls name resolution. This process requires that a client be | controls name resolution. This process requires that a client be | |||
configured with a set of trust anchors. | configured with a set of trust anchors. | |||
In general, a client MUST verify the service identity using the | In general, a client MUST verify the service identity using the | |||
verification process defined in Section 6 of [RFC6125]. The client | verification process defined in Section 6 of [RFC6125]. The client | |||
MUST construct a reference identity from the service's host: if the | MUST construct a reference identity from the service's host: if the | |||
host is a literal IP address (Section 4.3.5), the reference identity | host is a literal IP address (Section 4.3.5), the reference identity | |||
is an IP-ID, otherwise the host is a name and the reference identity | is an IP-ID, otherwise the host is a name and the reference identity | |||
is a DNS-ID. | is a DNS-ID. | |||
A reference identity of type CN-ID MUST NOT be used by clients. As | A reference identity of type CN-ID MUST NOT be used by clients. As | |||
noted in Section 6.2.1 of [RFC6125] a reference identity of type CN- | noted in Section 6.2.1 of [RFC6125], a reference identity of type CN- | |||
ID might be used by older clients. | ID might be used by older clients. | |||
A client might be specially configured to accept an alternative form | A client might be specially configured to accept an alternative form | |||
of server identity verification. For example, a client might be | of server identity verification. For example, a client might be | |||
connecting to a server whose address and hostname are dynamic, with | connecting to a server whose address and hostname are dynamic, with | |||
an expectation that the service will present a specific certificate | an expectation that the service will present a specific certificate | |||
(or a certificate matching some externally defined reference | (or a certificate matching some externally defined reference | |||
identity) rather than one matching the target URI's origin. | identity) rather than one matching the target URI's origin. | |||
In special cases, it might be appropriate for a client to simply | In special cases, it might be appropriate for a client to simply | |||
skipping to change at page 32, line 25 ¶ | skipping to change at line 1428 ¶ | |||
If the certificate is not valid for the target URI's origin, a user | If the certificate is not valid for the target URI's origin, a user | |||
agent MUST either obtain confirmation from the user before proceeding | agent MUST either obtain confirmation from the user before proceeding | |||
(see Section 3.5) or terminate the connection with a bad certificate | (see Section 3.5) or terminate the connection with a bad certificate | |||
error. Automated clients MUST log the error to an appropriate audit | error. Automated clients MUST log the error to an appropriate audit | |||
log (if available) and SHOULD terminate the connection (with a bad | log (if available) and SHOULD terminate the connection (with a bad | |||
certificate error). Automated clients MAY provide a configuration | certificate error). Automated clients MAY provide a configuration | |||
setting that disables this check, but MUST provide a setting which | setting that disables this check, but MUST provide a setting which | |||
enables it. | enables it. | |||
4.3.5. IP-ID reference identity | 4.3.5. IP-ID Reference Identity | |||
A server that is identified using an IP address literal in the "host" | A server that is identified using an IP address literal in the "host" | |||
field of an "https" URI has a reference identity of type IP-ID. An | field of an "https" URI has a reference identity of type IP-ID. An | |||
IP version 4 address uses the "IPv4address" ABNF rule and an IP | IP version 4 address uses the "IPv4address" ABNF rule, and an IP | |||
version 6 address uses the "IP-literal" production with the | version 6 address uses the "IP-literal" production with the | |||
"IPv6address" option; see Section 3.2.2 of [URI]. A reference | "IPv6address" option; see Section 3.2.2 of [URI]. A reference | |||
identity of IP-ID contains the decoded bytes of the IP address. | identity of IP-ID contains the decoded bytes of the IP address. | |||
An IP version 4 address is 4 octets and an IP version 6 address is 16 | An IP version 4 address is 4 octets, and an IP version 6 address is | |||
octets. Use of IP-ID is not defined for any other IP version. The | 16 octets. Use of IP-ID is not defined for any other IP version. | |||
iPAddress choice in the certificate subjectAltName extension does not | The iPAddress choice in the certificate subjectAltName extension does | |||
explicitly include the IP version and so relies on the length of the | not explicitly include the IP version and so relies on the length of | |||
address to distinguish versions; see Section 4.2.1.6 of [RFC5280]. | the address to distinguish versions; see Section 4.2.1.6 of | |||
[RFC5280]. | ||||
A reference identity of type IP-ID matches if the address is | A reference identity of type IP-ID matches if the address is | |||
identical to an iPAddress value of the subjectAltName extension of | identical to an iPAddress value of the subjectAltName extension of | |||
the certificate. | the certificate. | |||
5. Fields | 5. Fields | |||
HTTP uses _fields_ to provide data in the form of extensible key/ | HTTP uses "fields" to provide data in the form of extensible name/ | |||
value pairs with a registered key namespace. Fields are sent and | value pairs with a registered key namespace. Fields are sent and | |||
received within the header and trailer sections of messages | received within the header and trailer sections of messages | |||
(Section 6). | (Section 6). | |||
5.1. Field Names | 5.1. Field Names | |||
A field name labels the corresponding field value as having the | A field name labels the corresponding field value as having the | |||
semantics defined by that name. For example, the Date header field | semantics defined by that name. For example, the Date header field | |||
is defined in Section 6.6.1 as containing the origination timestamp | is defined in Section 6.6.1 as containing the origination timestamp | |||
for the message in which it appears. | for the message in which it appears. | |||
skipping to change at page 33, line 40 ¶ | skipping to change at line 1490 ¶ | |||
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 7.6.1) or the proxy | is listed in the Connection header field (Section 7.6.1) or the proxy | |||
is specifically configured to block, or otherwise transform, such | is specifically configured to block, or otherwise transform, such | |||
fields. Other recipients SHOULD ignore unrecognized header and | fields. Other recipients SHOULD ignore unrecognized header and | |||
trailer fields. Adhering to these requirements allows HTTP's | trailer fields. Adhering to these requirements allows HTTP's | |||
functionality to be extended without updating or removing deployed | functionality to be extended without updating or removing deployed | |||
intermediaries. | intermediaries. | |||
5.2. Field Lines and Combined Field Value | 5.2. Field Lines and Combined Field Value | |||
Field sections are composed of any number of _field lines_, each with | Field sections are composed of any number of "field lines", each with | |||
a _field name_ (see Section 5.1) identifying the field, and a _field | a "field name" (see Section 5.1) identifying the field, and a "field | |||
line value_ that conveys data for that instance of the field. | line value" that conveys data for that instance of the field. | |||
When a field name is only present once in a section, the combined | When a field name is only present once in a section, the combined | |||
_field value_ for that field consists of the corresponding field line | "field value" for that field consists of the corresponding field line | |||
value. When a field name is repeated within a section, its combined | value. When a field name is repeated within a section, its combined | |||
field value consists of the list of corresponding field line values | field value consists of the list of corresponding field line values | |||
within that section, concatenated in order, with each field line | within that section, concatenated in order, with each field line | |||
value separated by a comma. | value separated by a comma. | |||
For example, this section: | For example, this section: | |||
Example-Field: Foo, Bar | Example-Field: Foo, Bar | |||
Example-Field: Baz | Example-Field: Baz | |||
skipping to change at page 34, line 29 ¶ | skipping to change at line 1527 ¶ | |||
(",") and optional whitespace (OWS, defined in Section 5.6.3). For | (",") and optional whitespace (OWS, defined in Section 5.6.3). For | |||
consistency, use comma SP. | consistency, use comma SP. | |||
The order in which field lines with the same name are received is | The order in which field lines with the same name are received is | |||
therefore significant to the interpretation of the field value; a | therefore significant to the interpretation of the field value; a | |||
proxy MUST NOT change the order of these field line values when | proxy MUST NOT change the order of these field line values when | |||
forwarding a message. | forwarding a message. | |||
This means that, aside from the well-known exception noted below, a | This means that, aside from the well-known exception noted below, a | |||
sender MUST NOT generate multiple field lines with the same name in a | sender MUST NOT generate multiple field lines with the same name in a | |||
message (whether in the headers or trailers), or append a field line | message (whether in the headers or trailers) or append a field line | |||
when a field line of the same name already exists in the message, | when a field line of the same name already exists in the message, | |||
unless that field's definition allows multiple field line values to | unless that field's definition allows multiple field line values to | |||
be recombined as a comma-separated list [i.e., at least one | be recombined as a comma-separated list (i.e., at least one | |||
alternative of the field's definition allows a comma-separated list, | alternative of the field's definition allows a comma-separated list, | |||
such as an ABNF rule of #(values) defined in Section 5.6.1]. | such as an ABNF rule of #(values) defined in Section 5.6.1). | |||
| *Note:* In practice, the "Set-Cookie" header field ([COOKIE]) | | *Note:* In practice, the "Set-Cookie" header field ([COOKIE]) | |||
| often appears in a response message across multiple field lines | | often appears in a response message across multiple field lines | |||
| and does not use the list syntax, violating the above | | and does not use the list syntax, violating the above | |||
| requirements on multiple field lines with the same field name. | | requirements on multiple field lines with the same field name. | |||
| Since it cannot be combined into a single field value, | | Since it cannot be combined into a single field value, | |||
| recipients ought to handle "Set-Cookie" as a special case while | | recipients ought to handle "Set-Cookie" as a special case while | |||
| processing fields. (See Appendix A.2.3 of [Kri2001] for | | processing fields. (See Appendix A.2.3 of [Kri2001] for | |||
| details.) | | details.) | |||
skipping to change at page 36, line 20 ¶ | skipping to change at line 1614 ¶ | |||
and interpret those characters; a recipient of CR, LF, or NUL within | and interpret those characters; a recipient of CR, LF, or NUL within | |||
a field value MUST either reject the message or replace each of those | a field value MUST either reject the message or replace each of those | |||
characters with SP before further processing or forwarding of that | characters with SP before further processing or forwarding of that | |||
message. Field values containing other CTL characters are also | message. Field values containing other CTL characters are also | |||
invalid; however, recipients MAY retain such characters for the sake | invalid; however, recipients MAY retain such characters for the sake | |||
of robustness when they appear within a safe context (e.g., an | of robustness when they appear within a safe context (e.g., an | |||
application-specific quoted string that will not be processed by any | application-specific quoted string that will not be processed by any | |||
downstream HTTP parser). | downstream HTTP parser). | |||
Fields that only anticipate a single member as the field value are | Fields that only anticipate a single member as the field value are | |||
referred to as _singleton fields_. | referred to as "singleton fields". | |||
Fields that allow multiple members as the field value are referred to | Fields that allow multiple members as the field value are referred to | |||
as _list-based fields_. The list operator extension of Section 5.6.1 | as "list-based fields". The list operator extension of Section 5.6.1 | |||
is used as a common notation for defining field values that can | is used as a common notation for defining field values that can | |||
contain multiple members. | contain multiple members. | |||
Because commas (",") are used as the delimiter between members, they | Because commas (",") are used as the delimiter between members, they | |||
need to be treated with care if they are allowed as data within a | need to be treated with care if they are allowed as data within a | |||
member. This is true for both list-based and singleton fields, since | member. This is true for both list-based and singleton fields, since | |||
a singleton field might be erroneously sent with multiple members and | a singleton field might be erroneously sent with multiple members and | |||
detecting such errors improves interoperability. Fields that expect | detecting such errors improves interoperability. Fields that expect | |||
to contain a comma within a member, such as within an HTTP-date or | to contain a comma within a member, such as within an HTTP-date or | |||
URI-reference element, ought to be defined with delimiters around | URI-reference element, ought to be defined with delimiters around | |||
skipping to change at page 40, line 29 ¶ | skipping to change at line 1809 ¶ | |||
Comments can be included in some HTTP fields by surrounding the | Comments can be included in some HTTP fields by surrounding the | |||
comment text with parentheses. Comments are only allowed in fields | comment text with parentheses. Comments are only allowed in fields | |||
containing "comment" as part of their field value definition. | 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 | |||
5.6.6. Parameters | 5.6.6. Parameters | |||
Parameters are instances of name=value pairs; they are often used in | Parameters are instances of name/value pairs; they are often used in | |||
field values as a common syntax for appending auxiliary information | field values as a common syntax for appending auxiliary information | |||
to an item. Each parameter is usually delimited by an immediately | to an item. Each parameter is usually delimited by an immediately | |||
preceding semicolon. | preceding semicolon. | |||
parameters = *( OWS ";" OWS [ parameter ] ) | parameters = *( OWS ";" OWS [ parameter ] ) | |||
parameter = parameter-name "=" parameter-value | parameter = parameter-name "=" parameter-value | |||
parameter-name = token | parameter-name = token | |||
parameter-value = ( token / quoted-string ) | parameter-value = ( token / quoted-string ) | |||
Parameter names are case-insensitive. Parameter values might or | Parameter names are case-insensitive. Parameter values might or | |||
skipping to change at page 41, line 35 ¶ | skipping to change at line 1862 ¶ | |||
accept all three HTTP-date formats. When a sender generates a field | accept all three HTTP-date formats. When a sender generates a field | |||
that contains one or more timestamps defined as HTTP-date, the sender | that contains one or more timestamps defined as HTTP-date, the sender | |||
MUST generate those timestamps in the IMF-fixdate format. | MUST generate those timestamps in the IMF-fixdate format. | |||
An HTTP-date value represents time as an instance of Coordinated | An HTTP-date value represents time as an instance of Coordinated | |||
Universal Time (UTC). The first two formats indicate UTC by the | Universal Time (UTC). The first two formats indicate UTC by the | |||
three-letter abbreviation for Greenwich Mean Time, "GMT", a | three-letter abbreviation for Greenwich Mean Time, "GMT", a | |||
predecessor of the UTC name; values in the asctime format are assumed | predecessor of the UTC name; values in the asctime format are assumed | |||
to be in UTC. | to be in UTC. | |||
A _clock_ is an implementation capable of providing a reasonable | A "clock" is an implementation capable of providing a reasonable | |||
approximation of the current instant in UTC. A clock implementation | approximation of the current instant in UTC. A clock implementation | |||
ought to use NTP ([RFC5905]), or some similar protocol, to | ought to use NTP ([RFC5905]), or some similar protocol, to | |||
synchronize with UTC. | synchronize with UTC. | |||
Preferred format: | Preferred format: | |||
IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT | IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT | |||
; fixed length/zone/capitalization subset of the format | ; fixed length/zone/capitalization subset of the format | |||
; see Section 3.3 of [RFC5322] | ; see Section 3.3 of [RFC5322] | |||
skipping to change at page 43, line 22 ¶ | skipping to change at line 1930 ¶ | |||
two-digit year, MUST interpret a timestamp that appears to be more | two-digit year, MUST interpret a timestamp that appears to be more | |||
than 50 years in the future as representing the most recent year in | than 50 years in the future as representing the most recent year in | |||
the past that had the same last two digits. | the past that had the same last two digits. | |||
Recipients of timestamp values are encouraged to be robust in parsing | Recipients of timestamp values are encouraged to be robust in parsing | |||
timestamps unless otherwise restricted by the field definition. For | timestamps unless otherwise restricted by the field definition. For | |||
example, messages are occasionally forwarded over HTTP from a non- | example, messages are occasionally forwarded over HTTP from a non- | |||
HTTP source that might generate any of the date and time | HTTP source that might generate any of the date and time | |||
specifications defined by the Internet Message Format. | specifications defined by the Internet Message Format. | |||
| *Note:* HTTP requirements for the date/time stamp format apply | | *Note:* HTTP requirements for timestamp formats apply only to | |||
| only to their usage within the protocol stream. | | their usage within the protocol stream. Implementations are | |||
| Implementations are not required to use these formats for user | | not required to use these formats for user presentation, | |||
| presentation, request logging, etc. | | request logging, etc. | |||
6. Message Abstraction | 6. Message Abstraction | |||
Each major version of HTTP defines its own syntax for communicating | Each major version of HTTP defines its own syntax for communicating | |||
messages. This section defines an abstract data type for HTTP | messages. This section defines an abstract data type for HTTP | |||
messages based on a generalization of those message characteristics, | messages based on a generalization of those message characteristics, | |||
common structure, and capacity for conveying semantics. This | common structure, and capacity for conveying semantics. This | |||
abstraction is used to define requirements on senders and recipients | abstraction is used to define requirements on senders and recipients | |||
that are independent of the HTTP version, such that a message in one | that are independent of the HTTP version, such that a message in one | |||
version can be relayed through other versions without changing its | version can be relayed through other versions without changing its | |||
meaning. | meaning. | |||
A _message_ consists of control data to describe and route the | A "message" consists of the following: | |||
message, a headers lookup table of key/value pairs for extending that | ||||
control data and conveying additional information about the sender, | * control data to describe and route the message, | |||
message, content, or context, a potentially unbounded stream of | ||||
content, and a trailers lookup table of key/value pairs for | * a headers lookup table of name/value pairs for extending that | |||
communicating information obtained while sending the content. | control data and conveying additional information about the | |||
sender, message, content, or context, | ||||
* a potentially unbounded stream of content, and | ||||
* a trailers lookup table of name/value pairs for communicating | ||||
information obtained while sending the content. | ||||
Framing and control data is sent first, followed by a header section | Framing and control data is sent first, followed by a header section | |||
containing fields for the headers table. When a message includes | containing fields for the headers table. When a message includes | |||
content, the content is sent after the header section, potentially | content, the content is sent after the header section, potentially | |||
followed by a trailer section that might contain fields for the | followed by a trailer section that might contain fields for the | |||
trailers table. | trailers table. | |||
Messages are expected to be processed as a stream, wherein the | Messages are expected to be processed as a stream, wherein the | |||
purpose of that stream and its continued processing is revealed while | purpose of that stream and its continued processing is revealed while | |||
being read. Hence, control data describes what the recipient needs | being read. Hence, control data describes what the recipient needs | |||
to know immediately, header fields describe what needs to be known | to know immediately, header fields describe what needs to be known | |||
before receiving content, the content (when present) presumably | before receiving content, the content (when present) presumably | |||
contains what the recipient wants or needs to fulfill the message | contains what the recipient wants or needs to fulfill the message | |||
semantics, and trailer fields provide optional metadata that was | semantics, and trailer fields provide optional metadata that was | |||
unknown prior to sending the content. | unknown prior to sending the content. | |||
Messages are intended to be _self-descriptive_: everything a | Messages are intended to be "self-descriptive": everything a | |||
recipient needs to know about the message can be determined by | recipient needs to know about the message can be determined by | |||
looking at the message itself, after decoding or reconstituting parts | looking at the message itself, after decoding or reconstituting parts | |||
that have been compressed or elided in transit, without requiring an | that have been compressed or elided in transit, without requiring an | |||
understanding of the sender's current application state (established | understanding of the sender's current application state (established | |||
via prior messages). However, a client MUST retain knowledge of the | via prior messages). However, a client MUST retain knowledge of the | |||
request when parsing, interpreting, or caching a corresponding | request when parsing, interpreting, or caching a corresponding | |||
response. For example, responses to the HEAD method look just like | response. For example, responses to the HEAD method look just like | |||
the beginning of a response to GET, but cannot be parsed in the same | the beginning of a response to GET but cannot be parsed in the same | |||
manner. | manner. | |||
Note that this message abstraction is a generalization across many | Note that this message abstraction is a generalization across many | |||
versions of HTTP, including features that might not be found in some | versions of HTTP, including features that might not be found in some | |||
versions. For example, trailers were introduced within the HTTP/1.1 | versions. For example, trailers were introduced within the HTTP/1.1 | |||
chunked transfer coding as a trailer section after the content. An | chunked transfer coding as a trailer section after the content. An | |||
equivalent feature is present in HTTP/2 and HTTP/3 within the header | equivalent feature is present in HTTP/2 and HTTP/3 within the header | |||
block that terminates each stream. | block that terminates each stream. | |||
6.1. Framing and Completeness | 6.1. Framing and Completeness | |||
skipping to change at page 44, line 47 ¶ | skipping to change at line 2007 ¶ | |||
mechanism. | mechanism. | |||
HTTP/0.9 and early deployments of HTTP/1.0 used closure of the | HTTP/0.9 and early deployments of HTTP/1.0 used closure of the | |||
underlying connection to end a response. For backwards | underlying connection to end a response. For backwards | |||
compatibility, this implicit framing is also allowed in HTTP/1.1. | compatibility, this implicit framing is also allowed in HTTP/1.1. | |||
However, implicit framing can fail to distinguish an incomplete | However, implicit framing can fail to distinguish an incomplete | |||
response if the connection closes early. For that reason, almost all | response if the connection closes early. For that reason, almost all | |||
modern implementations use explicit framing in the form of length- | modern implementations use explicit framing in the form of length- | |||
delimited sequences of message data. | delimited sequences of message data. | |||
A message is considered _complete_ when all of the octets indicated | A message is considered "complete" when all of the octets indicated | |||
by its framing are available. Note that, when no explicit framing is | by its framing are available. Note that, when no explicit framing is | |||
used, a response message that is ended by the underlying connection's | used, a response message that is ended by the underlying connection's | |||
close is considered complete even though it might be | close is considered complete even though it might be | |||
indistinguishable from an incomplete response, unless a transport- | indistinguishable from an incomplete response, unless a transport- | |||
level error indicates that it is not complete. | level error indicates that it is not complete. | |||
6.2. Control Data | 6.2. Control Data | |||
Messages start with control data that describe its primary purpose. | Messages start with control data that describe its primary purpose. | |||
Request message control data includes a request method (Section 9), | Request message control data includes a request method (Section 9), | |||
skipping to change at page 46, line 11 ¶ | skipping to change at line 2069 ¶ | |||
implements SHOULD process the message as if it were in the highest | implements SHOULD process the message as if it were in the highest | |||
minor version within that major version to which the recipient is | minor version within that major version to which the recipient is | |||
conformant. A recipient can assume that a message with a higher | conformant. A recipient can assume that a message with a higher | |||
minor version, when sent to a recipient that has not yet indicated | minor version, when sent to a recipient that has not yet indicated | |||
support for that higher version, is sufficiently backwards-compatible | support for that higher version, is sufficiently backwards-compatible | |||
to be safely processed by any implementation of the same major | to be safely processed by any implementation of the same major | |||
version. | version. | |||
6.3. Header Fields | 6.3. Header Fields | |||
Fields (Section 5) that are sent/received before the content are | Fields (Section 5) that are sent or received before the content are | |||
referred to as "header fields" (or just "headers", colloquially). | referred to as "header fields" (or just "headers", colloquially). | |||
The _header section_ of a message consists of a sequence of header | The "header section" of a message consists of a sequence of header | |||
field lines. Each header field might modify or extend message | field lines. Each header field might modify or extend message | |||
semantics, describe the sender, define the content, or provide | semantics, describe the sender, define the content, or provide | |||
additional context. | additional context. | |||
| *Note:* We refer to named fields specifically as a "header | | *Note:* We refer to named fields specifically as a "header | |||
| field" when they are only allowed to be sent in the header | | field" when they are only allowed to be sent in the header | |||
| section. | | section. | |||
6.4. Content | 6.4. Content | |||
HTTP messages often transfer a complete or partial representation as | HTTP messages often transfer a complete or partial representation as | |||
the message _content_: a stream of octets sent after the header | the message "content": a stream of octets sent after the header | |||
section, as delineated by the message framing. | section, as delineated by the message framing. | |||
This abstract definition of content reflects the data after it has | This abstract definition of content reflects the data after it has | |||
been extracted from the message framing. For example, an HTTP/1.1 | been extracted from the message framing. For example, an HTTP/1.1 | |||
message body (Section 6 of [HTTP/1.1]) might consist of a stream of | message body (Section 6 of [HTTP/1.1]) might consist of a stream of | |||
data encoded with the chunked transfer coding - a sequence of data | data encoded with the chunked transfer coding -- a sequence of data | |||
chunks, one zero-length chunk, and a trailer section - whereas the | chunks, one zero-length chunk, and a trailer section -- whereas the | |||
content of that same message includes only the data stream after the | content of that same message includes only the data stream after the | |||
transfer coding has been decoded; it does not include the chunk | transfer coding has been decoded; it does not include the chunk | |||
lengths, chunked framing syntax, nor the trailer fields | lengths, chunked framing syntax, nor the trailer fields | |||
(Section 6.5). | (Section 6.5). | |||
| *Note:* Some field names have a "Content-" prefix. This is an | | *Note:* Some field names have a "Content-" prefix. This is an | |||
| informal convention; while some of these fields refer to the | | informal convention; while some of these fields refer to the | |||
| content of the message, as defined above, others are scoped to | | content of the message, as defined above, others are scoped to | |||
| the selected representation (Section 3.2). See the individual | | the selected representation (Section 3.2). See the individual | |||
| field's definition to disambiguate. | | field's definition to disambiguate. | |||
skipping to change at page 49, line 7 ¶ | skipping to change at line 2207 ¶ | |||
the sender asserts that the content is a representation of the | the sender asserts that the content is a representation of the | |||
resource identified by the Content-Location field value. | resource identified by the Content-Location field value. | |||
However, such an assertion cannot be trusted unless it can be | However, such an assertion cannot be trusted unless it can be | |||
verified by other means (not defined by this specification). | verified by other means (not defined by this specification). | |||
7. Otherwise, the content is unidentified by HTTP, but a more | 7. Otherwise, the content is unidentified by HTTP, but a more | |||
specific identifier might be supplied within the content itself. | specific identifier might be supplied within the content itself. | |||
6.5. Trailer Fields | 6.5. Trailer Fields | |||
Fields (Section 5) that are located within a _trailer section_ are | Fields (Section 5) that are located within a "trailer section" are | |||
referred to as "trailer fields" (or just "trailers", colloquially). | referred to as "trailer fields" (or just "trailers", colloquially). | |||
Trailer fields can be useful for supplying message integrity checks, | Trailer fields can be useful for supplying message integrity checks, | |||
digital signatures, delivery metrics, or post-processing status | digital signatures, delivery metrics, or post-processing status | |||
information. | information. | |||
Trailer fields ought to be processed and stored separately from the | Trailer fields ought to be processed and stored separately from the | |||
fields in the header section to avoid contradicting message semantics | fields in the header section to avoid contradicting message semantics | |||
known at the time the header section was complete. The presence or | known at the time the header section was complete. The presence or | |||
absence of certain header fields might impact choices made for the | absence of certain header fields might impact choices made for the | |||
routing or processing of the message as a whole before the trailers | routing or processing of the message as a whole before the trailers | |||
are received; those choices cannot be unmade by the later discovery | are received; those choices cannot be unmade by the later discovery | |||
of trailer fields. | of trailer fields. | |||
6.5.1. Limitations on use of Trailers | 6.5.1. Limitations on Use of Trailers | |||
A trailer section is only possible when supported by the version of | A trailer section is only possible when supported by the version of | |||
HTTP in use and enabled by an explicit framing mechanism. For | HTTP in use and enabled by an explicit framing mechanism. For | |||
example, the chunked coding in HTTP/1.1 allows a trailer section to | example, the chunked transfer coding in HTTP/1.1 allows a trailer | |||
be sent after the content (Section 7.1.2 of [HTTP/1.1]). | section to be sent after the content (Section 7.1.2 of [HTTP/1.1]). | |||
Many fields cannot be processed outside the header section because | Many fields cannot be processed outside the header section because | |||
their evaluation is necessary prior to receiving the content, such as | their evaluation is necessary prior to receiving the content, such as | |||
those that describe message framing, routing, authentication, request | those that describe message framing, routing, authentication, request | |||
modifiers, response controls, or content format. A sender MUST NOT | modifiers, response controls, or content format. A sender MUST NOT | |||
generate a trailer field unless the sender knows the corresponding | generate a trailer field unless the sender knows the corresponding | |||
header field name's definition permits the field to be sent in | header field name's definition permits the field to be sent in | |||
trailers. | trailers. | |||
Trailer fields can be difficult to process by intermediaries that | Trailer fields can be difficult to process by intermediaries that | |||
skipping to change at page 50, line 37 ¶ | skipping to change at line 2278 ¶ | |||
field value. | field value. | |||
Like header fields, trailer fields with the same name are processed | Like header fields, trailer fields with the same name are processed | |||
in the order received; multiple trailer field lines with the same | in the order received; multiple trailer field lines with the same | |||
name have the equivalent semantics as appending the multiple values | name have the equivalent semantics as appending the multiple values | |||
as a list of members. Trailer fields that might be generated more | as a list of members. Trailer fields that might be generated more | |||
than once during a message MUST be defined as a list-based field even | than once during a message MUST be defined as a list-based field even | |||
if each member value is only processed once per field line received. | if each member value is only processed once per field line received. | |||
At the end of a message, a recipient MAY treat the set of received | At the end of a message, a recipient MAY treat the set of received | |||
trailer fields as a data structure of key/value pairs, similar to | trailer fields as a data structure of name/value pairs, similar to | |||
(but separate from) the header fields. Additional processing | (but separate from) the header fields. Additional processing | |||
expectations, if any, can be defined within the field specification | expectations, if any, can be defined within the field specification | |||
for a field intended for use in trailers. | for a field intended for use in trailers. | |||
6.6. Message Metadata | 6.6. Message Metadata | |||
Fields that describe the message itself, such as when and how the | Fields that describe the message itself, such as when and how the | |||
message has been generated, can appear in both requests and | message has been generated, can appear in both requests and | |||
responses. | responses. | |||
skipping to change at page 52, line 46 ¶ | skipping to change at line 2375 ¶ | |||
7.1. Determining the Target Resource | 7.1. Determining the Target Resource | |||
Although HTTP is used in a wide variety of applications, most clients | Although HTTP is used in a wide variety of applications, most clients | |||
rely on the same resource identification mechanism and configuration | rely on the same resource identification mechanism and configuration | |||
techniques as general-purpose Web browsers. Even when communication | techniques as general-purpose Web browsers. Even when communication | |||
options are hard-coded in a client's configuration, we can think of | options are hard-coded in a client's configuration, we can think of | |||
their combined effect as a URI reference (Section 4.1). | their combined effect as a URI reference (Section 4.1). | |||
A URI reference is resolved to its absolute form in order to obtain | A URI reference is resolved to its absolute form in order to obtain | |||
the _target URI_. The target URI excludes the reference's fragment | the "target URI". The target URI excludes the reference's fragment | |||
component, if any, since fragment identifiers are reserved for | component, if any, since fragment identifiers are reserved for | |||
client-side processing ([URI], Section 3.5). | client-side processing ([URI], Section 3.5). | |||
To perform an action on a _target resource_, the client sends a | To perform an action on a "target resource", the client sends a | |||
request message containing enough components of its parsed target URI | request message containing enough components of its parsed target URI | |||
to enable recipients to identify that same resource. For historical | to enable recipients to identify that same resource. For historical | |||
reasons, the parsed target URI components, collectively referred to | reasons, the parsed target URI components, collectively referred to | |||
as the _request target_, are sent within the message control data and | as the "request target", are sent within the message control data and | |||
the Host header field (Section 7.2). | the Host header field (Section 7.2). | |||
There are two unusual cases for which the request target components | There are two unusual cases for which the request target components | |||
are in a method-specific form: | are in a method-specific form: | |||
* For CONNECT (Section 9.3.6), the request target is the host name | * For CONNECT (Section 9.3.6), the request target is the host name | |||
and port number of the tunnel destination, separated by a colon. | and port number of the tunnel destination, separated by a colon. | |||
* For OPTIONS (Section 9.3.7), the request target can be a single | * For OPTIONS (Section 9.3.7), the request target can be a single | |||
asterisk ("*"). | asterisk ("*"). | |||
skipping to change at page 53, line 28 ¶ | skipping to change at line 2406 ¶ | |||
NOT be used with other methods. | NOT be used with other methods. | |||
Upon receipt of a client's request, a server reconstructs the target | Upon receipt of a client's request, a server reconstructs the target | |||
URI from the received components in accordance with their local | URI from the received components in accordance with their local | |||
configuration and incoming connection context. This reconstruction | configuration and incoming connection context. This reconstruction | |||
is specific to each major protocol version. For example, Section 3.3 | is specific to each major protocol version. For example, Section 3.3 | |||
of [HTTP/1.1] defines how a server determines the target URI of an | of [HTTP/1.1] defines how a server determines the target URI of an | |||
HTTP/1.1 request. | HTTP/1.1 request. | |||
| *Note:* Previous specifications defined the recomposed target | | *Note:* Previous specifications defined the recomposed target | |||
| URI as a distinct concept, the _effective request URI_. | | URI as a distinct concept, the "effective request URI". | |||
7.2. Host and :authority | 7.2. Host and :authority | |||
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. | host names. | |||
In HTTP/2 [HTTP/2] and HTTP/3 [HTTP/3], the Host header field is, in | In HTTP/2 [HTTP/2] and HTTP/3 [HTTP/3], the Host header field is, in | |||
some cases, supplanted by the ":authority" pseudo-header field of a | some cases, supplanted by the ":authority" pseudo-header field of a | |||
skipping to change at page 56, line 7 ¶ | skipping to change at line 2530 ¶ | |||
The mechanism used to correlate between request and response messages | The mechanism used to correlate between request and response messages | |||
is version dependent; some versions of HTTP use implicit ordering of | is version dependent; some versions of HTTP use implicit ordering of | |||
messages, while others use an explicit identifier. | messages, while others use an explicit identifier. | |||
All responses, regardless of the status code (including interim | All responses, regardless of the status code (including interim | |||
responses) can be sent at any time after a request is received, even | responses) can be sent at any time after a request is received, even | |||
if the request is not yet complete. A response can complete before | if the request is not yet complete. A response can complete before | |||
its corresponding request is complete (Section 6.1). Likewise, | its corresponding request is complete (Section 6.1). Likewise, | |||
clients are not expected to wait any specific amount of time for a | clients are not expected to wait any specific amount of time for a | |||
response. Clients (including intermediaries) might abandon a request | response. Clients (including intermediaries) might abandon a request | |||
if the response is not forthcoming within a reasonable period of | if the response is not received within a reasonable period of time. | |||
time. | ||||
A client that receives a response while it is still sending the | A client that receives a response while it is still sending the | |||
associated request SHOULD continue sending that request, unless it | associated request SHOULD continue sending that request unless it | |||
receives an explicit indication to the contrary (see, e.g., | receives an explicit indication to the contrary (see, e.g., | |||
Section 9.5 of [HTTP/1.1] and Section 6.4 of [HTTP/2]). | Section 9.5 of [HTTP/1.1] and Section 6.4 of [HTTP/2]). | |||
7.6. Message Forwarding | 7.6. Message Forwarding | |||
As described in Section 3.7, intermediaries can serve a variety of | As described in Section 3.7, 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. | |||
Intermediaries are expected to forward messages even when protocol | Intermediaries are expected to forward messages even when protocol | |||
elements are not recognized (e.g., new methods, status codes, or | elements are not recognized (e.g., new methods, status codes, or | |||
field names), since that preserves extensibility for downstream | field names) since that preserves extensibility for downstream | |||
recipients. | recipients. | |||
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 7.6.1, and exclude fields from | header field, as specified in Section 7.6.1, and exclude fields from | |||
being forwarded that are only intended for the incoming connection. | 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 | |||
skipping to change at page 57, line 5 ¶ | skipping to change at line 2574 ¶ | |||
or forwarding downstream. However, senders and recipients cannot | or forwarding downstream. However, senders and recipients cannot | |||
rely on incremental delivery of partial messages, since some | rely on incremental delivery of partial messages, since some | |||
implementations will buffer or delay message forwarding for the sake | implementations will buffer or delay message forwarding for the sake | |||
of network efficiency, security checks, or content transformations. | of network efficiency, security checks, or content transformations. | |||
7.6.1. Connection | 7.6.1. Connection | |||
The "Connection" header field allows the sender to list desired | The "Connection" header field allows the sender to list desired | |||
control options for the current connection. | control options for the current connection. | |||
Connection = #connection-option | ||||
connection-option = token | ||||
Connection options are case-insensitive. | ||||
When a field aside from Connection is used to supply control | When a field aside from Connection is used to supply control | |||
information for or about the current connection, the sender MUST list | information for or about the current connection, the sender MUST list | |||
the corresponding field name within the Connection header field. | the corresponding field name within the Connection header field. | |||
Note that some versions of HTTP prohibit the use of fields for such | Note that some versions of HTTP prohibit the use of fields for such | |||
information, and therefore do not allow the Connection field. | information, and therefore do not allow the Connection field. | |||
Intermediaries MUST parse a received Connection header field before a | Intermediaries MUST parse a received Connection header field before a | |||
message is forwarded and, for each connection-option in this field, | message is forwarded and, for each connection-option in this field, | |||
remove any header or trailer field(s) from the message with the same | remove any header or trailer field(s) from the message with the same | |||
name as the connection-option, and then remove the Connection header | name as the connection-option, and then remove the Connection header | |||
field itself (or replace it with the intermediary's own connection | field itself (or replace it with the intermediary's own control | |||
options for the forwarded message). | options for the forwarded message). | |||
Hence, the Connection header field provides a declarative way of | Hence, the Connection header field provides a declarative way of | |||
distinguishing fields that are only intended for the immediate | distinguishing fields that are only intended for the immediate | |||
recipient ("hop-by-hop") from those fields that are intended for all | recipient ("hop-by-hop") from those fields that are intended for all | |||
recipients on the chain ("end-to-end"), enabling the message to be | recipients on the chain ("end-to-end"), enabling the message to be | |||
self-descriptive and allowing future connection-specific extensions | self-descriptive and allowing future connection-specific extensions | |||
to be deployed without fear that they will be blindly forwarded by | to be deployed without fear that they will be blindly forwarded by | |||
older intermediaries. | older intermediaries. | |||
Furthermore, intermediaries SHOULD remove or replace field(s) whose | Furthermore, intermediaries SHOULD remove or replace fields that are | |||
semantics are known to require removal before forwarding, whether or | known to require removal before forwarding, whether or not they | |||
not they appear as a Connection option, after applying those fields' | appear as a connection-option, after applying those fields' | |||
semantics. This includes but is not limited to: | semantics. This includes but is not limited to: | |||
* Proxy-Connection (Appendix C.2.2 of [HTTP/1.1]) | * Proxy-Connection (Appendix C.2.2 of [HTTP/1.1]) | |||
* Keep-Alive (Section 19.7.1 of [RFC2068]) | * Keep-Alive (Section 19.7.1 of [RFC2068]) | |||
* TE (Section 10.1.4) | * TE (Section 10.1.4) | |||
* Transfer-Encoding (Section 6.1 of [HTTP/1.1]) | * Transfer-Encoding (Section 6.1 of [HTTP/1.1]) | |||
* Upgrade (Section 7.8) | * Upgrade (Section 7.8) | |||
The Connection header field's value has the following grammar: | ||||
Connection = #connection-option | ||||
connection-option = token | ||||
Connection options are case-insensitive. | ||||
A sender MUST NOT send a connection option corresponding to a field | A sender MUST NOT send a connection option corresponding to a field | |||
that is intended for all recipients of the content. For example, | that is intended for all recipients of the content. For example, | |||
Cache-Control is never appropriate as a connection option | Cache-Control is never appropriate as a connection option | |||
(Section 5.2 of [CACHING]). | (Section 5.2 of [CACHING]). | |||
Connection options do not always correspond to a field present in the | Connection options do not always correspond to a field present in the | |||
message, since a connection-specific field might not be needed if | message, since a connection-specific field might not be needed if | |||
there are no parameters associated with a connection option. In | there are no parameters associated with a connection option. In | |||
contrast, a connection-specific field received without a | contrast, a connection-specific field received without a | |||
corresponding connection option usually indicates that the field has | corresponding connection option usually indicates that the field has | |||
been improperly forwarded by an intermediary and ought to be ignored | been improperly forwarded by an intermediary and ought to be ignored | |||
by the recipient. | by the recipient. | |||
When defining a new connection option that does not correspond to a | When defining a new connection option that does not correspond to a | |||
field, specification authors ought to reserve the corresponding field | field, specification authors ought to reserve the corresponding field | |||
name anyway in order to avoid later collisions. Such reserved field | name anyway in order to avoid later collisions. Such reserved field | |||
names are registered in the Hypertext Transfer Protocol (HTTP) Field | names are registered in the "Hypertext Transfer Protocol (HTTP) Field | |||
Name Registry (Section 16.3.1). | Name Registry" (Section 16.3.1). | |||
7.6.2. Max-Forwards | 7.6.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 9.3.8) and OPTIONS (Section 9.3.7) request methods to limit | (Section 9.3.8) and OPTIONS (Section 9.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 | |||
skipping to change at page 61, line 5 ¶ | skipping to change at line 2752 ¶ | |||
Some intermediaries include features for transforming messages and | Some intermediaries include features for transforming messages and | |||
their content. A proxy might, for example, convert between image | their content. 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 content intended for | when these transformations are applied to content 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 content received is identical to the | are used to ensure that the content received is identical to the | |||
original. | original. | |||
An HTTP-to-HTTP proxy is called a _transforming proxy_ if it is | An HTTP-to-HTTP proxy is called a "transforming proxy" if it is | |||
designed or configured to modify messages in a semantically | designed or configured to modify messages in a semantically | |||
meaningful way (i.e., modifications, beyond those required by normal | meaningful way (i.e., modifications, beyond those required by normal | |||
HTTP processing, that change the message in a way that would be | HTTP processing, that change the message in a way that would be | |||
significant to the original sender or potentially significant to | significant to the original sender or potentially significant to | |||
downstream recipients). For example, a transforming proxy might be | downstream recipients). For example, a transforming proxy might be | |||
acting as a shared annotation server (modifying responses to include | acting as a shared annotation server (modifying responses to include | |||
references to a local annotation database), a malware filter, a | references to a local annotation database), a malware filter, a | |||
format transcoder, or a privacy filter. Such transformations are | format transcoder, or a privacy filter. Such transformations are | |||
presumed to be desired by whichever client (or client organization) | presumed to be desired by whichever client (or client organization) | |||
chose the proxy. | chose the proxy. | |||
skipping to change at page 61, line 29 ¶ | skipping to change at line 2776 ¶ | |||
received when forwarding the request. A proxy MUST NOT change the | received when forwarding the request. A proxy MUST NOT change the | |||
host name if the target URI contains a fully qualified domain name. | host name if the target URI contains a fully qualified 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 target URI when forwarding it to the next inbound server | received target URI when forwarding it to the next inbound server | |||
except as required by that forwarding protocol. For example, a proxy | except as required by that forwarding protocol. For example, a proxy | |||
forwarding a request to an origin server via HTTP/1.1 will replace an | forwarding a request to an origin server via HTTP/1.1 will replace an | |||
empty path with "/" (Section 3.2.1 of [HTTP/1.1]) or "*" | empty path with "/" (Section 3.2.1 of [HTTP/1.1]) or "*" | |||
(Section 3.2.4 of [HTTP/1.1]), depending on the request method. | (Section 3.2.4 of [HTTP/1.1]), depending on the request method. | |||
A proxy MUST NOT transform the content (Section 6.4) of a message | A proxy MUST NOT transform the content (Section 6.4) of a response | |||
that contains a no-transform cache-control response directive | message that contains a no-transform cache directive (Section 5.2.2.6 | |||
(Section 5.2 of [CACHING]). Note that this does not include changes | of [CACHING]). Note that this does not apply to message | |||
to the message body that do not affect the content, such as transfer | transformations that do not change the content, such as the addition | |||
codings (Section 7 of [HTTP/1.1]). | or removal of transfer codings (Section 7 of [HTTP/1.1]). | |||
A proxy MAY transform the content of a message that does not contain | A proxy MAY transform the content of a message that does not contain | |||
a no-transform cache-control directive. A proxy that transforms the | a no-transform cache directive. A proxy that transforms the content | |||
content of a 200 (OK) response can inform downstream recipients that | of a 200 (OK) response can inform downstream recipients that a | |||
a transformation has been applied by changing the response status | transformation has been applied by changing the response status code | |||
code to 203 (Non-Authoritative Information) (Section 15.3.4). | to 203 (Non-Authoritative Information) (Section 15.3.4). | |||
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 content) unless the | or the selected representation (other than the content) 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. | |||
7.8. Upgrade | 7.8. Upgrade | |||
The "Upgrade" header field is intended to provide a simple mechanism | The "Upgrade" header field is intended to provide a simple mechanism | |||
skipping to change at page 65, line 47 ¶ | skipping to change at line 2983 ¶ | |||
a data format and various processing models: how to process that data | a data format and various processing models: how to process that data | |||
in accordance with the message context. | in accordance with the message context. | |||
media-type = type "/" subtype parameters | media-type = type "/" subtype parameters | |||
type = token | type = token | |||
subtype = token | subtype = token | |||
The type and subtype tokens are case-insensitive. | The type and subtype tokens are case-insensitive. | |||
The type/subtype MAY be followed by semicolon-delimited parameters | The type/subtype MAY be followed by semicolon-delimited parameters | |||
(Section 5.6.6) in the form of name=value pairs. The presence or | (Section 5.6.6) in the form of name/value pairs. The presence or | |||
absence of a parameter might be significant to the processing of a | absence of a parameter might be significant to the processing of a | |||
media type, depending on its definition within the media type | media type, depending on its definition within the media type | |||
registry. Parameter values might or might not be case-sensitive, | registry. Parameter values might or might not be case-sensitive, | |||
depending on the semantics of the parameter name. | depending on the semantics of the parameter name. | |||
For example, the following media types are equivalent in describing | For example, the following media types are equivalent in describing | |||
HTML text data encoded in the UTF-8 character encoding scheme, but | HTML text data encoded in the UTF-8 character encoding scheme, but | |||
the first is preferred for consistency (the "charset" parameter value | the first is preferred for consistency (the "charset" parameter value | |||
is defined as being case-insensitive in [RFC2046], Section 4.1.2): | 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 | |||
Media types ought to be registered with IANA according to the | Media types ought to be registered with IANA according to the | |||
procedures defined in [BCP13]. | procedures defined in [BCP13]. | |||
8.3.2. Charset | 8.3.2. Charset | |||
HTTP uses _charset_ names to indicate or negotiate the character | HTTP uses "charset" names to indicate or negotiate the character | |||
encoding scheme ([RFC6365], Section 1.3) of a textual representation. | encoding scheme ([RFC6365], Section 2) of a textual representation. | |||
In the fields defined by this document, charset names appear either | In the fields defined by this document, charset names appear either | |||
in parameters (Content-Type), or, for Accept-Encoding, in the form of | in parameters (Content-Type), or, for Accept-Encoding, in the form of | |||
a plain token. In both cases, charset names are matched case- | a plain token. In both cases, charset names are matched case- | |||
insensitively. | insensitively. | |||
Charset names ought to be registered in the IANA "Character Sets" | Charset names ought to be registered in the IANA "Character Sets" | |||
registry (<https://www.iana.org/assignments/character-sets>) | registry (<https://www.iana.org/assignments/character-sets>) | |||
according to the procedures defined in Section 2 of [RFC2978]. | according to the procedures defined in Section 2 of [RFC2978]. | |||
| *Note:* In theory, charset names are defined by the "mime- | | *Note:* In theory, charset names are defined by the "mime- | |||
| charset" ABNF rule defined in Section 2.3 of [RFC2978] (as | | charset" ABNF rule defined in Section 2.3 of [RFC2978] (as | |||
| corrected in [Err1912]). That rule allows two characters that | | corrected in [Err1912]). That rule allows two characters that | |||
| are not included in "token" ("{" and "}"), but no charset name | | are not included in "token" ("{" and "}"), but no charset name | |||
| registered at the time of this writing includes braces (see | | registered at the time of this writing includes braces (see | |||
| [Err5433]). | | [Err5433]). | |||
8.3.3. Multipart Types | 8.3.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 content. For example, | implementations that generate or process the content. 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 | |||
skipping to change at page 67, line 33 ¶ | skipping to change at line 3059 ¶ | |||
Content-Encoding = #content-coding | Content-Encoding = #content-coding | |||
An example of its use is | An example of its use is | |||
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. Note that the coding named "identity" is reserved | they were applied. Note that the coding named "identity" is reserved | |||
for its special role in Accept-Encoding, and thus SHOULD NOT be | for its special role in Accept-Encoding and thus SHOULD NOT be | |||
included. | included. | |||
Additional information about the encoding parameters can be provided | Additional information about the encoding parameters can be provided | |||
by other header fields not defined by this specification. | by other header fields not defined by this specification. | |||
Unlike Transfer-Encoding (Section 6.1 of [HTTP/1.1]), the codings | Unlike Transfer-Encoding (Section 6.1 of [HTTP/1.1]), 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. | |||
skipping to change at page 69, line 48 ¶ | skipping to change at line 3167 ¶ | |||
Content-Language: mi, en | Content-Language: mi, en | |||
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 limited | Content-Language MAY be applied to any media type -- it is not | |||
to textual documents. | limited to textual documents. | |||
8.5.1. Language Tags | 8.5.1. 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-Language header fields. Accept-Language uses the broader | Content-Language header fields. Accept-Language uses the broader | |||
skipping to change at page 70, line 41 ¶ | skipping to change at line 3206 ¶ | |||
8.6. Content-Length | 8.6. Content-Length | |||
The "Content-Length" header field indicates the associated | The "Content-Length" header field indicates the associated | |||
representation's data length as a decimal non-negative integer number | representation's data length as a decimal non-negative integer number | |||
of octets. When transferring a representation as content, Content- | of octets. When transferring a representation as content, Content- | |||
Length refers specifically to the amount of data enclosed so that it | Length refers specifically to the amount of data enclosed so that it | |||
can be used to delimit framing (e.g., Section 6.2 of [HTTP/1.1]). In | can be used to delimit framing (e.g., Section 6.2 of [HTTP/1.1]). In | |||
other cases, Content-Length indicates the selected representation's | other cases, Content-Length indicates the selected representation's | |||
current length, which can be used by recipients to estimate transfer | current length, which can be used by recipients to estimate transfer | |||
time or compare to previously stored representations. | time or to compare with previously stored representations. | |||
Content-Length = 1*DIGIT | Content-Length = 1*DIGIT | |||
An example is | An example is | |||
Content-Length: 3495 | Content-Length: 3495 | |||
A user agent SHOULD send Content-Length in a request when the method | A user agent SHOULD send Content-Length in a request when the method | |||
defines a meaning for enclosed content and it is not sending | defines a meaning for enclosed content and it is not sending | |||
Transfer-Encoding. For example, a user agent normally sends Content- | Transfer-Encoding. For example, a user agent normally sends Content- | |||
skipping to change at page 71, line 51 ¶ | skipping to change at line 3265 ¶ | |||
If the message is forwarded by a downstream intermediary, a Content- | If the message is forwarded by a downstream intermediary, a Content- | |||
Length field value that is inconsistent with the received message | Length field value that is inconsistent with the received message | |||
framing might cause a security failure due to request smuggling or | framing might cause a security failure due to request smuggling or | |||
response splitting. | response splitting. | |||
As a result, a sender MUST NOT forward a message with a Content- | As a result, a sender MUST NOT forward a message with a Content- | |||
Length header field value that is known to be incorrect. | Length header field value that is known to be incorrect. | |||
Likewise, a sender MUST NOT forward a message with a Content-Length | Likewise, a sender MUST NOT forward a message with a Content-Length | |||
header field value that does not match the ABNF above, with one | header field value that does not match the ABNF above, with one | |||
exception: A recipient of a Content-Length header field value | exception: a recipient of a Content-Length header field value | |||
consisting of the same decimal value repeated as a comma-separated | consisting of the same decimal value repeated as a comma-separated | |||
list (e.g, "Content-Length: 42, 42"), MAY either reject the message | list (e.g, "Content-Length: 42, 42") MAY either reject the message as | |||
as invalid or replace that invalid field value with a single instance | invalid or replace that invalid field value with a single instance of | |||
of the decimal value, since this likely indicates that a duplicate | the decimal value, since this likely indicates that a duplicate was | |||
was generated or combined by an upstream message processor. | generated or combined by an upstream message processor. | |||
8.7. Content-Location | 8.7. 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 content. In other words, if one | representation in this message's content. 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 content in this message. | representation that is enclosed as content in this message. | |||
skipping to change at page 74, line 7 ¶ | skipping to change at line 3360 ¶ | |||
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. | |||
8.8. Validator Fields | 8.8. Validator Fields | |||
Resource metadata is referred to as a _validator_ if it can be used | Resource metadata is referred to as a "validator" if it can be used | |||
within a precondition (Section 13.1) to make a conditional request | within a precondition (Section 13.1) to make a conditional request | |||
(Section 13). Validator fields convey a current validator for the | (Section 13). Validator fields convey a current validator for the | |||
selected representation (Section 3.2). | selected representation (Section 3.2). | |||
In responses to safe requests, validator fields describe the selected | In responses to safe requests, validator fields describe the selected | |||
representation chosen by the origin server while handling the | representation chosen by the origin server while handling the | |||
response. Note that, depending on the method and status code | response. Note that, depending on the method and status code | |||
semantics, the selected representation for a given response is not | semantics, the selected representation for a given response is not | |||
necessarily the same as the representation enclosed as response | necessarily the same as the representation enclosed as response | |||
content. | content. | |||
In a successful response to a state-changing request, validator | In a successful response to a state-changing request, validator | |||
fields describe the new representation that has replaced the prior | fields describe the new representation that has replaced the prior | |||
selected representation as a result of processing the request. | selected representation as a result of processing the request. | |||
For example, an ETag field in a 201 (Created) response communicates | For example, an ETag field in a 201 (Created) response communicates | |||
the entity-tag of the newly created resource's representation, so | the entity tag of the newly created resource's representation, so | |||
that the entity-tag can be used as a validator in later conditional | that the entity tag can be used as a validator in later conditional | |||
requests to prevent the "lost update" problem. | requests to prevent the "lost update" problem. | |||
This specification defines two forms of metadata that are commonly | This specification defines two forms of metadata that are commonly | |||
used to observe resource state and test for preconditions: | used to observe resource state and test for preconditions: | |||
modification dates (Section 8.8.2) and opaque entity tags | modification dates (Section 8.8.2) and opaque entity tags | |||
(Section 8.8.3). Additional metadata that reflects resource state | (Section 8.8.3). Additional metadata that reflects resource state | |||
has been defined by various extensions of HTTP, such as Web | has been defined by various extensions of HTTP, such as Web | |||
Distributed Authoring and Versioning [WEBDAV], that are beyond the | Distributed Authoring and Versioning [WEBDAV], that are beyond the | |||
scope of this specification. | scope of this specification. | |||
8.8.1. Weak versus Strong | 8.8.1. Weak versus Strong | |||
Validators come in two flavors: strong or weak. Weak validators are | Validators come in two flavors: strong or weak. Weak validators are | |||
easy to generate but are far less useful for comparisons. Strong | easy to generate but are far less useful for comparisons. Strong | |||
validators are ideal for comparisons but can be very difficult (and | validators are ideal for comparisons but can be very difficult (and | |||
occasionally impossible) to generate efficiently. Rather than impose | occasionally impossible) to generate efficiently. Rather than impose | |||
that all forms of resource adhere to the same strength of validator, | that all forms of resource adhere to the same strength of validator, | |||
HTTP exposes the type of validator in use and imposes restrictions on | HTTP exposes the type of validator in use and imposes restrictions on | |||
when weak validators can be used as preconditions. | when weak validators can be used as preconditions. | |||
A _strong validator_ is representation metadata that changes value | A "strong validator" is representation metadata that changes value | |||
whenever a change occurs to the representation data that would be | whenever a change occurs to the representation data that would be | |||
observable in the content of a 200 (OK) response to GET. | observable in the content of a 200 (OK) response to GET. | |||
A strong validator might change for reasons other than a change to | A strong validator might change for reasons other than a change to | |||
the representation data, such as when a semantically significant part | the representation data, such as when a semantically significant part | |||
of the representation metadata is changed (e.g., Content-Type), but | of the representation metadata is changed (e.g., Content-Type), but | |||
it is in the best interests of the origin server to only change the | it is in the best interests of the origin server to only change the | |||
value when it is necessary to invalidate the stored responses held by | value when it is necessary to invalidate the stored responses held by | |||
remote caches and authoring tools. | remote caches and authoring tools. | |||
skipping to change at page 75, line 32 ¶ | skipping to change at line 3434 ¶ | |||
accessible to GET. A collision-resistant hash function applied to | accessible to GET. A collision-resistant hash function applied to | |||
the representation data is also sufficient if the data is available | the representation data is also sufficient if the data is available | |||
prior to the response header fields being sent and the digest does | prior to the response header fields being sent and the digest does | |||
not need to be recalculated every time a validation request is | not need to be recalculated every time a validation request is | |||
received. However, if a resource has distinct representations that | received. However, if a resource has distinct representations that | |||
differ only in their metadata, such as might occur with content | differ only in their metadata, such as might occur with content | |||
negotiation over media types that happen to share the same data | negotiation over media types that happen to share the same data | |||
format, then the origin server needs to incorporate additional | format, then the origin server needs to incorporate additional | |||
information in the validator to distinguish those representations. | information in the validator to distinguish those representations. | |||
In contrast, a _weak validator_ is representation metadata that might | In contrast, a "weak validator" is representation metadata that might | |||
not change for every change to the representation data. This | not change for every change to the representation data. This | |||
weakness might be due to limitations in how the value is calculated | weakness might be due to limitations in how the value is calculated | |||
(e.g., clock resolution), an inability to ensure uniqueness for all | (e.g., clock resolution), an inability to ensure uniqueness for all | |||
possible representations of the resource, or a desire of the resource | possible representations of the resource, or a desire of the resource | |||
owner to group representations by some self-determined set of | owner to group representations by some self-determined set of | |||
equivalency rather than unique sequences of data. | equivalency rather than unique sequences of data. | |||
An origin server SHOULD change a weak entity-tag whenever it | An origin server SHOULD change a weak entity tag whenever it | |||
considers prior representations to be unacceptable as a substitute | considers prior representations to be unacceptable as a substitute | |||
for the current representation. In other words, a weak entity-tag | for the current representation. In other words, a weak entity tag | |||
ought to change whenever the origin server wants caches to invalidate | ought to change whenever the origin server wants caches to invalidate | |||
old responses. | old responses. | |||
For example, the representation of a weather report that changes in | For example, the representation of a weather report that changes in | |||
content every second, based on dynamic measurements, might be grouped | content every second, based on dynamic measurements, might be grouped | |||
into sets of equivalent representations (from the origin server's | into sets of equivalent representations (from the origin server's | |||
perspective) with the same weak validator in order to allow cached | perspective) with the same weak validator in order to allow cached | |||
representations to be valid for a reasonable period of time (perhaps | representations to be valid for a reasonable period of time (perhaps | |||
adjusted dynamically based on server load or weather quality). | adjusted dynamically based on server load or weather quality). | |||
Likewise, a representation's modification time, if defined with only | Likewise, a representation's modification time, if defined with only | |||
one-second resolution, might be a weak validator if it is possible | one-second resolution, might be a weak validator if it is possible | |||
for the representation to be modified twice during a single second | for the representation to be modified twice during a single second | |||
and retrieved between those modifications. | and retrieved between those modifications. | |||
Likewise, a validator is weak if it is shared by two or more | Likewise, a validator is weak if it is shared by two or more | |||
representations of a given resource at the same time, unless those | representations of a given resource at the same time, unless those | |||
representations have identical representation data. For example, if | representations have identical representation data. For example, if | |||
the origin server sends the same validator for a representation with | the origin server sends the same validator for a representation with | |||
a gzip content coding applied as it does for a representation with no | a gzip content coding applied as it does for a representation with no | |||
skipping to change at page 78, line 29 ¶ | skipping to change at line 3568 ¶ | |||
is enough difference between the Last-Modified and Date values to | is enough difference between the Last-Modified and Date values to | |||
make clock synchronization issues unlikely. | make clock synchronization issues unlikely. | |||
This method relies on the fact that if two different responses were | This method relies on the fact that if two different responses were | |||
sent by the origin server during the same second, but both had the | sent by the origin server during the same second, but both had the | |||
same Last-Modified time, then at least one of those responses would | same Last-Modified time, then at least one of those responses would | |||
have a Date value equal to its Last-Modified time. | have a Date value equal to its Last-Modified time. | |||
8.8.3. ETag | 8.8.3. ETag | |||
The "ETag" field in a response provides the current entity-tag for | The "ETag" field in a response provides the current entity tag for | |||
the selected representation, as determined at the conclusion of | the selected representation, as determined at the conclusion of | |||
handling the request. An entity-tag is an opaque validator for | handling the request. An entity tag is an opaque validator for | |||
differentiating between multiple representations of the same | differentiating between multiple representations of the same | |||
resource, regardless of whether those multiple representations are | resource, regardless of whether those multiple representations are | |||
due to resource state changes over time, content negotiation | due to resource state changes over time, content negotiation | |||
resulting in multiple representations being valid at the same time, | resulting in multiple representations being valid at the same time, | |||
or both. An entity-tag consists of an opaque quoted string, possibly | or both. An entity tag consists of an opaque quoted string, possibly | |||
prefixed by a weakness indicator. | prefixed by a weakness indicator. | |||
ETag = entity-tag | ETag = entity-tag | |||
entity-tag = [ weak ] opaque-tag | entity-tag = [ weak ] opaque-tag | |||
weak = %s"W/" | weak = %s"W/" | |||
opaque-tag = DQUOTE *etagc DQUOTE | opaque-tag = DQUOTE *etagc DQUOTE | |||
etagc = %x21 / %x23-7E / obs-text | etagc = %x21 / %x23-7E / obs-text | |||
; VCHAR except double quotes, plus obs-text | ; VCHAR except double quotes, plus obs-text | |||
| *Note:* Previously, opaque-tag was defined to be a quoted- | | *Note:* Previously, opaque-tag was defined to be a quoted- | |||
| string ([RFC2616], Section 3.11); thus, some recipients might | | string ([RFC2616], Section 3.11); thus, some recipients might | |||
| perform backslash unescaping. Servers therefore ought to avoid | | perform backslash unescaping. Servers therefore ought to avoid | |||
| backslash characters in entity tags. | | backslash characters in entity tags. | |||
An entity-tag can be more reliable for validation than a modification | An entity tag can be more reliable for validation than a modification | |||
date in situations where it is inconvenient to store modification | date in situations where it is inconvenient to store modification | |||
dates, where the one-second resolution of HTTP date values is not | dates, where the one-second resolution of HTTP-date values is not | |||
sufficient, or where modification dates are not consistently | sufficient, or where modification dates are not consistently | |||
maintained. | maintained. | |||
Examples: | Examples: | |||
ETag: "xyzzy" | ETag: "xyzzy" | |||
ETag: W/"xyzzy" | ETag: W/"xyzzy" | |||
ETag: "" | ETag: "" | |||
An entity-tag can be either a weak or strong validator, with strong | An entity tag can be either a weak or strong validator, with strong | |||
being the default. If an origin server provides an entity-tag for a | being the default. If an origin server provides an entity tag for a | |||
representation and the generation of that entity-tag does not satisfy | representation and the generation of that entity tag does not satisfy | |||
all of the characteristics of a strong validator (Section 8.8.1), | all of the characteristics of a strong validator (Section 8.8.1), | |||
then the origin server MUST mark the entity-tag as weak by prefixing | then the origin server MUST mark the entity tag as weak by prefixing | |||
its opaque value with "W/" (case-sensitive). | its opaque value with "W/" (case-sensitive). | |||
A sender MAY send the Etag field in a trailer section (see | A sender MAY send the ETag field in a trailer section (see | |||
Section 6.5). However, since trailers are often ignored, it is | Section 6.5). However, since trailers are often ignored, it is | |||
preferable to send Etag as a header field unless the entity-tag is | preferable to send ETag as a header field unless the entity tag is | |||
generated while sending the content. | generated while sending the content. | |||
8.8.3.1. Generation | 8.8.3.1. Generation | |||
The principle behind entity-tags is that only the service author | The principle behind entity tags is that only the service author | |||
knows the implementation of a resource well enough to select the most | knows the implementation of a resource well enough to select the most | |||
accurate and efficient validation mechanism for that resource, and | accurate and efficient validation mechanism for that resource, and | |||
that any such mechanism can be mapped to a simple sequence of octets | that any such mechanism can be mapped to a simple sequence of octets | |||
for easy comparison. Since the value is opaque, there is no need for | for easy comparison. Since the value is opaque, there is no need for | |||
the client to be aware of how each entity-tag is constructed. | the client to be aware of how each entity tag is constructed. | |||
For example, a resource that has implementation-specific versioning | For example, a resource that has implementation-specific versioning | |||
applied to all changes might use an internal revision number, perhaps | applied to all changes might use an internal revision number, perhaps | |||
combined with a variance identifier for content negotiation, to | combined with a variance identifier for content negotiation, to | |||
accurately differentiate between representations. Other | accurately differentiate between representations. Other | |||
implementations might use a collision-resistant hash of | implementations might use a collision-resistant hash of | |||
representation content, a combination of various file attributes, or | representation content, a combination of various file attributes, or | |||
a modification timestamp that has sub-second resolution. | a modification timestamp that has sub-second resolution. | |||
An origin server SHOULD send an ETag for any selected representation | An origin server SHOULD send an ETag for any selected representation | |||
for which detection of changes can be reasonably and consistently | for which detection of changes can be reasonably and consistently | |||
determined, since the entity-tag's use in conditional requests and | determined, since the entity tag's use in conditional requests and | |||
evaluating cache freshness ([CACHING]) can substantially reduce | evaluating cache freshness ([CACHING]) can substantially reduce | |||
unnecessary transfers and significantly improve service availability, | unnecessary transfers and significantly improve service availability, | |||
scalability, and reliability. | scalability, and reliability. | |||
8.8.3.2. Comparison | 8.8.3.2. Comparison | |||
There are two entity-tag comparison functions, depending on whether | There are two entity tag comparison functions, depending on whether | |||
or not the comparison context allows the use of weak validators: | or not the comparison context allows the use of weak validators: | |||
_Strong comparison_: two entity-tags are equivalent if both are not | "Strong comparison": two entity tags are equivalent if both are not | |||
weak and their opaque-tags match character-by-character. | weak and their opaque-tags match character-by-character. | |||
_Weak comparison_: two entity-tags are equivalent if their opaque- | "Weak comparison": two entity tags are equivalent if their opaque- | |||
tags match character-by-character, regardless of either or both | tags match character-by-character, regardless of either or both | |||
being tagged as "weak". | being tagged as "weak". | |||
The example below shows the results for a set of entity-tag pairs and | The example below shows the results for a set of entity tag pairs and | |||
both the weak and strong comparison function results: | both the weak and strong comparison function results: | |||
+========+========+===================+=================+ | +========+========+===================+=================+ | |||
| ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | | | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | | |||
+========+========+===================+=================+ | +========+========+===================+=================+ | |||
| W/"1" | W/"1" | no match | match | | | W/"1" | W/"1" | no match | match | | |||
+--------+--------+-------------------+-----------------+ | +--------+--------+-------------------+-----------------+ | |||
| W/"1" | W/"2" | no match | no match | | | W/"1" | W/"2" | no match | no match | | |||
+--------+--------+-------------------+-----------------+ | +--------+--------+-------------------+-----------------+ | |||
| W/"1" | "1" | no match | match | | | W/"1" | "1" | no match | match | | |||
+--------+--------+-------------------+-----------------+ | +--------+--------+-------------------+-----------------+ | |||
| "1" | "1" | match | match | | | "1" | "1" | match | match | | |||
+--------+--------+-------------------+-----------------+ | +--------+--------+-------------------+-----------------+ | |||
Table 3 | Table 3 | |||
8.8.3.3. Example: Entity-Tags Varying on Content-Negotiated Resources | 8.8.3.3. Example: Entity Tags Varying on Content-Negotiated Resources | |||
Consider a resource that is subject to content negotiation | Consider a resource that is subject to content negotiation | |||
(Section 12), and where the representations sent in response to a GET | (Section 12), and where the representations sent in response to a GET | |||
request vary based on the Accept-Encoding request header field | request vary based on the Accept-Encoding request header field | |||
(Section 12.5.3): | (Section 12.5.3): | |||
>> Request: | >> Request: | |||
GET /index HTTP/1.1 | GET /index HTTP/1.1 | |||
Host: www.example.com | Host: www.example.com | |||
skipping to change at page 81, line 34 ¶ | skipping to change at line 3715 ¶ | |||
Date: Fri, 26 Mar 2010 00:05:00 GMT | Date: Fri, 26 Mar 2010 00:05:00 GMT | |||
ETag: "123-b" | ETag: "123-b" | |||
Content-Length: 43 | Content-Length: 43 | |||
Vary: Accept-Encoding | Vary: Accept-Encoding | |||
Content-Type: text/plain | Content-Type: text/plain | |||
Content-Encoding: gzip | Content-Encoding: gzip | |||
...binary data... | ...binary data... | |||
| *Note:* Content codings are a property of the representation | | *Note:* Content codings are a property of the representation | |||
| data, so a strong entity-tag for a content-encoded | | data, so a strong entity tag for a content-encoded | |||
| representation has to be distinct from the entity tag of an | | representation has to be distinct from the entity tag of an | |||
| unencoded representation to prevent potential conflicts during | | unencoded representation to prevent potential conflicts during | |||
| cache updates and range requests. In contrast, transfer | | cache updates and range requests. In contrast, transfer | |||
| codings (Section 7 of [HTTP/1.1]) apply only during message | | codings (Section 7 of [HTTP/1.1]) apply only during message | |||
| transfer and do not result in distinct entity-tags. | | transfer and do not result in distinct entity tags. | |||
9. Methods | 9. Methods | |||
9.1. Overview | 9.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 | |||
skipping to change at page 83, line 5 ¶ | skipping to change at line 3759 ¶ | |||
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. | commonly used in HTTP, as outlined by the following table. | |||
+=========+============================================+=======+ | +=============+============================================+=======+ | |||
| Method | Description | Ref. | | | Method Name | Description | Ref. | | |||
+=========+============================================+=======+ | +=============+============================================+=======+ | |||
| GET | Transfer a current representation of the | 9.3.1 | | | GET | Transfer a current representation of the | 9.3.1 | | |||
| | target resource. | | | | | target resource. | | | |||
+---------+--------------------------------------------+-------+ | +-------------+--------------------------------------------+-------+ | |||
| HEAD | Same as GET, but do not transfer the | 9.3.2 | | | HEAD | Same as GET, but do not transfer the | 9.3.2 | | |||
| | response content. | | | | | response content. | | | |||
+---------+--------------------------------------------+-------+ | +-------------+--------------------------------------------+-------+ | |||
| POST | Perform resource-specific processing on | 9.3.3 | | | POST | Perform resource-specific processing on | 9.3.3 | | |||
| | the request content. | | | | | the request content. | | | |||
+---------+--------------------------------------------+-------+ | +-------------+--------------------------------------------+-------+ | |||
| PUT | Replace all current representations of the | 9.3.4 | | | PUT | Replace all current representations of the | 9.3.4 | | |||
| | target resource with the request content. | | | | | target resource with the request content. | | | |||
+---------+--------------------------------------------+-------+ | +-------------+--------------------------------------------+-------+ | |||
| DELETE | Remove all current representations of the | 9.3.5 | | | DELETE | Remove all current representations of the | 9.3.5 | | |||
| | target resource. | | | | | target resource. | | | |||
+---------+--------------------------------------------+-------+ | +-------------+--------------------------------------------+-------+ | |||
| CONNECT | Establish a tunnel to the server | 9.3.6 | | | CONNECT | Establish a tunnel to the server | 9.3.6 | | |||
| | identified by the target resource. | | | | | identified by the target resource. | | | |||
+---------+--------------------------------------------+-------+ | +-------------+--------------------------------------------+-------+ | |||
| OPTIONS | Describe the communication options for the | 9.3.7 | | | OPTIONS | Describe the communication options for the | 9.3.7 | | |||
| | target resource. | | | | | target resource. | | | |||
+---------+--------------------------------------------+-------+ | +-------------+--------------------------------------------+-------+ | |||
| TRACE | Perform a message loop-back test along the | 9.3.8 | | | TRACE | Perform a message loop-back test along the | 9.3.8 | | |||
| | path to the target resource. | | | | | path to the target resource. | | | |||
+---------+--------------------------------------------+-------+ | +-------------+--------------------------------------------+-------+ | |||
Table 4 | 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 10.2.1). However, the set of allowed | Allow header field (Section 10.2.1). However, the set of allowed | |||
methods can change dynamically. An origin server that receives a | methods can change dynamically. An origin server that receives a | |||
request method that is unrecognized or not implemented SHOULD respond | request method that is unrecognized or not implemented SHOULD respond | |||
with the 501 (Not Implemented) status code. An origin server that | with the 501 (Not Implemented) status code. An origin server that | |||
receives a request method that is recognized and implemented, but not | receives a request method that is recognized and implemented, but not | |||
skipping to change at page 84, line 9 ¶ | skipping to change at line 3810 ¶ | |||
Additional methods, outside the scope of this specification, have | Additional methods, outside the scope of this specification, have | |||
been specified 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", as described in Section 16.1. | Registry", as described in Section 16.1. | |||
9.2. Common Method Properties | 9.2. Common Method Properties | |||
9.2.1. Safe Methods | 9.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 | |||
entirely read-only, or that causes side effects while invoking a safe | entirely read-only, or that causes side effects while invoking a safe | |||
method. What is important, however, is that the client did not | method. What is important, however, is that the client did not | |||
skipping to change at page 85, line 20 ¶ | skipping to change at line 3858 ¶ | |||
parameters, such as "page?do=delete". If the purpose of such a | 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. | |||
9.2.2. Idempotent Methods | 9.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 | |||
other non-idempotent side effects for each idempotent request. | other non-idempotent side effects for each idempotent request. | |||
skipping to change at page 86, line 17 ¶ | skipping to change at line 3904 ¶ | |||
automatically retry a POST request if the underlying transport | automatically retry a POST request if the underlying transport | |||
connection closed before any part of a response is received, | connection closed before any part of a response is received, | |||
particularly if an idle persistent connection was used. | particularly if an idle persistent connection was used. | |||
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. | |||
9.2.3. Methods and Caching | 9.2.3. Methods and Caching | |||
For a cache to store and use a response, the associated method needs | For a cache to store and use a response, the associated method needs | |||
to explicitly allow caching, and detail under what conditions a | to explicitly allow caching and to detail under what conditions a | |||
response can be used to satisfy subsequent requests; a method | response can be used to satisfy subsequent requests; a method | |||
definition which does not do so cannot be cached. For additional | definition that does not do so cannot be cached. For additional | |||
requirements see [CACHING]. | requirements see [CACHING]. | |||
This specification defines caching semantics for GET, HEAD, and POST, | This specification defines caching semantics for GET, HEAD, and POST, | |||
although the overwhelming majority of cache implementations only | although the overwhelming majority of cache implementations only | |||
support GET and HEAD. | support GET and HEAD. | |||
9.3. Method Definitions | 9.3. Method Definitions | |||
9.3.1. GET | 9.3.1. GET | |||
skipping to change at page 89, line 25 ¶ | skipping to change at line 4056 ¶ | |||
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 10.2.2) and a representation that describes the status of | (Section 10.2.2) and a representation that describes the status of | |||
the 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 [CACHING]) and a | explicit freshness information (see Section 4.2.1 of [CACHING]) 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 | |||
target URI (Section 8.7). A cached POST response can be reused to | target URI (Section 8.7). A cached POST response can be reused to | |||
satisfy a later GET or HEAD request, but not a POST request, since | satisfy a later GET or HEAD request. In contrast, a POST request | |||
POST is required to be written through to the origin server, because | cannot be satisfied by a cached POST response because POST is | |||
it is unsafe; see Section 4 of [CACHING]. | potentially 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. | |||
skipping to change at page 91, line 21 ¶ | skipping to change at line 4148 ¶ | |||
of the resource state). | of the resource state). | |||
An origin server MUST NOT send a validator field (Section 8.8), such | An origin server MUST NOT send a validator field (Section 8.8), such | |||
as an ETag or Last-Modified field, in a successful response to PUT | as an ETag or Last-Modified field, in a successful response to PUT | |||
unless the request's representation data was saved without any | unless the request's representation data was saved without any | |||
transformation applied to the content (i.e., the resource's new | transformation applied to the content (i.e., the resource's new | |||
representation data is identical to the content received in the PUT | representation data is identical to the content received in the PUT | |||
request) and the validator field value reflects the new | request) and the validator field value reflects the new | |||
representation. This requirement allows a user agent to know when | representation. This requirement allows a user agent to know when | |||
the representation it sent (and retains in memory) is the result of | the representation it sent (and retains in memory) is the result of | |||
the PUT, and thus doesn't need to be retrieved again from the origin | the PUT, and thus it doesn't need to be retrieved again from the | |||
server. The new validator(s) received in the response can be used | origin server. The new validator(s) received in the response can be | |||
for future conditional requests in order to prevent accidental | used for future conditional requests in order to prevent accidental | |||
overwrites (Section 13.1). | overwrites (Section 13.1). | |||
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 page 93, line 5 ¶ | skipping to change at line 4212 ¶ | |||
might or might not be destroyed by the origin server, and the | might or might not be destroyed by the origin server, and the | |||
associated storage might or might not be reclaimed, depending | associated storage might or might not be reclaimed, depending | |||
entirely on the nature of the resource and its implementation by the | entirely on the nature of the resource and its implementation by the | |||
origin server (which are beyond the scope of this specification). | origin server (which are beyond the scope of this specification). | |||
Likewise, other implementation aspects of a resource might need to be | Likewise, other implementation aspects of a resource might need to be | |||
deactivated or archived as a result of a DELETE, such as database or | deactivated or archived as a result of a DELETE, such as database or | |||
gateway connections. In general, it is assumed that the origin | gateway connections. In general, it is assumed that the origin | |||
server will only allow DELETE on resources for which it has a | server will only allow DELETE on resources for which it has a | |||
prescribed mechanism for accomplishing the deletion. | prescribed mechanism for accomplishing the deletion. | |||
Relatively few resources allow the DELETE method - its primary use is | Relatively few resources allow the DELETE method -- its primary use | |||
for remote authoring environments, where the user has some direction | is for remote authoring environments, where the user has some | |||
regarding its effect. For example, a resource that was previously | direction regarding its effect. For example, a resource that was | |||
created using a PUT request, or identified via the Location header | previously created using a PUT request, or identified via the | |||
field after a 201 (Created) response to a POST request, might allow a | Location header field after a 201 (Created) response to a POST | |||
corresponding DELETE request to undo those actions. Similarly, | request, might allow a corresponding DELETE request to undo those | |||
custom user agent implementations that implement an authoring | actions. Similarly, custom user agent implementations that implement | |||
function, such as revision control clients using HTTP for remote | an authoring function, such as revision control clients using HTTP | |||
operations, might use DELETE based on an assumption that the server's | for remote operations, might use DELETE based on an assumption that | |||
URI space has been crafted to correspond to a version repository. | the server's URI space has been crafted to correspond to a version | |||
repository. | ||||
If a DELETE method is successfully applied, the origin server SHOULD | If a DELETE method is successfully applied, the origin server SHOULD | |||
send | send | |||
* a 202 (Accepted) status code if the action will likely succeed but | * a 202 (Accepted) status code if the action will likely succeed but | |||
has not yet been enacted, | has not yet been enacted, | |||
* a 204 (No Content) status code if the action has been enacted and | * a 204 (No Content) status code if the action has been enacted and | |||
no further information is to be supplied, or | no further information is to be supplied, or | |||
skipping to change at page 96, line 33 ¶ | skipping to change at line 4378 ¶ | |||
such content. | such content. | |||
Responses to the OPTIONS method are not cacheable. | Responses to the OPTIONS method are not cacheable. | |||
9.3.8. TRACE | 9.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 content of a 200 (OK) response. The | back to the client as the content of a 200 (OK) response. The | |||
"message/http" (Section 10.1 of [HTTP/1.1]) format is one way to do | "message/http" format (Section 10.1 of [HTTP/1.1]) is one way to do | |||
so. The final recipient is either the origin server or the first | so. The final recipient is either the origin server or the first | |||
server to receive a Max-Forwards value of zero (0) in the request | server to receive a Max-Forwards value of zero (0) in the request | |||
(Section 7.6.2). | (Section 7.6.2). | |||
A client MUST NOT generate fields in a TRACE request containing | A client MUST NOT generate fields in a TRACE request containing | |||
sensitive data that might be disclosed by the response. For example, | sensitive data that might be disclosed by the response. For example, | |||
it would be foolish for a user agent to send stored user credentials | it would be foolish for a user agent to send stored user credentials | |||
(Section 11) or cookies [COOKIE] in a TRACE request. The final | (Section 11) or cookies [COOKIE] in a TRACE request. The final | |||
recipient of the request SHOULD exclude any request fields that are | recipient of the request SHOULD exclude any request fields that are | |||
likely to contain sensitive data when that recipient generates the | likely to contain sensitive data when that recipient generates the | |||
skipping to change at page 97, line 36 ¶ | skipping to change at line 4430 ¶ | |||
The Expect field value is case-insensitive. | The Expect field value is case-insensitive. | |||
The only expectation defined by this specification is "100-continue" | The only expectation defined by this specification is "100-continue" | |||
(with no defined parameters). | (with no defined parameters). | |||
A server that receives an Expect field value containing a member | A server that receives an Expect field value containing a member | |||
other than 100-continue MAY respond with a 417 (Expectation Failed) | other than 100-continue MAY respond with a 417 (Expectation Failed) | |||
status code to indicate that the unexpected expectation cannot be | status code to indicate that the unexpected expectation cannot be | |||
met. | met. | |||
A _100-continue_ expectation informs recipients that the client is | A "100-continue" expectation informs recipients that the client is | |||
about to send (presumably large) content in this request and wishes | about to send (presumably large) content in this request and wishes | |||
to receive a 100 (Continue) interim response if the method, target | to receive a 100 (Continue) interim response if the method, target | |||
URI, and header fields are not sufficient to cause an immediate | URI, and header fields are not sufficient to cause an immediate | |||
success, redirect, or error response. This allows the client to wait | success, redirect, or error response. This allows the client to wait | |||
for an indication that it is worthwhile to send the content before | for an indication that it is worthwhile to send the content before | |||
actually doing so, which can improve efficiency when the data is huge | actually doing so, which can improve efficiency when the data is huge | |||
or when the client anticipates that an error is likely (e.g., when | or when the client anticipates that an error is likely (e.g., when | |||
sending a state-changing method, for the first time, without | sending a state-changing method, for the first time, without | |||
previously verified authentication credentials). | previously verified authentication credentials). | |||
skipping to change at page 99, line 10 ¶ | skipping to change at line 4494 ¶ | |||
* A server that sends a 100 (Continue) response MUST ultimately send | * A server that sends a 100 (Continue) response MUST ultimately send | |||
a final status code, once it receives and processes the request | a final status code, once it receives and processes the request | |||
content, unless the connection is closed prematurely. | content, unless the connection is closed prematurely. | |||
* A server that responds with a final status code before reading the | * A server that responds with a final status code before reading the | |||
entire request content SHOULD indicate whether it intends to close | entire request content SHOULD indicate whether it intends to close | |||
the connection (e.g., see Section 9.6 of [HTTP/1.1]) or continue | the connection (e.g., see Section 9.6 of [HTTP/1.1]) or continue | |||
reading the request content. | reading the request content. | |||
An origin server MUST, upon receiving an HTTP/1.1 (or later) request | Upon receiving an HTTP/1.1 (or later) request that has a method, | |||
that has a method, target URI, and complete header section that | target URI, and complete header section that contains a 100-continue | |||
contains a 100-continue expectation and an indication that request | expectation and an indication that request content will follow, an | |||
content will follow, either send an immediate response with a final | origin server MUST send either: | |||
status code, if that status can be determined by examining just the | ||||
method, target URI, and header fields, or send an immediate 100 | ||||
(Continue) response to encourage the client to send the request | ||||
content. The origin server MUST NOT wait for the content before | ||||
sending the 100 (Continue) response. | ||||
A proxy MUST, upon receiving an HTTP/1.1 (or later) request that has | * an immediate response with a final status code, if that status can | |||
a method, target URI, and complete header section that contains a | be determined by examining just the method, target URI, and header | |||
100-continue expectation and indicates a request content will follow, | fields, or | |||
either send an immediate response with a final status code, if that | ||||
status can be determined by examining just the method, target URI, | * an immediate 100 (Continue) response to encourage the client to | |||
and header fields, or begin forwarding the request toward the origin | send the request content. | |||
server by sending a corresponding request-line and header section to | ||||
the next inbound server. If the proxy believes (from configuration | The origin server MUST NOT wait for the content before sending the | |||
or past interaction) that the next inbound server only supports | 100 (Continue) response. | |||
HTTP/1.0, the proxy MAY generate an immediate 100 (Continue) response | ||||
to encourage the client to begin sending the content. | Upon receiving an HTTP/1.1 (or later) request that has a method, | |||
target URI, and complete header section that contains a 100-continue | ||||
expectation and indicates a request content will follow, a proxy MUST | ||||
either: | ||||
* send an immediate response with a final status code, if that | ||||
status can be determined by examining just the method, target URI, | ||||
and header fields, or | ||||
* forward the request toward the origin server by sending a | ||||
corresponding request-line and header section to the next inbound | ||||
server. | ||||
If the proxy believes (from configuration or past interaction) that | ||||
the next inbound server only supports HTTP/1.0, the proxy MAY | ||||
generate an immediate 100 (Continue) response to encourage the client | ||||
to begin sending the content. | ||||
10.1.2. From | 10.1.2. From | |||
The "From" header field contains an Internet email address for a | The "From" header field contains an Internet email address for a | |||
human user who controls the requesting user agent. The address ought | human user who controls the requesting user agent. The address ought | |||
to be machine-usable, as defined by "mailbox" in Section 3.4 of | to be machine-usable, as defined by "mailbox" in Section 3.4 of | |||
[RFC5322]: | [RFC5322]: | |||
From = mailbox | From = mailbox | |||
mailbox = <mailbox, see [RFC5322], Section 3.4> | mailbox = <mailbox, see [RFC5322], Section 3.4> | |||
An example is: | An example is: | |||
From: webmaster@example.org | From: spider-admin@example.org | |||
The From header field is rarely sent by non-robotic user agents. A | The From header field is rarely sent by non-robotic user agents. A | |||
user agent SHOULD NOT send a From header field without explicit | user agent SHOULD NOT send a From header field without explicit | |||
configuration by the user, since that might conflict with the user's | configuration by the user, since that might conflict with the user's | |||
privacy interests or their site's security policy. | privacy interests or their site's security policy. | |||
A robotic user agent SHOULD send a valid From header field so that | A robotic user agent SHOULD send a valid From header field so that | |||
the person responsible for running the robot can be contacted if | the person responsible for running the robot can be contacted if | |||
problems occur on servers, such as if the robot is sending excessive, | problems occur on servers, such as if the robot is sending excessive, | |||
unwanted, or invalid requests. | unwanted, or invalid requests. | |||
skipping to change at page 101, line 32 ¶ | skipping to change at line 4623 ¶ | |||
information disclosure in Referer ought to restrict their changes to | information disclosure in Referer ought to restrict their changes to | |||
specific edits, such as replacing internal domain names with | specific edits, such as replacing internal domain names with | |||
pseudonyms or truncating the query and/or path components. An | pseudonyms or truncating the query and/or path components. An | |||
intermediary SHOULD NOT modify or delete the Referer header field | intermediary SHOULD NOT modify or delete the Referer header field | |||
when the field value shares the same scheme and host as the target | when the field value shares the same scheme and host as the target | |||
URI. | URI. | |||
10.1.4. TE | 10.1.4. TE | |||
The "TE" header field describes capabilities of the client with | The "TE" header field describes capabilities of the client with | |||
regard to transfer encodings and trailer sections. | regard to transfer codings and trailer sections. | |||
A TE field with a "trailers" member sent in a request indicates that | As described in Section 6.5, a TE field with a "trailers" member sent | |||
the client will not discard trailer fields, as described in | in a request indicates that the client will not discard trailer | |||
Section 6.5. | fields. | |||
TE is also used within HTTP/1.1 to advise servers about what transfer | TE is also used within HTTP/1.1 to advise servers about which | |||
codings the client is able to accept in a response. As of | transfer codings the client is able to accept in a response. As of | |||
publication, only HTTP/1.1 uses transfer codings (see Section 7 of | publication, only HTTP/1.1 uses transfer codings (see Section 7 of | |||
[HTTP/1.1]). | [HTTP/1.1]). | |||
The TE field value is a list of members, with each member (aside from | The TE field value is a list of members, with each member (aside from | |||
"trailers") consisting of a transfer coding name token with an | "trailers") consisting of a transfer coding name token with an | |||
optional weight indicating the client's relative preference for that | optional weight indicating the client's relative preference for that | |||
transfer coding (Section 12.4.2) and optional parameters for that | transfer coding (Section 12.4.2) and optional parameters for that | |||
transfer coding. | transfer coding. | |||
TE = #t-codings | TE = #t-codings | |||
skipping to change at page 103, line 45 ¶ | skipping to change at line 4725 ¶ | |||
Allow: GET, HEAD, PUT | Allow: GET, HEAD, PUT | |||
The actual set of allowed methods is defined by the origin server at | The actual set of allowed methods is defined by the origin server at | |||
the time of each request. An origin server MUST generate an Allow | the time of each request. An origin server MUST generate an Allow | |||
header field in a 405 (Method Not Allowed) response and MAY do so in | header field in a 405 (Method Not Allowed) response and MAY do so in | |||
any other response. An empty Allow field value indicates that the | any other response. An empty Allow field value indicates that the | |||
resource allows no methods, which might occur in a 405 response if | resource allows no methods, which might occur in a 405 response if | |||
the resource has been temporarily disabled by configuration. | the resource has been temporarily disabled by configuration. | |||
A proxy MUST NOT modify the Allow header field - it does not need to | A proxy MUST NOT modify the Allow header field -- it does not need to | |||
understand all of the indicated methods in order to handle them | understand all of the indicated methods in order to handle them | |||
according to the generic message handling rules. | according to the generic message handling rules. | |||
10.2.2. Location | 10.2.2. Location | |||
The "Location" header field is used in some responses to refer to a | The "Location" header field is used in some responses to refer to a | |||
specific resource in relation to the response. The type of | specific resource in relation to the response. The type of | |||
relationship is defined by the combination of request method and | relationship is defined by the combination of request method and | |||
status code semantics. | status code semantics. | |||
skipping to change at page 106, line 45 ¶ | skipping to change at line 4861 ¶ | |||
11. HTTP Authentication | 11. HTTP Authentication | |||
11.1. Authentication Scheme | 11.1. Authentication Scheme | |||
HTTP provides a general framework for access control and | HTTP provides a general framework for access control and | |||
authentication, via an extensible set of challenge-response | authentication, via an extensible set of challenge-response | |||
authentication schemes, which can be used by a server to challenge a | authentication schemes, which can be used by a server to challenge a | |||
client request and by a client to provide authentication information. | client request and by a client to provide authentication information. | |||
It uses a case-insensitive token to identify the authentication | It uses a case-insensitive token to identify the authentication | |||
scheme | scheme: | |||
auth-scheme = token | auth-scheme = token | |||
Aside from the general framework, this document does not specify any | Aside from the general framework, this document does not specify any | |||
authentication schemes. New and existing authentication schemes are | authentication schemes. New and existing authentication schemes are | |||
specified independently and ought to be registered within the | specified independently and ought to be registered within the | |||
"Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry". | "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry". | |||
For example, the "basic" and "digest" authentication schemes are | For example, the "basic" and "digest" authentication schemes are | |||
defined by RFC 7617 and RFC 7616, respectively. | defined by RFC 7617 [RFC7617] and RFC 7616 [RFC7616], respectively. | |||
11.2. Authentication Parameters | 11.2. Authentication Parameters | |||
The authentication scheme is followed by additional information | The authentication scheme is followed by additional information | |||
necessary for achieving authentication via that scheme as either a | necessary for achieving authentication via that scheme as either a | |||
comma-separated list of parameters or a single sequence of characters | comma-separated list of parameters or a single sequence of characters | |||
capable of holding base64-encoded information. | capable of holding base64-encoded information. | |||
token68 = 1*( ALPHA / DIGIT / | token68 = 1*( ALPHA / DIGIT / | |||
"-" / "." / "_" / "~" / "+" / "/" ) *"=" | "-" / "." / "_" / "~" / "+" / "/" ) *"=" | |||
The token68 syntax allows the 66 unreserved URI characters ([URI]), | The token68 syntax allows the 66 unreserved URI characters ([URI]), | |||
plus a few others, so that it can hold a base64, base64url (URL and | plus a few others, so that it can hold a base64, base64url (URL and | |||
filename safe alphabet), base32, or base16 (hex) encoding, with or | filename safe alphabet), base32, or base16 (hex) encoding, with or | |||
without padding, but excluding whitespace ([RFC4648]). | without padding, but excluding whitespace ([RFC4648]). | |||
Authentication parameters are name=value pairs, where the name token | Authentication parameters are name/value pairs, where the name token | |||
is matched case-insensitively and each parameter name MUST only occur | is matched case-insensitively and each parameter name MUST only occur | |||
once per challenge. | once per challenge. | |||
auth-param = token BWS "=" BWS ( token / quoted-string ) | auth-param = token BWS "=" BWS ( token / quoted-string ) | |||
Parameter values can be expressed either as "token" or as "quoted- | Parameter values can be expressed either as "token" or as "quoted- | |||
string" (Section 5.6). Authentication scheme definitions need to | string" (Section 5.6). Authentication scheme definitions need to | |||
accept both notations, both for senders and recipients, to allow | accept both notations, both for senders and recipients, to allow | |||
recipients to use generic parsing components regardless of the | recipients to use generic parsing components regardless of the | |||
authentication scheme. | authentication scheme. | |||
skipping to change at page 108, line 17 ¶ | skipping to change at line 4923 ¶ | |||
Proxy-Authenticate header field containing at least one challenge | Proxy-Authenticate header field containing at least one challenge | |||
applicable to the proxy for the requested resource. | applicable to the proxy for the requested resource. | |||
challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ] | challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ] | |||
| *Note:* Many clients fail to parse a challenge that contains an | | *Note:* Many clients fail to parse a challenge that contains an | |||
| unknown scheme. A workaround for this problem is to list well- | | unknown scheme. A workaround for this problem is to list well- | |||
| supported schemes (such as "basic") first. | | supported schemes (such as "basic") first. | |||
A user agent that wishes to authenticate itself with an origin server | A user agent that wishes to authenticate itself with an origin server | |||
- usually, but not necessarily, after receiving a 401 (Unauthorized) | -- usually, but not necessarily, after receiving a 401 (Unauthorized) | |||
- can do so by including an Authorization header field with the | -- can do so by including an Authorization header field with the | |||
request. | request. | |||
A client that wishes to authenticate itself with a proxy - usually, | A client that wishes to authenticate itself with a proxy -- usually, | |||
but not necessarily, after receiving a 407 (Proxy Authentication | but not necessarily, after receiving a 407 (Proxy Authentication | |||
Required) - can do so by including a Proxy-Authorization header field | Required) -- can do so by including a Proxy-Authorization header | |||
with the request. | field with the request. | |||
11.4. Credentials | 11.4. Credentials | |||
Both the Authorization field value and the Proxy-Authorization field | Both the Authorization field value and the Proxy-Authorization field | |||
value contain the client's credentials for the realm of the resource | value contain the client's credentials for the realm of the resource | |||
being requested, based upon a challenge received in a response | being requested, based upon a challenge received in a response | |||
(possibly at some point in the past). When creating their values, | (possibly at some point in the past). When creating their values, | |||
the user agent ought to do so by selecting the challenge with what it | the user agent ought to do so by selecting the challenge with what it | |||
considers to be the most secure auth-scheme that it understands, | considers to be the most secure auth-scheme that it understands, | |||
obtaining credentials from the user as appropriate. Transmission of | obtaining credentials from the user as appropriate. Transmission of | |||
skipping to change at page 109, line 28 ¶ | skipping to change at line 4978 ¶ | |||
encapsulation, and with additional header fields specifying | encapsulation, and with additional header fields specifying | |||
authentication information. However, such additional mechanisms are | authentication information. However, such additional mechanisms are | |||
not defined by this specification. | not defined by this specification. | |||
Note that various custom mechanisms for user authentication use the | Note that various custom mechanisms for user authentication use the | |||
Set-Cookie and Cookie header fields, defined in [COOKIE], for passing | Set-Cookie and Cookie header fields, defined in [COOKIE], for passing | |||
tokens related to authentication. | tokens related to authentication. | |||
11.5. Establishing a Protection Space (Realm) | 11.5. Establishing a Protection Space (Realm) | |||
The _realm_ authentication parameter is reserved for use by | The "realm" authentication parameter is reserved for use by | |||
authentication schemes that wish to indicate a scope of protection. | authentication schemes that wish to indicate a scope of protection. | |||
A _protection space_ is defined by the origin (see Section 4.3.1) of | A "protection space" is defined by the origin (see Section 4.3.1) of | |||
the server being accessed, in combination with the realm value if | the server being accessed, in combination with the realm value if | |||
present. These realms allow the protected resources on a server to | present. These realms allow the protected resources on a server to | |||
be partitioned into a set of protection spaces, each with its own | be partitioned into a set of protection spaces, each with its own | |||
authentication scheme and/or authorization database. The realm value | authentication scheme and/or authorization database. The realm value | |||
is a string, generally assigned by the origin server, that can have | is a string, generally assigned by the origin server, that can have | |||
additional semantics specific to the authentication scheme. Note | additional semantics specific to the authentication scheme. Note | |||
that a response can have multiple challenges with the same auth- | that a response can have multiple challenges with the same auth- | |||
scheme but with different realms. | scheme but with different realms. | |||
The protection space determines the domain over which credentials can | The protection space determines the domain over which credentials can | |||
skipping to change at page 110, line 48 ¶ | skipping to change at line 5041 ¶ | |||
value, as it might contain more than one challenge, and each | value, as it might contain more than one challenge, and each | |||
challenge can contain a comma-separated list of authentication | challenge can contain a comma-separated list of authentication | |||
parameters. Furthermore, the header field itself can occur multiple | parameters. Furthermore, the header field itself can occur multiple | |||
times. | times. | |||
For instance: | For instance: | |||
WWW-Authenticate: Basic realm="simple", Newauth realm="apps", | WWW-Authenticate: Basic realm="simple", Newauth realm="apps", | |||
type=1, title="Login to \"apps\"" | type=1, title="Login to \"apps\"" | |||
This header field contains two challenges; one for the "Basic" scheme | This header field contains two challenges, one for the "Basic" scheme | |||
with a realm value of "simple", and another for the "Newauth" scheme | with a realm value of "simple" and another for the "Newauth" scheme | |||
with a realm value of "apps", and two additional parameters "type" | with a realm value of "apps". It also contains two additional | |||
and "title". | parameters, "type" and "title". | |||
Some user agents do not recognise this form, however. As a result, | Some user agents do not recognize this form, however. As a result, | |||
sending a WWW-Authenticate field value with more than one member on | sending a WWW-Authenticate field value with more than one member on | |||
the same field line might not be interoperable. | the same field line might not be interoperable. | |||
| *Note:* The challenge grammar production uses the list syntax | | *Note:* The challenge grammar production uses the list syntax | |||
| as well. Therefore, a sequence of comma, whitespace, and comma | | as well. Therefore, a sequence of comma, whitespace, and comma | |||
| can be considered either as applying to the preceding | | can be considered either as applying to the preceding | |||
| challenge, or to be an empty entry in the list of challenges. | | challenge, or to be an empty entry in the list of challenges. | |||
| In practice, this ambiguity does not affect the semantics of | | In practice, this ambiguity does not affect the semantics of | |||
| the header field value and thus is harmless. | | the header field value and thus is harmless. | |||
11.6.2. Authorization | 11.6.2. Authorization | |||
The "Authorization" header field allows a user agent to authenticate | The "Authorization" header field allows a user agent to authenticate | |||
itself with an origin server - usually, but not necessarily, after | itself with an origin server -- usually, but not necessarily, after | |||
receiving a 401 (Unauthorized) response. Its value consists of | receiving a 401 (Unauthorized) response. Its value consists of | |||
credentials containing the authentication information of the user | credentials containing the authentication information of the user | |||
agent for the realm of the resource being requested. | agent for the realm of the resource being requested. | |||
Authorization = credentials | Authorization = credentials | |||
If a request is authenticated and a realm specified, the same | If a request is authenticated and a realm specified, the same | |||
credentials are presumed to be valid for all other requests within | credentials are presumed to be valid for all other requests within | |||
this realm (assuming that the authentication scheme itself does not | this realm (assuming that the authentication scheme itself does not | |||
require otherwise, such as credentials that vary according to a | require otherwise, such as credentials that vary according to a | |||
challenge value or using synchronized clocks). | challenge value or using synchronized clocks). | |||
A proxy forwarding a request MUST NOT modify any Authorization header | A proxy forwarding a request MUST NOT modify any Authorization header | |||
fields in that request. See Section 3.5 of [CACHING] for details of | fields in that request. See Section 3.5 of [CACHING] for details of | |||
and requirements pertaining to handling of the Authorization header | and requirements pertaining to handling of the Authorization header | |||
field by HTTP caches. | field by HTTP caches. | |||
11.6.3. Authentication-Info | 11.6.3. Authentication-Info | |||
HTTP authentication schemes can use the Authentication-Info response | HTTP authentication schemes can use the "Authentication-Info" | |||
field to communicate information after the client's authentication | response field to communicate information after the client's | |||
credentials have been accepted. This information can include a | authentication credentials have been accepted. This information can | |||
finalization message from the server (e.g., it can contain the server | include a finalization message from the server (e.g., it can contain | |||
authentication). | the server authentication). | |||
The field value is a list of parameters (name/value pairs), using the | The field value is a list of parameters (name/value pairs), using the | |||
"auth-param" syntax defined in Section 11.3. This specification only | "auth-param" syntax defined in Section 11.3. This specification only | |||
describes the generic format; authentication schemes using | describes the generic format; authentication schemes using | |||
Authentication-Info will define the individual parameters. The | Authentication-Info will define the individual parameters. The | |||
"Digest" Authentication Scheme, for instance, defines multiple | "Digest" Authentication Scheme, for instance, defines multiple | |||
parameters in Section 3.5 of [RFC7616]. | parameters in Section 3.5 of [RFC7616]. | |||
Authentication-Info = #auth-param | Authentication-Info = #auth-param | |||
skipping to change at page 113, line 16 ¶ | skipping to change at line 5153 ¶ | |||
only to the next inbound proxy that demanded authentication using the | only to the next inbound proxy that demanded authentication using the | |||
Proxy-Authenticate header field. When multiple proxies are used in a | Proxy-Authenticate header field. When multiple proxies are used in a | |||
chain, the Proxy-Authorization header field is consumed by the first | chain, the Proxy-Authorization header field is consumed by the first | |||
inbound proxy that was expecting to receive credentials. A proxy MAY | inbound proxy that was expecting to receive credentials. A proxy MAY | |||
relay the credentials from the client request to the next proxy if | relay the credentials from the client request to the next proxy if | |||
that is the mechanism by which the proxies cooperatively authenticate | that is the mechanism by which the proxies cooperatively authenticate | |||
a given request. | a given request. | |||
11.7.3. Proxy-Authentication-Info | 11.7.3. Proxy-Authentication-Info | |||
The Proxy-Authentication-Info response header field is equivalent to | The "Proxy-Authentication-Info" response header field is equivalent | |||
Authentication-Info, except that it applies to proxy authentication | to Authentication-Info, except that it applies to proxy | |||
(Section 11.3) and its semantics are defined by the authentication | authentication (Section 11.3) and its semantics are defined by the | |||
scheme indicated by the Proxy-Authorization header field | authentication scheme indicated by the Proxy-Authorization header | |||
(Section 11.7.2) of the corresponding request: | field (Section 11.7.2) of the corresponding request: | |||
Proxy-Authentication-Info = #auth-param | Proxy-Authentication-Info = #auth-param | |||
However, unlike Authentication-Info, the Proxy-Authentication-Info | However, unlike Authentication-Info, the Proxy-Authentication-Info | |||
header field applies only to the next outbound client on the response | header field applies only to the next outbound client on the response | |||
chain. This is because only the client that chose a given proxy is | chain. This is because only the client that chose a given proxy is | |||
likely to have the credentials necessary for authentication. | likely to have the credentials necessary for authentication. | |||
However, when multiple proxies are used within the same | However, when multiple proxies are used within the same | |||
administrative domain, such as office and regional caching proxies | administrative domain, such as office and regional caching proxies | |||
within a large corporate network, it is common for credentials to be | within a large corporate network, it is common for credentials to be | |||
skipping to change at page 114, line 4 ¶ | skipping to change at line 5190 ¶ | |||
that information; for example, in different formats, languages, or | that information; for example, in different formats, languages, or | |||
encodings. Likewise, different users or user agents might have | encodings. Likewise, different users or user agents might have | |||
differing capabilities, characteristics, or preferences that could | differing capabilities, characteristics, or preferences that could | |||
influence which representation, among those available, would be best | influence which representation, among those available, would be best | |||
to deliver. For this reason, HTTP provides mechanisms for content | to deliver. For this reason, HTTP provides mechanisms for content | |||
negotiation. | negotiation. | |||
This specification defines three patterns of content negotiation that | This specification defines three patterns of content negotiation that | |||
can be made visible within the protocol: "proactive" negotiation, | can be made visible within the protocol: "proactive" negotiation, | |||
where the server selects the representation based upon the user | where the server selects the representation based upon the user | |||
agent's stated preferences, "reactive" negotiation, where the server | agent's stated preferences; "reactive" negotiation, where the server | |||
provides a list of representations for the user agent to choose from, | provides a list of representations for the user agent to choose from; | |||
and "request content" negotiation, where the user agent selects the | and "request content" negotiation, where the user agent selects the | |||
representation for a future request based upon the server's stated | representation for a future request based upon the server's stated | |||
preferences in past responses. | preferences in past responses. | |||
Other patterns of content negotiation include "conditional content", | Other patterns of content negotiation include "conditional content", | |||
where the representation consists of multiple parts that are | where the representation consists of multiple parts that are | |||
selectively rendered based on user agent parameters, "active | selectively rendered based on user agent parameters, "active | |||
content", where the representation contains a script that makes | content", where the representation contains a script that makes | |||
additional (more specific) requests based on the user agent | additional (more specific) requests based on the user agent | |||
characteristics, and "Transparent Content Negotiation" ([RFC2295]), | characteristics, and "Transparent Content Negotiation" ([RFC2295]), | |||
skipping to change at page 114, line 31 ¶ | skipping to change at line 5217 ¶ | |||
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. | or generates those responses. | |||
12.1. Proactive Negotiation | 12.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_ | preferred representation, it is called "proactive negotiation" | |||
(a.k.a., _server-driven negotiation_). Selection is based on the | (a.k.a., "server-driven negotiation"). Selection is based on the | |||
available representations for a response (the dimensions over which | available representations for a response (the dimensions over which | |||
it might vary, such as language, content coding, etc.) compared to | it might vary, such as language, content coding, etc.) compared to | |||
various information supplied in the request, including both the | various information supplied in the request, including both the | |||
explicit negotiation header fields below and implicit | explicit negotiation header fields below and implicit | |||
characteristics, such as the client's network address or parts of the | characteristics, such as the client's network address or parts of the | |||
User-Agent field. | 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 (when | "best guess" to the user agent along with the first response (when | |||
that "best guess" is good enough for the user, this avoids the round | that "best guess" is good enough for the user, this avoids the round- | |||
trip delay of a subsequent request). In order to improve the | trip delay of a subsequent request). 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. | |||
Proactive negotiation has serious disadvantages: | Proactive negotiation has serious disadvantages: | |||
* It is impossible for the server to accurately determine what might | * It is impossible for the server to accurately determine what might | |||
be "best" for any given user, since that would require complete | be "best" for any given user, since that would require complete | |||
knowledge of both the capabilities of the user agent and the | knowledge of both the capabilities of the user agent and the | |||
intended use for the response (e.g., does the user want to view it | intended use for the response (e.g., does the user want to view it | |||
skipping to change at page 115, line 41 ¶ | skipping to change at line 5273 ¶ | |||
The request header fields Accept, Accept-Charset, Accept-Encoding, | The request header fields Accept, Accept-Charset, Accept-Encoding, | |||
and Accept-Language are defined below for a user agent to engage in | and Accept-Language are defined below for a user agent to engage in | |||
proactive negotiation of the response content. The preferences sent | proactive negotiation of the response content. The preferences sent | |||
in these fields apply to any content in the response, including | in these fields apply to any content in the response, including | |||
representations of the target resource, representations of error or | representations of the target resource, representations of error or | |||
processing status, and potentially even the miscellaneous text | processing status, and potentially even the miscellaneous text | |||
strings that might appear within the protocol. | strings that might appear within the protocol. | |||
12.2. Reactive Negotiation | 12.2. Reactive Negotiation | |||
With _reactive negotiation_ (a.k.a., _agent-driven negotiation_), | With "reactive negotiation" (a.k.a., "agent-driven negotiation"), | |||
selection of content (regardless of the status code) is performed by | selection of content (regardless of the status code) is performed by | |||
the user agent after receiving an initial response. The mechanism | the user agent after receiving an initial response. The mechanism | |||
for reactive negotiation might be as simple as a list of references | for reactive negotiation might be as simple as a list of references | |||
to alternative representations. | to alternative representations. | |||
If the user agent is not satisfied by the initial response content, | If the user agent is not satisfied by the initial response content, | |||
it can perform a GET request on one or more of the alternative | it can perform a GET request on one or more of the alternative | |||
resources to obtain a different representation. Selection of such | resources to obtain a different representation. Selection of such | |||
alternatives might be performed automatically (by the user agent) or | alternatives might be performed automatically (by the user agent) or | |||
manually (e.g., by the user selecting from a hypertext menu). | manually (e.g., by the user selecting from a hypertext menu). | |||
skipping to change at page 116, line 30 ¶ | skipping to change at line 5310 ¶ | |||
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. | developed. | |||
12.3. Request Content Negotiation | 12.3. Request Content Negotiation | |||
When content negotiation preferences are sent in a server's response, | When content negotiation preferences are sent in a server's response, | |||
the listed preferences are called _request content negotiation_ | the listed preferences are called "request content negotiation" | |||
because they intend to influence selection of an appropriate content | because they intend to influence selection of an appropriate content | |||
for subsequent requests to that resource. For example, the Accept | for subsequent requests to that resource. For example, the Accept | |||
(Section 12.5.1) and Accept-Encoding (Section 12.5.3) header fields | (Section 12.5.1) and Accept-Encoding (Section 12.5.3) header fields | |||
can be sent in a response to indicate preferred media types and | can be sent in a response to indicate preferred media types and | |||
content codings for subsequent requests to that resource. | content codings for subsequent requests to that resource. | |||
Similarly, Section 3.1 of [RFC5789] defines the "Accept-Patch" | Similarly, Section 3.1 of [RFC5789] defines the "Accept-Patch" | |||
response header field which allows discovery of which content types | response header field, which allows discovery of which content types | |||
are accepted in PATCH requests. | are accepted in PATCH requests. | |||
12.4. Content Negotiation Field Features | 12.4. Content Negotiation Field Features | |||
12.4.1. Absence | 12.4.1. Absence | |||
For each of the content negotiation fields, a request that does not | For each of the content negotiation fields, a request that does not | |||
contain the field implies that the sender has no preference on that | contain the field implies that the sender has no preference on that | |||
dimension of negotiation. | dimension of negotiation. | |||
skipping to change at page 117, line 45 ¶ | skipping to change at line 5374 ¶ | |||
12.4.3. Wildcard Values | 12.4.3. Wildcard Values | |||
Most of these header fields, where indicated, define a wildcard value | Most of these header fields, where indicated, define a wildcard value | |||
("*") to select unspecified values. If no wildcard is present, | ("*") to select unspecified values. If no wildcard is present, | |||
values that are not explicitly mentioned in the field are considered | values that are not explicitly mentioned in the field are considered | |||
unacceptable. Within Vary, the wildcard value means that the | unacceptable. Within Vary, the wildcard value means that the | |||
variance is unlimited. | variance is unlimited. | |||
| *Note:* In practice, using wildcards in content negotiation has | | *Note:* In practice, using wildcards in content negotiation has | |||
| limited practical value, because it is seldom useful to say, | | limited practical value because it is seldom useful to say, for | |||
| for example, "I prefer image/* more or less than (some other | | example, "I prefer image/* more or less than (some other | |||
| specific value)". Clients can explicitly request a 406 (Not | | specific value)". By sending Accept: */*;q=0, clients can | |||
| Acceptable) response if a more preferred format is not | | explicitly request a 406 (Not Acceptable) response if a more | |||
| available by sending Accept: */*;q=0, but they still need to be | | preferred format is not available, but they still need to be | |||
| able to handle a different response, since the server is | | able to handle a different response since the server is allowed | |||
| allowed to ignore their preference. | | to ignore their preference. | |||
12.5. Content Negotiation Fields | 12.5. Content Negotiation Fields | |||
12.5.1. Accept | 12.5.1. Accept | |||
The "Accept" header field can be used by user agents to specify their | The "Accept" header field can be used by user agents to specify their | |||
preferences regarding response media types. For example, Accept | preferences regarding response media types. For example, Accept | |||
header fields can be used to indicate that the request is | header fields can be used to indicate that the request is | |||
specifically limited to a small set of desired types, as in the case | specifically limited to a small set of desired types, as in the case | |||
of a request for an in-line image. | of a request for an in-line image. | |||
When sent by a server in a response, Accept provides information | When sent by a server in a response, Accept provides information | |||
about what content types are preferred in the content of a subsequent | about which content types are preferred in the content of a | |||
request to the same resource. | subsequent request to the same resource. | |||
Accept = #( media-range [ weight ] ) | Accept = #( media-range [ weight ] ) | |||
media-range = ( "*/*" | media-range = ( "*/*" | |||
/ ( type "/" "*" ) | / ( type "/" "*" ) | |||
/ ( type "/" subtype ) | / ( type "/" subtype ) | |||
) parameters | ) parameters | |||
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 | |||
skipping to change at page 121, line 5 ¶ | skipping to change at line 5517 ¶ | |||
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 header field, | The special value "*", if present in the Accept-Charset header field, | |||
matches every charset that is not mentioned elsewhere in the field. | matches every charset that is not mentioned elsewhere in the field. | |||
| *Note:* Accept-Charset is deprecated because UTF-8 has become | | *Note:* Accept-Charset is deprecated because UTF-8 has become | |||
| nearly ubiquitous and sending a detailed list of user-preferred | | nearly ubiquitous and sending a detailed list of user-preferred | |||
| charsets wastes bandwidth, increases latency, and makes passive | | charsets wastes bandwidth, increases latency, and makes passive | |||
| fingerprinting far too easy (Section 17.13). Most general- | | fingerprinting far too easy (Section 17.13). Most general- | |||
| purpose user agents do not send Accept-Charset, unless | | purpose user agents do not send Accept-Charset unless | |||
| specifically configured to do so. | | specifically configured to do so. | |||
12.5.3. Accept-Encoding | 12.5.3. Accept-Encoding | |||
The "Accept-Encoding" header field can be used to indicate | The "Accept-Encoding" header field can be used to indicate | |||
preferences regarding the use of content codings (Section 8.4.1). | preferences regarding the use of content codings (Section 8.4.1). | |||
When sent by a user agent in a request, Accept-Encoding indicates the | When sent by a user agent in a request, Accept-Encoding indicates the | |||
content codings acceptable in a response. | content codings acceptable in a response. | |||
When sent by a server in a response, Accept-Encoding provides | When sent by a server in a response, Accept-Encoding provides | |||
information about what content codings are preferred in the content | information about which content codings are preferred in the content | |||
of a subsequent request to the same resource. | of a subsequent request to the same resource. | |||
An "identity" token is used as a synonym for "no encoding" in order | An "identity" token is used as a synonym for "no encoding" in order | |||
to communicate when no encoding is preferred. | to communicate when no encoding is 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 (weight) | Each codings value MAY be given an associated quality value (weight) | |||
representing the preference for that encoding, as defined in | representing the preference for that encoding, as defined in | |||
skipping to change at page 122, line 18 ¶ | skipping to change at line 5576 ¶ | |||
defined in Section 12.4.2, a qvalue of 0 means "not acceptable".) | defined in Section 12.4.2, a qvalue of 0 means "not acceptable".) | |||
A representation could be encoded with multiple content codings. | A representation could be encoded with multiple content codings. | |||
However, most content codings are alternative ways to accomplish the | However, most content codings are alternative ways to accomplish the | |||
same purpose (e.g., data compression). When selecting between | same purpose (e.g., data compression). When selecting between | |||
multiple content codings that have the same purpose, the acceptable | multiple content codings that have the same purpose, 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 field value that is empty | An Accept-Encoding header field with a field value that is empty | |||
implies that the user agent does not want any content coding in | 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 a non-empty Accept-Encoding header field is present in | |||
and none of the available representations for the response have a | a request and none of the available representations for the response | |||
content coding that is listed as acceptable, the origin server SHOULD | have a content coding that is listed as acceptable, the origin server | |||
send a response without any content coding. | SHOULD send a response without any content coding unless the identity | |||
coding is indicated as unacceptable. | ||||
When the Accept-Encoding header field is present in a response, it | When the Accept-Encoding header field is present in a response, it | |||
indicates what content codings the resource was willing to accept in | indicates what content codings the resource was willing to accept in | |||
the associated request. The field value is evaluated the same way as | the associated request. The field value is evaluated the same way as | |||
in a request. | in a request. | |||
Note that this information is specific to the associated request; the | Note that this information is specific to the associated request; the | |||
set of supported encodings might be different for other resources on | set of supported encodings might be different for other resources on | |||
the same server and could change over time or depend on other aspects | the same server and could change over time or depend on other aspects | |||
of the request (such as the request method). | of the request (such as the request method). | |||
skipping to change at page 122, line 45 ¶ | skipping to change at line 5604 ¶ | |||
include an Accept-Encoding header field in that response, allowing | include an Accept-Encoding header field in that response, allowing | |||
clients to distinguish between issues related to content codings and | clients to distinguish between issues related to content codings and | |||
media types. In order to avoid confusion with issues related to | media types. In order to avoid confusion with issues related to | |||
media types, servers that fail a request with a 415 status for | media types, servers that fail a request with a 415 status for | |||
reasons unrelated to content codings MUST NOT include the Accept- | reasons unrelated to content codings MUST NOT include the Accept- | |||
Encoding header field. | Encoding header field. | |||
The most common use of Accept-Encoding is in responses with a 415 | The most common use of Accept-Encoding is in responses with a 415 | |||
(Unsupported Media Type) status code, in response to optimistic use | (Unsupported Media Type) status code, in response to optimistic use | |||
of a content coding by clients. However, the header field can also | of a content coding by clients. However, the header field can also | |||
be used to indicate to clients that content codings are supported, to | be used to indicate to clients that content codings are supported in | |||
optimize future interactions. For example, a resource might include | order to optimize future interactions. For example, a resource might | |||
it in a 2xx (Successful) response when the request content was big | include it in a 2xx (Successful) response when the request content | |||
enough to justify use of a compression coding but the client failed | was big enough to justify use of a compression coding but the client | |||
do so. | failed do so. | |||
12.5.4. Accept-Language | 12.5.4. 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 8.5.1. | response. Language tags are defined in Section 8.5.1. | |||
Accept-Language = #( language-range [ weight ] ) | Accept-Language = #( language-range [ weight ] ) | |||
language-range = | language-range = | |||
<language-range, see [RFC4647], Section 2.1> | <language-range, see [RFC4647], Section 2.1> | |||
skipping to change at page 125, line 21 ¶ | skipping to change at line 5720 ¶ | |||
response when it wishes that response to be selectively reused for | response when it wishes that response to be selectively reused for | |||
subsequent requests. Generally, that is the case when the response | subsequent requests. Generally, that is the case when the response | |||
content has been tailored to better fit the preferences expressed by | content has been tailored to better fit the preferences expressed by | |||
those selecting header fields, such as when an origin server has | those selecting header fields, such as when an origin server has | |||
selected the response's language based on the request's | selected the response's language based on the request's | |||
Accept-Language header field. | Accept-Language header field. | |||
Vary might be elided when an origin server considers variance in | Vary might be elided when an origin server considers variance in | |||
content selection to be less significant than Vary's performance | content selection to be less significant than Vary's performance | |||
impact on caching, particularly when reuse is already limited by | impact on caching, particularly when reuse is already limited by | |||
Cache-Control response directives (Section 5.2 of [CACHING]). | cache response directives (Section 5.2 of [CACHING]). | |||
There is no need to send the Authorization field name in Vary because | There is no need to send the Authorization field name in Vary because | |||
reuse of that response for a different user is prohibited by the | reuse of that response for a different user is prohibited by the | |||
field definition (Section 11.6.2). Likewise, if the response content | field definition (Section 11.6.2). Likewise, if the response content | |||
has been selected or influenced by network region but the origin | has been selected or influenced by network region, but the origin | |||
server wants the cached response to be reused even if recipients move | server wants the cached response to be reused even if recipients move | |||
from one region to another, then there is no need for the origin | from one region to another, then there is no need for the origin | |||
server to indicate such variance in Vary. | server to indicate such variance in Vary. | |||
13. Conditional Requests | 13. Conditional Requests | |||
A conditional request is an HTTP request with one or more request | A conditional request is an HTTP request with one or more request | |||
header fields that indicate a precondition to be tested before | header fields that indicate a precondition to be tested before | |||
applying the request method to the target resource. Section 13.2 | applying the request method to the target resource. Section 13.2 | |||
defines when to evaluate preconditions and their order of precedence | defines when to evaluate preconditions and their order of precedence | |||
skipping to change at page 126, line 38 ¶ | skipping to change at line 5786 ¶ | |||
implementation is signaled by some other property of the target | implementation is signaled by some other property of the target | |||
resource. This encourages a focus on mutually agreed deployment of | resource. This encourages a focus on mutually agreed deployment of | |||
common standards. | common standards. | |||
13.1.1. If-Match | 13.1.1. 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 8.8.3.2), since the | comparing entity tags for If-Match (Section 8.8.3.2), since the | |||
client intends this precondition to prevent the method from being | client intends this precondition to prevent the method from being | |||
applied if there have been any changes to the representation data. | applied if there have been any changes to the representation data. | |||
If-Match = "*" / #entity-tag | If-Match = "*" / #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). In general, it can be used with | prevent the "lost update" problem). In general, it can be used with | |||
any method that involves the selection or modification of a | any method that involves the selection or modification of a | |||
representation to abort the request if the selected representation's | representation to abort the request if the selected representation's | |||
current entity-tag is not a member within the If-Match field value. | current entity tag is not a member within the If-Match field value. | |||
When an origin server receives a request that selects a | When an origin server receives a request that selects a | |||
representation and that request includes an If-Match header field, | representation and that request includes an If-Match header field, | |||
the origin server MUST evaluate the If-Match condition as per | the origin server MUST evaluate the If-Match condition per | |||
Section 13.2 prior to performing the method. | Section 13.2 prior to performing the method. | |||
To evaluate a received If-Match header field: | To evaluate a received If-Match header field: | |||
1. If the field value is "*", the condition is true if the origin | 1. If the field value is "*", the condition is true if the origin | |||
server has a current representation for the target resource. | server has a current representation for the target resource. | |||
2. If the field value is a list of entity-tags, the condition is | 2. If the field value is a list of entity tags, the condition is | |||
true if any of the listed tags match the entity-tag of the | true if any of the listed tags match the entity tag of the | |||
selected representation. | selected representation. | |||
3. Otherwise, the condition is false. | 3. Otherwise, the condition is false. | |||
An origin server that evaluates an If-Match condition MUST NOT | An origin server that evaluates an If-Match condition MUST NOT | |||
perform the requested method if the condition evaluates to false. | perform the requested method if the condition evaluates to false. | |||
Instead, the origin server MAY indicate that the conditional request | Instead, the origin server MAY indicate that the conditional request | |||
failed by responding with a 412 (Precondition Failed) status code. | failed by responding with a 412 (Precondition Failed) status code. | |||
Alternatively, if the request is a state-changing operation that | Alternatively, if the request is a state-changing operation that | |||
appears to have already been applied to the selected representation, | appears to have already been applied to the selected representation, | |||
skipping to change at page 127, line 50 ¶ | skipping to change at line 5843 ¶ | |||
(i.e., the change requested by the user agent has already succeeded, | (i.e., the change requested by the user agent has already succeeded, | |||
but the user agent might not be aware of it, perhaps because the | but the user agent might not be aware of it, perhaps because the | |||
prior response was lost or an equivalent change was made by some | prior response was lost or an equivalent change was made by some | |||
other user agent). | other user agent). | |||
Allowing an origin server to send a success response when a change | Allowing an origin server to send a success response when a change | |||
request appears to have already been applied is more efficient for | request appears to have already been applied is more efficient for | |||
many authoring use cases, but comes with some risk if multiple user | many authoring use cases, but comes with some risk if multiple user | |||
agents are making change requests that are very similar but not | agents are making change requests that are very similar but not | |||
cooperative. For example, multiple user agents writing to a common | cooperative. For example, multiple user agents writing to a common | |||
resource as a semaphore (e.g., a non-atomic increment) are likely to | resource as a semaphore (e.g., a nonatomic increment) are likely to | |||
collide and potentially lose important state transitions. For those | collide and potentially lose important state transitions. For those | |||
kinds of resources, an origin server is better off being stringent in | kinds of resources, an origin server is better off being stringent in | |||
sending 412 for every failed precondition on an unsafe method. In | sending 412 for every failed precondition on an unsafe method. In | |||
other cases, excluding the ETag field from a success response might | other cases, excluding the ETag field from a success response might | |||
encourage the user agent to perform a GET as its next request to | encourage the user agent to perform a GET as its next request to | |||
eliminate confusion about the resource's current state. | eliminate confusion about the resource's current state. | |||
A client MAY send an If-Match header field in a GET request to | A client MAY send an If-Match header field in a GET request to | |||
indicate that it would prefer a 412 (Precondition Failed) response if | indicate that it would prefer a 412 (Precondition Failed) response if | |||
the selected representation does not match. However, this is only | the selected representation does not match. However, this is only | |||
useful in range requests (Section 14), for completing a previously | useful in range requests (Section 14) for completing a previously | |||
received partial representation, when there is no desire for a new | received partial representation when there is no desire for a new | |||
representation. If-Range (Section 13.1.5) is better suited for range | representation. If-Range (Section 13.1.5) is better suited for range | |||
requests when the client prefers to receive a new representation. | requests when the client prefers to receive a new representation. | |||
A cache or intermediary MAY ignore If-Match because its | A cache or intermediary MAY ignore If-Match because its | |||
interoperability features are only necessary for an origin server. | interoperability features are only necessary for an origin server. | |||
Note that an If-Match header field with a list value containing "*" | Note that an If-Match header field with a list value containing "*" | |||
and other values (including other instances of "*") is syntactically | and other values (including other instances of "*") is syntactically | |||
invalid (therefore not allowed to be generated) and furthermore is | invalid (therefore not allowed to be generated) and furthermore is | |||
unlikely to be interoperable. | unlikely to be interoperable. | |||
13.1.2. If-None-Match | 13.1.2. 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 8.8.3.2), since weak entity- | entity tags for If-None-Match (Section 8.8.3.2), since weak entity | |||
tags can be used for cache validation even if there have been changes | tags can be used for cache validation even if there have been changes | |||
to the representation data. | to the representation data. | |||
If-None-Match = "*" / #entity-tag | If-None-Match = "*" / #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: * | |||
If-None-Match is primarily used in conditional GET requests to enable | If-None-Match is primarily used in conditional GET requests to enable | |||
efficient updates of cached information with a minimum amount of | efficient updates of cached information with a minimum amount of | |||
transaction overhead. When a client desires to update one or more | transaction overhead. When a client desires to update one or more | |||
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 9.2.1). This is a variation on the "lost update" problem | (Section 9.2.1). This is a variation on the "lost update" problem | |||
that might arise if more than one client attempts to create an | that might arise if more than one client attempts to create an | |||
initial representation for the target resource. | initial representation for the target resource. | |||
When an origin server receives a request that selects a | When an origin server receives a request that selects a | |||
representation and that request includes an If-None-Match header | representation and that request includes an If-None-Match header | |||
field, the origin server MUST evaluate the If-None-Match condition as | field, the origin server MUST evaluate the If-None-Match condition | |||
per Section 13.2 prior to performing the method. | per Section 13.2 prior to performing the method. | |||
To evaluate a received If-None-Match header field: | To evaluate a received If-None-Match header field: | |||
1. If the field value is "*", the condition is false if the origin | 1. If the field value is "*", the condition is false if the origin | |||
server has a current representation for the target resource. | server has a current representation for the target resource. | |||
2. If the field value is a list of entity-tags, the condition is | 2. If the field value is a list of entity tags, the condition is | |||
false if one of the listed tags matches the entity-tag of the | false if one of the listed tags matches the entity tag of the | |||
selected representation. | selected representation. | |||
3. Otherwise, the condition is true. | 3. Otherwise, the condition is true. | |||
An origin server that evaluates an If-None-Match condition MUST NOT | An origin server that evaluates an If-None-Match condition MUST NOT | |||
perform the requested method if the condition evaluates to false; | perform the requested method if the condition evaluates to false; | |||
instead, the origin server MUST respond with either a) the 304 (Not | instead, the origin server MUST respond with either a) the 304 (Not | |||
Modified) status code if the request method is GET or HEAD or b) the | Modified) status code if the request method is GET or HEAD or b) the | |||
412 (Precondition Failed) status code for all other request methods. | 412 (Precondition Failed) status code for all other request methods. | |||
skipping to change at page 130, line 39 ¶ | skipping to change at line 5971 ¶ | |||
HEAD. | HEAD. | |||
A recipient MUST ignore the If-Modified-Since header field if the | A recipient MUST ignore the If-Modified-Since header field if the | |||
resource does not have a modification date available. | resource does not have a modification date available. | |||
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 header field to generate the field | the cached message's Last-Modified header field to generate the field | |||
value of If-Modified-Since. This behavior is most interoperable for | value of If-Modified-Since. This behavior is most interoperable for | |||
cases where clocks are poorly synchronized or when the server has | cases where clocks are poorly synchronized or when the server has | |||
chosen to only honor exact timestamp matches (due to a problem with | chosen to only honor exact timestamp matches (due to a problem with | |||
Last-Modified dates that appear to go "back in time" when the origin | Last-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 | |||
skipping to change at page 131, line 29 ¶ | skipping to change at line 5998 ¶ | |||
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 clock or a Date header field received from | based on either its own clock or a Date header field received from | |||
the server in a prior response. Origin servers that choose an exact | the server in a prior response. Origin servers that choose an exact | |||
timestamp match based on the selected representation's Last-Modified | timestamp match based on the selected representation's Last-Modified | |||
header field will not be able to help the user agent limit its data | header field will not be able to help the user agent limit its data | |||
transfers to only those changed during the specified window. | transfers to only those changed during the specified window. | |||
When an origin server receives a request that selects a | When an origin server receives a request that selects a | |||
representation and that request includes an If-Modified-Since header | representation and that request includes an If-Modified-Since header | |||
field without an If-None-Match header field, the origin server SHOULD | field without an If-None-Match header field, the origin server SHOULD | |||
evaluate the If-Modified-Since condition as per Section 13.2 prior to | evaluate the If-Modified-Since condition per Section 13.2 prior to | |||
performing the method. | performing the method. | |||
To evaluate a received If-Modified-Since header field: | To evaluate a received If-Modified-Since header field: | |||
1. If the selected representation's last modification date is | 1. If the selected representation's last modification date is | |||
earlier or equal to the date provided in the field value, the | earlier or equal to the date provided in the field value, the | |||
condition is false. | condition is false. | |||
2. Otherwise, the condition is true. | 2. Otherwise, the condition is true. | |||
skipping to change at page 132, line 11 ¶ | skipping to change at line 6024 ¶ | |||
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 [CACHING]. | field are defined in Section 4.3.2 of [CACHING]. | |||
13.1.4. If-Unmodified-Since | 13.1.4. 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 If-Unmodified- | be a more accurate replacement for the condition in If-Unmodified- | |||
skipping to change at page 132, line 38 ¶ | skipping to change at line 6051 ¶ | |||
A recipient MUST ignore the If-Unmodified-Since header field if the | A recipient MUST ignore the If-Unmodified-Since header field if the | |||
resource does not have a modification date available. | resource does not have a modification date available. | |||
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). In general, it can be used with | prevent the "lost update" problem). In general, it can be used with | |||
any method that involves the selection or modification of a | any method that involves the selection or modification of a | |||
representation to abort the request if the selected representation's | representation to abort the request if the selected representation's | |||
last modification date has changed since the date provided in the If- | last modification date has changed since the date provided in the If- | |||
Unmodified-Since field value. | Unmodified-Since field value. | |||
When an origin server receives a request that selects a | When an origin server receives a request that selects a | |||
representation and that request includes an If-Unmodified-Since | representation and that request includes an If-Unmodified-Since | |||
header field without an If-Match header field, the origin server MUST | header field without an If-Match header field, the origin server MUST | |||
evaluate the If-Unmodified-Since condition as per Section 13.2 prior | evaluate the If-Unmodified-Since condition per Section 13.2 prior to | |||
to performing the method. | performing the method. | |||
To evaluate a received If-Unmodified-Since header field: | To evaluate a received If-Unmodified-Since header field: | |||
1. If the selected representation's last modification date is | 1. 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, | |||
the condition is true. | the condition is true. | |||
2. Otherwise, the condition is false. | 2. Otherwise, the condition is false. | |||
An origin server that evaluates an If-Unmodified-Since condition MUST | An origin server that evaluates an If-Unmodified-Since condition MUST | |||
skipping to change at page 133, line 34 ¶ | skipping to change at line 6095 ¶ | |||
request appears to have already been applied is more efficient for | request appears to have already been applied is more efficient for | |||
many authoring use cases, but comes with some risk if multiple user | many authoring use cases, but comes with some risk if multiple user | |||
agents are making change requests that are very similar but not | agents are making change requests that are very similar but not | |||
cooperative. In those cases, an origin server is better off being | cooperative. In those cases, an origin server is better off being | |||
stringent in sending 412 for every failed precondition on an unsafe | stringent in sending 412 for every failed precondition on an unsafe | |||
method. | method. | |||
A client MAY send an If-Unmodified-Since header field in a GET | A client MAY send an If-Unmodified-Since header field in a GET | |||
request to indicate that it would prefer a 412 (Precondition Failed) | request to indicate that it would prefer a 412 (Precondition Failed) | |||
response if the selected representation has been modified. However, | response if the selected representation has been modified. However, | |||
this is only useful in range requests (Section 14), for completing a | this is only useful in range requests (Section 14) for completing a | |||
previously received partial representation, when there is no desire | previously received partial representation when there is no desire | |||
for a new representation. If-Range (Section 13.1.5) is better suited | for a new representation. If-Range (Section 13.1.5) is better suited | |||
for range requests when the client prefers to receive a new | for range requests when the client prefers to receive a new | |||
representation. | representation. | |||
A cache or intermediary MAY ignore If-Unmodified-Since because its | A cache or intermediary MAY ignore If-Unmodified-Since because its | |||
interoperability features are only necessary for an origin server. | interoperability features are only necessary for an origin server. | |||
13.1.5. If-Range | 13.1.5. If-Range | |||
The "If-Range" header field provides a special conditional request | The "If-Range" header field provides a special conditional request | |||
skipping to change at page 134, line 31 ¶ | skipping to change at line 6139 ¶ | |||
examining the first three characters for a DQUOTE. | examining the first three characters for a DQUOTE. | |||
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 If- | does not contain a Range header field. A server MUST ignore an 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 If- | entity tag that is marked as weak. A client MUST NOT generate an If- | |||
Range header field containing an HTTP-date unless the client has no | Range header field containing an HTTP-date unless the client has 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 8.8.2.2. | strong validator in the sense defined by Section 8.8.2.2. | |||
A server that receives an If-Range header field on a Range request | A server that receives an If-Range header field on a Range request | |||
MUST evaluate the condition as per Section 13.2 prior to performing | MUST evaluate the condition per Section 13.2 prior to performing the | |||
the method. | method. | |||
To evaluate a received If-Range header field containing an HTTP-date: | To evaluate a received If-Range header field containing an HTTP-date: | |||
1. If the HTTP-date validator provided is not a strong validator in | 1. If the HTTP-date validator provided is not a strong validator in | |||
the sense defined by Section 8.8.2.2, the condition is false. | the sense defined by Section 8.8.2.2, the condition is false. | |||
2. If the HTTP-date validator provided exactly matches the | 2. If the HTTP-date validator provided exactly matches the | |||
Last-Modified field value for the selected representation, the | Last-Modified field value for the selected representation, the | |||
condition is true. | condition is true. | |||
skipping to change at page 135, line 16 ¶ | skipping to change at line 6173 ¶ | |||
field value for the selected representation using the strong | field value for the selected representation using the strong | |||
comparison function (Section 8.8.3.2), the condition is true. | comparison function (Section 8.8.3.2), the condition is true. | |||
2. Otherwise, the condition is false. | 2. Otherwise, the condition is false. | |||
A recipient of an If-Range header field MUST ignore the Range header | A recipient of an If-Range header field MUST ignore the Range header | |||
field if the If-Range condition evaluates to false. Otherwise, the | field if the If-Range condition evaluates to false. Otherwise, the | |||
recipient SHOULD process the Range header field as requested. | recipient SHOULD process the Range header field as requested. | |||
Note that the If-Range comparison is by exact match, including when | Note that the If-Range comparison is by exact match, including when | |||
the validator is an HTTP-date, and so differs from the "earlier than | the validator is an HTTP-date, and so it differs from the "earlier | |||
or equal to" comparison used when evaluating an If-Unmodified-Since | than or equal to" comparison used when evaluating an | |||
conditional. | If-Unmodified-Since conditional. | |||
13.2. Evaluation of Preconditions | 13.2. Evaluation of Preconditions | |||
13.2.1. When to Evaluate | 13.2.1. When to Evaluate | |||
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 process | performed its normal request checks and just before it would process | |||
the request content (if any) or perform the action associated with | the request content (if any) or perform the action associated with | |||
the request method. A server MUST ignore all received preconditions | the request method. A server MUST ignore all received preconditions | |||
skipping to change at page 135, line 49 ¶ | skipping to change at line 6206 ¶ | |||
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 | Note that protocol extensions can modify the conditions under which | |||
preconditions are evaluated or the consequences of their evaluation. | preconditions are evaluated or the consequences of their evaluation. | |||
For example, the "immutable" cache directive (defined by [RFC8246]) | For example, the immutable cache directive (defined by [RFC8246]) | |||
instructs caches to forgo forwarding conditional requests when they | instructs caches to forgo forwarding conditional requests when they | |||
hold a fresh response. | hold a fresh response. | |||
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. | |||
skipping to change at page 138, line 9 ¶ | skipping to change at line 6307 ¶ | |||
recipients not implementing this feature (or not supporting it for | recipients not implementing this feature (or not supporting it for | |||
the target resource) can respond as if it is a normal GET request | the target resource) can respond as if it is a normal GET request | |||
without impacting interoperability. Partial responses are indicated | without impacting interoperability. Partial responses are indicated | |||
by a distinct status code to not be mistaken for full responses by | by a distinct status code to not be mistaken for full responses by | |||
caches that might not implement the feature. | caches that might not implement the feature. | |||
14.1. Range Units | 14.1. Range Units | |||
Representation data can be partitioned into subranges when there are | Representation data can be partitioned into subranges when there are | |||
addressable structural units inherent to that data's content coding | addressable structural units inherent to that data's content coding | |||
or media type. For example, octet (a.k.a., byte) boundaries are a | or media type. For example, octet (a.k.a. byte) boundaries are a | |||
structural unit common to all representation data, allowing | structural unit common to all representation data, allowing | |||
partitions of the data to be identified as a range of bytes at some | partitions of the data to be identified as a range of bytes at some | |||
offset from the start or end of that data. | offset from the start or end of that data. | |||
This general notion of a _range unit_ is used in the Accept-Ranges | This general notion of a "range unit" is used in the Accept-Ranges | |||
(Section 14.3) response header field to advertise support for range | (Section 14.3) response header field to advertise support for range | |||
requests, the Range (Section 14.2) request header field to delineate | requests, the Range (Section 14.2) request header field to delineate | |||
the parts of a representation that are requested, and the | the parts of a representation that are requested, and the | |||
Content-Range (Section 14.4) header field to describe which part of a | Content-Range (Section 14.4) header field to describe which part of a | |||
representation is being transferred. | representation is being transferred. | |||
range-unit = token | range-unit = token | |||
All range unit names are case-insensitive and ought to be registered | All range unit names are case-insensitive and ought to be registered | |||
within the "HTTP Range Unit Registry", as defined in Section 16.5.1. | within the "HTTP Range Unit Registry", as defined in Section 16.5.1. | |||
skipping to change at page 139, line 26 ¶ | skipping to change at line 6372 ¶ | |||
suffix-range = "-" suffix-length | suffix-range = "-" suffix-length | |||
suffix-length = 1*DIGIT | suffix-length = 1*DIGIT | |||
To provide for extensibility, the other-range rule is a mostly | To provide for extensibility, the other-range rule is a mostly | |||
unconstrained grammar that allows application-specific or future | unconstrained grammar that allows application-specific or future | |||
range units to define additional range specifiers. | range units to define additional range specifiers. | |||
other-range = 1*( %x21-2B / %x2D-7E ) | other-range = 1*( %x21-2B / %x2D-7E ) | |||
; 1*(VCHAR excluding comma) | ; 1*(VCHAR excluding comma) | |||
A ranges-specifier is invalid if it contains any range-spec that is | ||||
invalid or undefined for the indicated range-unit. | ||||
A valid ranges-specifier is "satisfiable" if it contains at least one | ||||
range-spec that is satisfiable, as defined by the indicated | ||||
range-unit. Otherwise, the ranges-specifier is "unsatisfiable". | ||||
14.1.2. Byte Ranges | 14.1.2. Byte Ranges | |||
The "bytes" range unit is used to express subranges of a | The "bytes" range unit is used to express subranges of a | |||
representation data's octet sequence. Each byte range is expressed | representation data's octet sequence. Each byte range is expressed | |||
as an integer range at some offset, relative to either the beginning | as an integer range at some offset, relative to either the beginning | |||
(int-range) or end (suffix-range) of the representation data. Byte | (int-range) or end (suffix-range) of the representation data. Byte | |||
ranges do not use the other-range specifier. | ranges do not use the other-range specifier. | |||
The first-pos value in a bytes int-range gives the offset of the | 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 | first byte in a range. The last-pos value gives the offset of the | |||
skipping to change at page 140, line 13 ¶ | skipping to change at line 6415 ¶ | |||
bytes=500-999 | bytes=500-999 | |||
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-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-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 (N > 0) of the selected | A client can refer to the last N bytes (N > 0) of the selected | |||
representation using a suffix-range. If the selected representation | representation using a suffix-range. If the selected representation | |||
is shorter than the specified suffix-length, the entire | is shorter than the specified suffix-length, the entire | |||
representation is used. | representation is used. | |||
Additional examples, assuming a representation of length 10000: | Additional examples, assuming a representation of length 10000: | |||
* The final 500 bytes (byte offsets 9500-9999, inclusive): | * The final 500 bytes (byte offsets 9500-9999, inclusive): | |||
bytes=-500 | bytes=-500 | |||
skipping to change at page 140, line 42 ¶ | skipping to change at line 6444 ¶ | |||
* The first, middle, and last 1000 bytes: | * The first, middle, and last 1000 bytes: | |||
bytes= 0-999, 4500-5499, -1000 | bytes= 0-999, 4500-5499, -1000 | |||
* Other valid (but not canonical) specifications of the second 500 | * 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 bytes range-set includes at least one range-spec with a | For a GET request, a valid bytes range-spec is satisfiable if it is | |||
first-pos that is less than the current length of the representation, | either: | |||
or at least one suffix-range with a non-zero suffix-length, then the | ||||
bytes range-set is satisfiable. Otherwise, the bytes range-set is | ||||
unsatisfiable. | ||||
If the selected representation has zero length, the only satisfiable | * an int-range with a first-pos that is less than the current length | |||
form of range-spec is a suffix-range with a non-zero suffix-length. | of the selected representation or | |||
* a suffix-range with a non-zero suffix-length. | ||||
When a selected representation has zero length, the only satisfiable | ||||
form of range-spec in a GET request is a suffix-range with a non-zero | ||||
suffix-length. | ||||
In the byte-range syntax, first-pos, last-pos, and suffix-length are | In the byte-range syntax, first-pos, last-pos, and suffix-length are | |||
expressed as decimal number of octets. Since there is no predefined | expressed as decimal number of octets. Since there is no predefined | |||
limit to the length of content, recipients MUST anticipate | limit to the length of content, recipients MUST anticipate | |||
potentially large decimal numerals and prevent parsing errors due to | potentially large decimal numerals and prevent parsing errors due to | |||
integer conversion overflows. | integer conversion overflows. | |||
14.2. Range | 14.2. Range | |||
The "Range" header field on a GET request modifies the method | The "Range" header field on a GET request modifies the method | |||
skipping to change at page 141, line 26 ¶ | skipping to change at line 6477 ¶ | |||
selected representation. | selected representation. | |||
Range = ranges-specifier | Range = ranges-specifier | |||
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 they support efficient recovery from partially failed transfers | since they support efficient recovery from partially failed transfers | |||
and partial retrieval of large representations. | and partial retrieval of large representations. | |||
A server MUST ignore a Range header field received with a request | A server MUST ignore a Range header field received with a request | |||
method which is unrecognized or for which range handling is not | method that is unrecognized or for which range handling is not | |||
defined. For this specification, GET is the only method for which | defined. For this specification, GET is the only method for which | |||
range handling is defined. | range handling is defined. | |||
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 contains an invalid ranges-specifier | |||
set of many small ranges that are not listed in ascending order, | (Section 14.1.1), a ranges-specifier with more than two overlapping | |||
since both are indications of either a broken client or a deliberate | ranges, or a set of many small ranges that are not listed in | |||
denial-of-service attack (Section 17.15). A client SHOULD NOT | ascending order, since these are indications of either a broken | |||
request multiple ranges that are inherently less efficient to process | client or a deliberate denial-of-service attack (Section 17.15). A | |||
and transfer than a single range that encompasses the same data. | client SHOULD NOT request multiple ranges that are inherently less | |||
efficient to process and transfer than a single range that | ||||
encompasses the same data. | ||||
A server that supports range requests MAY ignore a Range header field | A server that supports range requests MAY ignore a Range header field | |||
when the selected representation has no content (i.e., the selected | when the selected representation has no content (i.e., the selected | |||
representation's data is of zero length). | representation's data is of zero length). | |||
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 | |||
skipping to change at page 142, line 24 ¶ | skipping to change at line 6518 ¶ | |||
The Range header field is evaluated after evaluating the precondition | The Range header field is evaluated after evaluating the precondition | |||
header fields defined in Section 13.1, and only if the result in | header fields defined in Section 13.1, and only if the result in | |||
absence of the Range header field would be a 200 (OK) response. In | absence of the Range header field would be a 200 (OK) response. In | |||
other words, Range is ignored when a conditional GET would result in | other words, Range is ignored when a conditional GET would result in | |||
a 304 (Not Modified) response. | a 304 (Not Modified) response. | |||
The If-Range header field (Section 13.1.5) can be used as a | The If-Range header field (Section 13.1.5) can be used as a | |||
precondition 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, the received Range field-value | |||
valid and satisfiable (as defined in Section 14.1.2), the server | contains a valid ranges-specifier with a range-unit supported for | |||
SHOULD send a 206 (Partial Content) response with a content | that target resource, and that ranges-specifier is satisfiable with | |||
containing one or more partial representations that correspond to the | respect to the selected representation, the server SHOULD send a 206 | |||
satisfiable ranges requested. | (Partial Content) response with content containing one or more | |||
partial representations that correspond to the satisfiable | ||||
range-spec(s) requested. | ||||
The above does not imply that a server will send all requested | The above does not imply that a server will send all requested | |||
ranges. In some cases, it may only be possible (or efficient) to | ranges. In some cases, it may only be possible (or efficient) to | |||
send a portion of the requested ranges first, while expecting the | send a portion of the requested ranges first, while expecting the | |||
client to re-request the remaining portions later if they are still | client to re-request the remaining portions later if they are still | |||
desired (see Section 15.3.7). | desired (see Section 15.3.7). | |||
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, the received Range field-value | |||
invalid or unsatisfiable, the server SHOULD send a 416 (Range Not | contains a valid ranges-specifier, and either the range-unit is not | |||
Satisfiable) response. | supported for that target resource or the ranges-specifier is | |||
unsatisfiable with respect to the selected representation, the server | ||||
SHOULD send a 416 (Range Not Satisfiable) response. | ||||
14.3. Accept-Ranges | 14.3. Accept-Ranges | |||
The "Accept-Ranges" field in a response indicates whether an upstream | The "Accept-Ranges" field in a response indicates whether an upstream | |||
server supports range requests for the target resource. | server supports range requests for the target resource. | |||
Accept-Ranges = acceptable-ranges | Accept-Ranges = acceptable-ranges | |||
acceptable-ranges = 1#range-unit | acceptable-ranges = 1#range-unit | |||
For example, a server that supports byte-range requests | For example, a server that supports byte-range requests | |||
skipping to change at page 146, line 12 ¶ | skipping to change at line 6698 ¶ | |||
specifically defined for partial updates (for example, the PATCH | specifically defined for partial updates (for example, the PATCH | |||
method defined in [RFC5789]). | method defined in [RFC5789]). | |||
14.6. Media Type multipart/byteranges | 14.6. 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 | |||
each with its own Content-Type and Content-Range fields. The | parts, 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. | |||
Implementation Notes: | Implementation Notes: | |||
1. Additional CRLFs might precede the first boundary string in the | 1. Additional CRLFs might precede the first boundary string in the | |||
body. | body. | |||
2. Although [RFC2046] permits the boundary string to be quoted, some | 2. Although [RFC2046] permits the boundary string to be quoted, some | |||
existing implementations handle a quoted boundary string | existing implementations handle a quoted boundary string | |||
incorrectly. | incorrectly. | |||
3. A number of clients and servers were coded to an early draft of | 3. A number of clients and servers were coded to an early draft of | |||
the byteranges specification that used a media type of multipart/ | the byteranges specification that used a media type of | |||
x-byteranges , which is almost (but not quite) compatible with | "multipart/x-byteranges", which is almost (but not quite) | |||
this type. | compatible with this type. | |||
Despite the name, the "multipart/byteranges" media type is not | Despite the name, the "multipart/byteranges" media type is not | |||
limited to byte ranges. The following example uses an "exampleunit" | limited to byte ranges. The following example uses an "exampleunit" | |||
range unit: | range unit: | |||
HTTP/1.1 206 Partial Content | HTTP/1.1 206 Partial Content | |||
Date: Tue, 14 Nov 1995 06:25:24 GMT | Date: Tue, 14 Nov 1995 06:25:24 GMT | |||
Last-Modified: Tue, 14 July 04:58:08 GMT | Last-Modified: Tue, 14 July 04:58:08 GMT | |||
Content-Length: 2331785 | Content-Length: 2331785 | |||
Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES | Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES | |||
skipping to change at page 147, line 4 ¶ | skipping to change at line 6738 ¶ | |||
Content-Type: video/example | Content-Type: video/example | |||
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-- | |||
The following information serves as the registration form for the | The following information serves as the registration form for the | |||
multipart/byteranges media type. | "multipart/byteranges" media type. | |||
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 17 | Security considerations: see Section 17 | |||
Interoperability considerations: N/A | Interoperability considerations: N/A | |||
Published specification: This specification (see Section 14.6). | Published specification: RFC 9110 (see Section 14.6) | |||
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: Deprecated alias names for this type: N/A | Additional information: 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 Aut | Person and email address to contact for further information: See Aut | |||
hors' 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 | |||
15. Status Codes | 15. Status Codes | |||
The status code of a response is a three-digit integer code that | The status code of a response is a three-digit integer code that | |||
describes the result of the request and the semantics of the | describes the result of the request and the semantics of the | |||
response, including whether the request was successful and what | response, including whether the request was successful and what | |||
content is enclosed (if any). All valid status codes are within the | content is enclosed (if any). All valid status codes are within the | |||
range of 100 to 599, inclusive. | range of 100 to 599, inclusive. | |||
skipping to change at page 149, line 6 ¶ | skipping to change at line 6829 ¶ | |||
Request) status code. The response message will usually contain a | Request) status code. The response message will usually contain a | |||
representation that explains the status. | representation that explains the status. | |||
Values outside the range 100..599 are invalid. Implementations often | Values outside the range 100..599 are invalid. Implementations often | |||
use three-digit integer values outside of that range (i.e., 600..999) | use three-digit integer values outside of that range (i.e., 600..999) | |||
for internal communication of non-HTTP status (e.g., library errors). | for internal communication of non-HTTP status (e.g., library errors). | |||
A client that receives a response with an invalid status code SHOULD | A client that receives a response with an invalid status code SHOULD | |||
process the response as if it had a 5xx (Server Error) status code. | process the response as if it had a 5xx (Server Error) status code. | |||
A single request can have multiple associated responses: zero or more | A single request can have multiple associated responses: zero or more | |||
_interim_ (non-final) responses with status codes in the | "interim" (non-final) responses with status codes in the | |||
"informational" (1xx) range, followed by exactly one _final_ response | "informational" (1xx) range, followed by exactly one "final" response | |||
with a status code in one of the other ranges. | with a status code in one of the other ranges. | |||
15.1. Overview of Status Codes | 15.1. Overview of Status Codes | |||
The status codes listed below are defined in this specification. The | The status codes listed below are defined in this specification. The | |||
reason phrases listed here are only recommendations - they can be | reason phrases listed here are only recommendations -- they can be | |||
replaced by local equivalents or left out altogether without | replaced by local equivalents or left out altogether without | |||
affecting the protocol. | affecting the protocol. | |||
Responses with status codes that are defined as heuristically | Responses with status codes that are defined as heuristically | |||
cacheable (e.g., 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, | cacheable (e.g., 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, | |||
414, and 501 in this specification) can be reused by a cache with | 414, and 501 in this specification) can be reused by a cache with | |||
heuristic expiration unless otherwise indicated by the method | heuristic expiration unless otherwise indicated by the method | |||
definition or explicit cache controls [CACHING]; all other status | definition or explicit cache controls [CACHING]; all other status | |||
codes are not heuristically cacheable. | codes are not heuristically cacheable. | |||
Additional status codes, outside the scope of this specification, | Additional status codes, outside the scope of this specification, | |||
have been specified for use in HTTP. All such status codes ought to | have been specified for use in HTTP. All such status codes ought to | |||
be registered within the "Hypertext Transfer Protocol (HTTP) Status | be registered within the "Hypertext Transfer Protocol (HTTP) Status | |||
Code Registry", as described in Section 16.2. | Code Registry", as described in Section 16.2. | |||
15.2. Informational 1xx | 15.2. Informational 1xx | |||
The _1xx (Informational)_ class of status code indicates an interim | The 1xx (Informational) class of status code indicates an interim | |||
response for communicating connection status or request progress | response for communicating connection status or request progress | |||
prior to completing the requested action and sending a final | prior to completing the requested action and sending a final | |||
response. Since HTTP/1.0 did not define any 1xx status codes, a | response. Since HTTP/1.0 did not define any 1xx status codes, a | |||
server MUST NOT send a 1xx response to an HTTP/1.0 client. | server MUST NOT send a 1xx response to an HTTP/1.0 client. | |||
A 1xx response is terminated by the end of the header section; it | A 1xx response is terminated by the end of the header section; it | |||
cannot contain content or trailers. | cannot contain content or trailers. | |||
A client MUST be able to parse one or more 1xx responses received | A client MUST be able to parse one or more 1xx responses received | |||
prior to a final response, even if the client does not expect one. A | prior to a final response, even if the client does not expect one. A | |||
user agent MAY ignore unexpected 1xx responses. | user agent MAY ignore unexpected 1xx responses. | |||
A proxy MUST forward 1xx responses unless the proxy itself requested | A proxy MUST forward 1xx responses unless the proxy itself requested | |||
the generation of the 1xx response. For example, if a proxy adds an | the generation of the 1xx response. For example, if a proxy adds an | |||
"Expect: 100-continue" header field when it forwards a request, then | "Expect: 100-continue" header field when it forwards a request, then | |||
it need not forward the corresponding 100 (Continue) response(s). | it need not forward the corresponding 100 (Continue) response(s). | |||
15.2.1. 100 Continue | 15.2.1. 100 Continue | |||
The _100 (Continue)_ status code indicates that the initial part of a | The 100 (Continue) status code indicates that the initial part of a | |||
request has been received and has not yet been rejected by the | request has been received and has not yet been rejected by the | |||
server. The server intends to send a final response after the | server. The server intends to send a final response after the | |||
request has been fully received and acted upon. | request has been fully received and acted upon. | |||
When the request contains an Expect header field that includes a | When the request contains an Expect header field that includes a | |||
100-continue expectation, the 100 response indicates that the server | 100-continue expectation, the 100 response indicates that the server | |||
wishes to receive the request content, as described in | wishes to receive the request content, as described in | |||
Section 10.1.1. The client ought to continue sending the request and | Section 10.1.1. The client ought to continue sending the request and | |||
discard the 100 response. | discard the 100 response. | |||
If the request did not contain an Expect header field containing the | If the request did not contain an Expect header field containing the | |||
100-continue expectation, the client can simply discard this interim | 100-continue expectation, the client can simply discard this interim | |||
response. | response. | |||
15.2.2. 101 Switching Protocols | 15.2.2. 101 Switching Protocols | |||
The _101 (Switching Protocols)_ status code indicates that the server | The 101 (Switching Protocols) status code indicates that the server | |||
understands and is willing to comply with the client's request, via | understands and is willing to comply with the client's request, via | |||
the Upgrade header field (Section 7.8), for a change in the | the Upgrade header field (Section 7.8), for a change in the | |||
application protocol being used on this connection. The server MUST | application protocol being used on this connection. The server MUST | |||
generate an Upgrade header field in the response that indicates which | generate an Upgrade header field in the response that indicates which | |||
protocol(s) will be in effect after this response. | protocol(s) will be in effect after this response. | |||
It is assumed that the server will only agree to switch protocols | It is assumed that the server will only agree to switch protocols | |||
when it is advantageous to do so. For example, switching to a newer | when it is advantageous to do so. For example, switching to a newer | |||
version of HTTP might be advantageous over older versions, and | version of HTTP might be advantageous over older versions, and | |||
switching to a real-time, synchronous protocol might be advantageous | switching to a real-time, synchronous protocol might be advantageous | |||
when delivering resources that use such features. | when delivering resources that use such features. | |||
15.3. Successful 2xx | 15.3. Successful 2xx | |||
The _2xx (Successful)_ class of status code indicates that the | The 2xx (Successful) class of status code indicates that the client's | |||
client's request was successfully received, understood, and accepted. | request was successfully received, understood, and accepted. | |||
15.3.1. 200 OK | 15.3.1. 200 OK | |||
The _200 (OK)_ status code indicates that the request has succeeded. | The 200 (OK) status code indicates that the request has succeeded. | |||
The content sent in a 200 response depends on the request method. | The content sent in a 200 response depends on the request method. | |||
For the methods defined by this specification, the intended meaning | For the methods defined by this specification, the intended meaning | |||
of the content can be summarized as: | of the content can be summarized as: | |||
+================+============================================+ | +================+============================================+ | |||
| request method | response content is a representation of | | | Request Method | Response content is a representation of: | | |||
+================+============================================+ | +================+============================================+ | |||
| GET | the target resource | | | GET | the target resource | | |||
+----------------+--------------------------------------------+ | +----------------+--------------------------------------------+ | |||
| HEAD | the target resource, like GET, but without | | | HEAD | the target resource, like GET, but without | | |||
| | transferring the representation data | | | | transferring the representation data | | |||
+----------------+--------------------------------------------+ | +----------------+--------------------------------------------+ | |||
| POST | the status of, or results obtained from, | | | POST | the status of, or results obtained from, | | |||
| | the action | | | | the action | | |||
+----------------+--------------------------------------------+ | +----------------+--------------------------------------------+ | |||
| PUT, DELETE | the status of the action | | | PUT, DELETE | the status of the action | | |||
skipping to change at page 151, line 31 ¶ | skipping to change at line 6942 ¶ | |||
| TRACE | the request message as received by the | | | TRACE | the request message as received by the | | |||
| | server returning the trace | | | | server returning the trace | | |||
+----------------+--------------------------------------------+ | +----------------+--------------------------------------------+ | |||
Table 6 | Table 6 | |||
Aside from responses to CONNECT, a 200 response is expected to | Aside from responses to CONNECT, a 200 response is expected to | |||
contain message content unless the message framing explicitly | contain message content unless the message framing explicitly | |||
indicates that the content has zero length. If some aspect of the | indicates that the content has zero length. If some aspect of the | |||
request indicates a preference for no content upon success, the | request indicates a preference for no content upon success, the | |||
origin server ought to send a _204 (No Content)_ response instead. | origin server ought to send a 204 (No Content) response instead. For | |||
For CONNECT, there is no content because the successful result is a | CONNECT, there is no content because the successful result is a | |||
tunnel, which begins immediately after the 200 response header | tunnel, which begins immediately after the 200 response header | |||
section. | section. | |||
A 200 response is heuristically cacheable; i.e., unless otherwise | A 200 response is heuristically cacheable; i.e., unless otherwise | |||
indicated by the method definition or explicit cache controls (see | indicated by the method definition or explicit cache controls (see | |||
Section 4.2.2 of [CACHING]). | Section 4.2.2 of [CACHING]). | |||
In 200 responses to GET or HEAD, an origin server SHOULD send any | In 200 responses to GET or HEAD, an origin server SHOULD send any | |||
available validator fields (Section 8.8) for the selected | available validator fields (Section 8.8) for the selected | |||
representation, with both a strong entity-tag and a Last-Modified | representation, with both a strong entity tag and a Last-Modified | |||
date being preferred. | date being preferred. | |||
In 200 responses to state-changing methods, any validator fields | In 200 responses to state-changing methods, any validator fields | |||
(Section 8.8) sent in the response convey the current validators for | (Section 8.8) sent in the response convey the current validators for | |||
the new representation formed as a result of successfully applying | the new representation formed as a result of successfully applying | |||
the request semantics. Note that the PUT method (Section 9.3.4) has | the request semantics. Note that the PUT method (Section 9.3.4) has | |||
additional requirements that might preclude sending such validators. | additional requirements that might preclude sending such validators. | |||
15.3.2. 201 Created | 15.3.2. 201 Created | |||
The _201 (Created)_ status code indicates that the request has been | The 201 (Created) status code indicates that the request has been | |||
fulfilled and has resulted in one or more new resources being | fulfilled and has resulted in one or more new resources being | |||
created. The primary resource created by the request is identified | created. The primary resource created by the request is identified | |||
by either a Location header field in the response or, if no Location | by either a Location header field in the response or, if no Location | |||
header field is received, by the target URI. | header field is received, by the target URI. | |||
The 201 response content typically describes and links to the | The 201 response content typically describes and links to the | |||
resource(s) created. Any validator fields (Section 8.8) sent in the | resource(s) created. Any validator fields (Section 8.8) sent in the | |||
response convey the current validators for a new representation | response convey the current validators for a new representation | |||
created by the request. Note that the PUT method (Section 9.3.4) has | created by the request. Note that the PUT method (Section 9.3.4) has | |||
additional requirements that might preclude sending such validators. | additional requirements that might preclude sending such validators. | |||
15.3.3. 202 Accepted | 15.3.3. 202 Accepted | |||
The _202 (Accepted)_ status code indicates that the request has been | The 202 (Accepted) status code indicates that the request has been | |||
accepted for processing, but the processing has not been completed. | accepted for processing, but the processing has not been completed. | |||
The request might or might not eventually be acted upon, as it might | The request might or might not eventually be acted upon, as it might | |||
be disallowed when processing actually takes place. There is no | be disallowed when processing actually takes place. There is no | |||
facility in HTTP for re-sending a status code from an asynchronous | facility in HTTP for re-sending a status code from an asynchronous | |||
operation. | operation. | |||
The 202 response is intentionally noncommittal. Its purpose is to | The 202 response is intentionally noncommittal. Its purpose is to | |||
allow a server to accept a request for some other process (perhaps a | allow a server to accept a request for some other process (perhaps a | |||
batch-oriented process that is only run once per day) without | batch-oriented process that is only run once per day) without | |||
requiring that the user agent's connection to the server persist | requiring that the user agent's connection to the server persist | |||
until the process is completed. The representation sent with this | until the process is completed. The representation sent with this | |||
response ought to describe the request's current status and point to | response ought to describe the request's current status and point to | |||
(or embed) a status monitor that can provide the user with an | (or embed) a status monitor that can provide the user with an | |||
estimate of when the request will be fulfilled. | estimate of when the request will be fulfilled. | |||
15.3.4. 203 Non-Authoritative Information | 15.3.4. 203 Non-Authoritative Information | |||
The _203 (Non-Authoritative Information)_ status code indicates that | The 203 (Non-Authoritative Information) status code indicates that | |||
the request was successful but the enclosed content has been modified | the request was successful but the enclosed content has been modified | |||
from that of the origin server's 200 (OK) response by a transforming | from that of the origin server's 200 (OK) response by a transforming | |||
proxy (Section 7.7). This status code allows the proxy to notify | proxy (Section 7.7). This status code allows the proxy to notify | |||
recipients when a transformation has been applied, since that | recipients when a transformation has been applied, since that | |||
knowledge might impact later decisions regarding the content. For | knowledge might impact later decisions regarding the content. For | |||
example, future cache validation requests for the content might only | example, future cache validation requests for the content might only | |||
be applicable along the same request path (through the same proxies). | be applicable along the same request path (through the same proxies). | |||
A 203 response is heuristically cacheable; i.e., unless otherwise | A 203 response is heuristically cacheable; i.e., unless otherwise | |||
indicated by the method definition or explicit cache controls (see | indicated by the method definition or explicit cache controls (see | |||
Section 4.2.2 of [CACHING]). | Section 4.2.2 of [CACHING]). | |||
15.3.5. 204 No Content | 15.3.5. 204 No Content | |||
The _204 (No Content)_ status code indicates that the server has | The 204 (No Content) status code indicates that the server has | |||
successfully fulfilled the request and that there is no additional | successfully fulfilled the request and that there is no additional | |||
content to send in the response content. Metadata in the response | content to send in the response content. Metadata in the response | |||
header fields refer to the target resource and its selected | header fields refer to the target resource and its selected | |||
representation after the requested action was applied. | representation after the requested action was applied. | |||
For example, if a 204 status code is received in response to a PUT | For example, if a 204 status code is received in response to a PUT | |||
request and the response contains an ETag field, then the PUT was | request and the response contains an ETag field, then the PUT was | |||
successful and the ETag field value contains the entity-tag for the | successful and the ETag field value contains the entity tag for the | |||
new representation of that target resource. | new representation of that target resource. | |||
The 204 response allows a server to indicate that the action has been | The 204 response allows a server to indicate that the action has been | |||
successfully applied to the target resource, while implying that the | successfully applied to the target resource, while implying that the | |||
user agent does not need to traverse away from its current "document | user agent does not need to traverse away from its current "document | |||
view" (if any). The server assumes that the user agent will provide | view" (if any). The server assumes that the user agent will provide | |||
some indication of the success to its user, in accord with its own | some indication of the success to its user, in accord with its own | |||
interface, and apply any new or updated metadata in the response to | interface, and apply any new or updated metadata in the response to | |||
its active representation. | its active representation. | |||
skipping to change at page 153, line 41 ¶ | skipping to change at line 7045 ¶ | |||
A 204 response is terminated by the end of the header section; it | A 204 response is terminated by the end of the header section; it | |||
cannot contain content or trailers. | cannot contain content or trailers. | |||
A 204 response is heuristically cacheable; i.e., unless otherwise | A 204 response is heuristically cacheable; i.e., unless otherwise | |||
indicated by the method definition or explicit cache controls (see | indicated by the method definition or explicit cache controls (see | |||
Section 4.2.2 of [CACHING]). | Section 4.2.2 of [CACHING]). | |||
15.3.6. 205 Reset Content | 15.3.6. 205 Reset Content | |||
The _205 (Reset Content)_ status code indicates that the server has | The 205 (Reset Content) status code indicates that the server has | |||
fulfilled the request and desires that the user agent reset the | fulfilled the request and desires that the user agent reset the | |||
"document view", which caused the request to be sent, to its original | "document view", which caused the request to be sent, to its original | |||
state as received from the origin server. | state as received from the origin server. | |||
This response is intended to support a common data entry use case | This response is intended to support a common data entry use case | |||
where the user receives content that supports data entry (a form, | where the user receives content that supports data entry (a form, | |||
notepad, canvas, etc.), enters or manipulates data in that space, | notepad, canvas, etc.), enters or manipulates data in that space, | |||
causes the entered data to be submitted in a request, and then the | causes the entered data to be submitted in a request, and then the | |||
data entry mechanism is reset for the next entry so that the user can | data entry mechanism is reset for the next entry so that the user can | |||
easily initiate another input action. | easily initiate another input action. | |||
Since the 205 status code implies that no additional content will be | Since the 205 status code implies that no additional content will be | |||
provided, a server MUST NOT generate content in a 205 response. | provided, a server MUST NOT generate content in a 205 response. | |||
15.3.7. 206 Partial Content | 15.3.7. 206 Partial Content | |||
The _206 (Partial Content)_ status code indicates that the server is | The 206 (Partial Content) status code indicates that the server is | |||
successfully fulfilling a range request for the target resource by | successfully fulfilling a range request for the target resource by | |||
transferring one or more parts of the selected representation. | transferring one or more parts of the selected representation. | |||
A server that supports range requests (Section 14) will usually | A server that supports range requests (Section 14) will usually | |||
attempt to satisfy all of the requested ranges, since sending less | attempt to satisfy all of the requested ranges, since sending less | |||
data will likely result in another client request for the remainder. | data will likely result in another client request for the remainder. | |||
However, a server might want to send only a subset of the data | However, a server might want to send only a subset of the data | |||
requested for reasons of its own, such as temporary unavailability, | requested for reasons of its own, such as temporary unavailability, | |||
cache efficiency, load balancing, etc. Since a 206 response is self- | cache efficiency, load balancing, etc. Since a 206 response is self- | |||
descriptive, the client can still understand a response that only | descriptive, the client can still understand a response that only | |||
skipping to change at page 154, line 41 ¶ | skipping to change at line 7093 ¶ | |||
Content-Location, and Vary. | Content-Location, and Vary. | |||
A Content-Length header field present in a 206 response indicates the | A Content-Length header field present in a 206 response indicates the | |||
number of octets in the content of this message, which is usually not | number of octets in the content of this message, which is usually not | |||
the complete length of the selected representation. Each | the complete length of the selected representation. Each | |||
Content-Range header field includes information about the selected | Content-Range header field includes information about the selected | |||
representation's complete length. | representation's complete length. | |||
A sender that generates a 206 response to a request with an If-Range | A sender that generates a 206 response to a request with an If-Range | |||
header field SHOULD NOT generate other representation header fields | header field SHOULD NOT generate other representation header fields | |||
beyond those required, because the client already has a prior | beyond those required because the client already has a prior response | |||
response containing those header fields. Otherwise, a sender MUST | containing those header fields. Otherwise, a sender MUST generate | |||
generate all of the representation header fields that would have been | all of the representation header fields that would have been sent in | |||
sent in a 200 (OK) response to the same request. | a 200 (OK) response to the same request. | |||
A 206 response is heuristically cacheable; i.e., unless otherwise | A 206 response is heuristically cacheable; i.e., unless otherwise | |||
indicated by explicit cache controls (see Section 4.2.2 of | indicated by explicit cache controls (see Section 4.2.2 of | |||
[CACHING]). | [CACHING]). | |||
15.3.7.1. Single Part | 15.3.7.1. Single Part | |||
If a single part is being transferred, the server generating the 206 | If a single part is being transferred, the server generating the 206 | |||
response MUST generate a Content-Range header field, describing what | response MUST generate a Content-Range header field, describing what | |||
range of the selected representation is enclosed, and a content | range of the selected representation is enclosed, and a content | |||
skipping to change at page 155, line 26 ¶ | skipping to change at line 7123 ¶ | |||
Content-Length: 26012 | Content-Length: 26012 | |||
Content-Type: image/gif | Content-Type: image/gif | |||
... 26012 bytes of partial image data ... | ... 26012 bytes of partial image data ... | |||
15.3.7.2. Multiple Parts | 15.3.7.2. Multiple Parts | |||
If multiple parts are being transferred, the server generating the | If multiple parts are being transferred, the server generating the | |||
206 response MUST generate "multipart/byteranges" content, as defined | 206 response MUST generate "multipart/byteranges" content, as defined | |||
in Section 14.6, and a Content-Type header field containing the | in Section 14.6, and a Content-Type header field containing the | |||
multipart/byteranges media type and its required boundary parameter. | "multipart/byteranges" media type and its required boundary | |||
To avoid confusion with single-part responses, a server MUST NOT | parameter. To avoid confusion with single-part responses, a server | |||
generate a Content-Range header field in the HTTP header section of a | MUST NOT generate a Content-Range header field in the HTTP header | |||
multiple part response (this field will be sent in each part | section of a multiple part response (this field will be sent in each | |||
instead). | part instead). | |||
Within the header area of each body part in the multipart content, | Within the header area of each body part in the multipart content, | |||
the server MUST generate a Content-Range header field corresponding | the server MUST generate a Content-Range header field corresponding | |||
to the range being enclosed in that body part. If the selected | to the range being enclosed in that body part. If the selected | |||
representation would have had a Content-Type header field in a 200 | representation would have had a Content-Type header field in a 200 | |||
(OK) response, the server SHOULD generate that same Content-Type | (OK) response, the server SHOULD generate that same Content-Type | |||
header field in the header area of each body part. For example: | header field in the header area of each body part. For example: | |||
HTTP/1.1 206 Partial Content | HTTP/1.1 206 Partial Content | |||
Date: Wed, 15 Nov 1995 06:25:24 GMT | Date: Wed, 15 Nov 1995 06:25:24 GMT | |||
skipping to change at page 156, line 28 ¶ | skipping to change at line 7159 ¶ | |||
Content-Range: bytes 7000-7999/8000 | Content-Range: bytes 7000-7999/8000 | |||
...the second range | ...the second range | |||
--THIS_STRING_SEPARATES-- | --THIS_STRING_SEPARATES-- | |||
When multiple ranges are requested, a server MAY coalesce any of the | When multiple ranges are requested, a server MAY coalesce any of the | |||
ranges that overlap, or that are separated by a gap that is smaller | ranges that overlap, or that are separated by a gap that is smaller | |||
than the overhead of sending multiple parts, regardless of the order | than the overhead of sending multiple parts, regardless of the order | |||
in which the corresponding range-spec appeared in the received Range | in which the corresponding range-spec appeared in the received Range | |||
header field. Since the typical overhead between each part of a | header field. Since the typical overhead between each part of a | |||
multipart/byteranges is around 80 bytes, depending on the selected | "multipart/byteranges" is around 80 bytes, depending on the selected | |||
representation's media type and the chosen boundary parameter length, | representation's media type and the chosen boundary parameter length, | |||
it can be less efficient to transfer many small disjoint parts than | it can be less efficient to transfer many small disjoint parts than | |||
it is to transfer the entire selected representation. | it is to transfer the entire selected representation. | |||
A server MUST NOT generate a multipart response to a request for a | A server MUST NOT generate a multipart response to a request for a | |||
single range, since a client that does not request multiple parts | single range, since a client that does not request multiple parts | |||
might not support multipart responses. However, a server MAY | might not support multipart responses. However, a server MAY | |||
generate a multipart/byteranges response with only a single body part | generate a "multipart/byteranges" response with only a single body | |||
if multiple ranges were requested and only one range was found to be | part if multiple ranges were requested and only one range was found | |||
satisfiable or only one range remained after coalescing. A client | to be satisfiable or only one range remained after coalescing. A | |||
that cannot process a multipart/byteranges response MUST NOT generate | client that cannot process a "multipart/byteranges" response MUST NOT | |||
a request that asks for multiple ranges. | generate a request that asks for multiple ranges. | |||
A server that generates a multipart response SHOULD send the parts in | A server that generates a multipart response SHOULD send the parts in | |||
the same order that the corresponding range-spec appeared in the | the same order that the corresponding range-spec appeared in the | |||
received Range header field, excluding those ranges that were deemed | received Range header field, excluding those ranges that were deemed | |||
unsatisfiable or that were coalesced into other ranges. A client | unsatisfiable or that were coalesced into other ranges. A client | |||
that receives a multipart response MUST inspect the Content-Range | that receives a multipart response MUST inspect the Content-Range | |||
header field present in each body part in order to determine which | header field present in each body part in order to determine which | |||
range is contained in that body part; a client cannot rely on | range is contained in that body part; a client cannot rely on | |||
receiving the same ranges that it requested, nor the same order that | receiving the same ranges that it requested, nor the same order that | |||
it requested. | it requested. | |||
skipping to change at page 157, line 42 ¶ | skipping to change at line 7220 ¶ | |||
The combined response content consists of the union of partial | The combined response content consists of the union of partial | |||
content ranges within the new response and all of the matching stored | content ranges within the new response and all of the matching stored | |||
responses. If the union consists of the entire range of the | responses. If the union consists of the entire range of the | |||
representation, then the client MUST process the combined response as | representation, then the client MUST process the combined response as | |||
if it were a complete 200 (OK) response, including a Content-Length | if it were a complete 200 (OK) response, including a Content-Length | |||
header field that reflects the complete length. Otherwise, the | header field that reflects the complete length. Otherwise, the | |||
client MUST process the set of continuous ranges as one of the | client MUST process the set of continuous ranges as one of the | |||
following: an incomplete 200 (OK) response if the combined response | following: an incomplete 200 (OK) response if the combined response | |||
is a prefix of the representation, a single 206 (Partial Content) | is a prefix of the representation, a single 206 (Partial Content) | |||
response containing multipart/byteranges content, or multiple 206 | response containing "multipart/byteranges" content, or multiple 206 | |||
(Partial Content) responses, each with one continuous range that is | (Partial Content) responses, each with one continuous range that is | |||
indicated by a Content-Range header field. | indicated by a Content-Range header field. | |||
15.4. Redirection 3xx | 15.4. Redirection 3xx | |||
The _3xx (Redirection)_ class of status code indicates that further | The 3xx (Redirection) class of status code indicates that further | |||
action needs to be taken by the user agent in order to fulfill the | action needs to be taken by the user agent in order to fulfill the | |||
request. There are several types of redirects: | request. There are several types of redirects: | |||
1. Redirects that indicate this resource might be available at a | 1. Redirects that indicate this resource might be available at a | |||
different URI, as provided by the Location header field, as in | different URI, as provided by the Location header field, as in | |||
the status codes 301 (Moved Permanently), 302 (Found), 307 | the status codes 301 (Moved Permanently), 302 (Found), 307 | |||
(Temporary Redirect), and 308 (Permanent Redirect). | (Temporary Redirect), and 308 (Permanent Redirect). | |||
2. Redirection that offers a choice among matching resources capable | 2. Redirection that offers a choice among matching resources capable | |||
of representing this resource, as in the 300 (Multiple Choices) | of representing this resource, as in the 300 (Multiple Choices) | |||
skipping to change at page 158, line 32 ¶ | skipping to change at line 7257 ¶ | |||
| and 302 (Found) were originally defined as method-preserving | | and 302 (Found) were originally defined as method-preserving | |||
| ([HTTP/1.0], Section 9.3) to match their implementation at | | ([HTTP/1.0], Section 9.3) to match their implementation at | |||
| CERN; 303 (See Other) was defined for a redirection that | | CERN; 303 (See Other) was defined for a redirection that | |||
| changed its method to GET. However, early user agents split on | | changed its method to GET. However, early user agents split on | |||
| whether to redirect POST requests as POST (according to then- | | whether to redirect POST requests as POST (according to then- | |||
| current specification) or as GET (the safer alternative when | | current specification) or as GET (the safer alternative when | |||
| redirected to a different site). Prevailing practice | | redirected to a different site). Prevailing practice | |||
| eventually converged on changing the method to GET. 307 | | eventually converged on changing the method to GET. 307 | |||
| (Temporary Redirect) and 308 (Permanent Redirect) [RFC7538] | | (Temporary Redirect) and 308 (Permanent Redirect) [RFC7538] | |||
| were later added to unambiguously indicate method-preserving | | were later added to unambiguously indicate method-preserving | |||
| redirects, and 301/302 have been adjusted to allow a POST | | redirects, and status codes 301 and 302 have been adjusted to | |||
| request to be redirected as GET. | | allow a POST request to be redirected as GET. | |||
If a Location header field (Section 10.2.2) is provided, the user | If a Location header field (Section 10.2.2) is provided, the user | |||
agent MAY automatically redirect its request to the URI referenced by | agent MAY automatically redirect its request to the URI referenced by | |||
the Location field value, even if the specific status code is not | the Location field value, even if the specific status code is not | |||
understood. Automatic redirection needs to be done with care for | understood. Automatic redirection needs to be done with care for | |||
methods not known to be safe, as defined in Section 9.2.1, since the | methods not known to be safe, as defined in Section 9.2.1, since the | |||
user might not wish to redirect an unsafe request. | user might not wish to redirect an unsafe request. | |||
When automatically following a redirected request, the user agent | When automatically following a redirected request, the user agent | |||
SHOULD resend the original request message with the following | SHOULD resend the original request message with the following | |||
skipping to change at page 159, line 15 ¶ | skipping to change at line 7289 ¶ | |||
1. Connection-specific header fields (see Section 7.6.1), | 1. Connection-specific header fields (see Section 7.6.1), | |||
2. Header fields specific to the client's proxy configuration, | 2. Header fields specific to the client's proxy configuration, | |||
including (but not limited to) Proxy-Authorization, | including (but not limited to) Proxy-Authorization, | |||
3. Origin-specific header fields (if any), including (but not | 3. Origin-specific header fields (if any), including (but not | |||
limited to) Host, | limited to) Host, | |||
4. Validating header fields that were added by the | 4. Validating header fields that were added by the | |||
implementation's cache (e.g., If-None-Match, | implementation's cache (e.g., If-None-Match, | |||
If-Modified-Since), | If-Modified-Since), and | |||
5. Resource-specific header fields, including (but not limited | 5. Resource-specific header fields, including (but not limited | |||
to) Referer, Origin, Authorization, and Cookie. | to) Referer, Origin, Authorization, and Cookie. | |||
3. Consider removing header fields that were not automatically | 3. Consider removing header fields that were not automatically | |||
generated by the implementation (i.e., those present in the | generated by the implementation (i.e., those present in the | |||
request because they were added by the calling context) where | request because they were added by the calling context) where | |||
there are security implications; this includes but is not limited | there are security implications; this includes but is not limited | |||
to Authorization and Cookie. | to Authorization and Cookie. | |||
skipping to change at page 159, line 44 ¶ | skipping to change at line 7318 ¶ | |||
A client SHOULD detect and intervene in cyclical redirections (i.e., | A client SHOULD detect and intervene in cyclical redirections (i.e., | |||
"infinite" redirection loops). | "infinite" redirection loops). | |||
| *Note:* An earlier version of this specification recommended a | | *Note:* An earlier version of this specification recommended a | |||
| maximum of five redirections ([RFC2068], Section 10.3). | | maximum of five redirections ([RFC2068], Section 10.3). | |||
| Content developers need to be aware that some clients might | | Content developers need to be aware that some clients might | |||
| implement such a fixed limitation. | | implement such a fixed limitation. | |||
15.4.1. 300 Multiple Choices | 15.4.1. 300 Multiple Choices | |||
The _300 (Multiple Choices)_ status code indicates that the target | The 300 (Multiple Choices) status code indicates that the target | |||
resource has more than one representation, each with its own more | resource has more than one representation, each with its own more | |||
specific identifier, and information about the alternatives is being | specific identifier, and information about the alternatives is being | |||
provided so that the user (or user agent) can select a preferred | provided so that the user (or user agent) can select a preferred | |||
representation by redirecting its request to one or more of those | representation by redirecting its request to one or more of those | |||
identifiers. In other words, the server desires that the user agent | identifiers. In other words, the server desires that the user agent | |||
engage in reactive negotiation to select the most appropriate | engage in reactive negotiation to select the most appropriate | |||
representation(s) for its needs (Section 12). | representation(s) for its needs (Section 12). | |||
If the server has a preferred choice, the server SHOULD generate a | If the server has a preferred choice, the server SHOULD generate a | |||
Location header field containing a preferred choice's URI reference. | Location header field containing a preferred choice's URI reference. | |||
skipping to change at page 160, line 39 ¶ | skipping to change at line 7361 ¶ | |||
| 406 responses and be transferred in responses to the HEAD | | 406 responses and be transferred in responses to the HEAD | |||
| method. However, lack of deployment and disagreement over | | method. However, lack of deployment and disagreement over | |||
| syntax led to both URI and Alternates (a subsequent proposal) | | syntax led to both URI and Alternates (a subsequent proposal) | |||
| being dropped from this specification. It is possible to | | being dropped from this specification. It is possible to | |||
| communicate the list as a Link header field value [RFC8288] | | communicate the list as a Link header field value [RFC8288] | |||
| whose members have a relationship of "alternate", though | | whose members have a relationship of "alternate", though | |||
| deployment is a chicken-and-egg problem. | | deployment is a chicken-and-egg problem. | |||
15.4.2. 301 Moved Permanently | 15.4.2. 301 Moved Permanently | |||
The _301 (Moved Permanently)_ status code indicates that the target | The 301 (Moved Permanently) status code indicates that the target | |||
resource has been assigned a new permanent URI and any future | resource has been assigned a new permanent URI and any future | |||
references to this resource ought to use one of the enclosed URIs. | references to this resource ought to use one of the enclosed URIs. | |||
The server is suggesting that a user agent with link-editing | The server is suggesting that a user agent with link-editing | |||
capability can permanently replace references to the target URI with | capability can permanently replace references to the target URI with | |||
one of the new references sent by the server. However, this | one of the new references sent by the server. However, this | |||
suggestion is usually ignored unless the user agent is actively | suggestion is usually ignored unless the user agent is actively | |||
editing references (e.g., engaged in authoring content), the | editing references (e.g., engaged in authoring content), the | |||
connection is secured, and the origin server is a trusted authority | connection is secured, and the origin server is a trusted authority | |||
for the content being edited. | for the content being edited. | |||
skipping to change at page 161, line 22 ¶ | skipping to change at line 7389 ¶ | |||
| request method from POST to GET for the subsequent request. If | | request method from POST to GET for the subsequent request. If | |||
| this behavior is undesired, the 308 (Permanent Redirect) status | | this behavior is undesired, the 308 (Permanent Redirect) status | |||
| code can be used instead. | | code can be used instead. | |||
A 301 response is heuristically cacheable; i.e., unless otherwise | A 301 response is heuristically cacheable; i.e., unless otherwise | |||
indicated by the method definition or explicit cache controls (see | indicated by the method definition or explicit cache controls (see | |||
Section 4.2.2 of [CACHING]). | Section 4.2.2 of [CACHING]). | |||
15.4.3. 302 Found | 15.4.3. 302 Found | |||
The _302 (Found)_ status code indicates that the target resource | The 302 (Found) status code indicates that the target resource | |||
resides temporarily under a different URI. Since the redirection | resides temporarily under a different URI. Since the redirection | |||
might be altered on occasion, the client ought to continue to use the | might be altered on occasion, the client ought to continue to use the | |||
target URI for future requests. | target URI for future requests. | |||
The server SHOULD generate a Location header field in the response | The server SHOULD generate a Location header field in the response | |||
containing a URI reference for the different URI. The user agent MAY | containing a URI reference for the different URI. The user agent MAY | |||
use the Location field value for automatic redirection. The server's | use the Location field value for automatic redirection. The server's | |||
response content usually contains a short hypertext note with a | response content usually contains a short hypertext note with a | |||
hyperlink to the different URI(s). | hyperlink to the different URI(s). | |||
| *Note:* For historical reasons, a user agent MAY change the | | *Note:* For historical reasons, a user agent MAY change the | |||
| request method from POST to GET for the subsequent request. If | | request method from POST to GET for the subsequent request. If | |||
| this behavior is undesired, the 307 (Temporary Redirect) status | | this behavior is undesired, the 307 (Temporary Redirect) status | |||
| code can be used instead. | | code can be used instead. | |||
15.4.4. 303 See Other | 15.4.4. 303 See Other | |||
The _303 (See Other)_ status code indicates that the server is | The 303 (See Other) status code indicates that the server is | |||
redirecting the user agent to a different resource, as indicated by a | redirecting the user agent to a different resource, as indicated by a | |||
URI in the Location header field, which is intended to provide an | URI in the Location header field, which is intended to provide an | |||
indirect response to the original request. A user agent can perform | indirect response to the original request. A user agent can perform | |||
a retrieval request targeting that URI (a GET or HEAD request if | a retrieval request targeting that URI (a GET or HEAD request if | |||
using HTTP), which might also be redirected, and present the eventual | using HTTP), which might also be redirected, and present the eventual | |||
result as an answer to the original request. Note that the new URI | result as an answer to the original request. Note that the new URI | |||
in the Location header field is not considered equivalent to the | in the Location header field is not considered equivalent to the | |||
target URI. | target URI. | |||
This status code is applicable to any HTTP method. It is primarily | This status code is applicable to any HTTP method. It is primarily | |||
skipping to change at page 162, line 28 ¶ | skipping to change at line 7440 ¶ | |||
answers to the questions of what can be represented, what | answers to the questions of what can be represented, what | |||
representations are adequate, and what might be a useful description | representations are adequate, and what might be a useful description | |||
are outside the scope of HTTP. | are outside the scope of HTTP. | |||
Except for responses to a HEAD request, the representation of a 303 | Except for responses to a HEAD request, the representation of a 303 | |||
response ought to contain a short hypertext note with a hyperlink to | response ought to contain a short hypertext note with a hyperlink to | |||
the same URI reference provided in the Location header field. | the same URI reference provided in the Location header field. | |||
15.4.5. 304 Not Modified | 15.4.5. 304 Not Modified | |||
The _304 (Not Modified)_ status code indicates that a conditional GET | The 304 (Not Modified) status code indicates that a conditional GET | |||
or HEAD request has been received and would have resulted in a 200 | or HEAD request has been received and would have resulted in a 200 | |||
(OK) response if it were not for the fact that the condition | (OK) response if it were not for the fact that the condition | |||
evaluated to false. In other words, there is no need for the server | evaluated to false. In other words, there is no need for the server | |||
to transfer a representation of the target resource because the | to transfer a representation of the target resource because the | |||
request indicates that the client, which made the request | request indicates that the client, which made the request | |||
conditional, already has a valid representation; the server is | conditional, already has a valid representation; the server is | |||
therefore redirecting the client to make use of that stored | therefore redirecting the client to make use of that stored | |||
representation as if it were the content of a 200 (OK) response. | representation as if it were the content of a 200 (OK) response. | |||
The server generating a 304 response MUST generate any of the | The server generating a 304 response MUST generate any of the | |||
following header fields that would have been sent in a 200 (OK) | following header fields that would have been sent in a 200 (OK) | |||
response to the same request: Cache-Control, Content-Location, Date, | response to the same request: | |||
ETag, Expires, and Vary. | ||||
* Content-Location, Date, ETag, and Vary | ||||
* Cache-Control and Expires (see [CACHING]) | ||||
Since the goal of a 304 response is to minimize information transfer | Since the goal of a 304 response is to minimize information transfer | |||
when the recipient already has one or more cached representations, a | when the recipient already has one or more cached representations, a | |||
sender SHOULD NOT generate representation metadata other than the | sender SHOULD NOT generate representation metadata other than the | |||
above listed fields unless said metadata exists for the purpose of | above listed fields unless said metadata exists for the purpose of | |||
guiding cache updates (e.g., Last-Modified might be useful if the | guiding cache updates (e.g., Last-Modified might be useful if the | |||
response does not have an ETag field). | response does not have an ETag field). | |||
Requirements on a cache that receives a 304 response are defined in | Requirements on a cache that receives a 304 response are defined in | |||
Section 4.3.4 of [CACHING]. If the conditional request originated | Section 4.3.4 of [CACHING]. If the conditional request originated | |||
with an outbound client, such as a user agent with its own cache | with an outbound client, such as a user agent with its own cache | |||
sending a conditional GET to a shared proxy, then the proxy SHOULD | sending a conditional GET to a shared proxy, then the proxy SHOULD | |||
forward the 304 response to that client. | forward the 304 response to that client. | |||
A 304 response is terminated by the end of the header section; it | A 304 response is terminated by the end of the header section; it | |||
cannot contain content or trailers. | cannot contain content or trailers. | |||
15.4.6. 305 Use Proxy | 15.4.6. 305 Use Proxy | |||
The _305 (Use Proxy)_ status code was defined in a previous version | The 305 (Use Proxy) status code was defined in a previous version of | |||
of this specification and is now deprecated (Appendix B of | this specification and is now deprecated (Appendix B of [RFC7231]). | |||
[RFC7231]). | ||||
15.4.7. 306 (Unused) | 15.4.7. 306 (Unused) | |||
The 306 status code was defined in a previous version of this | The 306 status code was defined in a previous version of this | |||
specification, is no longer used, and the code is reserved. | specification, is no longer used, and the code is reserved. | |||
15.4.8. 307 Temporary Redirect | 15.4.8. 307 Temporary Redirect | |||
The _307 (Temporary Redirect)_ status code indicates that the target | The 307 (Temporary Redirect) status code indicates that the target | |||
resource resides temporarily under a different URI and the user agent | resource resides temporarily under a different URI and the user agent | |||
MUST NOT change the request method if it performs an automatic | MUST NOT change the request method if it performs an automatic | |||
redirection to that URI. Since the redirection can change over time, | redirection to that URI. Since the redirection can change over time, | |||
the client ought to continue using the original target URI for future | the client ought to continue using the original target URI for future | |||
requests. | requests. | |||
The server SHOULD generate a Location header field in the response | The server SHOULD generate a Location header field in the response | |||
containing a URI reference for the different URI. The user agent MAY | containing a URI reference for the different URI. The user agent MAY | |||
use the Location field value for automatic redirection. The server's | use the Location field value for automatic redirection. The server's | |||
response content usually contains a short hypertext note with a | response content usually contains a short hypertext note with a | |||
hyperlink to the different URI(s). | hyperlink to the different URI(s). | |||
15.4.9. 308 Permanent Redirect | 15.4.9. 308 Permanent Redirect | |||
The _308 (Permanent Redirect)_ status code indicates that the target | The 308 (Permanent Redirect) status code indicates that the target | |||
resource has been assigned a new permanent URI and any future | resource has been assigned a new permanent URI and any future | |||
references to this resource ought to use one of the enclosed URIs. | references to this resource ought to use one of the enclosed URIs. | |||
The server is suggesting that a user agent with link-editing | The server is suggesting that a user agent with link-editing | |||
capability can permanently replace references to the target URI with | capability can permanently replace references to the target URI with | |||
one of the new references sent by the server. However, this | one of the new references sent by the server. However, this | |||
suggestion is usually ignored unless the user agent is actively | suggestion is usually ignored unless the user agent is actively | |||
editing references (e.g., engaged in authoring content), the | editing references (e.g., engaged in authoring content), the | |||
connection is secured, and the origin server is a trusted authority | connection is secured, and the origin server is a trusted authority | |||
for the content being edited. | for the content being edited. | |||
skipping to change at page 164, line 16 ¶ | skipping to change at line 7523 ¶ | |||
containing a preferred URI reference for the new permanent URI. The | containing a preferred URI reference for the new permanent URI. The | |||
user agent MAY use the Location field value for automatic | user agent MAY use the Location field value for automatic | |||
redirection. The server's response content usually contains a short | redirection. The server's response content usually contains a short | |||
hypertext note with a hyperlink to the new URI(s). | hypertext note with a hyperlink to the new URI(s). | |||
A 308 response is heuristically cacheable; i.e., unless otherwise | A 308 response is heuristically cacheable; i.e., unless otherwise | |||
indicated by the method definition or explicit cache controls (see | indicated by the method definition or explicit cache controls (see | |||
Section 4.2.2 of [CACHING]). | Section 4.2.2 of [CACHING]). | |||
| *Note:* This status code is much younger (June 2014) than its | | *Note:* This status code is much younger (June 2014) than its | |||
| sibling codes, and thus might not be recognized everywhere. | | sibling codes and thus might not be recognized everywhere. See | |||
| See Section 4 of [RFC7538] for deployment considerations. | | Section 4 of [RFC7538] for deployment considerations. | |||
15.5. Client Error 4xx | 15.5. Client Error 4xx | |||
The _4xx (Client Error)_ class of status code indicates that the | The 4xx (Client Error) class of status code indicates that the client | |||
client seems to have erred. Except when responding to a HEAD | seems to have erred. Except when responding to a HEAD request, the | |||
request, the server SHOULD send a representation containing an | server SHOULD send a representation containing an explanation of the | |||
explanation of the error situation, and whether it is a temporary or | error situation, and whether it is a temporary or permanent | |||
permanent condition. These status codes are applicable to any | condition. These status codes are applicable to any request method. | |||
request method. User agents SHOULD display any included | User agents SHOULD display any included representation to the user. | |||
representation to the user. | ||||
15.5.1. 400 Bad Request | 15.5.1. 400 Bad Request | |||
The _400 (Bad Request)_ status code indicates that the server cannot | The 400 (Bad Request) status code indicates that the server cannot or | |||
or will not process the request due to something that is perceived to | will not process the request due to something that is perceived to be | |||
be a client error (e.g., malformed request syntax, invalid request | a client error (e.g., malformed request syntax, invalid request | |||
message framing, or deceptive request routing). | message framing, or deceptive request routing). | |||
15.5.2. 401 Unauthorized | 15.5.2. 401 Unauthorized | |||
The _401 (Unauthorized)_ status code indicates that the request has | The 401 (Unauthorized) status code indicates that the request has not | |||
not been applied because it lacks valid authentication credentials | been applied because it lacks valid authentication credentials for | |||
for the target resource. The server generating a 401 response MUST | the target resource. The server generating a 401 response MUST send | |||
send a WWW-Authenticate header field (Section 11.6.1) containing at | a WWW-Authenticate header field (Section 11.6.1) containing at least | |||
least one challenge applicable to the target resource. | one challenge applicable to the target resource. | |||
If the request included authentication credentials, then the 401 | If the request included authentication credentials, then the 401 | |||
response indicates that authorization has been refused for those | response indicates that authorization has been refused for those | |||
credentials. The user agent MAY repeat the request with a new or | credentials. The user agent MAY repeat the request with a new or | |||
replaced Authorization header field (Section 11.6.2). If the 401 | replaced Authorization header field (Section 11.6.2). If the 401 | |||
response contains the same challenge as the prior response, and the | response contains the same challenge as the prior response, and the | |||
user agent has already attempted authentication at least once, then | user agent has already attempted authentication at least once, then | |||
the user agent SHOULD present the enclosed representation to the | the user agent SHOULD present the enclosed representation to the | |||
user, since it usually contains relevant diagnostic information. | user, since it usually contains relevant diagnostic information. | |||
15.5.3. 402 Payment Required | 15.5.3. 402 Payment Required | |||
The _402 (Payment Required)_ status code is reserved for future use. | The 402 (Payment Required) status code is reserved for future use. | |||
15.5.4. 403 Forbidden | 15.5.4. 403 Forbidden | |||
The _403 (Forbidden)_ status code indicates that the server | The 403 (Forbidden) status code indicates that the server understood | |||
understood the request but refuses to fulfill it. A server that | the request but refuses to fulfill it. A server that wishes to make | |||
wishes to make public why the request has been forbidden can describe | public why the request has been forbidden can describe that reason in | |||
that reason in the response content (if any). | the response content (if any). | |||
If authentication credentials were provided in the request, the | If authentication credentials were provided in the request, the | |||
server considers them insufficient to grant access. The client | server considers them insufficient to grant access. The client | |||
SHOULD NOT automatically repeat the request with the same | SHOULD NOT automatically repeat the request with the same | |||
credentials. The client MAY repeat the request with new or different | credentials. The client MAY repeat the request with new or different | |||
credentials. However, a request might be forbidden for reasons | credentials. However, a request might be forbidden for reasons | |||
unrelated to the credentials. | unrelated to the credentials. | |||
An origin server that wishes to "hide" the current existence of a | An origin server that wishes to "hide" the current existence of a | |||
forbidden target resource MAY instead respond with a status code of | forbidden target resource MAY instead respond with a status code of | |||
404 (Not Found). | 404 (Not Found). | |||
15.5.5. 404 Not Found | 15.5.5. 404 Not Found | |||
The _404 (Not Found)_ status code indicates that the origin server | The 404 (Not Found) status code indicates that the origin server did | |||
did not find a current representation for the target resource or is | not find a current representation for the target resource or is not | |||
not willing to disclose that one exists. A 404 status code does not | willing to disclose that one exists. A 404 status code does not | |||
indicate whether this lack of representation is temporary or | indicate whether this lack of representation is temporary or | |||
permanent; the 410 (Gone) status code is preferred over 404 if the | permanent; the 410 (Gone) status code is preferred over 404 if the | |||
origin server knows, presumably through some configurable means, that | origin server knows, presumably through some configurable means, that | |||
the condition is likely to be permanent. | the condition is likely to be permanent. | |||
A 404 response is heuristically cacheable; i.e., unless otherwise | A 404 response is heuristically cacheable; i.e., unless otherwise | |||
indicated by the method definition or explicit cache controls (see | indicated by the method definition or explicit cache controls (see | |||
Section 4.2.2 of [CACHING]). | Section 4.2.2 of [CACHING]). | |||
15.5.6. 405 Method Not Allowed | 15.5.6. 405 Method Not Allowed | |||
The _405 (Method Not Allowed)_ status code indicates that the method | The 405 (Method Not Allowed) status code indicates that the method | |||
received in the request-line is known by the origin server but not | received in the request-line is known by the origin server but not | |||
supported by the target resource. The origin server MUST generate an | supported by the target resource. The origin server MUST generate an | |||
Allow header field in a 405 response containing a list of the target | Allow header field in a 405 response containing a list of the target | |||
resource's currently supported methods. | resource's currently supported methods. | |||
A 405 response is heuristically cacheable; i.e., unless otherwise | A 405 response is heuristically cacheable; i.e., unless otherwise | |||
indicated by the method definition or explicit cache controls (see | indicated by the method definition or explicit cache controls (see | |||
Section 4.2.2 of [CACHING]). | Section 4.2.2 of [CACHING]). | |||
15.5.7. 406 Not Acceptable | 15.5.7. 406 Not Acceptable | |||
The _406 (Not Acceptable)_ status code indicates that the target | The 406 (Not Acceptable) status code indicates that the target | |||
resource does not have a current representation that would be | resource does not have a current representation that would be | |||
acceptable to the user agent, according to the proactive negotiation | acceptable to the user agent, according to the proactive negotiation | |||
header fields received in the request (Section 12.1), and the server | header fields received in the request (Section 12.1), and the server | |||
is unwilling to supply a default representation. | is unwilling to supply a default representation. | |||
The server SHOULD generate content containing a list of available | The server SHOULD generate content containing a list of available | |||
representation characteristics and corresponding resource identifiers | representation characteristics and corresponding resource identifiers | |||
from which the user or user agent can choose the one most | from which the user or user agent can choose the one most | |||
appropriate. A user agent MAY automatically select the most | appropriate. A user agent MAY automatically select the most | |||
appropriate choice from that list. However, this specification does | appropriate choice from that list. However, this specification does | |||
not define any standard for such automatic selection, as described in | not define any standard for such automatic selection, as described in | |||
Section 15.4.1. | Section 15.4.1. | |||
15.5.8. 407 Proxy Authentication Required | 15.5.8. 407 Proxy Authentication Required | |||
The _407 (Proxy Authentication Required)_ status code is similar to | The 407 (Proxy Authentication Required) status code is similar to 401 | |||
401 (Unauthorized), but it indicates that the client needs to | (Unauthorized), but it indicates that the client needs to | |||
authenticate itself in order to use a proxy for this request. The | authenticate itself in order to use a proxy for this request. The | |||
proxy MUST send a Proxy-Authenticate header field (Section 11.7.1) | proxy MUST send a Proxy-Authenticate header field (Section 11.7.1) | |||
containing a challenge applicable to that proxy for the request. The | containing a challenge applicable to that proxy for the request. The | |||
client MAY repeat the request with a new or replaced | client MAY repeat the request with a new or replaced | |||
Proxy-Authorization header field (Section 11.7.2). | Proxy-Authorization header field (Section 11.7.2). | |||
15.5.9. 408 Request Timeout | 15.5.9. 408 Request Timeout | |||
The _408 (Request Timeout)_ status code indicates that the server did | The 408 (Request Timeout) status code indicates that the server did | |||
not receive a complete request message within the time that it was | not receive a complete request message within the time that it was | |||
prepared to wait. | prepared to wait. | |||
If the client has an outstanding request in transit, it MAY repeat | If the client has an outstanding request in transit, it MAY repeat | |||
that request. If the current connection is not usable (e.g., as it | that request. If the current connection is not usable (e.g., as it | |||
would be in HTTP/1.1, because request delimitation is lost), a new | would be in HTTP/1.1 because request delimitation is lost), a new | |||
connection will be used. | connection will be used. | |||
15.5.10. 409 Conflict | 15.5.10. 409 Conflict | |||
The _409 (Conflict)_ status code indicates that the request could not | The 409 (Conflict) status code indicates that the request could not | |||
be completed due to a conflict with the current state of the target | be completed due to a conflict with the current state of the target | |||
resource. This code is used in situations where the user might be | resource. This code is used in situations where the user might be | |||
able to resolve the conflict and resubmit the request. The server | able to resolve the conflict and resubmit the request. The server | |||
SHOULD generate content that includes enough information for a user | SHOULD generate content that includes enough information for a user | |||
to recognize the source of the conflict. | to recognize the source of the conflict. | |||
Conflicts are most likely to occur in response to a PUT request. For | Conflicts are most likely to occur in response to a PUT request. For | |||
example, if versioning were being used and the representation being | example, if versioning were being used and the representation being | |||
PUT included changes to a resource that conflict with those made by | PUT included changes to a resource that conflict with those made by | |||
an earlier (third-party) request, the origin server might use a 409 | an earlier (third-party) request, the origin server might use a 409 | |||
response to indicate that it can't complete the request. In this | response to indicate that it can't complete the request. In this | |||
case, the response representation would likely contain information | case, the response representation would likely contain information | |||
useful for merging the differences based on the revision history. | useful for merging the differences based on the revision history. | |||
15.5.11. 410 Gone | 15.5.11. 410 Gone | |||
The _410 (Gone)_ status code indicates that access to the target | The 410 (Gone) status code indicates that access to the target | |||
resource is no longer available at the origin server and that this | resource is no longer available at the origin server and that this | |||
condition is likely to be permanent. If the origin server does not | condition is likely to be permanent. If the origin server does not | |||
know, or has no facility to determine, whether or not the condition | know, or has no facility to determine, whether or not the condition | |||
is permanent, the status code 404 (Not Found) ought to be used | is permanent, the status code 404 (Not Found) ought to be used | |||
instead. | instead. | |||
The 410 response is primarily intended to assist the task of web | The 410 response is primarily intended to assist the task of web | |||
maintenance by notifying the recipient that the resource is | maintenance by notifying the recipient that the resource is | |||
intentionally unavailable and that the server owners desire that | intentionally unavailable and that the server owners desire that | |||
remote links to that resource be removed. Such an event is common | remote links to that resource be removed. Such an event is common | |||
for limited-time, promotional services and for resources belonging to | for limited-time, promotional services and for resources belonging to | |||
individuals no longer associated with the origin server's site. It | individuals no longer associated with the origin server's site. It | |||
is not necessary to mark all permanently unavailable resources as | is not necessary to mark all permanently unavailable resources as | |||
"gone" or to keep the mark for any length of time - that is left to | "gone" or to keep the mark for any length of time -- that is left to | |||
the discretion of the server owner. | the discretion of the server owner. | |||
A 410 response is heuristically cacheable; i.e., unless otherwise | A 410 response is heuristically cacheable; i.e., unless otherwise | |||
indicated by the method definition or explicit cache controls (see | indicated by the method definition or explicit cache controls (see | |||
Section 4.2.2 of [CACHING]). | Section 4.2.2 of [CACHING]). | |||
15.5.12. 411 Length Required | 15.5.12. 411 Length Required | |||
The _411 (Length Required)_ status code indicates that the server | The 411 (Length Required) status code indicates that the server | |||
refuses to accept the request without a defined Content-Length | refuses to accept the request without a defined Content-Length | |||
(Section 8.6). The client MAY repeat the request if it adds a valid | (Section 8.6). The client MAY repeat the request if it adds a valid | |||
Content-Length header field containing the length of the request | Content-Length header field containing the length of the request | |||
content. | content. | |||
15.5.13. 412 Precondition Failed | 15.5.13. 412 Precondition Failed | |||
The _412 (Precondition Failed)_ status code indicates that one or | The 412 (Precondition Failed) status code indicates that one or more | |||
more conditions given in the request header fields evaluated to false | conditions given in the request header fields evaluated to false when | |||
when tested on the server (Section 13). This response status code | tested on the server (Section 13). This response status code allows | |||
allows the client to place preconditions on the current resource | the client to place preconditions on the current resource state (its | |||
state (its current representations and metadata) and, thus, prevent | current representations and metadata) and, thus, prevent the request | |||
the request method from being applied if the target resource is in an | method from being applied if the target resource is in an unexpected | |||
unexpected state. | state. | |||
15.5.14. 413 Content Too Large | 15.5.14. 413 Content Too Large | |||
The _413 (Content Too Large)_ status code indicates that the server | The 413 (Content Too Large) status code indicates that the server is | |||
is refusing to process a request because the request content is | refusing to process a request because the request content is larger | |||
larger than the server is willing or able to process. The server MAY | than the server is willing or able to process. The server MAY | |||
terminate the request, if the protocol version in use allows it; | terminate the request, if the protocol version in use allows it; | |||
otherwise, the server MAY close the connection. | otherwise, the server MAY close the connection. | |||
If the condition is temporary, the server SHOULD generate a | If the condition is temporary, the server SHOULD generate a | |||
Retry-After header field to indicate that it is temporary and after | Retry-After header field to indicate that it is temporary and after | |||
what time the client MAY try again. | what time the client MAY try again. | |||
15.5.15. 414 URI Too Long | 15.5.15. 414 URI Too Long | |||
The _414 (URI Too Long)_ status code indicates that the server is | The 414 (URI Too Long) status code indicates that the server is | |||
refusing to service the request because the target URI is longer than | refusing to service the request because the target URI is longer than | |||
the server is willing to interpret. This rare condition is only | the server is willing to interpret. This rare condition is only | |||
likely to occur when a client has improperly converted a POST request | likely to occur when a client has improperly converted a POST request | |||
to a GET request with long query information, when the client has | to a GET request with long query information, when the client has | |||
descended into a "black hole" of redirection (e.g., a redirected URI | descended into an infinite loop of redirection (e.g., a redirected | |||
prefix that points to a suffix of itself) or when the server is under | URI prefix that points to a suffix of itself) or when the server is | |||
attack by a client attempting to exploit potential security holes. | under attack by a client attempting to exploit potential security | |||
holes. | ||||
A 414 response is heuristically cacheable; i.e., unless otherwise | A 414 response is heuristically cacheable; i.e., unless otherwise | |||
indicated by the method definition or explicit cache controls (see | indicated by the method definition or explicit cache controls (see | |||
Section 4.2.2 of [CACHING]). | Section 4.2.2 of [CACHING]). | |||
15.5.16. 415 Unsupported Media Type | 15.5.16. 415 Unsupported Media Type | |||
The _415 (Unsupported Media Type)_ status code indicates that the | The 415 (Unsupported Media Type) status code indicates that the | |||
origin server is refusing to service the request because the content | origin server is refusing to service the request because the content | |||
is in a format not supported by this method on the target resource. | is in a format not supported by this method on the target resource. | |||
The format problem might be due to the request's indicated | The format problem might be due to the request's indicated | |||
Content-Type or Content-Encoding, or as a result of inspecting the | Content-Type or Content-Encoding, or as a result of inspecting the | |||
data directly. | data directly. | |||
If the problem was caused by an unsupported content coding, the | If the problem was caused by an unsupported content coding, the | |||
Accept-Encoding response header field (Section 12.5.3) ought to be | Accept-Encoding response header field (Section 12.5.3) ought to be | |||
used to indicate what (if any) content codings would have been | used to indicate which (if any) content codings would have been | |||
accepted in the request. | accepted in the request. | |||
On the other hand, if the cause was an unsupported media type, the | On the other hand, if the cause was an unsupported media type, the | |||
Accept response header field (Section 12.5.1) can be used to indicate | Accept response header field (Section 12.5.1) can be used to indicate | |||
what media types would have been accepted in the request. | which media types would have been accepted in the request. | |||
15.5.17. 416 Range Not Satisfiable | 15.5.17. 416 Range Not Satisfiable | |||
The _416 (Range Not Satisfiable)_ status code indicates that the set | The 416 (Range Not Satisfiable) status code indicates that the set of | |||
of ranges in the request's Range header field (Section 14.2) has been | ranges in the request's Range header field (Section 14.2) has been | |||
rejected either because none of the requested ranges are satisfiable | rejected either because none of the requested ranges are satisfiable | |||
or because the client has requested an excessive number of small or | or because the client has requested an excessive number of small or | |||
overlapping ranges (a potential denial of service attack). | overlapping ranges (a potential denial of service attack). | |||
Each range unit defines what is required for its own range sets to be | Each range unit defines what is required for its own range sets to be | |||
satisfiable. For example, Section 14.1.2 defines what makes a bytes | satisfiable. For example, Section 14.1.2 defines what makes a bytes | |||
range set satisfiable. | range set satisfiable. | |||
A server that generates a 416 response to a byte-range request SHOULD | A server that generates a 416 response to a byte-range request SHOULD | |||
generate a Content-Range header field specifying the current length | generate a Content-Range header field specifying the current length | |||
skipping to change at page 169, line 39 ¶ | skipping to change at line 7783 ¶ | |||
| representation in a 200 (OK) response. That is partly because | | representation in a 200 (OK) response. That is partly because | |||
| most clients are prepared to receive a 200 (OK) to complete the | | most clients are prepared to receive a 200 (OK) to complete the | |||
| task (albeit less efficiently) and partly because clients might | | task (albeit less efficiently) and partly because clients might | |||
| not stop making an invalid range request until they have | | not stop making an invalid range request until they have | |||
| received a complete representation. Thus, clients cannot | | received a complete representation. Thus, clients cannot | |||
| depend on receiving a 416 (Range Not Satisfiable) response even | | depend on receiving a 416 (Range Not Satisfiable) response even | |||
| when it is most appropriate. | | when it is most appropriate. | |||
15.5.18. 417 Expectation Failed | 15.5.18. 417 Expectation Failed | |||
The _417 (Expectation Failed)_ status code indicates that the | The 417 (Expectation Failed) status code indicates that the | |||
expectation given in the request's Expect header field | expectation given in the request's Expect header field | |||
(Section 10.1.1) could not be met by at least one of the inbound | (Section 10.1.1) could not be met by at least one of the inbound | |||
servers. | servers. | |||
15.5.19. 418 (Unused) | 15.5.19. 418 (Unused) | |||
[RFC2324] was an April 1 RFC that lampooned the various ways HTTP was | [RFC2324] was an April 1 RFC that lampooned the various ways HTTP was | |||
abused; one such abuse was the definition of an application-specific | abused; one such abuse was the definition of an application-specific | |||
418 status code. In the intervening years, this status code has been | 418 status code, which has been deployed as a joke often enough for | |||
widely implemented as an "Easter Egg", and therefore is effectively | the code to be unusable for any future use. | |||
consumed by this use. | ||||
Therefore, the 418 status code is reserved in the IANA HTTP Status | Therefore, the 418 status code is reserved in the IANA HTTP Status | |||
Code Registry. This indicates that the status code cannot be | Code Registry. This indicates that the status code cannot be | |||
assigned to other applications currently. If future circumstances | assigned to other applications currently. If future circumstances | |||
require its use (e.g., exhaustion of 4NN status codes), it can be re- | require its use (e.g., exhaustion of 4NN status codes), it can be re- | |||
assigned to another use. | assigned to another use. | |||
15.5.20. 421 Misdirected Request | 15.5.20. 421 Misdirected Request | |||
The 421 (Misdirected Request) status code indicates that the request | The 421 (Misdirected Request) status code indicates that the request | |||
skipping to change at page 170, line 33 ¶ | skipping to change at line 7823 ¶ | |||
different connection, such as a fresh connection specific to the | different connection, such as a fresh connection specific to the | |||
target resource's origin, or via an alternative service [ALTSVC]. | target resource's origin, or via an alternative service [ALTSVC]. | |||
A proxy MUST NOT generate a 421 response. | A proxy MUST NOT generate a 421 response. | |||
15.5.21. 422 Unprocessable Content | 15.5.21. 422 Unprocessable Content | |||
The 422 (Unprocessable Content) status code indicates that the server | The 422 (Unprocessable Content) status code indicates that the server | |||
understands the content type of the request content (hence a 415 | understands the content type of the request content (hence a 415 | |||
(Unsupported Media Type) status code is inappropriate), and the | (Unsupported Media Type) status code is inappropriate), and the | |||
syntax of the request content is correct, but was unable to process | syntax of the request content is correct, but it was unable to | |||
the contained instructions. For example, this status code can be | process the contained instructions. For example, this status code | |||
sent if an XML request content contains well-formed (i.e., | can be sent if an XML request content contains well-formed (i.e., | |||
syntactically correct), but semantically erroneous XML instructions. | syntactically correct), but semantically erroneous XML instructions. | |||
15.5.22. 426 Upgrade Required | 15.5.22. 426 Upgrade Required | |||
The _426 (Upgrade Required)_ status code indicates that the server | The 426 (Upgrade Required) status code indicates that the server | |||
refuses to perform the request using the current protocol but might | refuses to perform the request using the current protocol but might | |||
be willing to do so after the client upgrades to a different | be willing to do so after the client upgrades to a different | |||
protocol. The server MUST send an Upgrade header field in a 426 | protocol. The server MUST send an Upgrade header field in a 426 | |||
response to indicate the required protocol(s) (Section 7.8). | response to indicate the required protocol(s) (Section 7.8). | |||
Example: | Example: | |||
HTTP/1.1 426 Upgrade Required | HTTP/1.1 426 Upgrade Required | |||
Upgrade: HTTP/3.0 | Upgrade: HTTP/3.0 | |||
Connection: Upgrade | Connection: Upgrade | |||
Content-Length: 53 | Content-Length: 53 | |||
Content-Type: text/plain | Content-Type: text/plain | |||
This service requires use of the HTTP/3.0 protocol. | This service requires use of the HTTP/3.0 protocol. | |||
15.6. Server Error 5xx | 15.6. Server Error 5xx | |||
The _5xx (Server Error)_ class of status code indicates that the | The 5xx (Server Error) class of status code indicates that the server | |||
server is aware that it has erred or is incapable of performing the | is aware that it has erred or is incapable of performing the | |||
requested method. Except when responding to a HEAD request, the | requested method. Except when responding to a HEAD request, the | |||
server SHOULD send a representation containing an explanation of the | server SHOULD send a representation containing an explanation of the | |||
error situation, and whether it is a temporary or permanent | error situation, and whether it is a temporary or permanent | |||
condition. A user agent SHOULD display any included representation | condition. A user agent SHOULD display any included representation | |||
to the user. These response codes are applicable to any request | to the user. These status codes are applicable to any request | |||
method. | method. | |||
15.6.1. 500 Internal Server Error | 15.6.1. 500 Internal Server Error | |||
The _500 (Internal Server Error)_ status code indicates that the | The 500 (Internal Server Error) status code indicates that the server | |||
server encountered an unexpected condition that prevented it from | encountered an unexpected condition that prevented it from fulfilling | |||
fulfilling the request. | the request. | |||
15.6.2. 501 Not Implemented | 15.6.2. 501 Not Implemented | |||
The _501 (Not Implemented)_ status code indicates that the server | The 501 (Not Implemented) status code indicates that the server does | |||
does not support the functionality required to fulfill the request. | not support the functionality required to fulfill the request. This | |||
This is the appropriate response when the server does not recognize | is the appropriate response when the server does not recognize the | |||
the request method and is not capable of supporting it for any | request method and is not capable of supporting it for any resource. | |||
resource. | ||||
A 501 response is heuristically cacheable; i.e., unless otherwise | A 501 response is heuristically cacheable; i.e., unless otherwise | |||
indicated by the method definition or explicit cache controls (see | indicated by the method definition or explicit cache controls (see | |||
Section 4.2.2 of [CACHING]). | Section 4.2.2 of [CACHING]). | |||
15.6.3. 502 Bad Gateway | 15.6.3. 502 Bad Gateway | |||
The _502 (Bad Gateway)_ status code indicates that the server, while | The 502 (Bad Gateway) status code indicates that the server, while | |||
acting as a gateway or proxy, received an invalid response from an | acting as a gateway or proxy, received an invalid response from an | |||
inbound server it accessed while attempting to fulfill the request. | inbound server it accessed while attempting to fulfill the request. | |||
15.6.4. 503 Service Unavailable | 15.6.4. 503 Service Unavailable | |||
The _503 (Service Unavailable)_ status code indicates that the server | The 503 (Service Unavailable) status code indicates that the server | |||
is currently unable to handle the request due to a temporary overload | is currently unable to handle the request due to a temporary overload | |||
or scheduled maintenance, which will likely be alleviated after some | or scheduled maintenance, which will likely be alleviated after some | |||
delay. The server MAY send a Retry-After header field | delay. The server MAY send a Retry-After header field | |||
(Section 10.2.3) to suggest an appropriate amount of time for the | (Section 10.2.3) to suggest an appropriate amount of time for the | |||
client to wait before retrying the request. | client to wait before retrying the request. | |||
| *Note:* The existence of the 503 status code does not imply | | *Note:* The existence of the 503 status code does not imply | |||
| that a server has to use it when becoming overloaded. Some | | that a server has to use it when becoming overloaded. Some | |||
| servers might simply refuse the connection. | | servers might simply refuse the connection. | |||
15.6.5. 504 Gateway Timeout | 15.6.5. 504 Gateway Timeout | |||
The _504 (Gateway Timeout)_ status code indicates that the server, | The 504 (Gateway Timeout) status code indicates that the server, | |||
while acting as a gateway or proxy, did not receive a timely response | while acting as a gateway or proxy, did not receive a timely response | |||
from an upstream server it needed to access in order to complete the | from an upstream server it needed to access in order to complete the | |||
request. | request. | |||
15.6.6. 505 HTTP Version Not Supported | 15.6.6. 505 HTTP Version Not Supported | |||
The _505 (HTTP Version Not Supported)_ status code indicates that the | The 505 (HTTP Version Not Supported) status code indicates that the | |||
server does not support, or refuses to support, the major version of | server does not support, or refuses to support, the major version of | |||
HTTP that was used in the request message. The server is indicating | HTTP that was used in the request message. The server is indicating | |||
that it is unable or unwilling to complete the request using the same | that it is unable or unwilling to complete the request using the same | |||
major version as the client, as described in Section 2.5, other than | major version as the client, as described in Section 2.5, other than | |||
with this error message. The server SHOULD generate a representation | with this error message. The server SHOULD generate a representation | |||
for the 505 response that describes why that version is not supported | for the 505 response that describes why that version is not supported | |||
and what other protocols are supported by that server. | and what other protocols are supported by that server. | |||
16. Extending HTTP | 16. Extending HTTP | |||
HTTP defines a number of generic extension points that can be used to | HTTP defines a number of generic extension points that can be used to | |||
introduce capabilities to the protocol without introducing a new | introduce capabilities to the protocol without introducing a new | |||
version, including methods, status codes, field names, and further | version, including methods, status codes, field names, and further | |||
extensibility points within defined fields, such as authentication | extensibility points within defined fields, such as authentication | |||
schemes and cache-directives (see Cache-Control extensions in | schemes and cache directives (see Cache-Control extensions in | |||
Section 5.2.3 of [CACHING]). Because the semantics of HTTP are not | Section 5.2.3 of [CACHING]). Because the semantics of HTTP are not | |||
versioned, these extension points are persistent; the version of the | versioned, these extension points are persistent; the version of the | |||
protocol in use does not affect their semantics. | protocol in use does not affect their semantics. | |||
Version-independent extensions are discouraged from depending on or | Version-independent extensions are discouraged from depending on or | |||
interacting with the specific version of the protocol in use. When | interacting with the specific version of the protocol in use. When | |||
this is unavoidable, careful consideration needs to be given to how | this is unavoidable, careful consideration needs to be given to how | |||
the extension can interoperate across versions. | the extension can interoperate across versions. | |||
Additionally, specific versions of HTTP might have their own | Additionally, specific versions of HTTP might have their own | |||
extensibility points, such as transfer-codings in HTTP/1.1 | extensibility points, such as transfer codings in HTTP/1.1 | |||
(Section 6.1 of [HTTP/1.1]) and HTTP/2 ([HTTP/2]) SETTINGS or frame | (Section 6.1 of [HTTP/1.1]) and HTTP/2 SETTINGS or frame types | |||
types. These extension points are specific to the version of the | ([HTTP/2]). These extension points are specific to the version of | |||
protocol they occur within. | the protocol they occur within. | |||
Version-specific extensions cannot override or m |