| 796 | | <h1 id="rfc.section.1" class="np"><a href="#rfc.section.1">1.</a> <a id="introduction" href="#introduction">Introduction</a></h1> |
| 797 | | <p id="rfc.section.1.p.1">Each Hypertext Transfer Protocol (HTTP) message is either a request or a response. A server listens on a connection for a |
| 798 | | request, parses each message received, interprets the message semantics in relation to the identified request target, and |
| 799 | | responds to that request with one or more response messages. A client constructs request messages to communicate specific |
| 800 | | intentions, and examines received responses to see if the intentions were carried out and determine how to interpret the results. |
| 801 | | This document defines HTTP/1.1 request and response semantics in terms of the architecture defined in <a href="#Part1" id="rfc.xref.Part1.1"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>. |
| 802 | | </p> |
| 803 | | <p id="rfc.section.1.p.2">HTTP provides a uniform interface for interacting with a resource (<a href="#resources" title="Resources">Section 2</a>), regardless of its type, nature, or implementation, via the manipulation and transfer of representations (<a href="#representations" title="Representations">Section 3</a>). |
| 804 | | </p> |
| 805 | | <p id="rfc.section.1.p.3">HTTP semantics include the intentions defined by each request method (<a href="#methods" title="Request Methods">Section 4</a>), extensions to those semantics that might be described in request header fields (<a href="#request.header.fields" title="Request Header Fields">Section 5</a>), the meaning of status codes to indicate a machine-readable response (<a href="#status.codes" title="Response Status Codes">Section 6</a>), and the meaning of other control data and resource metadata that might be given in response header fields (<a href="#response.header.fields" title="Response Header Fields">Section 7</a>). |
| 806 | | </p> |
| 807 | | <p id="rfc.section.1.p.4"><span id="rfc.iref.c.1"></span> This document also defines representation metadata that describe how a payload is intended to be interpreted by a recipient, |
| 808 | | the request header fields that might influence content selection, and the various selection algorithms that are collectively |
| 809 | | referred to as "<dfn>content negotiation</dfn>" (<a href="#content.negotiation" title="Content Negotiation">Section 3.4</a>). |
| 810 | | </p> |
| 811 | | <h2 id="rfc.section.1.1"><a href="#rfc.section.1.1">1.1</a> <a id="conformance" href="#conformance">Conformance and Error Handling</a></h2> |
| 812 | | <p id="rfc.section.1.1.p.1">The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" |
| 813 | | in this document are to be interpreted as described in <a href="#RFC2119" id="rfc.xref.RFC2119.1"><cite title="Key words for use in RFCs to Indicate Requirement Levels">[RFC2119]</cite></a>. |
| 814 | | </p> |
| 815 | | <p id="rfc.section.1.1.p.2">Conformance criteria and considerations regarding error handling are defined in <a href="p1-messaging.html#conformance" title="Conformance and Error Handling">Section 2.5</a> of <a href="#Part1" id="rfc.xref.Part1.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>. |
| 816 | | </p> |
| 817 | | <h2 id="rfc.section.1.2"><a href="#rfc.section.1.2">1.2</a> <a id="notation" href="#notation">Syntax Notation</a></h2> |
| 818 | | <p id="rfc.section.1.2.p.1">This specification uses the Augmented Backus-Naur Form (ABNF) notation of <a href="#RFC5234" id="rfc.xref.RFC5234.1"><cite title="Augmented BNF for Syntax Specifications: ABNF">[RFC5234]</cite></a> with the list rule extension defined in <a href="p1-messaging.html#abnf.extension" title="ABNF list extension: #rule">Section 7</a> of <a href="#Part1" id="rfc.xref.Part1.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>. <a href="#imported.abnf" title="Imported ABNF">Appendix C</a> describes rules imported from other documents. <a href="#collected.abnf" title="Collected ABNF">Appendix D</a> shows the collected ABNF with the list rule expanded. |
| 819 | | </p> |
| 820 | | <p id="rfc.section.1.2.p.2">This specification uses the terms "character", "character encoding scheme", "charset", and "protocol element" as they are |
| 821 | | defined in <a href="#RFC6365" id="rfc.xref.RFC6365.1"><cite title="Terminology Used in Internationalization in the IETF">[RFC6365]</cite></a>. |
| 822 | | </p> |
| 823 | | <h1 id="rfc.section.2"><a href="#rfc.section.2">2.</a> <a id="resources" href="#resources">Resources</a></h1> |
| 824 | | <p id="rfc.section.2.p.1">The target of an HTTP request is called a resource. HTTP does not limit the nature of a resource; it merely defines an interface |
| 825 | | that might be used to interact with resources. Each resource is identified by a Uniform Resource Identifier (URI), as described |
| 826 | | in <a href="p1-messaging.html#uri" title="Uniform Resource Identifiers">Section 2.7</a> of <a href="#Part1" id="rfc.xref.Part1.4"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>. |
| 827 | | </p> |
| 828 | | <p id="rfc.section.2.p.2">When a client constructs an HTTP/1.1 request message, it sends the <a href="p1-messaging.html#target-resource" class="smpl">target URI</a> in one of various forms, as defined in (<a href="p1-messaging.html#request-target" title="Request Target">Section 5.3</a> of <a href="#Part1" id="rfc.xref.Part1.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). When a request is received, the server reconstructs an <a href="p1-messaging.html#effective.request.uri" class="smpl">effective request URI</a> for the target resource (<a href="p1-messaging.html#effective.request.uri" title="Effective Request URI">Section 5.5</a> of <a href="#Part1" id="rfc.xref.Part1.6"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). |
| 829 | | </p> |
| 830 | | <p id="rfc.section.2.p.3">One design goal of HTTP is to separate resource identification from request semantics, which is made possible by vesting the |
| 831 | | request semantics in the request method (<a href="#methods" title="Request Methods">Section 4</a>) and a few request-modifying header fields (<a href="#request.header.fields" title="Request Header Fields">Section 5</a>). Resource owners <em class="bcp14">SHOULD NOT</em> include request semantics within a URI, such as by specifying an action to invoke within the path or query components of the |
| 832 | | effective request URI, unless those semantics are disabled when they are inconsistent with the request method. |
| 833 | | </p> |
| 834 | | <div id="rfc.iref.r.1"></div> |
| 835 | | <div id="rfc.iref.s.1"></div> |
| 836 | | <h1 id="rfc.section.3"><a href="#rfc.section.3">3.</a> <a id="representations" href="#representations">Representations</a></h1> |
| 837 | | <p id="rfc.section.3.p.1">If we consider that a resource could be anything, and that the uniform interface provided by HTTP is similar to a window through |
| 838 | | which one can observe and act upon such a thing only through the communication of messages to some independent actor on the |
| 839 | | other side, then we need an abstraction to represent ("take the place of") the current or desired state of that thing in our |
| 840 | | communications. We call that abstraction a representation <a href="#REST" id="rfc.xref.REST.1"><cite title="Architectural Styles and the Design of Network-based Software Architectures">[REST]</cite></a>. |
| 841 | | </p> |
| 842 | | <p id="rfc.section.3.p.2">For the purposes of HTTP, a "<dfn>representation</dfn>" is information that is intended to reflect a past, current, or desired state of a given resource, in a format that can be |
| 843 | | readily communicated via the protocol, and that consists of a set of representation metadata and a potentially unbounded stream |
| 844 | | of representation data. |
| 845 | | </p> |
| 846 | | <p id="rfc.section.3.p.3">An origin server might be provided with, or capable of generating, multiple representations that are each intended to reflect |
| 847 | | the current state of a <a href="#resources" class="smpl">target resource</a>. In such cases, some algorithm is used by the origin server to select one of those representations as most applicable to |
| 848 | | a given request, usually based on <a href="#content.negotiation" class="smpl">content negotiation</a>. We refer to that one representation as the "<dfn>selected representation</dfn>" and use its particular data and metadata for evaluating conditional requests <a href="#Part4" id="rfc.xref.Part4.1"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests">[Part4]</cite></a> and constructing the payload for <a href="#status.200" class="smpl">200 (OK)</a> and <a href="p4-conditional.html#status.304" class="smpl">304 (Not Modified)</a> responses to GET (<a href="#GET" id="rfc.xref.GET.1" title="GET">Section 4.3.1</a>). |
| 849 | | </p> |
| 850 | | <h2 id="rfc.section.3.1"><a href="#rfc.section.3.1">3.1</a> <a id="representation.metadata" href="#representation.metadata">Representation Metadata</a></h2> |
| 851 | | <p id="rfc.section.3.1.p.1">Representation header fields provide metadata about the representation. When a message includes a payload body, the representation |
| 852 | | header fields describe how to interpret the representation data enclosed in the payload body. In a response to a HEAD request, |
| 853 | | the representation header fields describe the representation data that would have been enclosed in the payload body if the |
| 854 | | same request had been a GET. |
| 855 | | </p> |
| 856 | | <p id="rfc.section.3.1.p.2">The following header fields convey representation metadata:</p> |
| 857 | | <div id="rfc.table.u.1"> |
| 858 | | <table class="tt full left" cellpadding="3" cellspacing="0"> |
| 859 | | <thead> |
| 860 | | <tr> |
| 861 | | <th>Header Field Name</th> |
| 862 | | <th>Defined in...</th> |
| 863 | | </tr> |
| 864 | | </thead> |
| 865 | | <tbody> |
| 866 | | <tr> |
| 867 | | <td class="left">Content-Type</td> |
| 868 | | <td class="left"><a href="#header.content-type" id="rfc.xref.header.content-type.1" title="Content-Type">Section 3.1.1.5</a></td> |
| 869 | | </tr> |
| 870 | | <tr> |
| 871 | | <td class="left">Content-Encoding</td> |
| 872 | | <td class="left"><a href="#header.content-encoding" id="rfc.xref.header.content-encoding.1" title="Content-Encoding">Section 3.1.2.2</a></td> |
| 873 | | </tr> |
| 874 | | <tr> |
| 875 | | <td class="left">Content-Language</td> |
| 876 | | <td class="left"><a href="#header.content-language" id="rfc.xref.header.content-language.1" title="Content-Language">Section 3.1.3.2</a></td> |
| 877 | | </tr> |
| 878 | | <tr> |
| 879 | | <td class="left">Content-Location</td> |
| 880 | | <td class="left"><a href="#header.content-location" id="rfc.xref.header.content-location.1" title="Content-Location">Section 3.1.4.2</a></td> |
| 881 | | </tr> |
| 882 | | </tbody> |
| 883 | | </table> |
| | 799 | <div id="introduction"> |
| | 800 | <h1 id="rfc.section.1" class="np"><a href="#rfc.section.1">1.</a> <a href="#introduction">Introduction</a></h1> |
| | 801 | <p id="rfc.section.1.p.1">Each Hypertext Transfer Protocol (HTTP) message is either a request or a response. A server listens on a connection for a |
| | 802 | request, parses each message received, interprets the message semantics in relation to the identified request target, and |
| | 803 | responds to that request with one or more response messages. A client constructs request messages to communicate specific |
| | 804 | intentions, and examines received responses to see if the intentions were carried out and determine how to interpret the results. |
| | 805 | This document defines HTTP/1.1 request and response semantics in terms of the architecture defined in <a href="#Part1" id="rfc.xref.Part1.1"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>. |
| | 806 | </p> |
| | 807 | <p id="rfc.section.1.p.2">HTTP provides a uniform interface for interacting with a resource (<a href="#resources" title="Resources">Section 2</a>), regardless of its type, nature, or implementation, via the manipulation and transfer of representations (<a href="#representations" title="Representations">Section 3</a>). |
| | 808 | </p> |
| | 809 | <p id="rfc.section.1.p.3">HTTP semantics include the intentions defined by each request method (<a href="#methods" title="Request Methods">Section 4</a>), extensions to those semantics that might be described in request header fields (<a href="#request.header.fields" title="Request Header Fields">Section 5</a>), the meaning of status codes to indicate a machine-readable response (<a href="#status.codes" title="Response Status Codes">Section 6</a>), and the meaning of other control data and resource metadata that might be given in response header fields (<a href="#response.header.fields" title="Response Header Fields">Section 7</a>). |
| | 810 | </p> |
| | 811 | <p id="rfc.section.1.p.4"><span id="rfc.iref.c.1"></span> This document also defines representation metadata that describe how a payload is intended to be interpreted by a recipient, |
| | 812 | the request header fields that might influence content selection, and the various selection algorithms that are collectively |
| | 813 | referred to as "<dfn>content negotiation</dfn>" (<a href="#content.negotiation" title="Content Negotiation">Section 3.4</a>). |
| | 814 | </p> |
| | 815 | <div id="conformance"> |
| | 816 | <h2 id="rfc.section.1.1"><a href="#rfc.section.1.1">1.1</a> <a href="#conformance">Conformance and Error Handling</a></h2> |
| | 817 | <p id="rfc.section.1.1.p.1">The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" |
| | 818 | in this document are to be interpreted as described in <a href="#RFC2119" id="rfc.xref.RFC2119.1"><cite title="Key words for use in RFCs to Indicate Requirement Levels">[RFC2119]</cite></a>. |
| | 819 | </p> |
| | 820 | <p id="rfc.section.1.1.p.2">Conformance criteria and considerations regarding error handling are defined in <a href="p1-messaging.html#conformance" title="Conformance and Error Handling">Section 2.5</a> of <a href="#Part1" id="rfc.xref.Part1.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>. |
| | 821 | </p> |
| | 822 | </div> |
| | 823 | <div id="notation"> |
| | 824 | <h2 id="rfc.section.1.2"><a href="#rfc.section.1.2">1.2</a> <a href="#notation">Syntax Notation</a></h2> |
| | 825 | <p id="rfc.section.1.2.p.1">This specification uses the Augmented Backus-Naur Form (ABNF) notation of <a href="#RFC5234" id="rfc.xref.RFC5234.1"><cite title="Augmented BNF for Syntax Specifications: ABNF">[RFC5234]</cite></a> with the list rule extension defined in <a href="p1-messaging.html#abnf.extension" title="ABNF list extension: #rule">Section 7</a> of <a href="#Part1" id="rfc.xref.Part1.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>. <a href="#imported.abnf" title="Imported ABNF">Appendix C</a> describes rules imported from other documents. <a href="#collected.abnf" title="Collected ABNF">Appendix D</a> shows the collected ABNF with the list rule expanded. |
| | 826 | </p> |
| | 827 | <p id="rfc.section.1.2.p.2">This specification uses the terms "character", "character encoding scheme", "charset", and "protocol element" as they are |
| | 828 | defined in <a href="#RFC6365" id="rfc.xref.RFC6365.1"><cite title="Terminology Used in Internationalization in the IETF">[RFC6365]</cite></a>. |
| | 829 | </p> |
| | 830 | </div> |
| 912 | | </p> |
| 913 | | <div class="note" id="rfc.section.3.1.1.1.p.9"> |
| 914 | | <p><b>Note:</b> Unlike some similar constructs in other header fields, media type parameters do not allow whitespace (even "bad" whitespace) |
| 915 | | around the "=" character. |
| 916 | | </p> |
| | 927 | </p> |
| | 928 | <div class="note" id="rfc.section.3.1.1.1.p.9"> |
| | 929 | <p><b>Note:</b> Unlike some similar constructs in other header fields, media type parameters do not allow whitespace (even "bad" whitespace) |
| | 930 | around the "=" character. |
| | 931 | </p> |
| | 932 | </div> |
| | 933 | </div> |
| | 934 | <div id="charset"> |
| | 935 | <h4 id="rfc.section.3.1.1.2"><a href="#rfc.section.3.1.1.2">3.1.1.2</a> <a href="#charset">Charset</a></h4> |
| | 936 | <p id="rfc.section.3.1.1.2.p.1">HTTP uses <dfn>charset</dfn> names to indicate or negotiate the character encoding scheme of a textual representation <a href="#RFC6365" id="rfc.xref.RFC6365.2"><cite title="Terminology Used in Internationalization in the IETF">[RFC6365]</cite></a>. A charset is identified by a case-insensitive token. |
| | 937 | </p> |
| | 938 | <div id="rfc.figure.u.4"></div><pre class="inline"><span id="rfc.iref.g.7"></span> <a href="#charset" class="smpl">charset</a> = <a href="#imported.abnf" class="smpl">token</a> |
| | 939 | </pre><p id="rfc.section.3.1.1.2.p.3">Charset names ought to be registered in IANA Character Set registry (<<a href="http://www.iana.org/assignments/character-sets">http://www.iana.org/assignments/character-sets</a>>) according to the procedures defined in <a href="#RFC2978" id="rfc.xref.RFC2978.1"><cite title="IANA Charset Registration Procedures">[RFC2978]</cite></a>. |
| | 940 | </p> |
| | 941 | </div> |
| | 942 | <div id="canonicalization.and.text.defaults"> |
| | 943 | <h4 id="rfc.section.3.1.1.3"><a href="#rfc.section.3.1.1.3">3.1.1.3</a> <a href="#canonicalization.and.text.defaults">Canonicalization and Text Defaults</a></h4> |
| | 944 | <p id="rfc.section.3.1.1.3.p.1">Internet media types are registered with a canonical form in order to be interoperable among systems with varying native encoding |
| | 945 | formats. Representations selected or transferred via HTTP ought to be in canonical form, for many of the same reasons described |
| | 946 | by the Multipurpose Internet Mail Extensions (MIME) <a href="#RFC2045" id="rfc.xref.RFC2045.1"><cite title="Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies">[RFC2045]</cite></a>. However, the performance characteristics of email deployments (i.e., store and forward messages to peers) are significantly |
| | 947 | different from those common to HTTP and the Web (server-based information services). Furthermore, MIME's constraints for the |
| | 948 | sake of compatibility with older mail transfer protocols do not apply to HTTP (see <a href="#differences.between.http.and.mime" title="Differences between HTTP and MIME">Appendix A</a>). |
| | 949 | </p> |
| | 950 | <p id="rfc.section.3.1.1.3.p.2">MIME's canonical form requires that media subtypes of the "text" type use CRLF as the text line break. HTTP allows the transfer |
| | 951 | of text media with plain CR or LF alone representing a line break, when such line breaks are consistent for an entire representation. |
| | 952 | An HTTP sender <em class="bcp14">MAY</em> generate, and a recipient <em class="bcp14">MUST</em> be able to parse, line breaks in text media that consist of CRLF, bare CR, or bare LF. In addition, text media in HTTP is |
| | 953 | not limited to charsets that use octets 13 and 10 for CR and LF, respectively. This flexibility regarding line breaks applies |
| | 954 | only to text within a representation that has been assigned a "text" media type; it does not apply to "multipart" types or |
| | 955 | HTTP elements outside the payload body (e.g., header fields). |
| | 956 | </p> |
| | 957 | <p id="rfc.section.3.1.1.3.p.3">If a representation is encoded with a content-coding, the underlying data ought to be in a form defined above prior to being |
| | 958 | encoded. |
| | 959 | </p> |
| | 960 | </div> |
| | 961 | <div id="multipart.types"> |
| | 962 | <h4 id="rfc.section.3.1.1.4"><a href="#rfc.section.3.1.1.4">3.1.1.4</a> <a href="#multipart.types">Multipart Types</a></h4> |
| | 963 | <p id="rfc.section.3.1.1.4.p.1">MIME provides for a number of "multipart" types — encapsulations of one or more representations within a single message body. |
| | 964 | All multipart types share a common syntax, as defined in <a href="http://tools.ietf.org/html/rfc2046#section-5.1.1">Section 5.1.1</a> of <a href="#RFC2046" id="rfc.xref.RFC2046.2"><cite title="Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types">[RFC2046]</cite></a>, and include a boundary parameter as part of the media type value. The message body is itself a protocol element; a sender <em class="bcp14">MUST</em> generate only CRLF to represent line breaks between body parts. |
| | 965 | </p> |
| | 966 | <p id="rfc.section.3.1.1.4.p.2">HTTP message framing does not use the multipart boundary as an indicator of message body length, though it might be used by |
| | 967 | implementations that generate or process the payload. For example, the "multipart/form-data" type is often used for carrying |
| | 968 | form data in a request, as described in <a href="#RFC2388" id="rfc.xref.RFC2388.1"><cite title="Returning Values from Forms: multipart/form-data">[RFC2388]</cite></a>, and the "multipart/byteranges" type is defined by this specification for use in some <a href="p5-range.html#status.206" class="smpl">206 (Partial Content)</a> responses <a href="#Part5" id="rfc.xref.Part5.1"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a>. |
| | 969 | </p> |
| | 970 | </div> |
| | 971 | <div id="header.content-type"> |
| | 972 | <div id="rfc.iref.c.2"></div> |
| | 973 | <h4 id="rfc.section.3.1.1.5"><a href="#rfc.section.3.1.1.5">3.1.1.5</a> <a href="#header.content-type">Content-Type</a></h4> |
| | 974 | <p id="rfc.section.3.1.1.5.p.1">The "Content-Type" header field indicates the media type of the associated representation: either the representation enclosed |
| | 975 | in the message payload or the <a href="#representations" class="smpl">selected representation</a>, as determined by the message semantics. The indicated media type defines both the data format and how that data is intended |
| | 976 | to be processed by a recipient, within the scope of the received message semantics, after any content codings indicated by <a href="#header.content-encoding" class="smpl">Content-Encoding</a> are decoded. |
| | 977 | </p> |
| | 978 | <div id="rfc.figure.u.5"></div><pre class="inline"><span id="rfc.iref.g.8"></span> <a href="#header.content-type" class="smpl">Content-Type</a> = <a href="#media.type" class="smpl">media-type</a> |
| | 979 | </pre><p id="rfc.section.3.1.1.5.p.3">Media types are defined in <a href="#media.type" title="Media Type">Section 3.1.1.1</a>. An example of the field is |
| | 980 | </p> |
| | 981 | <div id="rfc.figure.u.6"></div><pre class="text"> Content-Type: text/html; charset=ISO-8859-4 |
| | 982 | </pre><p id="rfc.section.3.1.1.5.p.5">A sender that generates a message containing a payload body <em class="bcp14">SHOULD</em> generate a Content-Type header field in that message unless the intended media type of the enclosed representation is unknown |
| | 983 | to the sender. If a Content-Type header field is not present, the recipient <em class="bcp14">MAY</em> either assume a media type of "application/octet-stream" (<a href="#RFC2046" id="rfc.xref.RFC2046.3"><cite title="Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types">[RFC2046]</cite></a>, <a href="http://tools.ietf.org/html/rfc2046#section-4.5.1">Section 4.5.1</a>) or examine the data to determine its type. |
| | 984 | </p> |
| | 985 | <p id="rfc.section.3.1.1.5.p.6">In practice, resource owners do not always properly configure their origin server to provide the correct Content-Type for |
| | 986 | a given representation, with the result that some clients will examine a payload's content and override the specified type. |
| | 987 | Clients that do so risk drawing incorrect conclusions, which might expose additional security risks (e.g., "privilege escalation"). |
| | 988 | Furthermore, it is impossible to determine the sender's intent by examining the data format: many data formats match multiple |
| | 989 | media types that differ only in processing semantics. Implementers are encouraged to provide a means of disabling such "content |
| | 990 | sniffing" when it is used. |
| | 991 | </p> |
| | 992 | </div> |
| | 993 | </div> |
| | 994 | <div id="data.encoding"> |
| | 995 | <h3 id="rfc.section.3.1.2"><a href="#rfc.section.3.1.2">3.1.2</a> <a href="#data.encoding">Encoding for Compression or Integrity</a></h3> |
| | 996 | <div id="content.codings"> |
| | 997 | <div id="rfc.iref.c.3"></div> |
| | 998 | <div id="rfc.iref.c.4"></div> |
| | 999 | <div id="rfc.iref.x.1"></div> |
| | 1000 | <div id="rfc.iref.d.1"></div> |
| | 1001 | <div id="rfc.iref.g.9"></div> |
| | 1002 | <div id="rfc.iref.x.2"></div> |
| | 1003 | <h4 id="rfc.section.3.1.2.1"><a href="#rfc.section.3.1.2.1">3.1.2.1</a> <a href="#content.codings">Content Codings</a></h4> |
| | 1004 | <p id="rfc.section.3.1.2.1.p.1">Content coding values indicate an encoding transformation that has been or can be applied to a representation. Content codings |
| | 1005 | are primarily used to allow a representation to be compressed or otherwise usefully transformed without losing the identity |
| | 1006 | of its underlying media type and without loss of information. Frequently, the representation is stored in coded form, transmitted |
| | 1007 | directly, and only decoded by the final recipient. |
| | 1008 | </p> |
| | 1009 | <div id="rfc.figure.u.7"></div><pre class="inline"><span id="rfc.iref.g.10"></span> <a href="#content.codings" class="smpl">content-coding</a> = <a href="#imported.abnf" class="smpl">token</a> |
| | 1010 | </pre><p id="rfc.section.3.1.2.1.p.3">All content-coding values are case-insensitive and ought to be registered within the HTTP Content Coding registry, as defined |
| | 1011 | in <a href="#content.coding.registry" title="Content Coding Registry">Section 8.4</a>. They are used in the <a href="#header.accept-encoding" class="smpl">Accept-Encoding</a> (<a href="#header.accept-encoding" id="rfc.xref.header.accept-encoding.1" title="Accept-Encoding">Section 5.3.4</a>) and <a href="#header.content-encoding" class="smpl">Content-Encoding</a> (<a href="#header.content-encoding" id="rfc.xref.header.content-encoding.2" title="Content-Encoding">Section 3.1.2.2</a>) header fields. |
| | 1012 | </p> |
| | 1013 | <p id="rfc.section.3.1.2.1.p.4">The following content-coding values are defined by this specification: </p> |
| | 1014 | <ul class="empty"> |
| | 1015 | <li>compress (and x-compress): See <a href="p1-messaging.html#compress.coding" title="Compress Coding">Section 4.2.1</a> of <a href="#Part1" id="rfc.xref.Part1.7"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>. |
| | 1016 | </li> |
| | 1017 | <li>deflate: See <a href="p1-messaging.html#deflate.coding" title="Deflate Coding">Section 4.2.2</a> of <a href="#Part1" id="rfc.xref.Part1.8"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>. |
| | 1018 | </li> |
| | 1019 | <li>gzip (and x-gzip): See <a href="p1-messaging.html#gzip.coding" title="Gzip Coding">Section 4.2.3</a> of <a href="#Part1" id="rfc.xref.Part1.9"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>. |
| | 1020 | </li> |
| | 1021 | </ul> |
| | 1022 | </div> |
| | 1023 | <div id="header.content-encoding"> |
| | 1024 | <div id="rfc.iref.c.5"></div> |
| | 1025 | <h4 id="rfc.section.3.1.2.2"><a href="#rfc.section.3.1.2.2">3.1.2.2</a> <a href="#header.content-encoding">Content-Encoding</a></h4> |
| | 1026 | <p id="rfc.section.3.1.2.2.p.1">The "Content-Encoding" header field indicates what content codings have been applied to the representation, beyond those inherent |
| | 1027 | in the media type, and thus what decoding mechanisms have to be applied in order to obtain data in the media type referenced |
| | 1028 | by the <a href="#header.content-type" class="smpl">Content-Type</a> header field. Content-Encoding is primarily used to allow a representation's data to be compressed without losing the identity |
| | 1029 | of its underlying media type. |
| | 1030 | </p> |
| | 1031 | <div id="rfc.figure.u.8"></div><pre class="inline"><span id="rfc.iref.g.11"></span> <a href="#header.content-encoding" class="smpl">Content-Encoding</a> = 1#<a href="#content.codings" class="smpl">content-coding</a> |
| | 1032 | </pre><p id="rfc.section.3.1.2.2.p.3">An example of its use is</p> |
| | 1033 | <div id="rfc.figure.u.9"></div><pre class="text"> Content-Encoding: gzip |
| | 1034 | </pre><p id="rfc.section.3.1.2.2.p.5">If one or more encodings have been applied to a representation, the sender that applied the encodings <em class="bcp14">MUST</em> generate a Content-Encoding header field that lists the content codings in the order in which they were applied. Additional |
| | 1035 | information about the encoding parameters <em class="bcp14">MAY</em> be provided by other header fields not defined by this specification. |
| | 1036 | </p> |
| | 1037 | <p id="rfc.section.3.1.2.2.p.6">Unlike Transfer-Encoding (<a href="p1-messaging.html#header.transfer-encoding" title="Transfer-Encoding">Section 3.3.1</a> of <a href="#Part1" id="rfc.xref.Part1.10"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>), the codings listed in Content-Encoding are a characteristic of the representation; the representation is defined in terms |
| | 1038 | of the coded form, and all other metadata about the representation is about the coded form unless otherwise noted in the metadata |
| | 1039 | definition. Typically, the representation is only decoded just prior to rendering or analogous usage. |
| | 1040 | </p> |
| | 1041 | <p id="rfc.section.3.1.2.2.p.7">If the media type includes an inherent encoding, such as a data format that is always compressed, then that encoding would |
| | 1042 | not be restated in Content-Encoding even if it happens to be the same algorithm as one of the content codings. Such a content |
| | 1043 | coding would only be listed if, for some bizarre reason, it is applied a second time to form the representation. Likewise, |
| | 1044 | an origin server might choose to publish the same data as multiple representations that differ only in whether the coding |
| | 1045 | is defined as part of <a href="#header.content-type" class="smpl">Content-Type</a> or Content-Encoding, since some user agents will behave differently in their handling of each response (e.g., open a "Save |
| | 1046 | as ..." dialog instead of automatic decompression and rendering of content). |
| | 1047 | </p> |
| | 1048 | <p id="rfc.section.3.1.2.2.p.8">An origin server <em class="bcp14">MAY</em> respond with a status code of <a href="#status.415" class="smpl">415 (Unsupported Media Type)</a> if a representation in the request message has a content coding that is not acceptable. |
| | 1049 | </p> |
| | 1050 | </div> |
| | 1051 | </div> |
| | 1052 | <div id="audience.language"> |
| | 1053 | <h3 id="rfc.section.3.1.3"><a href="#rfc.section.3.1.3">3.1.3</a> <a href="#audience.language">Audience Language</a></h3> |
| | 1054 | <div id="language.tags"> |
| | 1055 | <h4 id="rfc.section.3.1.3.1"><a href="#rfc.section.3.1.3.1">3.1.3.1</a> <a href="#language.tags">Language Tags</a></h4> |
| | 1056 | <p id="rfc.section.3.1.3.1.p.1">A language tag, as defined in <a href="#RFC5646" id="rfc.xref.RFC5646.1"><cite title="Tags for Identifying Languages">[RFC5646]</cite></a>, identifies a natural language spoken, written, or otherwise conveyed by human beings for communication of information to |
| | 1057 | other human beings. Computer languages are explicitly excluded. |
| | 1058 | </p> |
| | 1059 | <p id="rfc.section.3.1.3.1.p.2">HTTP uses language tags within the <a href="#header.accept-language" class="smpl">Accept-Language</a> and <a href="#header.content-language" class="smpl">Content-Language</a> header fields. <a href="#header.accept-language" class="smpl">Accept-Language</a> uses the broader language-range production defined in <a href="#header.accept-language" id="rfc.xref.header.accept-language.1" title="Accept-Language">Section 5.3.5</a>, whereas <a href="#header.content-language" class="smpl">Content-Language</a> uses the language-tag production defined below. |
| | 1060 | </p> |
| | 1061 | <div id="rfc.figure.u.10"></div><pre class="inline"><span id="rfc.iref.g.12"></span> <a href="#language.tags" class="smpl">language-tag</a> = <Language-Tag, defined in <a href="#RFC5646" id="rfc.xref.RFC5646.2"><cite title="Tags for Identifying Languages">[RFC5646]</cite></a>, <a href="http://tools.ietf.org/html/rfc5646#section-2.1">Section 2.1</a>> |
| | 1062 | </pre><p id="rfc.section.3.1.3.1.p.4">A language tag is a sequence of one or more case-insensitive subtags, each separated by a hyphen character ("-", %x2D). In |
| | 1063 | most cases, a language tag consists of a primary language subtag that identifies a broad family of related languages (e.g., |
| | 1064 | "en" = English) which is optionally followed by a series of subtags that refine or narrow that language's range (e.g., "en-CA" |
| | 1065 | = the variety of English as communicated in Canada). Whitespace is not allowed within a language tag. Example tags include: |
| | 1066 | </p> |
| | 1067 | <div id="rfc.figure.u.11"></div><pre class="text"> fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN |
| | 1068 | </pre><p id="rfc.section.3.1.3.1.p.6">See <a href="#RFC5646" id="rfc.xref.RFC5646.3"><cite title="Tags for Identifying Languages">[RFC5646]</cite></a> for further information. |
| | 1069 | </p> |
| | 1070 | </div> |
| | 1071 | <div id="header.content-language"> |
| | 1072 | <div id="rfc.iref.c.6"></div> |
| | 1073 | <h4 id="rfc.section.3.1.3.2"><a href="#rfc.section.3.1.3.2">3.1.3.2</a> <a href="#header.content-language">Content-Language</a></h4> |
| | 1074 | <p id="rfc.section.3.1.3.2.p.1">The "Content-Language" header field describes the natural language(s) of the intended audience for the representation. Note |
| | 1075 | that this might not be equivalent to all the languages used within the representation. |
| | 1076 | </p> |
| | 1077 | <div id="rfc.figure.u.12"></div><pre class="inline"><span id="rfc.iref.g.13"></span> <a href="#header.content-language" class="smpl">Content-Language</a> = 1#<a href="#language.tags" class="smpl">language-tag</a> |
| | 1078 | </pre><p id="rfc.section.3.1.3.2.p.3">Language tags are defined in <a href="#language.tags" title="Language Tags">Section 3.1.3.1</a>. The primary purpose of Content-Language is to allow a user to identify and differentiate representations according to the |
| | 1079 | users' own preferred language. Thus, if the content is intended only for a Danish-literate audience, the appropriate field |
| | 1080 | is |
| | 1081 | </p> |
| | 1082 | <div id="rfc.figure.u.13"></div><pre class="text"> Content-Language: da |
| | 1083 | </pre><p id="rfc.section.3.1.3.2.p.5">If no Content-Language is specified, the default is that the content is intended for all language audiences. This might mean |
| | 1084 | that the sender does not consider it to be specific to any natural language, or that the sender does not know for which language |
| | 1085 | it is intended. |
| | 1086 | </p> |
| | 1087 | <p id="rfc.section.3.1.3.2.p.6">Multiple languages <em class="bcp14">MAY</em> be listed for content that is intended for multiple audiences. For example, a rendition of the "Treaty of Waitangi", presented |
| | 1088 | simultaneously in the original Maori and English versions, would call for |
| | 1089 | </p> |
| | 1090 | <div id="rfc.figure.u.14"></div><pre class="text"> Content-Language: mi, en |
| | 1091 | </pre><p id="rfc.section.3.1.3.2.p.8">However, just because multiple languages are present within a representation does not mean that it is intended for multiple |
| | 1092 | linguistic audiences. An example would be a beginner's language primer, such as "A First Lesson in Latin", which is clearly |
| | 1093 | intended to be used by an English-literate audience. In this case, the Content-Language would properly only include "en". |
| | 1094 | </p> |
| | 1095 | <p id="rfc.section.3.1.3.2.p.9">Content-Language <em class="bcp14">MAY</em> be applied to any media type — it is not limited to textual documents. |
| | 1096 | </p> |
| | 1097 | </div> |
| | 1098 | </div> |
| | 1099 | <div id="identification"> |
| | 1100 | <h3 id="rfc.section.3.1.4"><a href="#rfc.section.3.1.4">3.1.4</a> <a href="#identification">Identification</a></h3> |
| | 1101 | <div id="identifying.payload"> |
| | 1102 | <h4 id="rfc.section.3.1.4.1"><a href="#rfc.section.3.1.4.1">3.1.4.1</a> <a href="#identifying.payload">Identifying a Representation</a></h4> |
| | 1103 | <p id="rfc.section.3.1.4.1.p.1">When a complete or partial representation is transferred in a message payload, it is often desirable for the sender to supply, |
| | 1104 | or the recipient to determine, an identifier for a resource corresponding to that representation. |
| | 1105 | </p> |
| | 1106 | <p id="rfc.section.3.1.4.1.p.2">For a request message: </p> |
| | 1107 | <ul> |
| | 1108 | <li>If the request has a <a href="#header.content-location" class="smpl">Content-Location</a> header field, then the sender asserts that the payload is a representation of the resource identified by the Content-Location |
| | 1109 | field-value. However, such an assertion cannot be trusted unless it can be verified by other means (not defined by this specification). |
| | 1110 | The information might still be useful for revision history links. |
| | 1111 | </li> |
| | 1112 | <li>Otherwise, the payload is unidentified.</li> |
| | 1113 | </ul> |
| | 1114 | <p id="rfc.section.3.1.4.1.p.3">For a response message, the following rules are applied in order until a match is found: </p> |
| | 1115 | <ol> |
| | 1116 | <li>If the request is GET or HEAD and the response status code is <a href="#status.200" class="smpl">200 (OK)</a>, <a href="#status.204" class="smpl">204 (No Content)</a>, <a href="p5-range.html#status.206" class="smpl">206 (Partial Content)</a>, or <a href="p4-conditional.html#status.304" class="smpl">304 (Not Modified)</a>, the payload is a representation of the resource identified by the effective request URI (<a href="p1-messaging.html#effective.request.uri" title="Effective Request URI">Section 5.5</a> of <a href="#Part1" id="rfc.xref.Part1.11"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). |
| | 1117 | </li> |
| | 1118 | <li>If the request is GET or HEAD and the response status code is <a href="#status.203" class="smpl">203 (Non-Authoritative Information)</a>, the payload is a potentially modified or enhanced representation of the <a href="#resources" class="smpl">target resource</a> as provided by an intermediary. |
| | 1119 | </li> |
| | 1120 | <li>If the response has a <a href="#header.content-location" class="smpl">Content-Location</a> header field and its field-value is a reference to the same URI as the effective request URI, the payload is a representation |
| | 1121 | of the resource identified by the effective request URI. |
| | 1122 | </li> |
| | 1123 | <li>If the response has a <a href="#header.content-location" class="smpl">Content-Location</a> header field and its field-value is a reference to a URI different from the effective request URI, then the sender asserts |
| | 1124 | that the payload is a representation of the resource identified by the Content-Location field-value. However, such an assertion |
| | 1125 | cannot be trusted unless it can be verified by other means (not defined by this specification). |
| | 1126 | </li> |
| | 1127 | <li>Otherwise, the payload is unidentified.</li> |
| | 1128 | </ol> |
| | 1129 | </div> |
| | 1130 | <div id="header.content-location"> |
| | 1131 | <div id="rfc.iref.c.7"></div> |
| | 1132 | <h4 id="rfc.section.3.1.4.2"><a href="#rfc.section.3.1.4.2">3.1.4.2</a> <a href="#header.content-location">Content-Location</a></h4> |
| | 1133 | <p id="rfc.section.3.1.4.2.p.1">The "Content-Location" header field references a URI that can be used as an identifier for a specific resource corresponding |
| | 1134 | to the representation in this message's payload. In other words, if one were to perform a GET request on this URI at the time |
| | 1135 | of this message's generation, then a <a href="#status.200" class="smpl">200 (OK)</a> response would contain the same representation that is enclosed as payload in this message. |
| | 1136 | </p> |
| | 1137 | <div id="rfc.figure.u.15"></div><pre class="inline"><span id="rfc.iref.g.14"></span> <a href="#header.content-location" class="smpl">Content-Location</a> = <a href="#imported.abnf" class="smpl">absolute-URI</a> / <a href="#imported.abnf" class="smpl">partial-URI</a> |
| | 1138 | </pre><p id="rfc.section.3.1.4.2.p.3">The Content-Location value is not a replacement for the effective Request URI (<a href="p1-messaging.html#effective.request.uri" title="Effective Request URI">Section 5.5</a> of <a href="#Part1" id="rfc.xref.Part1.12"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). It is representation metadata. It has the same syntax and semantics as the header field of the same name defined for MIME |
| | 1139 | body parts in <a href="http://tools.ietf.org/html/rfc2557#section-4">Section 4</a> of <a href="#RFC2557" id="rfc.xref.RFC2557.1"><cite title="MIME Encapsulation of Aggregate Documents, such as HTML (MHTML)">[RFC2557]</cite></a>. However, its appearance in an HTTP message has some special implications for HTTP recipients. |
| | 1140 | </p> |
| | 1141 | <p id="rfc.section.3.1.4.2.p.4">If Content-Location is included in a <a href="#status.2xx" class="smpl">2xx (Successful)</a> response message and its value refers (after conversion to absolute form) to a URI that is the same as the effective request |
| | 1142 | URI, then the recipient <em class="bcp14">MAY</em> consider the payload to be a current representation of that resource at the time indicated by the message origination date. |
| | 1143 | For a GET or HEAD request, this is the same as the default semantics when no Content-Location is provided by the server. For |
| | 1144 | a state-changing request like PUT or POST, it implies that the server's response contains the new representation of that resource, |
| | 1145 | thereby distinguishing it from representations that might only report about the action (e.g., "It worked!"). This allows authoring |
| | 1146 | applications to update their local copies without the need for a subsequent GET request. |
| | 1147 | </p> |
| | 1148 | <p id="rfc.section.3.1.4.2.p.5">If Content-Location is included in a <a href="#status.2xx" class="smpl">2xx (Successful)</a> response message and its field-value refers to a URI that differs from the effective request URI, then the origin server claims |
| | 1149 | that the URI is an identifier for a different resource corresponding to the enclosed representation. Such a claim can only |
| | 1150 | be trusted if both identifiers share the same resource owner, which cannot be programmatically determined via HTTP. |
| | 1151 | </p> |
| | 1152 | <ul> |
| | 1153 | <li>For a response to a GET or HEAD request, this is an indication that the effective request URI refers to a resource that is |
| | 1154 | subject to content negotiation and the Content-Location field-value is a more specific identifier for the <a href="#representations" class="smpl">selected representation</a>. |
| | 1155 | </li> |
| | 1156 | <li>For a <a href="#status.201" class="smpl">201 (Created)</a> response to a state-changing method, a Content-Location field-value that is identical to the <a href="#header.location" class="smpl">Location</a> field-value indicates that this payload is a current representation of the newly created resource. |
| | 1157 | </li> |
| | 1158 | <li>Otherwise, such a Content-Location indicates that this payload is a representation reporting on the requested action's status |
| | 1159 | and that the same report is available (for future access with GET) at the given URI. For example, a purchase transaction made |
| | 1160 | via a POST request might include a receipt document as the payload of the <a href="#status.200" class="smpl">200 (OK)</a> response; the Content-Location field-value provides an identifier for retrieving a copy of that same receipt in the future. |
| | 1161 | </li> |
| | 1162 | </ul> |
| | 1163 | <p id="rfc.section.3.1.4.2.p.6">A user agent that sends Content-Location in a request message is stating that its value refers to where the user agent originally |
| | 1164 | obtained the content of the enclosed representation (prior to any modifications made by that user agent). In other words, |
| | 1165 | the user agent is providing a back link to the source of the original representation. |
| | 1166 | </p> |
| | 1167 | <p id="rfc.section.3.1.4.2.p.7">An origin server that receives a Content-Location field in a request message <em class="bcp14">MUST</em> treat the information as transitory request context rather than as metadata to be saved verbatim as part of the representation. |
| | 1168 | An origin server <em class="bcp14">MAY</em> use that context to guide in processing the request or to save it for other uses, such as within source links or versioning |
| | 1169 | metadata. However, an origin server <em class="bcp14">MUST NOT</em> use such context information to alter the request semantics. |
| | 1170 | </p> |
| | 1171 | <p id="rfc.section.3.1.4.2.p.8">For example, if a client makes a PUT request on a negotiated resource and the origin server accepts that PUT (without redirection), |
| | 1172 | then the new state of that resource is expected to be consistent with the one representation supplied in that PUT; the Content-Location |
| | 1173 | cannot be used as a form of reverse content selection identifier to update only one of the negotiated representations. If |
| | 1174 | the user agent had wanted the latter semantics, it would have applied the PUT directly to the Content-Location URI. |
| | 1175 | </p> |
| | 1176 | </div> |
| | 1177 | </div> |
| | 1178 | </div> |
| | 1179 | <div id="representation.data"> |
| | 1180 | <h2 id="rfc.section.3.2"><a href="#rfc.section.3.2">3.2</a> <a href="#representation.data">Representation Data</a></h2> |
| | 1181 | <p id="rfc.section.3.2.p.1">The representation data associated with an HTTP message is either provided as the payload body of the message or referred |
| | 1182 | to by the message semantics and the effective request URI. The representation data is in a format and encoding defined by |
| | 1183 | the representation metadata header fields. |
| | 1184 | </p> |
| | 1185 | <p id="rfc.section.3.2.p.2">The data type of the representation data is determined via the header fields <a href="#header.content-type" class="smpl">Content-Type</a> and <a href="#header.content-encoding" class="smpl">Content-Encoding</a>. These define a two-layer, ordered encoding model: |
| | 1186 | </p> |
| | 1187 | <div id="rfc.figure.u.16"></div><pre class="text"> representation-data := Content-Encoding( Content-Type( bits ) ) |
| | 1188 | </pre></div> |
| | 1189 | <div id="payload"> |
| | 1190 | <div id="rfc.iref.p.1"></div> |
| | 1191 | <h2 id="rfc.section.3.3"><a href="#rfc.section.3.3">3.3</a> <a href="#payload">Payload Semantics</a></h2> |
| | 1192 | <p id="rfc.section.3.3.p.1">Some HTTP messages transfer a complete or partial representation as the message "<dfn>payload</dfn>". In some cases, a payload might contain only the associated representation's header fields (e.g., responses to HEAD) or |
| | 1193 | only some part(s) of the representation data (e.g., the <a href="p5-range.html#status.206" class="smpl">206 (Partial Content)</a> status code). |
| | 1194 | </p> |
| | 1195 | <p id="rfc.section.3.3.p.2">The purpose of a payload in a request is defined by the method semantics. For example, a representation in the payload of |
| | 1196 | a PUT request (<a href="#PUT" id="rfc.xref.PUT.1" title="PUT">Section 4.3.4</a>) represents the desired state of the <a href="#resources" class="smpl">target resource</a> if the request is successfully applied, whereas a representation in the payload of a POST request (<a href="#POST" id="rfc.xref.POST.1" title="POST">Section 4.3.3</a>) represents an anonymous resource for providing data to be processed, such as the information that a user entered within |
| | 1197 | an HTML form. |
| | 1198 | </p> |
| | 1199 | <p id="rfc.section.3.3.p.3">In a response, the payload's purpose is defined by both the request method and the response status code. For example, the |
| | 1200 | payload of a <a href="#status.200" class="smpl">200 (OK)</a> response to GET (<a href="#GET" id="rfc.xref.GET.2" title="GET">Section 4.3.1</a>) represents the current state of the <a href="#resources" class="smpl">target resource</a>, as observed at the time of the message origination date (<a href="#header.date" id="rfc.xref.header.date.1" title="Date">Section 7.1.1.2</a>), whereas the payload of the same status code in a response to POST might represent either the processing result or the new |
| | 1201 | state of the target resource after applying the processing. Response messages with an error status code usually contain a |
| | 1202 | payload that represents the error condition, such that it describes the error state and what next steps are suggested for |
| | 1203 | resolving it. |
| | 1204 | </p> |
| | 1205 | <p id="rfc.section.3.3.p.4">Header fields that specifically describe the payload, rather than the associated representation, are referred to as "payload |
| | 1206 | header fields". Payload header fields are defined in other parts of this specification, due to their impact on message parsing. |
| | 1207 | </p> |
| | 1208 | <div id="rfc.table.u.2"> |
| | 1209 | <table class="tt full left" cellpadding="3" cellspacing="0"> |
| | 1210 | <thead> |
| | 1211 | <tr> |
| | 1212 | <th>Header Field Name</th> |
| | 1213 | <th>Defined in...</th> |
| | 1214 | </tr> |
| | 1215 | </thead> |
| | 1216 | <tbody> |
| | 1217 | <tr> |
| | 1218 | <td class="left">Content-Length</td> |
| | 1219 | <td class="left"><a href="p1-messaging.html#header.content-length" title="Content-Length">Section 3.3.2</a> of <a href="#Part1" id="rfc.xref.Part1.13"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a></td> |
| | 1220 | </tr> |
| | 1221 | <tr> |
| | 1222 | <td class="left">Content-Range</td> |
| | 1223 | <td class="left"><a href="p5-range.html#header.content-range" title="Content-Range">Section 4.2</a> of <a href="#Part5" id="rfc.xref.Part5.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a></td> |
| | 1224 | </tr> |
| | 1225 | <tr> |
| | 1226 | <td class="left">Transfer-Encoding</td> |
| | 1227 | <td class="left"><a href="p1-messaging.html#header.transfer-encoding" title="Transfer-Encoding">Section 3.3.1</a> of <a href="#Part1" id="rfc.xref.Part1.14"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a></td> |
| | 1228 | </tr> |
| | 1229 | </tbody> |
| | 1230 | </table> |
| | 1231 | </div> |
| | 1232 | </div> |
| | 1233 | <div id="content.negotiation"> |
| | 1234 | <h2 id="rfc.section.3.4"><a href="#rfc.section.3.4">3.4</a> <a href="#content.negotiation">Content Negotiation</a></h2> |
| | 1235 | <p id="rfc.section.3.4.p.1">When responses convey payload information, whether indicating a success or an error, the origin server often has different |
| | 1236 | ways of representing that information; for example, in different formats, languages, or encodings. Likewise, different users |
| | 1237 | or user agents might have differing capabilities, characteristics, or preferences that could influence which representation, |
| | 1238 | among those available, would be best to deliver. For this reason, HTTP provides mechanisms for <a href="#content.negotiation" class="smpl">content negotiation</a>. |
| | 1239 | </p> |
| | 1240 | <p id="rfc.section.3.4.p.2">This specification defines two patterns of content negotiation that can be made visible within the protocol: "proactive", |
| | 1241 | where the server selects the representation based upon the user agent's stated preferences, and "reactive" negotiation, where |
| | 1242 | the server provides a list of representations for the user agent to choose from. Other patterns of content negotiation include |
| | 1243 | "conditional content", where the representation consists of multiple parts that are selectively rendered based on user agent |
| | 1244 | parameters, "active content", where the representation contains a script that makes additional (more specific) requests based |
| | 1245 | on the user agent characteristics, and "Transparent Content Negotiation" (<a href="#RFC2295" id="rfc.xref.RFC2295.1"><cite title="Transparent Content Negotiation in HTTP">[RFC2295]</cite></a>), where content selection is performed by an intermediary. These patterns are not mutually exclusive, and each has trade-offs |
| | 1246 | in applicability and practicality. |
| | 1247 | </p> |
| | 1248 | <p id="rfc.section.3.4.p.3">Note that, in all cases, HTTP is not aware of the resource semantics. The consistency with which an origin server responds |
| | 1249 | to requests, over time and over the varying dimensions of content negotiation, and thus the "sameness" of a resource's observed |
| | 1250 | representations over time, is determined entirely by whatever entity or algorithm selects or generates those responses. HTTP |
| | 1251 | pays no attention to the man behind the curtain. |
| | 1252 | </p> |
| | 1253 | <div id="proactive.negotiation"> |
| | 1254 | <h3 id="rfc.section.3.4.1"><a href="#rfc.section.3.4.1">3.4.1</a> <a href="#proactive.negotiation">Proactive Negotiation</a></h3> |
| | 1255 | <p id="rfc.section.3.4.1.p.1">When content negotiation preferences are sent by the user agent in a request to encourage an algorithm located at the server |
| | 1256 | to select the preferred representation, it is called <dfn>proactive negotiation</dfn> (a.k.a., <dfn>server-driven negotiation</dfn>). Selection is based on the available representations for a response (the dimensions over which it might vary, such as language, |
| | 1257 | content-coding, etc.) compared to various information supplied in the request, including both the explicit negotiation fields |
| | 1258 | of <a href="#request.conneg" title="Content Negotiation">Section 5.3</a> and implicit characteristics, such as the client's network address or parts of the <a href="#header.user-agent" class="smpl">User-Agent</a> field. |
| | 1259 | </p> |
| | 1260 | <p id="rfc.section.3.4.1.p.2">Proactive negotiation is advantageous when the algorithm for selecting from among the available representations is difficult |
| | 1261 | to describe to a user agent, or when the server desires to send its "best guess" to the user agent along with the first response |
| | 1262 | (hoping to avoid the round-trip delay of a subsequent request if the "best guess" is good enough for the user). In order to |
| | 1263 | improve the server's guess, a user agent <em class="bcp14">MAY</em> send request header fields that describe its preferences. |
| | 1264 | </p> |
| | 1265 | <p id="rfc.section.3.4.1.p.3">Proactive negotiation has serious disadvantages: </p> |
| | 1266 | <ul> |
| | 1267 | <li>It is impossible for the server to accurately determine what might be "best" for any given user, since that would require |
| | 1268 | complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want |
| | 1269 | to view it on screen or print it on paper?); |
| | 1270 | </li> |
| | 1271 | <li>Having the user agent describe its capabilities in every request can be both very inefficient (given that only a small percentage |
| | 1272 | of responses have multiple representations) and a potential risk to the user's privacy; |
| | 1273 | </li> |
| | 1274 | <li>It complicates the implementation of an origin server and the algorithms for generating responses to a request; and,</li> |
| | 1275 | <li>It limits the reusability of responses for shared caching.</li> |
| | 1276 | </ul> |
| | 1277 | <p id="rfc.section.3.4.1.p.4">A user agent cannot rely on proactive negotiation preferences being consistently honored, since the origin server might not |
| | 1278 | implement proactive negotiation for the requested resource or might decide that sending a response that doesn't conform to |
| | 1279 | the user agent's preferences is better than sending a <a href="#status.406" class="smpl">406 (Not Acceptable)</a> response. |
| | 1280 | </p> |
| | 1281 | <p id="rfc.section.3.4.1.p.5">An origin server <em class="bcp14">MAY</em> generate a <a href="#header.vary" class="smpl">Vary</a> header field (<a href="#header.vary" id="rfc.xref.header.vary.1" title="Vary">Section 7.1.4</a>) in responses that are subject to proactive negotiation to indicate what parameters of request information might be used |
| | 1282 | in its selection algorithm, thereby providing a means for recipients to determine the reusability of that same response for |
| | 1283 | user agents with differing request information. |
| | 1284 | </p> |
| | 1285 | </div> |
| | 1286 | <div id="reactive.negotiation"> |
| | 1287 | <h3 id="rfc.section.3.4.2"><a href="#rfc.section.3.4.2">3.4.2</a> <a href="#reactive.negotiation">Reactive Negotiation</a></h3> |
| | 1288 | <p id="rfc.section.3.4.2.p.1">With <dfn>reactive negotiation</dfn> (a.k.a., <dfn>agent-driven negotiation</dfn>), selection of the best response representation (regardless of the status code) is performed by the user agent after receiving |
| | 1289 | an initial response from the origin server that contains a list of resources for alternative representations. If the user |
| | 1290 | agent is not satisfied by the initial response representation, it can perform a GET request on one or more of the alternative |
| | 1291 | resources, selected based on metadata included in the list, to obtain a different form of representation for that response. |
| | 1292 | Selection of alternatives might be performed automatically by the user agent or manually by the user selecting from a generated |
| | 1293 | (possibly hypertext) menu. |
| | 1294 | </p> |
| | 1295 | <p id="rfc.section.3.4.2.p.2">Note that the above refers to representations of the response, in general, not representations of the resource. The alternative |
| | 1296 | representations are only considered representations of the target resource if the response in which those alternatives are |
| | 1297 | provided has the semantics of being a representation of the target resource (e.g., a <a href="#status.200" class="smpl">200 (OK)</a> response to a GET request) or has the semantics of providing links to alternative representations for the target resource |
| | 1298 | (e.g., a <a href="#status.300" class="smpl">300 (Multiple Choices)</a> response to a GET request). |
| | 1299 | </p> |
| | 1300 | <p id="rfc.section.3.4.2.p.3">A server might choose not to send an initial representation, other than the list of alternatives, and thereby indicate that |
| | 1301 | reactive negotiation by the user agent is preferred. For example, the alternatives listed in responses with the <a href="#status.300" class="smpl">300 (Multiple Choices)</a> and <a href="#status.406" class="smpl">406 (Not Acceptable)</a> status codes include information about the available representations so that the user or user agent can react by making a |
| | 1302 | selection. |
| | 1303 | </p> |
| | 1304 | <p id="rfc.section.3.4.2.p.4">Reactive negotiation is advantageous when the response would vary over commonly-used dimensions (such as type, language, or |
| | 1305 | encoding), when the origin server is unable to determine a user agent's capabilities from examining the request, and generally |
| | 1306 | when public caches are used to distribute server load and reduce network usage. |
| | 1307 | </p> |
| | 1308 | <p id="rfc.section.3.4.2.p.5">Reactive negotiation suffers from the disadvantages of transmitting a list of alternatives to the user agent, which degrades |
| | 1309 | user-perceived latency if transmitted in the header section, and needing a second request to obtain an alternate representation. |
| | 1310 | Furthermore, this specification does not define a mechanism for supporting automatic selection, though it does not prevent |
| | 1311 | such a mechanism from being developed as an extension. |
| | 1312 | </p> |
| | 1313 | </div> |
| | 1314 | </div> |
| 918 | | <h4 id="rfc.section.3.1.1.2"><a href="#rfc.section.3.1.1.2">3.1.1.2</a> <a id="charset" href="#charset">Charset</a></h4> |
| 919 | | <p id="rfc.section.3.1.1.2.p.1">HTTP uses <dfn>charset</dfn> names to indicate or negotiate the character encoding scheme of a textual representation <a href="#RFC6365" id="rfc.xref.RFC6365.2"><cite title="Terminology Used in Internationalization in the IETF">[RFC6365]</cite></a>. A charset is identified by a case-insensitive token. |
| 920 | | </p> |
| 921 | | <div id="rfc.figure.u.4"></div><pre class="inline"><span id="rfc.iref.g.7"></span> <a href="#charset" class="smpl">charset</a> = <a href="#imported.abnf" class="smpl">token</a> |
| 922 | | </pre><p id="rfc.section.3.1.1.2.p.3">Charset names ought to be registered in IANA Character Set registry (<<a href="http://www.iana.org/assignments/character-sets">http://www.iana.org/assignments/character-sets</a>>) according to the procedures defined in <a href="#RFC2978" id="rfc.xref.RFC2978.1"><cite title="IANA Charset Registration Procedures">[RFC2978]</cite></a>. |
| 923 | | </p> |
| 924 | | <h4 id="rfc.section.3.1.1.3"><a href="#rfc.section.3.1.1.3">3.1.1.3</a> <a id="canonicalization.and.text.defaults" href="#canonicalization.and.text.defaults">Canonicalization and Text Defaults</a></h4> |
| 925 | | <p id="rfc.section.3.1.1.3.p.1">Internet media types are registered with a canonical form in order to be interoperable among systems with varying native encoding |
| 926 | | formats. Representations selected or transferred via HTTP ought to be in canonical form, for many of the same reasons described |
| 927 | | by the Multipurpose Internet Mail Extensions (MIME) <a href="#RFC2045" id="rfc.xref.RFC2045.1"><cite title="Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies">[RFC2045]</cite></a>. However, the performance characteristics of email deployments (i.e., store and forward messages to peers) are significantly |
| 928 | | different from those common to HTTP and the Web (server-based information services). Furthermore, MIME's constraints for the |
| 929 | | sake of compatibility with older mail transfer protocols do not apply to HTTP (see <a href="#differences.between.http.and.mime" title="Differences between HTTP and MIME">Appendix A</a>). |
| 930 | | </p> |
| 931 | | <p id="rfc.section.3.1.1.3.p.2">MIME's canonical form requires that media subtypes of the "text" type use CRLF as the text line break. HTTP allows the transfer |
| 932 | | of text media with plain CR or LF alone representing a line break, when such line breaks are consistent for an entire representation. |
| 933 | | An HTTP sender <em class="bcp14">MAY</em> generate, and a recipient <em class="bcp14">MUST</em> be able to parse, line breaks in text media that consist of CRLF, bare CR, or bare LF. In addition, text media in HTTP is |
| 934 | | not limited to charsets that use octets 13 and 10 for CR and LF, respectively. This flexibility regarding line breaks applies |
| 935 | | only to text within a representation that has been assigned a "text" media type; it does not apply to "multipart" types or |
| 936 | | HTTP elements outside the payload body (e.g., header fields). |
| 937 | | </p> |
| 938 | | <p id="rfc.section.3.1.1.3.p.3">If a representation is encoded with a content-coding, the underlying data ought to be in a form defined above prior to being |
| 939 | | encoded. |
| 940 | | </p> |
| 941 | | <h4 id="rfc.section.3.1.1.4"><a href="#rfc.section.3.1.1.4">3.1.1.4</a> <a id="multipart.types" href="#multipart.types">Multipart Types</a></h4> |
| 942 | | <p id="rfc.section.3.1.1.4.p.1">MIME provides for a number of "multipart" types — encapsulations of one or more representations within a single message body. |
| 943 | | All multipart types share a common syntax, as defined in <a href="http://tools.ietf.org/html/rfc2046#section-5.1.1">Section 5.1.1</a> of <a href="#RFC2046" id="rfc.xref.RFC2046.2"><cite title="Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types">[RFC2046]</cite></a>, and include a boundary parameter as part of the media type value. The message body is itself a protocol element; a sender <em class="bcp14">MUST</em> generate only CRLF to represent line breaks between body parts. |
| 944 | | </p> |
| 945 | | <p id="rfc.section.3.1.1.4.p.2">HTTP message framing does not use the multipart boundary as an indicator of message body length, though it might be used by |
| 946 | | implementations that generate or process the payload. For example, the "multipart/form-data" type is often used for carrying |
| 947 | | form data in a request, as described in <a href="#RFC2388" id="rfc.xref.RFC2388.1"><cite title="Returning Values from Forms: multipart/form-data">[RFC2388]</cite></a>, and the "multipart/byteranges" type is defined by this specification for use in some <a href="p5-range.html#status.206" class="smpl">206 (Partial Content)</a> responses <a href="#Part5" id="rfc.xref.Part5.1"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a>. |
| 948 | | </p> |
| 949 | | <div id="rfc.iref.c.2"></div> |
| 950 | | <h4 id="rfc.section.3.1.1.5"><a href="#rfc.section.3.1.1.5">3.1.1.5</a> <a id="header.content-type" href="#header.content-type">Content-Type</a></h4> |
| 951 | | <p id="rfc.section.3.1.1.5.p.1">The "Content-Type" header field indicates the media type of the associated representation: either the representation enclosed |
| 952 | | in the message payload or the <a href="#representations" class="smpl">selected representation</a>, as determined by the message semantics. The indicated media type defines both the data format and how that data is intended |
| 953 | | to be processed by a recipient, within the scope of the received message semantics, after any content codings indicated by <a href="#header.content-encoding" class="smpl">Content-Encoding</a> are decoded. |
| 954 | | </p> |
| 955 | | <div id="rfc.figure.u.5"></div><pre class="inline"><span id="rfc.iref.g.8"></span> <a href="#header.content-type" class="smpl">Content-Type</a> = <a href="#media.type" class="smpl">media-type</a> |
| 956 | | </pre><p id="rfc.section.3.1.1.5.p.3">Media types are defined in <a href="#media.type" title="Media Type">Section 3.1.1.1</a>. An example of the field is |
| 957 | | </p> |
| 958 | | <div id="rfc.figure.u.6"></div><pre class="text"> Content-Type: text/html; charset=ISO-8859-4 |
| 959 | | </pre><p id="rfc.section.3.1.1.5.p.5">A sender that generates a message containing a payload body <em class="bcp14">SHOULD</em> generate a Content-Type header field in that message unless the intended media type of the enclosed representation is unknown |
| 960 | | to the sender. If a Content-Type header field is not present, the recipient <em class="bcp14">MAY</em> either assume a media type of "application/octet-stream" (<a href="#RFC2046" id="rfc.xref.RFC2046.3"><cite title="Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types">[RFC2046]</cite></a>, <a href="http://tools.ietf.org/html/rfc2046#section-4.5.1">Section 4.5.1</a>) or examine the data to determine its type. |
| 961 | | </p> |
| 962 | | <p id="rfc.section.3.1.1.5.p.6">In practice, resource owners do not always properly configure their origin server to provide the correct Content-Type for |
| 963 | | a given representation, with the result that some clients will examine a payload's content and override the specified type. |
| 964 | | Clients that do so risk drawing incorrect conclusions, which might expose additional security risks (e.g., "privilege escalation"). |
| 965 | | Furthermore, it is impossible to determine the sender's intent by examining the data format: many data formats match multiple |
| 966 | | media types that differ only in processing semantics. Implementers are encouraged to provide a means of disabling such "content |
| 967 | | sniffing" when it is used. |
| 968 | | </p> |
| 969 | | <h3 id="rfc.section.3.1.2"><a href="#rfc.section.3.1.2">3.1.2</a> <a id="data.encoding" href="#data.encoding">Encoding for Compression or Integrity</a></h3> |
| 970 | | <div id="rfc.iref.c.3"></div> |
| 971 | | <div id="rfc.iref.c.4"></div> |
| 972 | | <div id="rfc.iref.x.1"></div> |
| 973 | | <div id="rfc.iref.d.1"></div> |
| 974 | | <div id="rfc.iref.g.9"></div> |
| 975 | | <div id="rfc.iref.x.2"></div> |
| 976 | | <h4 id="rfc.section.3.1.2.1"><a href="#rfc.section.3.1.2.1">3.1.2.1</a> <a id="content.codings" href="#content.codings">Content Codings</a></h4> |
| 977 | | <p id="rfc.section.3.1.2.1.p.1">Content coding values indicate an encoding transformation that has been or can be applied to a representation. Content codings |
| 978 | | are primarily used to allow a representation to be compressed or otherwise usefully transformed without losing the identity |
| 979 | | of its underlying media type and without loss of information. Frequently, the representation is stored in coded form, transmitted |
| 980 | | directly, and only decoded by the final recipient. |
| 981 | | </p> |
| 982 | | <div id="rfc.figure.u.7"></div><pre class="inline"><span id="rfc.iref.g.10"></span> <a href="#content.codings" class="smpl">content-coding</a> = <a href="#imported.abnf" class="smpl">token</a> |
| 983 | | </pre><p id="rfc.section.3.1.2.1.p.3">All content-coding values are case-insensitive and ought to be registered within the HTTP Content Coding registry, as defined |
| 984 | | in <a href="#content.coding.registry" title="Content Coding Registry">Section 8.4</a>. They are used in the <a href="#header.accept-encoding" class="smpl">Accept-Encoding</a> (<a href="#header.accept-encoding" id="rfc.xref.header.accept-encoding.1" title="Accept-Encoding">Section 5.3.4</a>) and <a href="#header.content-encoding" class="smpl">Content-Encoding</a> (<a href="#header.content-encoding" id="rfc.xref.header.content-encoding.2" title="Content-Encoding">Section 3.1.2.2</a>) header fields. |
| 985 | | </p> |
| 986 | | <p id="rfc.section.3.1.2.1.p.4">The following content-coding values are defined by this specification: </p> |
| 987 | | <ul class="empty"> |
| 988 | | <li>compress (and x-compress): See <a href="p1-messaging.html#compress.coding" title="Compress Coding">Section 4.2.1</a> of <a href="#Part1" id="rfc.xref.Part1.7"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>. |
| 989 | | </li> |
| 990 | | <li>deflate: See <a href="p1-messaging.html#deflate.coding" title="Deflate Coding">Section 4.2.2</a> of <a href="#Part1" id="rfc.xref.Part1.8"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>. |
| 991 | | </li> |
| 992 | | <li>gzip (and x-gzip): See <a href="p1-messaging.html#gzip.coding" title="Gzip Coding">Section 4.2.3</a> of <a href="#Part1" id="rfc.xref.Part1.9"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>. |
| 993 | | </li> |
| 994 | | </ul> |
| 995 | | <div id="rfc.iref.c.5"></div> |
| 996 | | <h4 id="rfc.section.3.1.2.2"><a href="#rfc.section.3.1.2.2">3.1.2.2</a> <a id="header.content-encoding" href="#header.content-encoding">Content-Encoding</a></h4> |
| 997 | | <p id="rfc.section.3.1.2.2.p.1">The "Content-Encoding" header field indicates what content codings have been applied to the representation, beyond those inherent |
| 998 | | in the media type, and thus what decoding mechanisms have to be applied in order to obtain data in the media type referenced |
| 999 | | by the <a href="#header.content-type" class="smpl">Content-Type</a> header field. Content-Encoding is primarily used to allow a representation's data to be compressed without losing the identity |
| 1000 | | of its underlying media type. |
| 1001 | | </p> |
| 1002 | | <div id="rfc.figure.u.8"></div><pre class="inline"><span id="rfc.iref.g.11"></span> <a href="#header.content-encoding" class="smpl">Content-Encoding</a> = 1#<a href="#content.codings" class="smpl">content-coding</a> |
| 1003 | | </pre><p id="rfc.section.3.1.2.2.p.3">An example of its use is</p> |
| 1004 | | <div id="rfc.figure.u.9"></div><pre class="text"> Content-Encoding: gzip |
| 1005 | | </pre><p id="rfc.section.3.1.2.2.p.5">If one or more encodings have been applied to a representation, the sender that applied the encodings <em class="bcp14">MUST</em> generate a Content-Encoding header field that lists the content codings in the order in which they were applied. Additional |
| 1006 | | information about the encoding parameters <em class="bcp14">MAY</em> be provided by other header fields not defined by this specification. |
| 1007 | | </p> |
| 1008 | | <p id="rfc.section.3.1.2.2.p.6">Unlike Transfer-Encoding (<a href="p1-messaging.html#header.transfer-encoding" title="Transfer-Encoding">Section 3.3.1</a> of <a href="#Part1" id="rfc.xref.Part1.10"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>), the codings listed in Content-Encoding are a characteristic of the representation; the representation is defined in terms |
| 1009 | | of the coded form, and all other metadata about the representation is about the coded form unless otherwise noted in the metadata |
| 1010 | | definition. Typically, the representation is only decoded just prior to rendering or analogous usage. |
| 1011 | | </p> |
| 1012 | | <p id="rfc.section.3.1.2.2.p.7">If the media type includes an inherent encoding, such as a data format that is always compressed, then that encoding would |
| 1013 | | not be restated in Content-Encoding even if it happens to be the same algorithm as one of the content codings. Such a content |
| 1014 | | coding would only be listed if, for some bizarre reason, it is applied a second time to form the representation. Likewise, |
| 1015 | | an origin server might choose to publish the same data as multiple representations that differ only in whether the coding |
| 1016 | | is defined as part of <a href="#header.content-type" class="smpl">Content-Type</a> or Content-Encoding, since some user agents will behave differently in their handling of each response (e.g., open a "Save |
| 1017 | | as ..." dialog instead of automatic decompression and rendering of content). |
| 1018 | | </p> |
| 1019 | | <p id="rfc.section.3.1.2.2.p.8">An origin server <em class="bcp14">MAY</em> respond with a status code of <a href="#status.415" class="smpl">415 (Unsupported Media Type)</a> if a representation in the request message has a content coding that is not acceptable. |
| 1020 | | </p> |
| 1021 | | <h3 id="rfc.section.3.1.3"><a href="#rfc.section.3.1.3">3.1.3</a> <a id="audience.language" href="#audience.language">Audience Language</a></h3> |
| 1022 | | <h4 id="rfc.section.3.1.3.1"><a href="#rfc.section.3.1.3.1">3.1.3.1</a> <a id="language.tags" href="#language.tags">Language Tags</a></h4> |
| 1023 | | <p id="rfc.section.3.1.3.1.p.1">A language tag, as defined in <a href="#RFC5646" id="rfc.xref.RFC5646.1"><cite title="Tags for Identifying Languages">[RFC5646]</cite></a>, identifies a natural language spoken, written, or otherwise conveyed by human beings for communication of information to |
| 1024 | | other human beings. Computer languages are explicitly excluded. |
| 1025 | | </p> |
| 1026 | | <p id="rfc.section.3.1.3.1.p.2">HTTP uses language tags within the <a href="#header.accept-language" class="smpl">Accept-Language</a> and <a href="#header.content-language" class="smpl">Content-Language</a> header fields. <a href="#header.accept-language" class="smpl">Accept-Language</a> uses the broader language-range production defined in <a href="#header.accept-language" id="rfc.xref.header.accept-language.1" title="Accept-Language">Section 5.3.5</a>, whereas <a href="#header.content-language" class="smpl">Content-Language</a> uses the language-tag production defined below. |
| 1027 | | </p> |
| 1028 | | <div id="rfc.figure.u.10"></div><pre class="inline"><span id="rfc.iref.g.12"></span> <a href="#language.tags" class="smpl">language-tag</a> = <Language-Tag, defined in <a href="#RFC5646" id="rfc.xref.RFC5646.2"><cite title="Tags for Identifying Languages">[RFC5646]</cite></a>, <a href="http://tools.ietf.org/html/rfc5646#section-2.1">Section 2.1</a>> |
| 1029 | | </pre><p id="rfc.section.3.1.3.1.p.4">A language tag is a sequence of one or more case-insensitive subtags, each separated by a hyphen character ("-", %x2D). In |
| 1030 | | most cases, a language tag consists of a primary language subtag that identifies a broad family of related languages (e.g., |
| 1031 | | "en" = English) which is optionally followed by a series of subtags that refine or narrow that language's range (e.g., "en-CA" |
| 1032 | | = the variety of English as communicated in Canada). Whitespace is not allowed within a language tag. Example tags include: |
| 1033 | | </p> |
| 1034 | | <div id="rfc.figure.u.11"></div><pre class="text"> fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN |
| 1035 | | </pre><p id="rfc.section.3.1.3.1.p.6">See <a href="#RFC5646" id="rfc.xref.RFC5646.3"><cite title="Tags for Identifying Languages">[RFC5646]</cite></a> for further information. |
| 1036 | | </p> |
| 1037 | | <div id="rfc.iref.c.6"></div> |
| 1038 | | <h4 id="rfc.section.3.1.3.2"><a href="#rfc.section.3.1.3.2">3.1.3.2</a> <a id="header.content-language" href="#header.content-language">Content-Language</a></h4> |
| 1039 | | <p id="rfc.section.3.1.3.2.p.1">The "Content-Language" header field describes the natural language(s) of the intended audience for the representation. Note |
| 1040 | | that this might not be equivalent to all the languages used within the representation. |
| 1041 | | </p> |
| 1042 | | <div id="rfc.figure.u.12"></div><pre class="inline"><span id="rfc.iref.g.13"></span> <a href="#header.content-language" class="smpl">Content-Language</a> = 1#<a href="#language.tags" class="smpl">language-tag</a> |
| 1043 | | </pre><p id="rfc.section.3.1.3.2.p.3">Language tags are defined in <a href="#language.tags" title="Language Tags">Section 3.1.3.1</a>. The primary purpose of Content-Language is to allow a user to identify and differentiate representations according to the |
| 1044 | | users' own preferred language. Thus, if the content is intended only for a Danish-literate audience, the appropriate field |
| 1045 | | is |
| 1046 | | </p> |
| 1047 | | <div id="rfc.figure.u.13"></div><pre class="text"> Content-Language: da |
| 1048 | | </pre><p id="rfc.section.3.1.3.2.p.5">If no Content-Language is specified, the default is that the content is intended for all language audiences. This might mean |
| 1049 | | that the sender does not consider it to be specific to any natural language, or that the sender does not know for which language |
| 1050 | | it is intended. |
| 1051 | | </p> |
| 1052 | | <p id="rfc.section.3.1.3.2.p.6">Multiple languages <em class="bcp14">MAY</em> be listed for content that is intended for multiple audiences. For example, a rendition of the "Treaty of Waitangi", presented |
| 1053 | | simultaneously in the original Maori and English versions, would call for |
| 1054 | | </p> |
| 1055 | | <div id="rfc.figure.u.14"></div><pre class="text"> Content-Language: mi, en |
| 1056 | | </pre><p id="rfc.section.3.1.3.2.p.8">However, just because multiple languages are present within a representation does not mean that it is intended for multiple |
| 1057 | | linguistic audiences. An example would be a beginner's language primer, such as "A First Lesson in Latin", which is clearly |
| 1058 | | intended to be used by an English-literate audience. In this case, the Content-Language would properly only include "en". |
| 1059 | | </p> |
| 1060 | | <p id="rfc.section.3.1.3.2.p.9">Content-Language <em class="bcp14">MAY</em> be applied to any media type — it is not limited to textual documents. |
| 1061 | | </p> |
| 1062 | | <h3 id="rfc.section.3.1.4"><a href="#rfc.section.3.1.4">3.1.4</a> <a id="identification" href="#identification">Identification</a></h3> |
| 1063 | | <h4 id="rfc.section.3.1.4.1"><a href="#rfc.section.3.1.4.1">3.1.4.1</a> <a id="identifying.payload" href="#identifying.payload">Identifying a Representation</a></h4> |
| 1064 | | <p id="rfc.section.3.1.4.1.p.1">When a complete or partial representation is transferred in a message payload, it is often desirable for the sender to supply, |
| 1065 | | or the recipient to determine, an identifier for a resource corresponding to that representation. |
| 1066 | | </p> |
| 1067 | | <p id="rfc.section.3.1.4.1.p.2">For a request message: </p> |
| 1068 | | <ul> |
| 1069 | | <li>If the request has a <a href="#header.content-location" class="smpl">Content-Location</a> header field, then the sender asserts that the payload is a representation of the resource identified by the Content-Location |
| 1070 | | field-value. However, such an assertion cannot be trusted unless it can be verified by other means (not defined by this specification). |
| 1071 | | The information might still be useful for revision history links. |
| 1072 | | </li> |
| 1073 | | <li>Otherwise, the payload is unidentified.</li> |
| 1074 | | </ul> |
| 1075 | | <p id="rfc.section.3.1.4.1.p.3">For a response message, the following rules are applied in order until a match is found: </p> |
| 1076 | | <ol> |
| 1077 | | <li>If the request is GET or HEAD and the response status code is <a href="#status.200" class="smpl">200 (OK)</a>, <a href="#status.204" class="smpl">204 (No Content)</a>, <a href="p5-range.html#status.206" class="smpl">206 (Partial Content)</a>, or <a href="p4-conditional.html#status.304" class="smpl">304 (Not Modified)</a>, the payload is a representation of the resource identified by the effective request URI (<a href="p1-messaging.html#effective.request.uri" title="Effective Request URI">Section 5.5</a> of <a href="#Part1" id="rfc.xref.Part1.11"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). |
| 1078 | | </li> |
| 1079 | | <li>If the request is GET or HEAD and the response status code is <a href="#status.203" class="smpl">203 (Non-Authoritative Information)</a>, the payload is a potentially modified or enhanced representation of the <a href="#resources" class="smpl">target resource</a> as provided by an intermediary. |
| 1080 | | </li> |
| 1081 | | <li>If the response has a <a href="#header.content-location" class="smpl">Content-Location</a> header field and its field-value is a reference to the same URI as the effective request URI, the payload is a representation |
| 1082 | | of the resource identified by the effective request URI. |
| 1083 | | </li> |
| 1084 | | <li>If the response has a <a href="#header.content-location" class="smpl">Content-Location</a> header field and its field-value is a reference to a URI different from the effective request URI, then the sender asserts |
| 1085 | | that the payload is a representation of the resource identified by the Content-Location field-value. However, such an assertion |
| 1086 | | cannot be trusted unless it can be verified by other means (not defined by this specification). |
| 1087 | | </li> |
| 1088 | | <li>Otherwise, the payload is unidentified.</li> |
| 1089 | | </ol> |
| 1090 | | <div id="rfc.iref.c.7"></div> |
| 1091 | | <h4 id="rfc.section.3.1.4.2"><a href="#rfc.section.3.1.4.2">3.1.4.2</a> <a id="header.content-location" href="#header.content-location">Content-Location</a></h4> |
| 1092 | | <p id="rfc.section.3.1.4.2.p.1">The "Content-Location" header field references a URI that can be used as an identifier for a specific resource corresponding |
| 1093 | | to the representation in this message's payload. In other words, if one were to perform a GET request on this URI at the time |
| 1094 | | of this message's generation, then a <a href="#status.200" class="smpl">200 (OK)</a> response would contain the same representation that is enclosed as payload in this message. |
| 1095 | | </p> |
| 1096 | | <div id="rfc.figure.u.15"></div><pre class="inline"><span id="rfc.iref.g.14"></span> <a href="#header.content-location" class="smpl">Content-Location</a> = <a href="#imported.abnf" class="smpl">absolute-URI</a> / <a href="#imported.abnf" class="smpl">partial-URI</a> |
| 1097 | | </pre><p id="rfc.section.3.1.4.2.p.3">The Content-Location value is not a replacement for the effective Request URI (<a href="p1-messaging.html#effective.request.uri" title="Effective Request URI">Section 5.5</a> of <a href="#Part1" id="rfc.xref.Part1.12"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). It is representation metadata. It has the same syntax and semantics as the header field of the same name defined for MIME |
| 1098 | | body parts in <a href="http://tools.ietf.org/html/rfc2557#section-4">Section 4</a> of <a href="#RFC2557" id="rfc.xref.RFC2557.1"><cite title="MIME Encapsulation of Aggregate Documents, such as HTML (MHTML)">[RFC2557]</cite></a>. However, its appearance in an HTTP message has some special implications for HTTP recipients. |
| 1099 | | </p> |
| 1100 | | <p id="rfc.section.3.1.4.2.p.4">If Content-Location is included in a <a href="#status.2xx" class="smpl">2xx (Successful)</a> response message and its value refers (after conversion to absolute form) to a URI that is the same as the effective request |
| 1101 | | URI, then the recipient <em class="bcp14">MAY</em> consider the payload to be a current representation of that resource at the time indicated by the message origination date. |
| 1102 | | For a GET or HEAD request, this is the same as the default semantics when no Content-Location is provided by the server. For |
| 1103 | | a state-changing request like PUT or POST, it implies that the server's response contains the new representation of that resource, |
| 1104 | | thereby distinguishing it from representations that might only report about the action (e.g., "It worked!"). This allows authoring |
| 1105 | | applications to update their local copies without the need for a subsequent GET request. |
| 1106 | | </p> |
| 1107 | | <p id="rfc.section.3.1.4.2.p.5">If Content-Location is included in a <a href="#status.2xx" class="smpl">2xx (Successful)</a> response message and its field-value refers to a URI that differs from the effective request URI, then the origin server claims |
| 1108 | | that the URI is an identifier for a different resource corresponding to the enclosed representation. Such a claim can only |
| 1109 | | be trusted if both identifiers share the same resource owner, which cannot be programmatically determined via HTTP. |
| 1110 | | </p> |
| 1111 | | <ul> |
| 1112 | | <li>For a response to a GET or HEAD request, this is an indication that the effective request URI refers to a resource that is |
| 1113 | | subject to content negotiation and the Content-Location field-value is a more specific identifier for the <a href="#representations" class="smpl">selected representation</a>. |
| 1114 | | </li> |
| 1115 | | <li>For a <a href="#status.201" class="smpl">201 (Created)</a> response to a state-changing method, a Content-Location field-value that is identical to the <a href="#header.location" class="smpl">Location</a> field-value indicates that this payload is a current representation of the newly created resource. |
| 1116 | | </li> |
| 1117 | | <li>Otherwise, such a Content-Location indicates that this payload is a representation reporting on the requested action's status |
| 1118 | | and that the same report is available (for future access with GET) at the given URI. For example, a purchase transaction made |
| 1119 | | via a POST request might include a receipt document as the payload of the <a href="#status.200" class="smpl">200 (OK)</a> response; the Content-Location field-value provides an identifier for retrieving a copy of that same receipt in the future. |
| 1120 | | </li> |
| 1121 | | </ul> |
| 1122 | | <p id="rfc.section.3.1.4.2.p.6">A user agent that sends Content-Location in a request message is stating that its value refers to where the user agent originally |
| 1123 | | obtained the content of the enclosed representation (prior to any modifications made by that user agent). In other words, |
| 1124 | | the user agent is providing a back link to the source of the original representation. |
| 1125 | | </p> |
| 1126 | | <p id="rfc.section.3.1.4.2.p.7">An origin server that receives a Content-Location field in a request message <em class="bcp14">MUST</em> treat the information as transitory request context rather than as metadata to be saved verbatim as part of the representation. |
| 1127 | | An origin server <em class="bcp14">MAY</em> use that context to guide in processing the request or to save it for other uses, such as within source links or versioning |
| 1128 | | metadata. However, an origin server <em class="bcp14">MUST NOT</em> use such context information to alter the request semantics. |
| 1129 | | </p> |
| 1130 | | <p id="rfc.section.3.1.4.2.p.8">For example, if a client makes a PUT request on a negotiated resource and the origin server accepts that PUT (without redirection), |
| 1131 | | then the new state of that resource is expected to be consistent with the one representation supplied in that PUT; the Content-Location |
| 1132 | | cannot be used as a form of reverse content selection identifier to update only one of the negotiated representations. If |
| 1133 | | the user agent had wanted the latter semantics, it would have applied the PUT directly to the Content-Location URI. |
| 1134 | | </p> |
| 1135 | | <h2 id="rfc.section.3.2"><a href="#rfc.section.3.2">3.2</a> <a id="representation.data" href="#representation.data">Representation Data</a></h2> |
| 1136 | | <p id="rfc.section.3.2.p.1">The representation data associated with an HTTP message is either provided as the payload body of the message or referred |
| 1137 | | to by the message semantics and the effective request URI. The representation data is in a format and encoding defined by |
| 1138 | | the representation metadata header fields. |
| 1139 | | </p> |
| 1140 | | <p id="rfc.section.3.2.p.2">The data type of the representation data is determined via the header fields <a href="#header.content-type" class="smpl">Content-Type</a> and <a href="#header.content-encoding" class="smpl">Content-Encoding</a>. These define a two-layer, ordered encoding model: |
| 1141 | | </p> |
| 1142 | | <div id="rfc.figure.u.16"></div><pre class="text"> representation-data := Content-Encoding( Content-Type( bits ) ) |
| 1143 | | </pre><div id="rfc.iref.p.1"></div> |
| 1144 | | <h2 id="rfc.section.3.3"><a href="#rfc.section.3.3">3.3</a> <a id="payload" href="#payload">Payload Semantics</a></h2> |
| 1145 | | <p id="rfc.section.3.3.p.1">Some HTTP messages transfer a complete or partial representation as the message "<dfn>payload</dfn>". In some cases, a payload might contain only the associated representation's header fields (e.g., responses to HEAD) or |
| 1146 | | only some part(s) of the representation data (e.g., the <a href="p5-range.html#status.206" class="smpl">206 (Partial Content)</a> status code). |
| 1147 | | </p> |
| 1148 | | <p id="rfc.section.3.3.p.2">The purpose of a payload in a request is defined by the method semantics. For example, a representation in the payload of |
| 1149 | | a PUT request (<a href="#PUT" id="rfc.xref.PUT.1" title="PUT">Section 4.3.4</a>) represents the desired state of the <a href="#resources" class="smpl">target resource</a> if the request is successfully applied, whereas a representation in the payload of a POST request (<a href="#POST" id="rfc.xref.POST.1" title="POST">Section 4.3.3</a>) represents an anonymous resource for providing data to be processed, such as the information that a user entered within |
| 1150 | | an HTML form. |
| 1151 | | </p> |
| 1152 | | <p id="rfc.section.3.3.p.3">In a response, the payload's purpose is defined by both the request method and the response status code. For example, the |
| 1153 | | payload of a <a href="#status.200" class="smpl">200 (OK)</a> response to GET (<a href="#GET" id="rfc.xref.GET.2" title="GET">Section 4.3.1</a>) represents the current state of the <a href="#resources" class="smpl">target resource</a>, as observed at the time of the message origination date (<a href="#header.date" id="rfc.xref.header.date.1" title="Date">Section 7.1.1.2</a>), whereas the payload of the same status code in a response to POST might represent either the processing result or the new |
| 1154 | | state of the target resource after applying the processing. Response messages with an error status code usually contain a |
| 1155 | | payload that represents the error condition, such that it describes the error state and what next steps are suggested for |
| 1156 | | resolving it. |
| 1157 | | </p> |
| 1158 | | <p id="rfc.section.3.3.p.4">Header fields that specifically describe the payload, rather than the associated representation, are referred to as "payload |
| 1159 | | header fields". Payload header fields are defined in other parts of this specification, due to their impact on message parsing. |
| 1160 | | </p> |
| 1161 | | <div id="rfc.table.u.2"> |
| 1162 | | <table class="tt full left" cellpadding="3" cellspacing="0"> |
| 1163 | | <thead> |
| 1164 | | <tr> |
| 1165 | | <th>Header Field Name</th> |
| 1166 | | <th>Defined in...</th> |
| 1167 | | </tr> |
| 1168 | | </thead> |
| 1169 | | <tbody> |
| 1170 | | <tr> |
| 1171 | | <td class="left">Content-Length</td> |
| 1172 | | <td class="left"><a href="p1-messaging.html#header.content-length" title="Content-Length">Section 3.3.2</a> of <a href="#Part1" id="rfc.xref.Part1.13"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a></td> |
| 1173 | | </tr> |
| 1174 | | <tr> |
| 1175 | | <td class="left">Content-Range</td> |
| 1176 | | <td class="left"><a href="p5-range.html#header.content-range" title="Content-Range">Section 4.2</a> of <a href="#Part5" id="rfc.xref.Part5.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a></td> |
| 1177 | | </tr> |
| 1178 | | <tr> |
| 1179 | | <td class="left">Transfer-Encoding</td> |
| 1180 | | <td class="left"><a href="p1-messaging.html#header.transfer-encoding" title="Transfer-Encoding">Section 3.3.1</a> of <a href="#Part1" id="rfc.xref.Part1.14"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a></td> |
| 1181 | | </tr> |
| 1182 | | </tbody> |
| 1183 | | </table> |
| 1184 | | </div> |
| 1185 | | <h2 id="rfc.section.3.4"><a href="#rfc.section.3.4">3.4</a> <a id="content.negotiation" href="#content.negotiation">Content Negotiation</a></h2> |
| 1186 | | <p id="rfc.section.3.4.p.1">When responses convey payload information, whether indicating a success or an error, the origin server often has different |
| 1187 | | ways of representing that information; for example, in different formats, languages, or encodings. Likewise, different users |
| 1188 | | or user agents might have differing capabilities, characteristics, or preferences that could influence which representation, |
| 1189 | | among those available, would be best to deliver. For this reason, HTTP provides mechanisms for <a href="#content.negotiation" class="smpl">content negotiation</a>. |
| 1190 | | </p> |
| 1191 | | <p id="rfc.section.3.4.p.2">This specification defines two patterns of content negotiation that can be made visible within the protocol: "proactive", |
| 1192 | | where the server selects the representation based upon the user agent's stated preferences, and "reactive" negotiation, where |
| 1193 | | the server provides a list of representations for the user agent to choose from. Other patterns of content negotiation include |
| 1194 | | "conditional content", where the representation consists of multiple parts that are selectively rendered based on user agent |
| 1195 | | parameters, "active content", where the representation contains a script that makes additional (more specific) requests based |
| 1196 | | on the user agent characteristics, and "Transparent Content Negotiation" (<a href="#RFC2295" id="rfc.xref.RFC2295.1"><cite title="Transparent Content Negotiation in HTTP">[RFC2295]</cite></a>), where content selection is performed by an intermediary. These patterns are not mutually exclusive, and each has trade-offs |
| 1197 | | in applicability and practicality. |
| 1198 | | </p> |
| 1199 | | <p id="rfc.section.3.4.p.3">Note that, in all cases, HTTP is not aware of the resource semantics. The consistency with which an origin server responds |
| 1200 | | to requests, over time and over the varying dimensions of content negotiation, and thus the "sameness" of a resource's observed |
| 1201 | | representations over time, is determined entirely by whatever entity or algorithm selects or generates those responses. HTTP |
| 1202 | | pays no attention to the man behind the curtain. |
| 1203 | | </p> |
| 1204 | | <h3 id="rfc.section.3.4.1"><a href="#rfc.section.3.4.1">3.4.1</a> <a id="proactive.negotiation" href="#proactive.negotiation">Proactive Negotiation</a></h3> |
| 1205 | | <p id="rfc.section.3.4.1.p.1">When content negotiation preferences are sent by the user agent in a request to encourage an algorithm located at the server |
| 1206 | | to select the preferred representation, it is called <dfn>proactive negotiation</dfn> (a.k.a., <dfn>server-driven negotiation</dfn>). Selection is based on the available representations for a response (the dimensions over which it might vary, such as language, |
| 1207 | | content-coding, etc.) compared to various information supplied in the request, including both the explicit negotiation fields |
| 1208 | | of <a href="#request.conneg" title="Content Negotiation">Section 5.3</a> and implicit characteristics, such as the client's network address or parts of the <a href="#header.user-agent" class="smpl">User-Agent</a> field. |
| 1209 | | </p> |
| 1210 | | <p id="rfc.section.3.4.1.p.2">Proactive negotiation is advantageous when the algorithm for selecting from among the available representations is difficult |
| 1211 | | to describe to a user agent, or when the server desires to send its "best guess" to the user agent along with the first response |
| 1212 | | (hoping to avoid the round-trip delay of a subsequent request if the "best guess" is good enough for the user). In order to |
| 1213 | | improve the server's guess, a user agent <em class="bcp14">MAY</em> send request header fields that describe its preferences. |
| 1214 | | </p> |
| 1215 | | <p id="rfc.section.3.4.1.p.3">Proactive negotiation has serious disadvantages: </p> |
| 1216 | | <ul> |
| 1217 | | <li>It is impossible for the server to accurately determine what might be "best" for any given user, since that would require |
| 1218 | | complete knowledge of both the capabilities of the user agent and the intended use for the response (e.g., does the user want |
| 1219 | | to view it on screen or print it on paper?); |
| 1220 | | </li> |
| 1221 | | <li>Having the user agent describe its capabilities in every request can be both very inefficient (given that only a small percentage |
| 1222 | | of responses have multiple representations) and a potential risk to the user's privacy; |
| 1223 | | </li> |
| 1224 | | <li>It complicates the implementation of an origin server and the algorithms for generating responses to a request; and,</li> |
| 1225 | | <li>It limits the reusability of responses for shared caching.</li> |
| 1226 | | </ul> |
| 1227 | | <p id="rfc.section.3.4.1.p.4">A user agent cannot rely on proactive negotiation preferences being consistently honored, since the origin server might not |
| 1228 | | implement proactive negotiation for the requested resource or might decide that sending a response that doesn't conform to |
| 1229 | | the user agent's preferences is better than sending a <a href="#status.406" class="smpl">406 (Not Acceptable)</a> response. |
| 1230 | | </p> |
| 1231 | | <p id="rfc.section.3.4.1.p.5">An origin server <em class="bcp14">MAY</em> generate a <a href="#header.vary" class="smpl">Vary</a> header field (<a href="#header.vary" id="rfc.xref.header.vary.1" title="Vary">Section 7.1.4</a>) in responses that are subject to proactive negotiation to indicate what parameters of request information might be used |
| 1232 | | in its selection algorithm, thereby providing a means for recipients to determine the reusability of that same response for |
| 1233 | | user agents with differing request information. |
| 1234 | | </p> |
| 1235 | | <h3 id="rfc.section.3.4.2"><a href="#rfc.section.3.4.2">3.4.2</a> <a id="reactive.negotiation" href="#reactive.negotiation">Reactive Negotiation</a></h3> |
| 1236 | | <p id="rfc.section.3.4.2.p.1">With <dfn>reactive negotiation</dfn> (a.k.a., <dfn>agent-driven negotiation</dfn>), selection of the best response representation (regardless of the status code) is performed by the user agent after receiving |
| 1237 | | an initial response from the origin server that contains a list of resources for alternative representations. If the user |
| 1238 | | agent is not satisfied by the initial response representation, it can perform a GET request on one or more of the alternative |
| 1239 | | resources, selected based on metadata included in the list, to obtain a different form of representation for that response. |
| 1240 | | Selection of alternatives might be performed automatically by the user agent or manually by the user selecting from a generated |
| 1241 | | (possibly hypertext) menu. |
| 1242 | | </p> |
| 1243 | | <p id="rfc.section.3.4.2.p.2">Note that the above refers to representations of the response, in general, not representations of the resource. The alternative |
| 1244 | | representations are only considered representations of the target resource if the response in which those alternatives are |
| 1245 | | provided has the semantics of being a representation of the target resource (e.g., a <a href="#status.200" class="smpl">200 (OK)</a> response to a GET request) or has the semantics of providing links to alternative representations for the target resource |
| 1246 | | (e.g., a <a href="#status.300" class="smpl">300 (Multiple Choices)</a> response to a GET request). |
| 1247 | | </p> |
| 1248 | | <p id="rfc.section.3.4.2.p.3">A server might choose not to send an initial representation, other than the list of alternatives, and thereby indicate that |
| 1249 | | reactive negotiation by the user agent is preferred. For example, the alternatives listed in responses with the <a href="#status.300" class="smpl">300 (Multiple Choices)</a> and <a href="#status.406" class="smpl">406 (Not Acceptable)</a> status codes include information about the available representations so that the user or user agent can react by making a |
| 1250 | | selection. |
| 1251 | | </p> |
| 1252 | | <p id="rfc.section.3.4.2.p.4">Reactive negotiation is advantageous when the response would vary over commonly-used dimensions (such as type, language, or |
| 1253 | | encoding), when the origin server is unable to determine a user agent's capabilities from examining the request, and generally |
| 1254 | | when public caches are used to distribute server load and reduce network usage. |
| 1255 | | </p> |
| 1256 | | <p id="rfc.section.3.4.2.p.5">Reactive negotiation suffers from the disadvantages of transmitting a list of alternatives to the user agent, which degrades |
| 1257 | | user-perceived latency if transmitted in the header section, and needing a second request to obtain an alternate representation. |
| 1258 | | Furthermore, this specification does not define a mechanism for supporting automatic selection, though it does not prevent |
| 1259 | | such a mechanism from being developed as an extension. |
| 1260 | | </p> |
| 1261 | | <h1 id="rfc.section.4"><a href="#rfc.section.4">4.</a> <a id="methods" href="#methods">Request Methods</a></h1> |
| 1262 | | <h2 id="rfc.section.4.1"><a href="#rfc.section.4.1">4.1</a> <a id="method.overview" href="#method.overview">Overview</a></h2> |
| 1263 | | <p id="rfc.section.4.1.p.1">The request method token is the primary source of request semantics; it indicates the purpose for which the client has made |
| 1264 | | this request and what is expected by the client as a successful result. |
| 1265 | | </p> |
| 1266 | | <p id="rfc.section.4.1.p.2">The request method's semantics might be further specialized by the semantics of some header fields when present in a request |
| 1267 | | (<a href="#request.header.fields" title="Request Header Fields">Section 5</a>) if those additional semantics do not conflict with the method. For example, a client can send conditional request header |
| 1268 | | fields (<a href="#request.conditionals" title="Conditionals">Section 5.2</a>) to make the requested action conditional on the current state of the target resource (<a href="#Part4" id="rfc.xref.Part4.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests">[Part4]</cite></a>). |
| 1269 | | </p> |
| 1270 | | <div id="rfc.figure.u.17"></div><pre class="inline"><span id="rfc.iref.g.15"></span> <a href="#method.overview" class="smpl">method</a> = <a href="#imported.abnf" class="smpl">token</a> |
| | 1316 | <div id="methods"> |
| | 1317 | <h1 id="rfc.section.4"><a href="#rfc.section.4">4.</a> <a href="#methods">Request Methods</a></h1> |
| | 1318 | <div id="method.overview"> |
| | 1319 | <h2 id="rfc.section.4.1"><a href="#rfc.section.4.1">4.1</a> <a href="#method.overview">Overview</a></h2> |
| | 1320 | <p id="rfc.section.4.1.p.1">The request method token is the primary source of request semantics; it indicates the purpose for which the client has made |
| | 1321 | this request and what is expected by the client as a successful result. |
| | 1322 | </p> |
| | 1323 | <p id="rfc.section.4.1.p.2">The request method's semantics might be further specialized by the semantics of some header fields when present in a request |
| | 1324 | (<a href="#request.header.fields" title="Request Header Fields">Section 5</a>) if those additional semantics do not conflict with the method. For example, a client can send conditional request header |
| | 1325 | fields (<a href="#request.conditionals" title="Conditionals">Section 5.2</a>) to make the requested action conditional on the current state of the target resource (<a href="#Part4" id="rfc.xref.Part4.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests">[Part4]</cite></a>). |
| | 1326 | </p> |
| | 1327 | <div id="rfc.figure.u.17"></div><pre class="inline"><span id="rfc.iref.g.15"></span> <a href="#method.overview" class="smpl">method</a> = <a href="#imported.abnf" class="smpl">token</a> |
| 1272 | | as applying semantics to a <a href="#resources" class="smpl">target resource</a> in much the same way as invoking a defined method on an identified object would apply semantics. The method token is case-sensitive |
| 1273 | | because it might be used as a gateway to object-based systems with case-sensitive method names. |
| 1274 | | </p> |
| 1275 | | <p id="rfc.section.4.1.p.5">Unlike distributed objects, the standardized request methods in HTTP are not resource-specific, since uniform interfaces provide |
| 1276 | | for better visibility and reuse in network-based systems <a href="#REST" id="rfc.xref.REST.2"><cite title="Architectural Styles and the Design of Network-based Software Architectures">[REST]</cite></a>. Once defined, a standardized method ought to have the same semantics when applied to any resource, though each resource |
| 1277 | | determines for itself whether those semantics are implemented or allowed. |
| 1278 | | </p> |
| 1279 | | <p id="rfc.section.4.1.p.6">This specification defines a number of standardized methods that are commonly used in HTTP, as outlined by the following table. |
| 1280 | | By convention, standardized methods are defined in all-uppercase ASCII letters. |
| 1281 | | </p> |
| 1282 | | <div id="rfc.table.1"> |
| 1283 | | <div id="table.of.methods"></div> |
| 1284 | | <table class="tt full left" cellpadding="3" cellspacing="0"> |
| 1285 | | <thead> |
| 1286 | | <tr> |
| 1287 | | <th>Method</th> |
| 1288 | | <th>Description</th> |
| 1289 | | <th>Sec.</th> |
| 1290 | | </tr> |
| 1291 | | </thead> |
| 1292 | | <tbody> |
| 1293 | | <tr> |
| 1294 | | <td class="left">GET</td> |
| 1295 | | <td class="left">Transfer a current representation of the target resource.</td> |
| 1296 | | <td class="left"><a href="#GET" id="rfc.xref.GET.3" title="GET">4.3.1</a></td> |
| 1297 | | </tr> |
| 1298 | | <tr> |
| 1299 | | <td class="left">HEAD</td> |
| 1300 | | <td class="left">Same as GET, but only transfer the status line and header section.</td> |
| 1301 | | <td class="left"><a href="#HEAD" id="rfc.xref.HEAD.1" title="HEAD">4.3.2</a></td> |
| 1302 | | </tr> |
| 1303 | | <tr> |
| 1304 | | <td class="left">POST</td> |
| 1305 | | <td class="left">Perform resource-specific processing on the request payload.</td> |
| 1306 | | <td class="left"><a href="#POST" id="rfc.xref.POST.2" title="POST">4.3.3</a></td> |
| 1307 | | </tr> |
| 1308 | | <tr> |
| 1309 | | <td class="left">PUT</td> |
| 1310 | | <td class="left">Replace all current representations of the target resource with the request payload.</td> |
| 1311 | | <td class="left"><a href="#PUT" id="rfc.xref.PUT.2" title="PUT">4.3.4</a></td> |
| 1312 | | </tr> |
| 1313 | | <tr> |
| 1314 | | <td class="left">DELETE</td> |
| 1315 | | <td class="left">Remove all current representations of the target resource.</td> |
| 1316 | | <td class="left"><a href="#DELETE" id="rfc.xref.DELETE.1" title="DELETE">4.3.5</a></td> |
| 1317 | | </tr> |
| 1318 | | <tr> |
| 1319 | | <td class="left">CONNECT</td> |
| 1320 | | <td class="left">Establish a tunnel to the server identified by the target resource.</td> |
| 1321 | | <td class="left"><a href="#CONNECT" id="rfc.xref.CONNECT.1" title="CONNECT">4.3.6</a></td> |
| 1322 | | </tr> |
| 1323 | | <tr> |
| 1324 | | <td class="left">OPTIONS</td> |
| 1325 | | <td class="left">Describe the communication options for the target resource.</td> |
| 1326 | | <td class="left"><a href="#OPTIONS" id="rfc.xref.OPTIONS.1" title="OPTIONS">4.3.7</a></td> |
| 1327 | | </tr> |
| 1328 | | <tr> |
| 1329 | | <td class="left">TRACE</td> |
| 1330 | | <td class="left">Perform a message loop-back test along the path to the target resource.</td> |
| 1331 | | <td class="left"><a href="#TRACE" id="rfc.xref.TRACE.1" title="TRACE">4.3.8</a></td> |
| 1332 | | </tr> |
| 1333 | | </tbody> |
| 1334 | | </table> |
| 1335 | | </div> |
| 1336 | | <p id="rfc.section.4.1.p.7">All general-purpose servers <em class="bcp14">MUST</em> support the methods GET and HEAD. All other methods are <em class="bcp14">OPTIONAL</em>; when implemented, a server <em class="bcp14">MUST</em> implement the above methods according to the semantics defined for them in <a href="#method.definitions" title="Method Definitions">Section 4.3</a>. |
| 1337 | | </p> |
| 1338 | | <p id="rfc.section.4.1.p.8">Additional methods, outside the scope of this specification, have been standardized for use in HTTP. All such methods ought |
| 1339 | | to be registered within the HTTP Method Registry maintained by IANA, as defined in <a href="#method.registry" title="Method Registry">Section 8.1</a>. |
| 1340 | | </p> |
| 1341 | | <p id="rfc.section.4.1.p.9">The set of methods allowed by a target resource can be listed in an <a href="#header.allow" class="smpl">Allow</a> header field (<a href="#header.allow" id="rfc.xref.header.allow.1" title="Allow">Section 7.4.1</a>). However, the set of allowed methods can change dynamically. When a request method is received that is unrecognized or not |
| 1342 | | implemented by an origin server, the origin server <em class="bcp14">SHOULD</em> respond with the <a href="#status.501" class="smpl">501 (Not Implemented)</a> status code. When a request method is received that is known by an origin server but not allowed for the target resource, |
| 1343 | | the origin server <em class="bcp14">SHOULD</em> respond with the <a href="#status.405" class="smpl">405 (Method Not Allowed)</a> status code. |
| 1344 | | </p> |
| 1345 | | <h2 id="rfc.section.4.2"><a href="#rfc.section.4.2">4.2</a> <a id="method.properties" href="#method.properties">Common Method Properties</a></h2> |
| 1346 | | <div id="rfc.iref.s.2"></div> |
| 1347 | | <h3 id="rfc.section.4.2.1"><a href="#rfc.section.4.2.1">4.2.1</a> <a id="safe.methods" href="#safe.methods">Safe Methods</a></h3> |
| 1348 | | <p id="rfc.section.4.2.1.p.1">Request methods are considered "<dfn>safe</dfn>" if their defined semantics are essentially read-only; i.e., the client does not request, and does not expect, any state |
| 1349 | | change on the origin server as a result of applying a safe method to a target resource. Likewise, reasonable use of a safe |
| 1350 | | method is not expected to cause any harm, loss of property, or unusual burden on the origin server. |
| 1351 | | </p> |
| 1352 | | <p id="rfc.section.4.2.1.p.2">This definition of safe methods does not prevent an implementation from including behavior that is potentially harmful, not |
| 1353 | | entirely read-only, or which causes side-effects while invoking a safe method. What is important, however, is that the client |
| 1354 | | did not request that additional behavior and cannot be held accountable for it. For example, most servers append request information |
| 1355 | | to access log files at the completion of every response, regardless of the method, and that is considered safe even though |
| 1356 | | the log storage might become full and crash the server. Likewise, a safe request initiated by selecting an advertisement on |
| 1357 | | the Web will often have the side-effect of charging an advertising account. |
| 1358 | | </p> |
| 1359 | | <p id="rfc.section.4.2.1.p.3">Of the request methods defined by this specification, the GET, HEAD, OPTIONS, and TRACE methods are defined to be safe.</p> |
| 1360 | | <p id="rfc.section.4.2.1.p.4">The purpose of distinguishing between safe and unsafe methods is to allow automated retrieval processes (spiders) and cache |
| 1361 | | performance optimization (pre-fetching) to work without fear of causing harm. In addition, it allows a user agent to apply |
| 1362 | | appropriate constraints on the automated use of unsafe methods when processing potentially untrusted content. |
| 1363 | | </p> |
| 1364 | | <p id="rfc.section.4.2.1.p.5">A user agent <em class="bcp14">SHOULD</em> distinguish between safe and unsafe methods when presenting potential actions to a user, such that the user can be made aware |
| 1365 | | of an unsafe action before it is requested. |
| 1366 | | </p> |
| 1367 | | <p id="rfc.section.4.2.1.p.6">When a resource is constructed such that parameters within the effective request URI have the effect of selecting an action, |
| 1368 | | it is the resource owner's responsibility to ensure that the action is consistent with the request method semantics. For example, |
| 1369 | | it is common for Web-based content editing software to use actions within query parameters, such as "page?do=delete". If the |
| 1370 | | purpose of such a resource is to perform an unsafe action, then the resource owner <em class="bcp14">MUST</em> disable or disallow that action when it is accessed using a safe request method. Failure to do so will result in unfortunate |
| 1371 | | side-effects when automated processes perform a GET on every URI reference for the sake of link maintenance, pre-fetching, |
| 1372 | | building a search index, etc. |
| 1373 | | </p> |
| 1374 | | <div id="rfc.iref.i.1"></div> |
| 1375 | | <h3 id="rfc.section.4.2.2"><a href="#rfc.section.4.2.2">4.2.2</a> <a id="idempotent.methods" href="#idempotent.methods">Idempotent Methods</a></h3> |
| 1376 | | <p id="rfc.section.4.2.2.p.1">Request methods are considered "<dfn id="idempotent">idempotent</dfn>" if the intended effect of multiple identical requests is the same as for a single request. Of the request methods defined |
| 1377 | | by this specification, the PUT, DELETE, and safe request methods are idempotent. |
| 1378 | | </p> |
| 1379 | | <p id="rfc.section.4.2.2.p.2">Like the definition of safe, the idempotent property only applies to what has been requested by the user; a server is free |
| 1380 | | to log each request separately, retain a revision control history, or implement other non-idempotent side-effects for each |
| 1381 | | idempotent request. |
| 1382 | | </p> |
| 1383 | | <p id="rfc.section.4.2.2.p.3">Idempotent methods are distinguished because the request can be repeated automatically if a communication failure occurs before |
| 1384 | | the client is able to read the server's response. For example, if a client sends a PUT request and the underlying connection |
| 1385 | | is closed before any response is received, then it can establish a new connection and retry the idempotent request because |
| 1386 | | it knows that repeating the request will have the same effect even if the original request succeeded. Note, however, that |
| 1387 | | repeated failures would indicate a problem within the server. |
| 1388 | | </p> |
| 1389 | | <div id="rfc.iref.c.8"></div> |
| 1390 | | <h3 id="rfc.section.4.2.3"><a href="#rfc.section.4.2.3">4.2.3</a> <a id="cacheable.methods" href="#cacheable.methods">Cacheable Methods</a></h3> |
| 1391 | | <p id="rfc.section.4.2.3.p.1">Request methods can be defined as "<dfn id="cacheable">cacheable</dfn>" to indicate that responses to them are allowed to be stored for future reuse; for specific requirements see <a href="#Part6" id="rfc.xref.Part6.1"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>. In general, safe methods that do not depend on a current or authoritative response are defined as cacheable; this specification |
| 1392 | | defines GET, HEAD and POST as cacheable, although the overwhelming majority of cache implementations only support GET and |
| 1393 | | HEAD. |
| 1394 | | </p> |
| 1395 | | <h2 id="rfc.section.4.3"><a href="#rfc.section.4.3">4.3</a> <a id="method.definitions" href="#method.definitions">Method Definitions</a></h2> |
| 1396 | | <h3 id="rfc.section.4.3.1"><a href="#rfc.section.4.3.1">4.3.1</a> <a id="GET" href="#GET">GET</a></h3> |
| 1397 | | <div id="rfc.iref.g.16"></div> |
| 1398 | | <p id="rfc.section.4.3.1.p.1">The GET method requests transfer of a current selected representation for the <a href="#resources" class="smpl">target resource</a>. GET is the primary mechanism of information retrieval and the focus of almost all performance optimizations. Hence, when |
| 1399 | | people speak of retrieving some identifiable information via HTTP, they are generally referring to making a GET request. |
| 1400 | | </p> |
| 1401 | | <p id="rfc.section.4.3.1.p.2">It is tempting to think of resource identifiers as remote filesystem pathnames, and of representations as being a copy of |
| 1402 | | the contents of such files. In fact, that is how many resources are implemented (see <a href="#attack.pathname" title="Attacks Based On File and Path Names">Section 9.1</a> for related security considerations). However, there are no such limitations in practice. The HTTP interface for a resource |
| 1403 | | is just as likely to be implemented as a tree of content objects, a programmatic view on various database records, or a gateway |
| 1404 | | to other information systems. Even when the URI mapping mechanism is tied to a filesystem, an origin server might be configured |
| 1405 | | to execute the files with the request as input and send the output as the representation, rather than transfer the files directly. |
| 1406 | | Regardless, only the origin server needs to know how each of its resource identifiers corresponds to an implementation, and |
| 1407 | | how each implementation manages to select and send a current representation of the target resource in a response to GET. |
| 1408 | | </p> |
| 1409 | | <p id="rfc.section.4.3.1.p.3">A client can alter the semantics of GET to be a "range request", requesting transfer of only some part(s) of the selected |
| 1410 | | representation, by sending a <a href="p5-range.html#header.range" class="smpl">Range</a> header field in the request (<a href="#Part5" id="rfc.xref.Part5.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a>). |
| 1411 | | </p> |
| 1412 | | <p id="rfc.section.4.3.1.p.4">A payload within a GET request message has no defined semantics; sending a payload body on a GET request might cause some |
| 1413 | | existing implementations to reject the request. |
| 1414 | | </p> |
| 1415 | | <p id="rfc.section.4.3.1.p.5">The response to a GET request is cacheable; a cache <em class="bcp14">MAY</em> use it to satisfy subsequent GET and HEAD requests unless otherwise indicated by the Cache-Control header field (<a href="p6-cache.html#header.cache-control" title="Cache-Control">Section 5.2</a> of <a href="#Part6" id="rfc.xref.Part6.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| 1416 | | </p> |
| 1417 | | <h3 id="rfc.section.4.3.2"><a href="#rfc.section.4.3.2">4.3.2</a> <a id="HEAD" href="#HEAD">HEAD</a></h3> |
| 1418 | | <div id="rfc.iref.h.1"></div> |
| 1419 | | <p id="rfc.section.4.3.2.p.1">The HEAD method is identical to GET except that the server <em class="bcp14">MUST NOT</em> send a message body in the response (i.e., the response terminates at the end of the header section). The server <em class="bcp14">SHOULD</em> send the same header fields in response to a HEAD request as it would have sent if the request had been a GET, except that |
| 1420 | | the payload header fields (<a href="#payload" title="Payload Semantics">Section 3.3</a>) <em class="bcp14">MAY</em> be omitted. This method can be used for obtaining metadata about the selected representation without transferring the representation |
| 1421 | | data and is often used for testing hypertext links for validity, accessibility, and recent modification. |
| 1422 | | </p> |
| 1423 | | <p id="rfc.section.4.3.2.p.2">A payload within a HEAD request message has no defined semantics; sending a payload body on a HEAD request might cause some |
| 1424 | | existing implementations to reject the request. |
| 1425 | | </p> |
| 1426 | | <p id="rfc.section.4.3.2.p.3">The response to a HEAD request is cacheable; a cache <em class="bcp14">MAY</em> use it to satisfy subsequent HEAD requests unless otherwise indicated by the Cache-Control header field (<a href="p6-cache.html#header.cache-control" title="Cache-Control">Section 5.2</a> of <a href="#Part6" id="rfc.xref.Part6.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). A HEAD response might also have an effect on previously cached responses to GET; see <a href="p6-cache.html#head.effects" title="Freshening Responses via HEAD">Section 4.3.5</a> of <a href="#Part6" id="rfc.xref.Part6.4"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>. |
| 1427 | | </p> |
| 1428 | | <div id="rfc.iref.p.2"></div> |
| 1429 | | <h3 id="rfc.section.4.3.3"><a href="#rfc.section.4.3.3">4.3.3</a> <a id="POST" href="#POST">POST</a></h3> |
| 1430 | | <p id="rfc.section.4.3.3.p.1">The POST method requests that the <a href="#resources" class="smpl">target resource</a> process the representation enclosed in the request according to the resource's own specific semantics. For example, POST is |
| 1431 | | used for the following functions (among others): |
| 1432 | | </p> |
| 1433 | | <ul> |
| 1434 | | <li>Providing a block of data, such as the fields entered into an HTML form, to a data-handling process;</li> |
| 1435 | | <li>Posting a message to a bulletin board, newsgroup, mailing list, blog, or similar group of articles;</li> |
| 1436 | | <li>Creating a new resource that has yet to be identified by the origin server; and</li> |
| 1437 | | <li>Appending data to a resource's existing representation(s).</li> |
| 1438 | | </ul> |
| 1439 | | <p id="rfc.section.4.3.3.p.2">An origin server indicates response semantics by choosing an appropriate status code depending on the result of processing |
| 1440 | | the POST request; almost all of the status codes defined by this specification might be received in a response to POST (the |
| 1441 | | exceptions being 206, 304, and 416). |
| 1442 | | </p> |
| 1443 | | <p id="rfc.section.4.3.3.p.3">If one or more resources has been created on the origin server as a result of successfully processing a POST request, the |
| 1444 | | origin server <em class="bcp14">SHOULD</em> send a <a href="#status.201" class="smpl">201 (Created)</a> response containing a <a href="#header.location" class="smpl">Location</a> header field that provides an identifier for the primary resource created (<a href="#header.location" id="rfc.xref.header.location.1" title="Location">Section 7.1.2</a>) and a representation that describes the status of the request while referring to the new resource(s). |
| 1445 | | </p> |
| 1446 | | <p id="rfc.section.4.3.3.p.4">Responses to POST requests are only cacheable when they include explicit freshness information (see <a href="p6-cache.html#calculating.freshness.lifetime" title="Calculating Freshness Lifetime">Section 4.2.1</a> of <a href="#Part6" id="rfc.xref.Part6.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). However, POST caching is not widely implemented. For cases where an origin server wishes the client to be able to cache |
| 1447 | | the result of a POST in a way that can be reused by a later GET, the origin server <em class="bcp14">MAY</em> send a <a href="#status.200" class="smpl">200 (OK)</a> response containing the result and a <a href="#header.content-location" class="smpl">Content-Location</a> header field that has the same value as the POST's effective request URI (<a href="#header.content-location" id="rfc.xref.header.content-location.2" title="Content-Location">Section 3.1.4.2</a>). |
| 1448 | | </p> |
| 1449 | | <p id="rfc.section.4.3.3.p.5">If the result of processing a POST would be equivalent to a representation of an existing resource, an origin server <em class="bcp14">MAY</em> redirect the user agent to that resource by sending a <a href="#status.303" class="smpl">303 (See Other)</a> response with the existing resource's identifier in the <a href="#header.location" class="smpl">Location</a> field. This has the benefits of providing the user agent a resource identifier and transferring the representation via a method |
| 1450 | | more amenable to shared caching, though at the cost of an extra request if the user agent does not already have the representation |
| 1451 | | cached. |
| 1452 | | </p> |
| 1453 | | <h3 id="rfc.section.4.3.4"><a href="#rfc.section.4.3.4">4.3.4</a> <a id="PUT" href="#PUT">PUT</a></h3> |
| 1454 | | <div id="rfc.iref.p.3"></div> |
| 1455 | | <p id="rfc.section.4.3.4.p.1">The PUT method requests that the state of the <a href="#resources" class="smpl">target resource</a> be created or replaced with the state defined by the representation enclosed in the request message payload. A successful |
| 1456 | | PUT of a given representation would suggest that a subsequent GET on that same target resource will result in an equivalent |
| 1457 | | representation being sent in a <a href="#status.200" class="smpl">200 (OK)</a> response. However, there is no guarantee that such a state change will be observable, since the target resource might be acted |
| 1458 | | upon by other user agents in parallel, or might be subject to dynamic processing by the origin server, before any subsequent |
| 1459 | | GET is received. A successful response only implies that the user agent's intent was achieved at the time of its processing |
| 1460 | | by the origin server. |
| 1461 | | </p> |
| 1462 | | <p id="rfc.section.4.3.4.p.2">If the target resource does not have a current representation and the PUT successfully creates one, then the origin server <em class="bcp14">MUST</em> inform the user agent by sending a <a href="#status.201" class="smpl">201 (Created)</a> response. If the target resource does have a current representation and that representation is successfully modified in accordance |
| 1463 | | with the state of the enclosed representation, then the origin server <em class="bcp14">MUST</em> send either a <a href="#status.200" class="smpl">200 (OK)</a> or a <a href="#status.204" class="smpl">204 (No Content)</a> response to indicate successful completion of the request. |
| 1464 | | </p> |
| 1465 | | <p id="rfc.section.4.3.4.p.3">An origin server <em class="bcp14">SHOULD</em> ignore unrecognized header fields received in a PUT request (i.e., do not save them as part of the resource state). |
| 1466 | | </p> |
| 1467 | | <p id="rfc.section.4.3.4.p.4">An origin server <em class="bcp14">SHOULD</em> verify that the PUT representation is consistent with any constraints the server has for the target resource that cannot or |
| 1468 | | will not be changed by the PUT. This is particularly important when the origin server uses internal configuration information |
| 1469 | | related to the URI in order to set the values for representation metadata on GET responses. When a PUT representation is inconsistent |
| 1470 | | with the target resource, the origin server <em class="bcp14">SHOULD</em> either make them consistent, by transforming the representation or changing the resource configuration, or respond with an |
| 1471 | | appropriate error message containing sufficient information to explain why the representation is unsuitable. The <a href="#status.409" class="smpl">409 (Conflict)</a> or <a href="#status.415" class="smpl">415 (Unsupported Media Type)</a> status codes are suggested, with the latter being specific to constraints on <a href="#header.content-type" class="smpl">Content-Type</a> values. |
| 1472 | | </p> |
| 1473 | | <p id="rfc.section.4.3.4.p.5">For example, if the target resource is configured to always have a <a href="#header.content-type" class="smpl">Content-Type</a> of "text/html" and the representation being PUT has a Content-Type of "image/jpeg", the origin server ought to do one of: |
| 1474 | | </p> |
| 1475 | | <ol class="la"> |
| 1476 | | <li>reconfigure the target resource to reflect the new media type;</li> |
| 1477 | | <li>transform the PUT representation to a format consistent with that of the resource before saving it as the new resource state; |
| 1478 | | or, |
| 1479 | | </li> |
| 1480 | | <li>reject the request with a <a href="#status.415" class="smpl">415 (Unsupported Media Type)</a> response indicating that the target resource is limited to "text/html", perhaps including a link to a different resource that |
| 1481 | | would be a suitable target for the new representation. |
| 1482 | | </li> |
| 1483 | | </ol> |
| 1484 | | <p id="rfc.section.4.3.4.p.6">HTTP does not define exactly how a PUT method affects the state of an origin server beyond what can be expressed by the intent |
| 1485 | | of the user agent request and the semantics of the origin server response. It does not define what a resource might be, in |
| 1486 | | any sense of that word, beyond the interface provided via HTTP. It does not define how resource state is "stored", nor how |
| 1487 | | such storage might change as a result of a change in resource state, nor how the origin server translates resource state into |
| 1488 | | representations. Generally speaking, all implementation details behind the resource interface are intentionally hidden by |
| 1489 | | the server. |
| 1490 | | </p> |
| 1491 | | <p id="rfc.section.4.3.4.p.7">An origin server <em class="bcp14">MUST NOT</em> send a validator header field (<a href="#response.validator" title="Validator Header Fields">Section 7.2</a>), such as an <a href="p4-conditional.html#header.etag" class="smpl">ETag</a> or <a href="p4-conditional.html#header.last-modified" class="smpl">Last-Modified</a> field, in a successful response to PUT unless the request's representation data was saved without any transformation applied |
| 1492 | | to the body (i.e., the resource's new representation data is identical to the representation data received in the PUT request) |
| 1493 | | and the validator field value reflects the new representation. This requirement allows a user agent to know when the representation |
| 1494 | | body it has in memory remains current as a result of the PUT, thus not in need of retrieving again from the origin server, |
| 1495 | | and that the new validator(s) received in the response can be used for future conditional requests in order to prevent accidental |
| 1496 | | overwrites (<a href="#request.conditionals" title="Conditionals">Section 5.2</a>). |
| 1497 | | </p> |
| 1498 | | <p id="rfc.section.4.3.4.p.8">The fundamental difference between the POST and PUT methods is highlighted by the different intent for the enclosed representation. |
| 1499 | | The target resource in a POST request is intended to handle the enclosed representation according to the resource's own semantics, |
| 1500 | | whereas the enclosed representation in a PUT request is defined as replacing the state of the target resource. Hence, the |
| 1501 | | intent of PUT is idempotent and visible to intermediaries, even though the exact effect is only known by the origin server. |
| 1502 | | </p> |
| 1503 | | <p id="rfc.section.4.3.4.p.9">Proper interpretation of a PUT request presumes that the user agent knows which target resource is desired. A service that |
| 1504 | | selects a proper URI on behalf of the client, after receiving a state-changing request, <em class="bcp14">SHOULD</em> be implemented using the POST method rather than PUT. If the origin server will not make the requested PUT state change to |
| 1505 | | the target resource and instead wishes to have it applied to a different resource, such as when the resource has been moved |
| 1506 | | to a different URI, then the origin server <em class="bcp14">MUST</em> send an appropriate <a href="#status.3xx" class="smpl">3xx (Redirection)</a> response; the user agent <em class="bcp14">MAY</em> then make its own decision regarding whether or not to redirect the request. |
| 1507 | | </p> |
| 1508 | | <p id="rfc.section.4.3.4.p.10">A PUT request applied to the target resource can have side-effects on other resources. For example, an article might have |
| 1509 | | a URI for identifying "the current version" (a resource) that is separate from the URIs identifying each particular version |
| 1510 | | (different resources that at one point shared the same state as the current version resource). A successful PUT request on |
| 1511 | | "the current version" URI might therefore create a new version resource in addition to changing the state of the target resource, |
| 1512 | | and might also cause links to be added between the related resources. |
| 1513 | | </p> |
| 1514 | | <p id="rfc.section.4.3.4.p.11">An origin server that allows PUT on a given target resource <em class="bcp14">MUST</em> send a <a href="#status.400" class="smpl">400 (Bad Request)</a> response to a PUT request that contains a <a href="p5-range.html#header.content-range" class="smpl">Content-Range</a> header field (<a href="p5-range.html#header.content-range" title="Content-Range">Section 4.2</a> of <a href="#Part5" id="rfc.xref.Part5.4"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a>), since the payload is likely to be partial content that has been mistakenly PUT as a full representation. Partial content |
| 1515 | | updates are possible by targeting a separately identified resource with state that overlaps a portion of the larger resource, |
| 1516 | | or by using a different method that has been specifically defined for partial updates (for example, the PATCH method defined |
| 1517 | | in <a href="#RFC5789" id="rfc.xref.RFC5789.1"><cite title="PATCH Method for HTTP">[RFC5789]</cite></a>). |
| 1518 | | </p> |
| 1519 | | <p id="rfc.section.4.3.4.p.12">Responses to the PUT method are not cacheable. If a successful PUT request passes through a cache that has one or more stored |
| 1520 | | responses for the effective request URI, those stored responses will be invalidated (see <a href="p6-cache.html#invalidation" title="Invalidation">Section 4.4</a> of <a href="#Part6" id="rfc.xref.Part6.6"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| 1521 | | </p> |
| 1522 | | <h3 id="rfc.section.4.3.5"><a href="#rfc.section.4.3.5">4.3.5</a> <a id="DELETE" href="#DELETE">DELETE</a></h3> |
| 1523 | | <div id="rfc.iref.d.2"></div> |
| 1524 | | <p id="rfc.section.4.3.5.p.1">The DELETE method requests that the origin server remove the association between the <a href="#resources" class="smpl">target resource</a> and its current functionality. In effect, this method is similar to the rm command in UNIX: it expresses a deletion operation |
| 1525 | | on the URI mapping of the origin server, rather than an expectation that the previously associated information be deleted. |
| 1526 | | </p> |
| 1527 | | <p id="rfc.section.4.3.5.p.2">If the target resource has one or more current representations, they might or might not be destroyed by the origin server, |
| 1528 | | and the associated storage might or might not be reclaimed, depending entirely on the nature of the resource and its implementation |
| 1529 | | by the origin server (which are beyond the scope of this specification). Likewise, other implementation aspects of a resource |
| 1530 | | might need to be deactivated or archived as a result of a DELETE, such as database or gateway connections. In general, it |
| 1531 | | is assumed that the origin server will only allow DELETE on resources for which it has a prescribed mechanism for accomplishing |
| 1532 | | the deletion. |
| 1533 | | </p> |
| 1534 | | <p id="rfc.section.4.3.5.p.3">Relatively few resources allow the DELETE method — its primary use is for remote authoring environments, where the user has |
| 1535 | | some direction regarding its effect. For example, a resource that was previously created using a PUT request, or identified |
| 1536 | | via the Location header field after a <a href="#status.201" class="smpl">201 (Created)</a> response to a POST request, might allow a corresponding DELETE request to undo those actions. Similarly, custom user agent |
| 1537 | | implementations that implement an authoring function, such as revision control clients using HTTP for remote operations, might |
| 1538 | | use DELETE based on an assumption that the server's URI space has been crafted to correspond to a version repository. |
| 1539 | | </p> |
| 1540 | | <p id="rfc.section.4.3.5.p.4">If a DELETE method is successfully applied, the origin server <em class="bcp14">SHOULD</em> send a <a href="#status.202" class="smpl">202 (Accepted)</a> status code if the action will likely succeed but has not yet been enacted, a <a href="#status.204" class="smpl">204 (No Content)</a> status code if the action has been enacted and no further information is to be supplied, or a <a href="#status.200" class="smpl">200 (OK)</a> status code if the action has been enacted and the response message includes a representation describing the status. |
| 1541 | | </p> |
| 1542 | | <p id="rfc.section.4.3.5.p.5">A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause |
| 1543 | | some existing implementations to reject the request. |
| 1544 | | </p> |
| 1545 | | <p id="rfc.section.4.3.5.p.6">Responses to the DELETE method are not cacheable. If a DELETE request passes through a cache that has one or more stored responses |
| 1546 | | for the effective request URI, those stored responses will be invalidated (see <a href="p6-cache.html#invalidation" title="Invalidation">Section 4.4</a> of <a href="#Part6" id="rfc.xref.Part6.7"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| 1547 | | </p> |
| 1548 | | <div id="rfc.iref.c.9"></div> |
| 1549 | | <h3 id="rfc.section.4.3.6"><a href="#rfc.section.4.3.6">4.3.6</a> <a id="CONNECT" href="#CONNECT">CONNECT</a></h3> |
| 1550 | | <p id="rfc.section.4.3.6.p.1">The CONNECT method requests that the recipient establish a tunnel to the destination origin server identified by the request-target |
| 1551 | | and, if successful, thereafter restrict its behavior to blind forwarding of packets, in both directions, until the tunnel |
| 1552 | | is closed. |
| 1553 | | </p> |
| 1554 | | <p id="rfc.section.4.3.6.p.2">CONNECT is intended only for use in requests to a proxy. An origin server that receives a CONNECT request for itself <em class="bcp14">MAY</em> respond with a <a href="#status.2xx" class="smpl">2xx</a> status code to indicate that a connection is established. However, most origin servers do not implement CONNECT. |
| 1555 | | </p> |
| 1556 | | <p id="rfc.section.4.3.6.p.3">A client sending a CONNECT request <em class="bcp14">MUST</em> send the authority form of request-target (<a href="p1-messaging.html#request-target" title="Request Target">Section 5.3</a> of <a href="#Part1" id="rfc.xref.Part1.15"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>); i.e., the request-target consists of only the host name and port number of the tunnel destination, separated by a colon. |
| 1557 | | For example, |
| 1558 | | </p> |
| 1559 | | <div id="rfc.figure.u.18"></div><pre class="text2">CONNECT server.example.com:80 HTTP/1.1 |
| | 1329 | as applying semantics to a <a href="#resources" class="smpl">target resource</a> in much the same way as invoking a defined method on an identified object would apply semantics. The method token is case-sensitive |
| | 1330 | because it might be used as a gateway to object-based systems with case-sensitive method names. |
| | 1331 | </p> |
| | 1332 | <p id="rfc.section.4.1.p.5">Unlike distributed objects, the standardized request methods in HTTP are not resource-specific, since uniform interfaces provide |
| | 1333 | for better visibility and reuse in network-based systems <a href="#REST" id="rfc.xref.REST.2"><cite title="Architectural Styles and the Design of Network-based Software Architectures">[REST]</cite></a>. Once defined, a standardized method ought to have the same semantics when applied to any resource, though each resource |
| | 1334 | determines for itself whether those semantics are implemented or allowed. |
| | 1335 | </p> |
| | 1336 | <p id="rfc.section.4.1.p.6">This specification defines a number of standardized methods that are commonly used in HTTP, as outlined by the following table. |
| | 1337 | By convention, standardized methods are defined in all-uppercase ASCII letters. |
| | 1338 | </p> |
| | 1339 | <div id="rfc.table.1"> |
| | 1340 | <div id="table.of.methods"></div> |
| | 1341 | <table class="tt full left" cellpadding="3" cellspacing="0"> |
| | 1342 | <thead> |
| | 1343 | <tr> |
| | 1344 | <th>Method</th> |
| | 1345 | <th>Description</th> |
| | 1346 | <th>Sec.</th> |
| | 1347 | </tr> |
| | 1348 | </thead> |
| | 1349 | <tbody> |
| | 1350 | <tr> |
| | 1351 | <td class="left">GET</td> |
| | 1352 | <td class="left">Transfer a current representation of the target resource.</td> |
| | 1353 | <td class="left"><a href="#GET" id="rfc.xref.GET.3" title="GET">4.3.1</a></td> |
| | 1354 | </tr> |
| | 1355 | <tr> |
| | 1356 | <td class="left">HEAD</td> |
| | 1357 | <td class="left">Same as GET, but only transfer the status line and header section.</td> |
| | 1358 | <td class="left"><a href="#HEAD" id="rfc.xref.HEAD.1" title="HEAD">4.3.2</a></td> |
| | 1359 | </tr> |
| | 1360 | <tr> |
| | 1361 | <td class="left">POST</td> |
| | 1362 | <td class="left">Perform resource-specific processing on the request payload.</td> |
| | 1363 | <td class="left"><a href="#POST" id="rfc.xref.POST.2" title="POST">4.3.3</a></td> |
| | 1364 | </tr> |
| | 1365 | <tr> |
| | 1366 | <td class="left">PUT</td> |
| | 1367 | <td class="left">Replace all current representations of the target resource with the request payload.</td> |
| | 1368 | <td class="left"><a href="#PUT" id="rfc.xref.PUT.2" title="PUT">4.3.4</a></td> |
| | 1369 | </tr> |
| | 1370 | <tr> |
| | 1371 | <td class="left">DELETE</td> |
| | 1372 | <td class="left">Remove all current representations of the target resource.</td> |
| | 1373 | <td class="left"><a href="#DELETE" id="rfc.xref.DELETE.1" title="DELETE">4.3.5</a></td> |
| | 1374 | </tr> |
| | 1375 | <tr> |
| | 1376 | <td class="left">CONNECT</td> |
| | 1377 | <td class="left">Establish a tunnel to the server identified by the target resource.</td> |
| | 1378 | <td class="left"><a href="#CONNECT" id="rfc.xref.CONNECT.1" title="CONNECT">4.3.6</a></td> |
| | 1379 | </tr> |
| | 1380 | <tr> |
| | 1381 | <td class="left">OPTIONS</td> |
| | 1382 | <td class="left">Describe the communication options for the target resource.</td> |
| | 1383 | <td class="left"><a href="#OPTIONS" id="rfc.xref.OPTIONS.1" title="OPTIONS">4.3.7</a></td> |
| | 1384 | </tr> |
| | 1385 | <tr> |
| | 1386 | <td class="left">TRACE</td> |
| | 1387 | <td class="left">Perform a message loop-back test along the path to the target resource.</td> |
| | 1388 | <td class="left"><a href="#TRACE" id="rfc.xref.TRACE.1" title="TRACE">4.3.8</a></td> |
| | 1389 | </tr> |
| | 1390 | </tbody> |
| | 1391 | </table> |
| | 1392 | </div> |
| | 1393 | <p id="rfc.section.4.1.p.7">All general-purpose servers <em class="bcp14">MUST</em> support the methods GET and HEAD. All other methods are <em class="bcp14">OPTIONAL</em>; when implemented, a server <em class="bcp14">MUST</em> implement the above methods according to the semantics defined for them in <a href="#method.definitions" title="Method Definitions">Section 4.3</a>. |
| | 1394 | </p> |
| | 1395 | <p id="rfc.section.4.1.p.8">Additional methods, outside the scope of this specification, have been standardized for use in HTTP. All such methods ought |
| | 1396 | to be registered within the HTTP Method Registry maintained by IANA, as defined in <a href="#method.registry" title="Method Registry">Section 8.1</a>. |
| | 1397 | </p> |
| | 1398 | <p id="rfc.section.4.1.p.9">The set of methods allowed by a target resource can be listed in an <a href="#header.allow" class="smpl">Allow</a> header field (<a href="#header.allow" id="rfc.xref.header.allow.1" title="Allow">Section 7.4.1</a>). However, the set of allowed methods can change dynamically. When a request method is received that is unrecognized or not |
| | 1399 | implemented by an origin server, the origin server <em class="bcp14">SHOULD</em> respond with the <a href="#status.501" class="smpl">501 (Not Implemented)</a> status code. When a request method is received that is known by an origin server but not allowed for the target resource, |
| | 1400 | the origin server <em class="bcp14">SHOULD</em> respond with the <a href="#status.405" class="smpl">405 (Method Not Allowed)</a> status code. |
| | 1401 | </p> |
| | 1402 | </div> |
| | 1403 | <div id="method.properties"> |
| | 1404 | <h2 id="rfc.section.4.2"><a href="#rfc.section.4.2">4.2</a> <a href="#method.properties">Common Method Properties</a></h2> |
| | 1405 | <div id="safe.methods"> |
| | 1406 | <div id="rfc.iref.s.2"></div> |
| | 1407 | <h3 id="rfc.section.4.2.1"><a href="#rfc.section.4.2.1">4.2.1</a> <a href="#safe.methods">Safe Methods</a></h3> |
| | 1408 | <p id="rfc.section.4.2.1.p.1">Request methods are considered "<dfn>safe</dfn>" if their defined semantics are essentially read-only; i.e., the client does not request, and does not expect, any state |
| | 1409 | change on the origin server as a result of applying a safe method to a target resource. Likewise, reasonable use of a safe |
| | 1410 | method is not expected to cause any harm, loss of property, or unusual burden on the origin server. |
| | 1411 | </p> |
| | 1412 | <p id="rfc.section.4.2.1.p.2">This definition of safe methods does not prevent an implementation from including behavior that is potentially harmful, not |
| | 1413 | entirely read-only, or which causes side-effects while invoking a safe method. What is important, however, is that the client |
| | 1414 | did not request that additional behavior and cannot be held accountable for it. For example, most servers append request information |
| | 1415 | to access log files at the completion of every response, regardless of the method, and that is considered safe even though |
| | 1416 | the log storage might become full and crash the server. Likewise, a safe request initiated by selecting an advertisement on |
| | 1417 | the Web will often have the side-effect of charging an advertising account. |
| | 1418 | </p> |
| | 1419 | <p id="rfc.section.4.2.1.p.3">Of the request methods defined by this specification, the GET, HEAD, OPTIONS, and TRACE methods are defined to be safe.</p> |
| | 1420 | <p id="rfc.section.4.2.1.p.4">The purpose of distinguishing between safe and unsafe methods is to allow automated retrieval processes (spiders) and cache |
| | 1421 | performance optimization (pre-fetching) to work without fear of causing harm. In addition, it allows a user agent to apply |
| | 1422 | appropriate constraints on the automated use of unsafe methods when processing potentially untrusted content. |
| | 1423 | </p> |
| | 1424 | <p id="rfc.section.4.2.1.p.5">A user agent <em class="bcp14">SHOULD</em> distinguish between safe and unsafe methods when presenting potential actions to a user, such that the user can be made aware |
| | 1425 | of an unsafe action before it is requested. |
| | 1426 | </p> |
| | 1427 | <p id="rfc.section.4.2.1.p.6">When a resource is constructed such that parameters within the effective request URI have the effect of selecting an action, |
| | 1428 | it is the resource owner's responsibility to ensure that the action is consistent with the request method semantics. For example, |
| | 1429 | it is common for Web-based content editing software to use actions within query parameters, such as "page?do=delete". If the |
| | 1430 | purpose of such a resource is to perform an unsafe action, then the resource owner <em class="bcp14">MUST</em> disable or disallow that action when it is accessed using a safe request method. Failure to do so will result in unfortunate |
| | 1431 | side-effects when automated processes perform a GET on every URI reference for the sake of link maintenance, pre-fetching, |
| | 1432 | building a search index, etc. |
| | 1433 | </p> |
| | 1434 | </div> |
| | 1435 | <div id="idempotent.methods"> |
| | 1436 | <div id="rfc.iref.i.1"></div> |
| | 1437 | <h3 id="rfc.section.4.2.2"><a href="#rfc.section.4.2.2">4.2.2</a> <a href="#idempotent.methods">Idempotent Methods</a></h3> |
| | 1438 | <p id="rfc.section.4.2.2.p.1">Request methods are considered "<dfn id="idempotent">idempotent</dfn>" if the intended effect of multiple identical requests is the same as for a single request. Of the request methods defined |
| | 1439 | by this specification, the PUT, DELETE, and safe request methods are idempotent. |
| | 1440 | </p> |
| | 1441 | <p id="rfc.section.4.2.2.p.2">Like the definition of safe, the idempotent property only applies to what has been requested by the user; a server is free |
| | 1442 | to log each request separately, retain a revision control history, or implement other non-idempotent side-effects for each |
| | 1443 | idempotent request. |
| | 1444 | </p> |
| | 1445 | <p id="rfc.section.4.2.2.p.3">Idempotent methods are distinguished because the request can be repeated automatically if a communication failure occurs before |
| | 1446 | the client is able to read the server's response. For example, if a client sends a PUT request and the underlying connection |
| | 1447 | is closed before any response is received, then it can establish a new connection and retry the idempotent request because |
| | 1448 | it knows that repeating the request will have the same effect even if the original request succeeded. Note, however, that |
| | 1449 | repeated failures would indicate a problem within the server. |
| | 1450 | </p> |
| | 1451 | </div> |
| | 1452 | <div id="cacheable.methods"> |
| | 1453 | <div id="rfc.iref.c.8"></div> |
| | 1454 | <h3 id="rfc.section.4.2.3"><a href="#rfc.section.4.2.3">4.2.3</a> <a href="#cacheable.methods">Cacheable Methods</a></h3> |
| | 1455 | <p id="rfc.section.4.2.3.p.1">Request methods can be defined as "<dfn id="cacheable">cacheable</dfn>" to indicate that responses to them are allowed to be stored for future reuse; for specific requirements see <a href="#Part6" id="rfc.xref.Part6.1"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>. In general, safe methods that do not depend on a current or authoritative response are defined as cacheable; this specification |
| | 1456 | defines GET, HEAD and POST as cacheable, although the overwhelming majority of cache implementations only support GET and |
| | 1457 | HEAD. |
| | 1458 | </p> |
| | 1459 | </div> |
| | 1460 | </div> |
| | 1461 | <div id="method.definitions"> |
| | 1462 | <h2 id="rfc.section.4.3"><a href="#rfc.section.4.3">4.3</a> <a href="#method.definitions">Method Definitions</a></h2> |
| | 1463 | <div id="GET"> |
| | 1464 | <h3 id="rfc.section.4.3.1"><a href="#rfc.section.4.3.1">4.3.1</a> <a href="#GET">GET</a></h3> |
| | 1465 | <div id="rfc.iref.g.16"></div> |
| | 1466 | <p id="rfc.section.4.3.1.p.1">The GET method requests transfer of a current selected representation for the <a href="#resources" class="smpl">target resource</a>. GET is the primary mechanism of information retrieval and the focus of almost all performance optimizations. Hence, when |
| | 1467 | people speak of retrieving some identifiable information via HTTP, they are generally referring to making a GET request. |
| | 1468 | </p> |
| | 1469 | <p id="rfc.section.4.3.1.p.2">It is tempting to think of resource identifiers as remote filesystem pathnames, and of representations as being a copy of |
| | 1470 | the contents of such files. In fact, that is how many resources are implemented (see <a href="#attack.pathname" title="Attacks Based On File and Path Names">Section 9.1</a> for related security considerations). However, there are no such limitations in practice. The HTTP interface for a resource |
| | 1471 | is just as likely to be implemented as a tree of content objects, a programmatic view on various database records, or a gateway |
| | 1472 | to other information systems. Even when the URI mapping mechanism is tied to a filesystem, an origin server might be configured |
| | 1473 | to execute the files with the request as input and send the output as the representation, rather than transfer the files directly. |
| | 1474 | Regardless, only the origin server needs to know how each of its resource identifiers corresponds to an implementation, and |
| | 1475 | how each implementation manages to select and send a current representation of the target resource in a response to GET. |
| | 1476 | </p> |
| | 1477 | <p id="rfc.section.4.3.1.p.3">A client can alter the semantics of GET to be a "range request", requesting transfer of only some part(s) of the selected |
| | 1478 | representation, by sending a <a href="p5-range.html#header.range" class="smpl">Range</a> header field in the request (<a href="#Part5" id="rfc.xref.Part5.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a>). |
| | 1479 | </p> |
| | 1480 | <p id="rfc.section.4.3.1.p.4">A payload within a GET request message has no defined semantics; sending a payload body on a GET request might cause some |
| | 1481 | existing implementations to reject the request. |
| | 1482 | </p> |
| | 1483 | <p id="rfc.section.4.3.1.p.5">The response to a GET request is cacheable; a cache <em class="bcp14">MAY</em> use it to satisfy subsequent GET and HEAD requests unless otherwise indicated by the Cache-Control header field (<a href="p6-cache.html#header.cache-control" title="Cache-Control">Section 5.2</a> of <a href="#Part6" id="rfc.xref.Part6.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| | 1484 | </p> |
| | 1485 | </div> |
| | 1486 | <div id="HEAD"> |
| | 1487 | <h3 id="rfc.section.4.3.2"><a href="#rfc.section.4.3.2">4.3.2</a> <a href="#HEAD">HEAD</a></h3> |
| | 1488 | <div id="rfc.iref.h.1"></div> |
| | 1489 | <p id="rfc.section.4.3.2.p.1">The HEAD method is identical to GET except that the server <em class="bcp14">MUST NOT</em> send a message body in the response (i.e., the response terminates at the end of the header section). The server <em class="bcp14">SHOULD</em> send the same header fields in response to a HEAD request as it would have sent if the request had been a GET, except that |
| | 1490 | the payload header fields (<a href="#payload" title="Payload Semantics">Section 3.3</a>) <em class="bcp14">MAY</em> be omitted. This method can be used for obtaining metadata about the selected representation without transferring the representation |
| | 1491 | data and is often used for testing hypertext links for validity, accessibility, and recent modification. |
| | 1492 | </p> |
| | 1493 | <p id="rfc.section.4.3.2.p.2">A payload within a HEAD request message has no defined semantics; sending a payload body on a HEAD request might cause some |
| | 1494 | existing implementations to reject the request. |
| | 1495 | </p> |
| | 1496 | <p id="rfc.section.4.3.2.p.3">The response to a HEAD request is cacheable; a cache <em class="bcp14">MAY</em> use it to satisfy subsequent HEAD requests unless otherwise indicated by the Cache-Control header field (<a href="p6-cache.html#header.cache-control" title="Cache-Control">Section 5.2</a> of <a href="#Part6" id="rfc.xref.Part6.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). A HEAD response might also have an effect on previously cached responses to GET; see <a href="p6-cache.html#head.effects" title="Freshening Responses via HEAD">Section 4.3.5</a> of <a href="#Part6" id="rfc.xref.Part6.4"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>. |
| | 1497 | </p> |
| | 1498 | </div> |
| | 1499 | <div id="POST"> |
| | 1500 | <div id="rfc.iref.p.2"></div> |
| | 1501 | <h3 id="rfc.section.4.3.3"><a href="#rfc.section.4.3.3">4.3.3</a> <a href="#POST">POST</a></h3> |
| | 1502 | <p id="rfc.section.4.3.3.p.1">The POST method requests that the <a href="#resources" class="smpl">target resource</a> process the representation enclosed in the request according to the resource's own specific semantics. For example, POST is |
| | 1503 | used for the following functions (among others): |
| | 1504 | </p> |
| | 1505 | <ul> |
| | 1506 | <li>Providing a block of data, such as the fields entered into an HTML form, to a data-handling process;</li> |
| | 1507 | <li>Posting a message to a bulletin board, newsgroup, mailing list, blog, or similar group of articles;</li> |
| | 1508 | <li>Creating a new resource that has yet to be identified by the origin server; and</li> |
| | 1509 | <li>Appending data to a resource's existing representation(s).</li> |
| | 1510 | </ul> |
| | 1511 | <p id="rfc.section.4.3.3.p.2">An origin server indicates response semantics by choosing an appropriate status code depending on the result of processing |
| | 1512 | the POST request; almost all of the status codes defined by this specification might be received in a response to POST (the |
| | 1513 | exceptions being 206, 304, and 416). |
| | 1514 | </p> |
| | 1515 | <p id="rfc.section.4.3.3.p.3">If one or more resources has been created on the origin server as a result of successfully processing a POST request, the |
| | 1516 | origin server <em class="bcp14">SHOULD</em> send a <a href="#status.201" class="smpl">201 (Created)</a> response containing a <a href="#header.location" class="smpl">Location</a> header field that provides an identifier for the primary resource created (<a href="#header.location" id="rfc.xref.header.location.1" title="Location">Section 7.1.2</a>) and a representation that describes the status of the request while referring to the new resource(s). |
| | 1517 | </p> |
| | 1518 | <p id="rfc.section.4.3.3.p.4">Responses to POST requests are only cacheable when they include explicit freshness information (see <a href="p6-cache.html#calculating.freshness.lifetime" title="Calculating Freshness Lifetime">Section 4.2.1</a> of <a href="#Part6" id="rfc.xref.Part6.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). However, POST caching is not widely implemented. For cases where an origin server wishes the client to be able to cache |
| | 1519 | the result of a POST in a way that can be reused by a later GET, the origin server <em class="bcp14">MAY</em> send a <a href="#status.200" class="smpl">200 (OK)</a> response containing the result and a <a href="#header.content-location" class="smpl">Content-Location</a> header field that has the same value as the POST's effective request URI (<a href="#header.content-location" id="rfc.xref.header.content-location.2" title="Content-Location">Section 3.1.4.2</a>). |
| | 1520 | </p> |
| | 1521 | <p id="rfc.section.4.3.3.p.5">If the result of processing a POST would be equivalent to a representation of an existing resource, an origin server <em class="bcp14">MAY</em> redirect the user agent to that resource by sending a <a href="#status.303" class="smpl">303 (See Other)</a> response with the existing resource's identifier in the <a href="#header.location" class="smpl">Location</a> field. This has the benefits of providing the user agent a resource identifier and transferring the representation via a method |
| | 1522 | more amenable to shared caching, though at the cost of an extra request if the user agent does not already have the representation |
| | 1523 | cached. |
| | 1524 | </p> |
| | 1525 | </div> |
| | 1526 | <div id="PUT"> |
| | 1527 | <h3 id="rfc.section.4.3.4"><a href="#rfc.section.4.3.4">4.3.4</a> <a href="#PUT">PUT</a></h3> |
| | 1528 | <div id="rfc.iref.p.3"></div> |
| | 1529 | <p id="rfc.section.4.3.4.p.1">The PUT method requests that the state of the <a href="#resources" class="smpl">target resource</a> be created or replaced with the state defined by the representation enclosed in the request message payload. A successful |
| | 1530 | PUT of a given representation would suggest that a subsequent GET on that same target resource will result in an equivalent |
| | 1531 | representation being sent in a <a href="#status.200" class="smpl">200 (OK)</a> response. However, there is no guarantee that such a state change will be observable, since the target resource might be acted |
| | 1532 | upon by other user agents in parallel, or might be subject to dynamic processing by the origin server, before any subsequent |
| | 1533 | GET is received. A successful response only implies that the user agent's intent was achieved at the time of its processing |
| | 1534 | by the origin server. |
| | 1535 | </p> |
| | 1536 | <p id="rfc.section.4.3.4.p.2">If the target resource does not have a current representation and the PUT successfully creates one, then the origin server <em class="bcp14">MUST</em> inform the user agent by sending a <a href="#status.201" class="smpl">201 (Created)</a> response. If the target resource does have a current representation and that representation is successfully modified in accordance |
| | 1537 | with the state of the enclosed representation, then the origin server <em class="bcp14">MUST</em> send either a <a href="#status.200" class="smpl">200 (OK)</a> or a <a href="#status.204" class="smpl">204 (No Content)</a> response to indicate successful completion of the request. |
| | 1538 | </p> |
| | 1539 | <p id="rfc.section.4.3.4.p.3">An origin server <em class="bcp14">SHOULD</em> ignore unrecognized header fields received in a PUT request (i.e., do not save them as part of the resource state). |
| | 1540 | </p> |
| | 1541 | <p id="rfc.section.4.3.4.p.4">An origin server <em class="bcp14">SHOULD</em> verify that the PUT representation is consistent with any constraints the server has for the target resource that cannot or |
| | 1542 | will not be changed by the PUT. This is particularly important when the origin server uses internal configuration information |
| | 1543 | related to the URI in order to set the values for representation metadata on GET responses. When a PUT representation is inconsistent |
| | 1544 | with the target resource, the origin server <em class="bcp14">SHOULD</em> either make them consistent, by transforming the representation or changing the resource configuration, or respond with an |
| | 1545 | appropriate error message containing sufficient information to explain why the representation is unsuitable. The <a href="#status.409" class="smpl">409 (Conflict)</a> or <a href="#status.415" class="smpl">415 (Unsupported Media Type)</a> status codes are suggested, with the latter being specific to constraints on <a href="#header.content-type" class="smpl">Content-Type</a> values. |
| | 1546 | </p> |
| | 1547 | <p id="rfc.section.4.3.4.p.5">For example, if the target resource is configured to always have a <a href="#header.content-type" class="smpl">Content-Type</a> of "text/html" and the representation being PUT has a Content-Type of "image/jpeg", the origin server ought to do one of: |
| | 1548 | </p> |
| | 1549 | <ol class="la"> |
| | 1550 | <li>reconfigure the target resource to reflect the new media type;</li> |
| | 1551 | <li>transform the PUT representation to a format consistent with that of the resource before saving it as the new resource state; |
| | 1552 | or, |
| | 1553 | </li> |
| | 1554 | <li>reject the request with a <a href="#status.415" class="smpl">415 (Unsupported Media Type)</a> response indicating that the target resource is limited to "text/html", perhaps including a link to a different resource that |
| | 1555 | would be a suitable target for the new representation. |
| | 1556 | </li> |
| | 1557 | </ol> |
| | 1558 | <p id="rfc.section.4.3.4.p.6">HTTP does not define exactly how a PUT method affects the state of an origin server beyond what can be expressed by the intent |
| | 1559 | of the user agent request and the semantics of the origin server response. It does not define what a resource might be, in |
| | 1560 | any sense of that word, beyond the interface provided via HTTP. It does not define how resource state is "stored", nor how |
| | 1561 | such storage might change as a result of a change in resource state, nor how the origin server translates resource state into |
| | 1562 | representations. Generally speaking, all implementation details behind the resource interface are intentionally hidden by |
| | 1563 | the server. |
| | 1564 | </p> |
| | 1565 | <p id="rfc.section.4.3.4.p.7">An origin server <em class="bcp14">MUST NOT</em> send a validator header field (<a href="#response.validator" title="Validator Header Fields">Section 7.2</a>), such as an <a href="p4-conditional.html#header.etag" class="smpl">ETag</a> or <a href="p4-conditional.html#header.last-modified" class="smpl">Last-Modified</a> field, in a successful response to PUT unless the request's representation data was saved without any transformation applied |
| | 1566 | to the body (i.e., the resource's new representation data is identical to the representation data received in the PUT request) |
| | 1567 | and the validator field value reflects the new representation. This requirement allows a user agent to know when the representation |
| | 1568 | body it has in memory remains current as a result of the PUT, thus not in need of retrieving again from the origin server, |
| | 1569 | and that the new validator(s) received in the response can be used for future conditional requests in order to prevent accidental |
| | 1570 | overwrites (<a href="#request.conditionals" title="Conditionals">Section 5.2</a>). |
| | 1571 | </p> |
| | 1572 | <p id="rfc.section.4.3.4.p.8">The fundamental difference between the POST and PUT methods is highlighted by the different intent for the enclosed representation. |
| | 1573 | The target resource in a POST request is intended to handle the enclosed representation according to the resource's own semantics, |
| | 1574 | whereas the enclosed representation in a PUT request is defined as replacing the state of the target resource. Hence, the |
| | 1575 | intent of PUT is idempotent and visible to intermediaries, even though the exact effect is only known by the origin server. |
| | 1576 | </p> |
| | 1577 | <p id="rfc.section.4.3.4.p.9">Proper interpretation of a PUT request presumes that the user agent knows which target resource is desired. A service that |
| | 1578 | selects a proper URI on behalf of the client, after receiving a state-changing request, <em class="bcp14">SHOULD</em> be implemented using the POST method rather than PUT. If the origin server will not make the requested PUT state change to |
| | 1579 | the target resource and instead wishes to have it applied to a different resource, such as when the resource has been moved |
| | 1580 | to a different URI, then the origin server <em class="bcp14">MUST</em> send an appropriate <a href="#status.3xx" class="smpl">3xx (Redirection)</a> response; the user agent <em class="bcp14">MAY</em> then make its own decision regarding whether or not to redirect the request. |
| | 1581 | </p> |
| | 1582 | <p id="rfc.section.4.3.4.p.10">A PUT request applied to the target resource can have side-effects on other resources. For example, an article might have |
| | 1583 | a URI for identifying "the current version" (a resource) that is separate from the URIs identifying each particular version |
| | 1584 | (different resources that at one point shared the same state as the current version resource). A successful PUT request on |
| | 1585 | "the current version" URI might therefore create a new version resource in addition to changing the state of the target resource, |
| | 1586 | and might also cause links to be added between the related resources. |
| | 1587 | </p> |
| | 1588 | <p id="rfc.section.4.3.4.p.11">An origin server that allows PUT on a given target resource <em class="bcp14">MUST</em> send a <a href="#status.400" class="smpl">400 (Bad Request)</a> response to a PUT request that contains a <a href="p5-range.html#header.content-range" class="smpl">Content-Range</a> header field (<a href="p5-range.html#header.content-range" title="Content-Range">Section 4.2</a> of <a href="#Part5" id="rfc.xref.Part5.4"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a>), since the payload is likely to be partial content that has been mistakenly PUT as a full representation. Partial content |
| | 1589 | updates are possible by targeting a separately identified resource with state that overlaps a portion of the larger resource, |
| | 1590 | or by using a different method that has been specifically defined for partial updates (for example, the PATCH method defined |
| | 1591 | in <a href="#RFC5789" id="rfc.xref.RFC5789.1"><cite title="PATCH Method for HTTP">[RFC5789]</cite></a>). |
| | 1592 | </p> |
| | 1593 | <p id="rfc.section.4.3.4.p.12">Responses to the PUT method are not cacheable. If a successful PUT request passes through a cache that has one or more stored |
| | 1594 | responses for the effective request URI, those stored responses will be invalidated (see <a href="p6-cache.html#invalidation" title="Invalidation">Section 4.4</a> of <a href="#Part6" id="rfc.xref.Part6.6"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| | 1595 | </p> |
| | 1596 | </div> |
| | 1597 | <div id="DELETE"> |
| | 1598 | <h3 id="rfc.section.4.3.5"><a href="#rfc.section.4.3.5">4.3.5</a> <a href="#DELETE">DELETE</a></h3> |
| | 1599 | <div id="rfc.iref.d.2"></div> |
| | 1600 | <p id="rfc.section.4.3.5.p.1">The DELETE method requests that the origin server remove the association between the <a href="#resources" class="smpl">target resource</a> and its current functionality. In effect, this method is similar to the rm command in UNIX: it expresses a deletion operation |
| | 1601 | on the URI mapping of the origin server, rather than an expectation that the previously associated information be deleted. |
| | 1602 | </p> |
| | 1603 | <p id="rfc.section.4.3.5.p.2">If the target resource has one or more current representations, they might or might not be destroyed by the origin server, |
| | 1604 | and the associated storage might or might not be reclaimed, depending entirely on the nature of the resource and its implementation |
| | 1605 | by the origin server (which are beyond the scope of this specification). Likewise, other implementation aspects of a resource |
| | 1606 | might need to be deactivated or archived as a result of a DELETE, such as database or gateway connections. In general, it |
| | 1607 | is assumed that the origin server will only allow DELETE on resources for which it has a prescribed mechanism for accomplishing |
| | 1608 | the deletion. |
| | 1609 | </p> |
| | 1610 | <p id="rfc.section.4.3.5.p.3">Relatively few resources allow the DELETE method — its primary use is for remote authoring environments, where the user has |
| | 1611 | some direction regarding its effect. For example, a resource that was previously created using a PUT request, or identified |
| | 1612 | via the Location header field after a <a href="#status.201" class="smpl">201 (Created)</a> response to a POST request, might allow a corresponding DELETE request to undo those actions. Similarly, custom user agent |
| | 1613 | implementations that implement an authoring function, such as revision control clients using HTTP for remote operations, might |
| | 1614 | use DELETE based on an assumption that the server's URI space has been crafted to correspond to a version repository. |
| | 1615 | </p> |
| | 1616 | <p id="rfc.section.4.3.5.p.4">If a DELETE method is successfully applied, the origin server <em class="bcp14">SHOULD</em> send a <a href="#status.202" class="smpl">202 (Accepted)</a> status code if the action will likely succeed but has not yet been enacted, a <a href="#status.204" class="smpl">204 (No Content)</a> status code if the action has been enacted and no further information is to be supplied, or a <a href="#status.200" class="smpl">200 (OK)</a> status code if the action has been enacted and the response message includes a representation describing the status. |
| | 1617 | </p> |
| | 1618 | <p id="rfc.section.4.3.5.p.5">A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause |
| | 1619 | some existing implementations to reject the request. |
| | 1620 | </p> |
| | 1621 | <p id="rfc.section.4.3.5.p.6">Responses to the DELETE method are not cacheable. If a DELETE request passes through a cache that has one or more stored responses |
| | 1622 | for the effective request URI, those stored responses will be invalidated (see <a href="p6-cache.html#invalidation" title="Invalidation">Section 4.4</a> of <a href="#Part6" id="rfc.xref.Part6.7"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| | 1623 | </p> |
| | 1624 | </div> |
| | 1625 | <div id="CONNECT"> |
| | 1626 | <div id="rfc.iref.c.9"></div> |
| | 1627 | <h3 id="rfc.section.4.3.6"><a href="#rfc.section.4.3.6">4.3.6</a> <a href="#CONNECT">CONNECT</a></h3> |
| | 1628 | <p id="rfc.section.4.3.6.p.1">The CONNECT method requests that the recipient establish a tunnel to the destination origin server identified by the request-target |
| | 1629 | and, if successful, thereafter restrict its behavior to blind forwarding of packets, in both directions, until the tunnel |
| | 1630 | is closed. |
| | 1631 | </p> |
| | 1632 | <p id="rfc.section.4.3.6.p.2">CONNECT is intended only for use in requests to a proxy. An origin server that receives a CONNECT request for itself <em class="bcp14">MAY</em> respond with a <a href="#status.2xx" class="smpl">2xx</a> status code to indicate that a connection is established. However, most origin servers do not implement CONNECT. |
| | 1633 | </p> |
| | 1634 | <p id="rfc.section.4.3.6.p.3">A client sending a CONNECT request <em class="bcp14">MUST</em> send the authority form of request-target (<a href="p1-messaging.html#request-target" title="Request Target">Section 5.3</a> of <a href="#Part1" id="rfc.xref.Part1.15"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>); i.e., the request-target consists of only the host name and port number of the tunnel destination, separated by a colon. |
| | 1635 | For example, |
| | 1636 | </p> |
| | 1637 | <div id="rfc.figure.u.18"></div><pre class="text2">CONNECT server.example.com:80 HTTP/1.1 |
| 1577 | | or reserved TCP port that is not intended for Web traffic. For example, a CONNECT to a request-target of "example.com:25" |
| 1578 | | would suggest that the proxy connect to the reserved port for SMTP traffic; if allowed, that could trick the proxy into relaying |
| 1579 | | spam email. Proxies that support CONNECT <em class="bcp14">SHOULD</em> restrict its use to a limited set of known ports or a configurable whitelist of safe request targets. |
| 1580 | | </p> |
| 1581 | | <p id="rfc.section.4.3.6.p.10">A server <em class="bcp14">MUST NOT</em> send any <a href="p1-messaging.html#header.transfer-encoding" class="smpl">Transfer-Encoding</a> or <a href="p1-messaging.html#header.content-length" class="smpl">Content-Length</a> header fields in a <a href="#status.2xx" class="smpl">2xx (Successful)</a> response to CONNECT. A client <em class="bcp14">MUST</em> ignore any Content-Length or Transfer-Encoding header fields received in a successful response to CONNECT. |
| 1582 | | </p> |
| 1583 | | <p id="rfc.section.4.3.6.p.11">A payload within a CONNECT request message has no defined semantics; sending a payload body on a CONNECT request might cause |
| 1584 | | some existing implementations to reject the request. |
| 1585 | | </p> |
| 1586 | | <p id="rfc.section.4.3.6.p.12">Responses to the CONNECT method are not cacheable.</p> |
| 1587 | | <h3 id="rfc.section.4.3.7"><a href="#rfc.section.4.3.7">4.3.7</a> <a id="OPTIONS" href="#OPTIONS">OPTIONS</a></h3> |
| 1588 | | <div id="rfc.iref.o.1"></div> |
| 1589 | | <p id="rfc.section.4.3.7.p.1">The OPTIONS method requests information about the communication options available for the target resource, either at the origin |
| 1590 | | server or an intervening intermediary. This method allows a client to determine the options and/or requirements associated |
| 1591 | | with a resource, or the capabilities of a server, without implying a resource action. |
| 1592 | | </p> |
| 1593 | | <p id="rfc.section.4.3.7.p.2">An OPTIONS request with an asterisk ("*") as the request-target (<a href="p1-messaging.html#request-target" title="Request Target">Section 5.3</a> of <a href="#Part1" id="rfc.xref.Part1.16"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>) applies to the server in general rather than to a specific resource. Since a server's communication options typically depend |
| 1594 | | on the resource, the "*" request is only useful as a "ping" or "no-op" type of method; it does nothing beyond allowing the |
| 1595 | | client to test the capabilities of the server. For example, this can be used to test a proxy for HTTP/1.1 conformance (or |
| 1596 | | lack thereof). |
| 1597 | | </p> |
| 1598 | | <p id="rfc.section.4.3.7.p.3">If the request-target is not an asterisk, the OPTIONS request applies to the options that are available when communicating |
| 1599 | | with the target resource. |
| 1600 | | </p> |
| 1601 | | <p id="rfc.section.4.3.7.p.4">A server generating a successful response to OPTIONS <em class="bcp14">SHOULD</em> send any header fields that might indicate optional features implemented by the server and applicable to the target resource |
| 1602 | | (e.g., <a href="#header.allow" class="smpl">Allow</a>), including potential extensions not defined by this specification. The response payload, if any, might also describe the |
| 1603 | | communication options in a machine or human-readable representation. A standard format for such a representation is not defined |
| 1604 | | by this specification, but might be defined by future extensions to HTTP. A server <em class="bcp14">MUST</em> generate a <a href="p1-messaging.html#header.content-length" class="smpl">Content-Length</a> field with a value of "0" if no payload body is to be sent in the response. |
| 1605 | | </p> |
| 1606 | | <p id="rfc.section.4.3.7.p.5">A client <em class="bcp14">MAY</em> send a <a href="#header.max-forwards" class="smpl">Max-Forwards</a> header field in an OPTIONS request to target a specific recipient in the request chain (see <a href="#header.max-forwards" id="rfc.xref.header.max-forwards.1" title="Max-Forwards">Section 5.1.2</a>). A proxy <em class="bcp14">MUST NOT</em> generate a Max-Forwards header field while forwarding a request unless that request was received with a Max-Forwards field. |
| 1607 | | </p> |
| 1608 | | <p id="rfc.section.4.3.7.p.6">A client that generates an OPTIONS request containing a payload body <em class="bcp14">MUST</em> send a valid <a href="#header.content-type" class="smpl">Content-Type</a> header field describing the representation media type. Although this specification does not define any use for such a payload, |
| 1609 | | future extensions to HTTP might use the OPTIONS body to make more detailed queries about the target resource. |
| 1610 | | </p> |
| 1611 | | <p id="rfc.section.4.3.7.p.7">Responses to the OPTIONS method are not cacheable.</p> |
| 1612 | | <h3 id="rfc.section.4.3.8"><a href="#rfc.section.4.3.8">4.3.8</a> <a id="TRACE" href="#TRACE">TRACE</a></h3> |
| 1613 | | <div id="rfc.iref.t.1"></div> |
| 1614 | | <p id="rfc.section.4.3.8.p.1">The TRACE method requests a remote, application-level loop-back of the request message. The final recipient of the request <em class="bcp14">SHOULD</em> reflect the message received, excluding some fields described below, back to the client as the message body of a <a href="#status.200" class="smpl">200 (OK)</a> response with a <a href="#header.content-type" class="smpl">Content-Type</a> of "message/http" (<a href="p1-messaging.html#internet.media.type.message.http" title="Internet Media Type message/http">Section 8.3.1</a> of <a href="#Part1" id="rfc.xref.Part1.17"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). The final recipient is either the origin server or the first server to receive a <a href="#header.max-forwards" class="smpl">Max-Forwards</a> value of zero (0) in the request (<a href="#header.max-forwards" id="rfc.xref.header.max-forwards.2" title="Max-Forwards">Section 5.1.2</a>). |
| 1615 | | </p> |
| 1616 | | <p id="rfc.section.4.3.8.p.2">A client <em class="bcp14">MUST NOT</em> generate header fields in a TRACE request containing sensitive data that might be disclosed by the response. For example, |
| 1617 | | it would be foolish for a user agent to send stored user credentials <a href="#Part7" id="rfc.xref.Part7.1"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">[Part7]</cite></a> or cookies <a href="#RFC6265" id="rfc.xref.RFC6265.1"><cite title="HTTP State Management Mechanism">[RFC6265]</cite></a> in a TRACE request. The final recipient of the request <em class="bcp14">SHOULD</em> exclude any request header fields that are likely to contain sensitive data when that recipient generates the response body. |
| 1618 | | </p> |
| 1619 | | <p id="rfc.section.4.3.8.p.3">TRACE allows the client to see what is being received at the other end of the request chain and use that data for testing |
| 1620 | | or diagnostic information. The value of the <a href="p1-messaging.html#header.via" class="smpl">Via</a> header field (<a href="p1-messaging.html#header.via" title="Via">Section 5.7.1</a> of <a href="#Part1" id="rfc.xref.Part1.18"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>) is of particular interest, since it acts as a trace of the request chain. Use of the <a href="#header.max-forwards" class="smpl">Max-Forwards</a> header field allows the client to limit the length of the request chain, which is useful for testing a chain of proxies forwarding |
| 1621 | | messages in an infinite loop. |
| 1622 | | </p> |
| 1623 | | <p id="rfc.section.4.3.8.p.4">A client <em class="bcp14">MUST NOT</em> send a message body in a TRACE request. |
| 1624 | | </p> |
| 1625 | | <p id="rfc.section.4.3.8.p.5">Responses to the TRACE method are not cacheable.</p> |
| 1626 | | <h1 id="rfc.section.5"><a href="#rfc.section.5">5.</a> <a id="request.header.fields" href="#request.header.fields">Request Header Fields</a></h1> |
| 1627 | | <p id="rfc.section.5.p.1">A client sends request header fields to provide more information about the request context, make the request conditional based |
| 1628 | | on the target resource state, suggest preferred formats for the response, supply authentication credentials, or modify the |
| 1629 | | expected request processing. These fields act as request modifiers, similar to the parameters on a programming language method |
| 1630 | | invocation. |
| 1631 | | </p> |
| 1632 | | <h2 id="rfc.section.5.1"><a href="#rfc.section.5.1">5.1</a> <a id="request.controls" href="#request.controls">Controls</a></h2> |
| 1633 | | <p id="rfc.section.5.1.p.1">Controls are request header fields that direct specific handling of the request.</p> |
| 1634 | | <div id="rfc.table.u.3"> |
| 1635 | | <table class="tt full left" cellpadding="3" cellspacing="0"> |
| 1636 | | <thead> |
| 1637 | | <tr> |
| 1638 | | <th>Header Field Name</th> |
| 1639 | | <th>Defined in...</th> |
| 1640 | | </tr> |
| 1641 | | </thead> |
| 1642 | | <tbody> |
| 1643 | | <tr> |
| 1644 | | <td class="left">Cache-Control</td> |
| 1645 | | <td class="left"><a href="p6-cache.html#header.cache-control" title="Cache-Control">Section 5.2</a> of <a href="#Part6" id="rfc.xref.Part6.8"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a></td> |
| 1646 | | </tr> |
| 1647 | | <tr> |
| 1648 | | <td class="left">Expect</td> |
| 1649 | | <td class="left"><a href="#header.expect" id="rfc.xref.header.expect.1" title="Expect">Section 5.1.1</a></td> |
| 1650 | | </tr> |
| 1651 | | <tr> |
| 1652 | | <td class="left">Host</td> |
| 1653 | | <td class="left"><a href="p1-messaging.html#header.host" title="Host">Section 5.4</a> of <a href="#Part1" id="rfc.xref.Part1.19"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a></td> |
| 1654 | | </tr> |
| 1655 | | <tr> |
| 1656 | | <td class="left">Max-Forwards</td> |
| 1657 | | <td class="left"><a href="#header.max-forwards" id="rfc.xref.header.max-forwards.3" title="Max-Forwards">Section 5.1.2</a></td> |
| 1658 | | </tr> |
| 1659 | | <tr> |
| 1660 | | <td class="left">Pragma</td> |
| 1661 | | <td class="left"><a href="p6-cache.html#header.pragma" title="Pragma">Section 5.4</a> of <a href="#Part6" id="rfc.xref.Part6.9"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a></td> |
| 1662 | | </tr> |
| 1663 | | <tr> |
| 1664 | | <td class="left">Range</td> |
| 1665 | | <td class="left"><a href="p5-range.html#header.range" title="Range">Section 3.1</a> of <a href="#Part5" id="rfc.xref.Part5.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a></td> |
| 1666 | | </tr> |
| 1667 | | <tr> |
| 1668 | | <td class="left">TE</td> |
| 1669 | | <td class="left"><a href="p1-messaging.html#header.te" title="TE">Section 4.3</a> of <a href="#Part1" id="rfc.xref.Part1.20"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a></td> |
| 1670 | | </tr> |
| 1671 | | </tbody> |
| 1672 | | </table> |
| | 1655 | or reserved TCP port that is not intended for Web traffic. For example, a CONNECT to a request-target of "example.com:25" |
| | 1656 | would suggest that the proxy connect to the reserved port for SMTP traffic; if allowed, that could trick the proxy into relaying |
| | 1657 | spam email. Proxies that support CONNECT <em class="bcp14">SHOULD</em> restrict its use to a limited set of known ports or a configurable whitelist of safe request targets. |
| | 1658 | </p> |
| | 1659 | <p id="rfc.section.4.3.6.p.10">A server <em class="bcp14">MUST NOT</em> send any <a href="p1-messaging.html#header.transfer-encoding" class="smpl">Transfer-Encoding</a> or <a href="p1-messaging.html#header.content-length" class="smpl">Content-Length</a> header fields in a <a href="#status.2xx" class="smpl">2xx (Successful)</a> response to CONNECT. A client <em class="bcp14">MUST</em> ignore any Content-Length or Transfer-Encoding header fields received in a successful response to CONNECT. |
| | 1660 | </p> |
| | 1661 | <p id="rfc.section.4.3.6.p.11">A payload within a CONNECT request message has no defined semantics; sending a payload body on a CONNECT request might cause |
| | 1662 | some existing implementations to reject the request. |
| | 1663 | </p> |
| | 1664 | <p id="rfc.section.4.3.6.p.12">Responses to the CONNECT method are not cacheable.</p> |
| | 1665 | </div> |
| | 1666 | <div id="OPTIONS"> |
| | 1667 | <h3 id="rfc.section.4.3.7"><a href="#rfc.section.4.3.7">4.3.7</a> <a href="#OPTIONS">OPTIONS</a></h3> |
| | 1668 | <div id="rfc.iref.o.1"></div> |
| | 1669 | <p id="rfc.section.4.3.7.p.1">The OPTIONS method requests information about the communication options available for the target resource, either at the origin |
| | 1670 | server or an intervening intermediary. This method allows a client to determine the options and/or requirements associated |
| | 1671 | with a resource, or the capabilities of a server, without implying a resource action. |
| | 1672 | </p> |
| | 1673 | <p id="rfc.section.4.3.7.p.2">An OPTIONS request with an asterisk ("*") as the request-target (<a href="p1-messaging.html#request-target" title="Request Target">Section 5.3</a> of <a href="#Part1" id="rfc.xref.Part1.16"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>) applies to the server in general rather than to a specific resource. Since a server's communication options typically depend |
| | 1674 | on the resource, the "*" request is only useful as a "ping" or "no-op" type of method; it does nothing beyond allowing the |
| | 1675 | client to test the capabilities of the server. For example, this can be used to test a proxy for HTTP/1.1 conformance (or |
| | 1676 | lack thereof). |
| | 1677 | </p> |
| | 1678 | <p id="rfc.section.4.3.7.p.3">If the request-target is not an asterisk, the OPTIONS request applies to the options that are available when communicating |
| | 1679 | with the target resource. |
| | 1680 | </p> |
| | 1681 | <p id="rfc.section.4.3.7.p.4">A server generating a successful response to OPTIONS <em class="bcp14">SHOULD</em> send any header fields that might indicate optional features implemented by the server and applicable to the target resource |
| | 1682 | (e.g., <a href="#header.allow" class="smpl">Allow</a>), including potential extensions not defined by this specification. The response payload, if any, might also describe the |
| | 1683 | communication options in a machine or human-readable representation. A standard format for such a representation is not defined |
| | 1684 | by this specification, but might be defined by future extensions to HTTP. A server <em class="bcp14">MUST</em> generate a <a href="p1-messaging.html#header.content-length" class="smpl">Content-Length</a> field with a value of "0" if no payload body is to be sent in the response. |
| | 1685 | </p> |
| | 1686 | <p id="rfc.section.4.3.7.p.5">A client <em class="bcp14">MAY</em> send a <a href="#header.max-forwards" class="smpl">Max-Forwards</a> header field in an OPTIONS request to target a specific recipient in the request chain (see <a href="#header.max-forwards" id="rfc.xref.header.max-forwards.1" title="Max-Forwards">Section 5.1.2</a>). A proxy <em class="bcp14">MUST NOT</em> generate a Max-Forwards header field while forwarding a request unless that request was received with a Max-Forwards field. |
| | 1687 | </p> |
| | 1688 | <p id="rfc.section.4.3.7.p.6">A client that generates an OPTIONS request containing a payload body <em class="bcp14">MUST</em> send a valid <a href="#header.content-type" class="smpl">Content-Type</a> header field describing the representation media type. Although this specification does not define any use for such a payload, |
| | 1689 | future extensions to HTTP might use the OPTIONS body to make more detailed queries about the target resource. |
| | 1690 | </p> |
| | 1691 | <p id="rfc.section.4.3.7.p.7">Responses to the OPTIONS method are not cacheable.</p> |
| | 1692 | </div> |
| | 1693 | <div id="TRACE"> |
| | 1694 | <h3 id="rfc.section.4.3.8"><a href="#rfc.section.4.3.8">4.3.8</a> <a href="#TRACE">TRACE</a></h3> |
| | 1695 | <div id="rfc.iref.t.1"></div> |
| | 1696 | <p id="rfc.section.4.3.8.p.1">The TRACE method requests a remote, application-level loop-back of the request message. The final recipient of the request <em class="bcp14">SHOULD</em> reflect the message received, excluding some fields described below, back to the client as the message body of a <a href="#status.200" class="smpl">200 (OK)</a> response with a <a href="#header.content-type" class="smpl">Content-Type</a> of "message/http" (<a href="p1-messaging.html#internet.media.type.message.http" title="Internet Media Type message/http">Section 8.3.1</a> of <a href="#Part1" id="rfc.xref.Part1.17"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). The final recipient is either the origin server or the first server to receive a <a href="#header.max-forwards" class="smpl">Max-Forwards</a> value of zero (0) in the request (<a href="#header.max-forwards" id="rfc.xref.header.max-forwards.2" title="Max-Forwards">Section 5.1.2</a>). |
| | 1697 | </p> |
| | 1698 | <p id="rfc.section.4.3.8.p.2">A client <em class="bcp14">MUST NOT</em> generate header fields in a TRACE request containing sensitive data that might be disclosed by the response. For example, |
| | 1699 | it would be foolish for a user agent to send stored user credentials <a href="#Part7" id="rfc.xref.Part7.1"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">[Part7]</cite></a> or cookies <a href="#RFC6265" id="rfc.xref.RFC6265.1"><cite title="HTTP State Management Mechanism">[RFC6265]</cite></a> in a TRACE request. The final recipient of the request <em class="bcp14">SHOULD</em> exclude any request header fields that are likely to contain sensitive data when that recipient generates the response body. |
| | 1700 | </p> |
| | 1701 | <p id="rfc.section.4.3.8.p.3">TRACE allows the client to see what is being received at the other end of the request chain and use that data for testing |
| | 1702 | or diagnostic information. The value of the <a href="p1-messaging.html#header.via" class="smpl">Via</a> header field (<a href="p1-messaging.html#header.via" title="Via">Section 5.7.1</a> of <a href="#Part1" id="rfc.xref.Part1.18"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>) is of particular interest, since it acts as a trace of the request chain. Use of the <a href="#header.max-forwards" class="smpl">Max-Forwards</a> header field allows the client to limit the length of the request chain, which is useful for testing a chain of proxies forwarding |
| | 1703 | messages in an infinite loop. |
| | 1704 | </p> |
| | 1705 | <p id="rfc.section.4.3.8.p.4">A client <em class="bcp14">MUST NOT</em> send a message body in a TRACE request. |
| | 1706 | </p> |
| | 1707 | <p id="rfc.section.4.3.8.p.5">Responses to the TRACE method are not cacheable.</p> |
| | 1708 | </div> |
| | 1709 | </div> |
| 2013 | | <p id="rfc.section.5.3.5.p.6">A request without any Accept-Language header field implies that the user agent will accept any language in response. If the |
| 2014 | | header field is present in a request and none of the available representations for the response have a matching language tag, |
| 2015 | | the origin server can either disregard the header field by treating the response as if it is not subject to content negotiation, |
| 2016 | | or honor the header field by sending a <a href="#status.406" class="smpl">406 (Not Acceptable)</a> response. However, the latter is not encouraged, as doing so can prevent users from accessing content that they might be able |
| 2017 | | to use (with translation software, for example). |
| 2018 | | </p> |
| 2019 | | <p id="rfc.section.5.3.5.p.7">Note that some recipients treat the order in which language tags are listed as an indication of descending priority, particularly |
| 2020 | | for tags that are assigned equal quality values (no value is the same as q=1). However, this behavior cannot be relied upon. |
| 2021 | | For consistency and to maximize interoperability, many user agents assign each language tag a unique quality value while also |
| 2022 | | listing them in order of decreasing quality. Additional discussion of language priority lists can be found in <a href="http://tools.ietf.org/html/rfc4647#section-2.3">Section 2.3</a> of <a href="#RFC4647" id="rfc.xref.RFC4647.2"><cite title="Matching of Language Tags">[RFC4647]</cite></a>. |
| 2023 | | </p> |
| 2024 | | <p id="rfc.section.5.3.5.p.8">For matching, <a href="http://tools.ietf.org/html/rfc4647#section-3">Section 3</a> of <a href="#RFC4647" id="rfc.xref.RFC4647.3"><cite title="Matching of Language Tags">[RFC4647]</cite></a> defines several matching schemes. Implementations can offer the most appropriate matching scheme for their requirements. The |
| 2025 | | "Basic Filtering" scheme (<a href="#RFC4647" id="rfc.xref.RFC4647.4"><cite title="Matching of Language Tags">[RFC4647]</cite></a>, <a href="http://tools.ietf.org/html/rfc4647#section-3.3.1">Section 3.3.1</a>) is identical to the matching scheme that was previously defined for HTTP in <a href="http://tools.ietf.org/html/rfc2616#section-14.4">Section 14.4</a> of <a href="#RFC2616" id="rfc.xref.RFC2616.1"><cite title="Hypertext Transfer Protocol -- HTTP/1.1">[RFC2616]</cite></a>. |
| 2026 | | </p> |
| 2027 | | <p id="rfc.section.5.3.5.p.9">It might be contrary to the privacy expectations of the user to send an Accept-Language header field with the complete linguistic |
| 2028 | | preferences of the user in every request (<a href="#fingerprinting" title="Browser Fingerprinting">Section 9.6</a>). |
| 2029 | | </p> |
| 2030 | | <p id="rfc.section.5.3.5.p.10">Since intelligibility is highly dependent on the individual user, user agents need to allow user control over the linguistic |
| 2031 | | preference. A user agent that does not provide such control to the user <em class="bcp14">MUST NOT</em> send an Accept-Language header field. |
| 2032 | | </p> |
| 2033 | | <div class="note" id="rfc.section.5.3.5.p.11"> |
| 2034 | | <p><b>Note:</b> User agents ought to provide guidance to users when setting a preference, since users are rarely familiar with the details |
| 2035 | | of language matching as described above. For example, users might assume that on selecting "en-gb", they will be served any |
| 2036 | | kind of English document if British English is not available. A user agent might suggest, in such a case, to add "en" to the |
| 2037 | | list for better matching behavior. |
| 2038 | | </p> |
| 2039 | | </div> |
| 2040 | | <h2 id="rfc.section.5.4"><a href="#rfc.section.5.4">5.4</a> <a id="request.auth" href="#request.auth">Authentication Credentials</a></h2> |
| 2041 | | <p id="rfc.section.5.4.p.1">Two header fields are used for carrying authentication credentials, as defined in <a href="#Part7" id="rfc.xref.Part7.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">[Part7]</cite></a>. Note that various custom mechanisms for user authentication use the Cookie header field for this purpose, as defined in <a href="#RFC6265" id="rfc.xref.RFC6265.2"><cite title="HTTP State Management Mechanism">[RFC6265]</cite></a>. |
| 2042 | | </p> |
| 2043 | | <div id="rfc.table.u.7"> |
| 2044 | | <table class="tt full left" cellpadding="3" cellspacing="0"> |
| 2045 | | <thead> |
| 2046 | | <tr> |
| 2047 | | <th>Header Field Name</th> |
| 2048 | | <th>Defined in...</th> |
| 2049 | | </tr> |
| 2050 | | </thead> |
| 2051 | | <tbody> |
| 2052 | | <tr> |
| 2053 | | <td class="left">Authorization</td> |
| 2054 | | <td class="left"><a href="p7-auth.html#header.authorization" title="Authorization">Section 4.1</a> of <a href="#Part7" id="rfc.xref.Part7.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">[Part7]</cite></a></td> |
| 2055 | | </tr> |
| 2056 | | <tr> |
| 2057 | | <td class="left">Proxy-Authorization</td> |
| 2058 | | <td class="left"><a href="p7-auth.html#header.proxy-authorization" title="Proxy-Authorization">Section 4.3</a> of <a href="#Part7" id="rfc.xref.Part7.4"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">[Part7]</cite></a></td> |
| 2059 | | </tr> |
| 2060 | | </tbody> |
| 2061 | | </table> |
| 2062 | | </div> |
| 2063 | | <h2 id="rfc.section.5.5"><a href="#rfc.section.5.5">5.5</a> <a id="request.context" href="#request.context">Request Context</a></h2> |
| 2064 | | <p id="rfc.section.5.5.p.1">The following request header fields provide additional information about the request context, including information about |
| 2065 | | the user, user agent, and resource behind the request. |
| 2066 | | </p> |
| 2067 | | <div id="rfc.table.u.8"> |
| 2068 | | <table class="tt full left" cellpadding="3" cellspacing="0"> |
| 2069 | | <thead> |
| 2070 | | <tr> |
| 2071 | | <th>Header Field Name</th> |
| 2072 | | <th>Defined in...</th> |
| 2073 | | </tr> |
| 2074 | | </thead> |
| 2075 | | <tbody> |
| 2076 | | <tr> |
| 2077 | | <td class="left">From</td> |
| 2078 | | <td class="left"><a href="#header.from" id="rfc.xref.header.from.1" title="From">Section 5.5.1</a></td> |
| 2079 | | </tr> |
| 2080 | | <tr> |
| 2081 | | <td class="left">Referer</td> |
| 2082 | | <td class="left"><a href="#header.referer" id="rfc.xref.header.referer.1" title="Referer">Section 5.5.2</a></td> |
| 2083 | | </tr> |
| 2084 | | <tr> |
| 2085 | | <td class="left">User-Agent</td> |
| 2086 | | <td class="left"><a href="#header.user-agent" id="rfc.xref.header.user-agent.1" title="User-Agent">Section 5.5.3</a></td> |
| 2087 | | </tr> |
| 2088 | | </tbody> |
| 2089 | | </table> |
| 2090 | | </div> |
| 2091 | | <div id="rfc.iref.f.1"></div> |
| 2092 | | <h3 id="rfc.section.5.5.1"><a href="#rfc.section.5.5.1">5.5.1</a> <a id="header.from" href="#header.from">From</a></h3> |
| 2093 | | <p id="rfc.section.5.5.1.p.1">The "From" header field contains an Internet email address for a human user who controls the requesting user agent. The address |
| 2094 | | ought to be machine-usable, as defined by "mailbox" in <a href="http://tools.ietf.org/html/rfc5322#section-3.4">Section 3.4</a> of <a href="#RFC5322" id="rfc.xref.RFC5322.1"><cite title="Internet Message Format">[RFC5322]</cite></a>: |
| 2095 | | </p> |
| 2096 | | <div id="rfc.figure.u.35"></div><pre class="inline"><span id="rfc.iref.g.30"></span> <a href="#header.from" class="smpl">From</a> = <a href="#header.from" class="smpl">mailbox</a> |
| | 2117 | <p id="rfc.section.5.3.5.p.6">A request without any Accept-Language header field implies that the user agent will accept any language in response. If the |
| | 2118 | header field is present in a request and none of the available representations for the response have a matching language tag, |
| | 2119 | the origin server can either disregard the header field by treating the response as if it is not subject to content negotiation, |
| | 2120 | or honor the header field by sending a <a href="#status.406" class="smpl">406 (Not Acceptable)</a> response. However, the latter is not encouraged, as doing so can prevent users from accessing content that they might be able |
| | 2121 | to use (with translation software, for example). |
| | 2122 | </p> |
| | 2123 | <p id="rfc.section.5.3.5.p.7">Note that some recipients treat the order in which language tags are listed as an indication of descending priority, particularly |
| | 2124 | for tags that are assigned equal quality values (no value is the same as q=1). However, this behavior cannot be relied upon. |
| | 2125 | For consistency and to maximize interoperability, many user agents assign each language tag a unique quality value while also |
| | 2126 | listing them in order of decreasing quality. Additional discussion of language priority lists can be found in <a href="http://tools.ietf.org/html/rfc4647#section-2.3">Section 2.3</a> of <a href="#RFC4647" id="rfc.xref.RFC4647.2"><cite title="Matching of Language Tags">[RFC4647]</cite></a>. |
| | 2127 | </p> |
| | 2128 | <p id="rfc.section.5.3.5.p.8">For matching, <a href="http://tools.ietf.org/html/rfc4647#section-3">Section 3</a> of <a href="#RFC4647" id="rfc.xref.RFC4647.3"><cite title="Matching of Language Tags">[RFC4647]</cite></a> defines several matching schemes. Implementations can offer the most appropriate matching scheme for their requirements. The |
| | 2129 | "Basic Filtering" scheme (<a href="#RFC4647" id="rfc.xref.RFC4647.4"><cite title="Matching of Language Tags">[RFC4647]</cite></a>, <a href="http://tools.ietf.org/html/rfc4647#section-3.3.1">Section 3.3.1</a>) is identical to the matching scheme that was previously defined for HTTP in <a href="http://tools.ietf.org/html/rfc2616#section-14.4">Section 14.4</a> of <a href="#RFC2616" id="rfc.xref.RFC2616.1"><cite title="Hypertext Transfer Protocol -- HTTP/1.1">[RFC2616]</cite></a>. |
| | 2130 | </p> |
| | 2131 | <p id="rfc.section.5.3.5.p.9">It might be contrary to the privacy expectations of the user to send an Accept-Language header field with the complete linguistic |
| | 2132 | preferences of the user in every request (<a href="#fingerprinting" title="Browser Fingerprinting">Section 9.6</a>). |
| | 2133 | </p> |
| | 2134 | <p id="rfc.section.5.3.5.p.10">Since intelligibility is highly dependent on the individual user, user agents need to allow user control over the linguistic |
| | 2135 | preference. A user agent that does not provide such control to the user <em class="bcp14">MUST NOT</em> send an Accept-Language header field. |
| | 2136 | </p> |
| | 2137 | <div class="note" id="rfc.section.5.3.5.p.11"> |
| | 2138 | <p><b>Note:</b> User agents ought to provide guidance to users when setting a preference, since users are rarely familiar with the details |
| | 2139 | of language matching as described above. For example, users might assume that on selecting "en-gb", they will be served any |
| | 2140 | kind of English document if British English is not available. A user agent might suggest, in such a case, to add "en" to the |
| | 2141 | list for better matching behavior. |
| | 2142 | </p> |
| | 2143 | </div> |
| | 2144 | </div> |
| | 2145 | </div> |
| | 2146 | <div id="request.auth"> |
| | 2147 | <h2 id="rfc.section.5.4"><a href="#rfc.section.5.4">5.4</a> <a href="#request.auth">Authentication Credentials</a></h2> |
| | 2148 | <p id="rfc.section.5.4.p.1">Two header fields are used for carrying authentication credentials, as defined in <a href="#Part7" id="rfc.xref.Part7.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">[Part7]</cite></a>. Note that various custom mechanisms for user authentication use the Cookie header field for this purpose, as defined in <a href="#RFC6265" id="rfc.xref.RFC6265.2"><cite title="HTTP State Management Mechanism">[RFC6265]</cite></a>. |
| | 2149 | </p> |
| | 2150 | <div id="rfc.table.u.7"> |
| | 2151 | <table class="tt full left" cellpadding="3" cellspacing="0"> |
| | 2152 | <thead> |
| | 2153 | <tr> |
| | 2154 | <th>Header Field Name</th> |
| | 2155 | <th>Defined in...</th> |
| | 2156 | </tr> |
| | 2157 | </thead> |
| | 2158 | <tbody> |
| | 2159 | <tr> |
| | 2160 | <td class="left">Authorization</td> |
| | 2161 | <td class="left"><a href="p7-auth.html#header.authorization" title="Authorization">Section 4.1</a> of <a href="#Part7" id="rfc.xref.Part7.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">[Part7]</cite></a></td> |
| | 2162 | </tr> |
| | 2163 | <tr> |
| | 2164 | <td class="left">Proxy-Authorization</td> |
| | 2165 | <td class="left"><a href="p7-auth.html#header.proxy-authorization" title="Proxy-Authorization">Section 4.3</a> of <a href="#Part7" id="rfc.xref.Part7.4"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">[Part7]</cite></a></td> |
| | 2166 | </tr> |
| | 2167 | </tbody> |
| | 2168 | </table> |
| | 2169 | </div> |
| | 2170 | </div> |
| | 2171 | <div id="request.context"> |
| | 2172 | <h2 id="rfc.section.5.5"><a href="#rfc.section.5.5">5.5</a> <a href="#request.context">Request Context</a></h2> |
| | 2173 | <p id="rfc.section.5.5.p.1">The following request header fields provide additional information about the request context, including information about |
| | 2174 | the user, user agent, and resource behind the request. |
| | 2175 | </p> |
| | 2176 | <div id="rfc.table.u.8"> |
| | 2177 | <table class="tt full left" cellpadding="3" cellspacing="0"> |
| | 2178 | <thead> |
| | 2179 | <tr> |
| | 2180 | <th>Header Field Name</th> |
| | 2181 | <th>Defined in...</th> |
| | 2182 | </tr> |
| | 2183 | </thead> |
| | 2184 | <tbody> |
| | 2185 | <tr> |
| | 2186 | <td class="left">From</td> |
| | 2187 | <td class="left"><a href="#header.from" id="rfc.xref.header.from.1" title="From">Section 5.5.1</a></td> |
| | 2188 | </tr> |
| | 2189 | <tr> |
| | 2190 | <td class="left">Referer</td> |
| | 2191 | <td class="left"><a href="#header.referer" id="rfc.xref.header.referer.1" title="Referer">Section 5.5.2</a></td> |
| | 2192 | </tr> |
| | 2193 | <tr> |
| | 2194 | <td class="left">User-Agent</td> |
| | 2195 | <td class="left"><a href="#header.user-agent" id="rfc.xref.header.user-agent.1" title="User-Agent">Section 5.5.3</a></td> |
| | 2196 | </tr> |
| | 2197 | </tbody> |
| | 2198 | </table> |
| | 2199 | </div> |
| | 2200 | <div id="header.from"> |
| | 2201 | <div id="rfc.iref.f.1"></div> |
| | 2202 | <h3 id="rfc.section.5.5.1"><a href="#rfc.section.5.5.1">5.5.1</a> <a href="#header.from">From</a></h3> |
| | 2203 | <p id="rfc.section.5.5.1.p.1">The "From" header field contains an Internet email address for a human user who controls the requesting user agent. The address |
| | 2204 | ought to be machine-usable, as defined by "mailbox" in <a href="http://tools.ietf.org/html/rfc5322#section-3.4">Section 3.4</a> of <a href="#RFC5322" id="rfc.xref.RFC5322.1"><cite title="Internet Message Format">[RFC5322]</cite></a>: |
| | 2205 | </p> |
| | 2206 | <div id="rfc.figure.u.35"></div><pre class="inline"><span id="rfc.iref.g.30"></span> <a href="#header.from" class="smpl">From</a> = <a href="#header.from" class="smpl">mailbox</a> |
| 2155 | | and the risk of a user being identified against their wishes ("fingerprinting"). |
| 2156 | | </p> |
| 2157 | | <p id="rfc.section.5.5.3.p.9">Likewise, implementations are encouraged not to use the product tokens of other implementations in order to declare compatibility |
| 2158 | | with them, as this circumvents the purpose of the field. If a user agent masquerades as a different user agent, recipients |
| 2159 | | can assume that the user intentionally desires to see responses tailored for that identified user agent, even if they might |
| 2160 | | not work as well for the actual user agent being used. |
| 2161 | | </p> |
| 2162 | | <h1 id="rfc.section.6"><a href="#rfc.section.6">6.</a> <a id="status.codes" href="#status.codes">Response Status Codes</a></h1> |
| 2163 | | <p id="rfc.section.6.p.1">The status-code element is a 3-digit integer code giving the result of the attempt to understand and satisfy the request.</p> |
| 2164 | | <p id="rfc.section.6.p.2">HTTP status codes are extensible. HTTP clients are not required to understand the meaning of all registered status codes, |
| 2165 | | though such understanding is obviously desirable. However, a client <em class="bcp14">MUST</em> understand the class of any status code, as indicated by the first digit, and treat an unrecognized status code as being equivalent |
| 2166 | | to the x00 status code of that class, with the exception that a recipient <em class="bcp14">MUST NOT</em> cache a response with an unrecognized status code. |
| 2167 | | </p> |
| 2168 | | <p id="rfc.section.6.p.3">For example, if an unrecognized status code of 471 is received by a client, the client can assume that there was something |
| 2169 | | wrong with its request and treat the response as if it had received a 400 status code. The response message will usually contain |
| 2170 | | a representation that explains the status. |
| 2171 | | </p> |
| 2172 | | <p id="rfc.section.6.p.4">The first digit of the status-code defines the class of response. The last two digits do not have any categorization role. |
| 2173 | | There are 5 values for the first digit: |
| 2174 | | </p> |
| 2175 | | <ul> |
| 2176 | | <li><a href="#status.1xx" class="smpl">1xx (Informational)</a>: The request was received, continuing process |
| 2177 | | </li> |
| 2178 | | <li><a href="#status.2xx" class="smpl">2xx (Successful)</a>: The request was successfully received, understood, and accepted |
| 2179 | | </li> |
| 2180 | | <li><a href="#status.3xx" class="smpl">3xx (Redirection)</a>: Further action needs to be taken in order to complete the request |
| 2181 | | </li> |
| 2182 | | <li><a href="#status.4xx" class="smpl">4xx (Client Error)</a>: The request contains bad syntax or cannot be fulfilled |
| 2183 | | </li> |
| 2184 | | <li><a href="#status.5xx" class="smpl">5xx (Server Error)</a>: The server failed to fulfill an apparently valid request |
| 2185 | | </li> |
| 2186 | | </ul> |
| 2187 | | <h2 id="rfc.section.6.1"><a href="#rfc.section.6.1">6.1</a> <a id="overview.of.status.codes" href="#overview.of.status.codes">Overview of Status Codes</a></h2> |
| 2188 | | <p id="rfc.section.6.1.p.1">The status codes listed below are defined in this specification, <a href="p4-conditional.html#status.code.definitions" title="Status Code Definitions">Section 4</a> of <a href="#Part4" id="rfc.xref.Part4.9"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests">[Part4]</cite></a>, <a href="p5-range.html#range.response" title="Responses to a Range Request">Section 4</a> of <a href="#Part5" id="rfc.xref.Part5.7"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a>, and <a href="p7-auth.html#status.code.definitions" title="Status Code Definitions">Section 3</a> of <a href="#Part7" id="rfc.xref.Part7.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">[Part7]</cite></a>. The reason phrases listed here are only recommendations — they can be replaced by local equivalents without affecting the |
| 2189 | | protocol. |
| 2190 | | </p> |
| 2191 | | <p id="rfc.section.6.1.p.2">Responses with status codes that are defined as cacheable by default (e.g., 200, 203, 206, 300, 301, and 410 in this specification) |
| 2192 | | can be reused by a cache with heuristic expiration unless otherwise indicated by the method definition or explicit cache controls <a href="#Part6" id="rfc.xref.Part6.10"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>; all other status codes are not cacheable by default. |
| 2193 | | </p> |
| 2194 | | <div id="rfc.table.u.9"> |
| 2195 | | <table class="tt full left" cellpadding="3" cellspacing="0"> |
| 2196 | | <thead> |
| 2197 | | <tr> |
| 2198 | | <th>code</th> |
| 2199 | | <th>reason-phrase</th> |
| 2200 | | <th>Defined in...</th> |
| 2201 | | </tr> |
| 2202 | | </thead> |
| 2203 | | <tbody> |
| 2204 | | <tr> |
| 2205 | | <td class="left">100</td> |
| 2206 | | <td class="left">Continue</td> |
| 2207 | | <td class="left"><a href="#status.100" id="rfc.xref.status.100.1" title="100 Continue">Section 6.2.1</a></td> |
| 2208 | | </tr> |
| 2209 | | <tr> |
| 2210 | | <td class="left">101</td> |
| 2211 | | <td class="left">Switching Protocols</td> |
| 2212 | | <td class="left"><a href="#status.101" id="rfc.xref.status.101.1" title="101 Switching Protocols">Section 6.2.2</a></td> |
| 2213 | | </tr> |
| 2214 | | <tr> |
| 2215 | | <td class="left">200</td> |
| 2216 | | <td class="left">OK</td> |
| 2217 | | <td class="left"><a href="#status.200" id="rfc.xref.status.200.1" title="200 OK">Section 6.3.1</a></td> |
| 2218 | | </tr> |
| 2219 | | <tr> |
| 2220 | | <td class="left">201</td> |
| 2221 | | <td class="left">Created</td> |
| 2222 | | <td class="left"><a href="#status.201" id="rfc.xref.status.201.1" title="201 Created">Section 6.3.2</a></td> |
| 2223 | | </tr> |
| 2224 | | <tr> |
| 2225 | | <td class="left">202</td> |
| 2226 | | <td class="left">Accepted</td> |
| 2227 | | <td class="left"><a href="#status.202" id="rfc.xref.status.202.1" title="202 Accepted">Section 6.3.3</a></td> |
| 2228 | | </tr> |
| 2229 | | <tr> |
| 2230 | | <td class="left">203</td> |
| 2231 | | <td class="left">Non-Authoritative Information</td> |
| 2232 | | <td class="left"><a href="#status.203" id="rfc.xref.status.203.1" title="203 Non-Authoritative Information">Section 6.3.4</a></td> |
| 2233 | | </tr> |
| 2234 | | <tr> |
| 2235 | | <td class="left">204</td> |
| 2236 | | <td class="left">No Content</td> |
| 2237 | | <td class="left"><a href="#status.204" id="rfc.xref.status.204.1" title="204 No Content">Section 6.3.5</a></td> |
| 2238 | | </tr> |
| 2239 | | <tr> |
| 2240 | | <td class="left">205</td> |
| 2241 | | <td class="left">Reset Content</td> |
| 2242 | | <td class="left"><a href="#status.205" id="rfc.xref.status.205.1" title="205 Reset Content">Section 6.3.6</a></td> |
| 2243 | | </tr> |
| 2244 | | <tr> |
| 2245 | | <td class="left">206</td> |
| 2246 | | <td class="left">Partial Content</td> |
| 2247 | | <td id="status.206" class="left"><a href="p5-range.html#status.206" title="206 Partial Content">Section 4.1</a> of <a href="#Part5" id="rfc.xref.Part5.8"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a></td> |
| 2248 | | </tr> |
| 2249 | | <tr> |
| 2250 | | <td class="left">300</td> |
| 2251 | | <td class="left">Multiple Choices</td> |
| 2252 | | <td class="left"><a href="#status.300" id="rfc.xref.status.300.1" title="300 Multiple Choices">Section 6.4.1</a></td> |
| 2253 | | </tr> |
| 2254 | | <tr> |
| 2255 | | <td class="left">301</td> |
| 2256 | | <td class="left">Moved Permanently</td> |
| 2257 | | <td class="left"><a href="#status.301" id="rfc.xref.status.301.1" title="301 Moved Permanently">Section 6.4.2</a></td> |
| 2258 | | </tr> |
| 2259 | | <tr> |
| 2260 | | <td class="left">302</td> |
| 2261 | | <td class="left">Found</td> |
| 2262 | | <td class="left"><a href="#status.302" id="rfc.xref.status.302.1" title="302 Found">Section 6.4.3</a></td> |
| 2263 | | </tr> |
| 2264 | | <tr> |
| 2265 | | <td class="left">303</td> |
| 2266 | | <td class="left">See Other</td> |
| 2267 | | <td class="left"><a href="#status.303" id="rfc.xref.status.303.1" title="303 See Other">Section 6.4.4</a></td> |
| 2268 | | </tr> |
| 2269 | | <tr> |
| 2270 | | <td class="left">304</td> |
| 2271 | | <td class="left">Not Modified</td> |
| 2272 | | <td id="status.304" class="left"><a href="p4-conditional.html#status.304" title="304 Not Modified">Section 4.1</a> of <a href="#Part4" id="rfc.xref.Part4.10"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests">[Part4]</cite></a></td> |
| 2273 | | </tr> |
| 2274 | | <tr> |
| 2275 | | <td class="left">305</td> |
| 2276 | | <td class="left">Use Proxy</td> |
| 2277 | | <td class="left"><a href="#status.305" id="rfc.xref.status.305.1" title="305 Use Proxy">Section 6.4.5</a></td> |
| 2278 | | </tr> |
| 2279 | | <tr> |
| 2280 | | <td class="left">307</td> |
| 2281 | | <td class="left">Temporary Redirect</td> |
| 2282 | | <td class="left"><a href="#status.307" id="rfc.xref.status.307.1" title="307 Temporary Redirect">Section 6.4.7</a></td> |
| 2283 | | </tr> |
| 2284 | | <tr> |
| 2285 | | <td class="left">400</td> |
| 2286 | | <td class="left">Bad Request</td> |
| 2287 | | <td class="left"><a href="#status.400" id="rfc.xref.status.400.1" title="400 Bad Request">Section 6.5.1</a></td> |
| 2288 | | </tr> |
| 2289 | | <tr> |
| 2290 | | <td class="left">401</td> |
| 2291 | | <td class="left">Unauthorized</td> |
| 2292 | | <td id="status.401" class="left"><a href="p7-auth.html#status.401" title="401 Unauthorized">Section 3.1</a> of <a href="#Part7" id="rfc.xref.Part7.6"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">[Part7]</cite></a></td> |
| 2293 | | </tr> |
| 2294 | | <tr> |
| 2295 | | <td class="left">402</td> |
| 2296 | | <td class="left">Payment Required</td> |
| 2297 | | <td class="left"><a href="#status.402" id="rfc.xref.status.402.1" title="402 Payment Required">Section 6.5.2</a></td> |
| 2298 | | </tr> |
| 2299 | | <tr> |
| 2300 | | <td class="left">403</td> |
| 2301 | | <td class="left">Forbidden</td> |
| 2302 | | <td class="left"><a href="#status.403" id="rfc.xref.status.403.1" title="403 Forbidden">Section 6.5.3</a></td> |
| 2303 | | </tr> |
| 2304 | | <tr> |
| 2305 | | <td class="left">404</td> |
| 2306 | | <td class="left">Not Found</td> |
| 2307 | | <td class="left"><a href="#status.404" id="rfc.xref.status.404.1" title="404 Not Found">Section 6.5.4</a></td> |
| 2308 | | </tr> |
| 2309 | | <tr> |
| 2310 | | <td class="left">405</td> |
| 2311 | | <td class="left">Method Not Allowed</td> |
| 2312 | | <td class="left"><a href="#status.405" id="rfc.xref.status.405.1" title="405 Method Not Allowed">Section 6.5.5</a></td> |
| 2313 | | </tr> |
| 2314 | | <tr> |
| 2315 | | <td class="left">406</td> |
| 2316 | | <td class="left">Not Acceptable</td> |
| 2317 | | <td class="left"><a href="#status.406" id="rfc.xref.status.406.1" title="406 Not Acceptable">Section 6.5.6</a></td> |
| 2318 | | </tr> |
| 2319 | | <tr> |
| 2320 | | <td class="left">407</td> |
| 2321 | | <td class="left">Proxy Authentication Required</td> |
| 2322 | | <td id="status.407" class="left"><a href="p7-auth.html#status.407" title="407 Proxy Authentication Required">Section 3.2</a> of <a href="#Part7" id="rfc.xref.Part7.7"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">[Part7]</cite></a></td> |
| 2323 | | </tr> |
| 2324 | | <tr> |
| 2325 | | <td class="left">408</td> |
| 2326 | | <td class="left">Request Time-out</td> |
| 2327 | | <td class="left"><a href="#status.408" id="rfc.xref.status.408.1" title="408 Request Timeout">Section 6.5.7</a></td> |
| 2328 | | </tr> |
| 2329 | | <tr> |
| 2330 | | <td class="left">409</td> |
| 2331 | | <td class="left">Conflict</td> |
| 2332 | | <td class="left"><a href="#status.409" id="rfc.xref.status.409.1" title="409 Conflict">Section 6.5.8</a></td> |
| 2333 | | </tr> |
| 2334 | | <tr> |
| 2335 | | <td class="left">410</td> |
| 2336 | | <td class="left">Gone</td> |
| 2337 | | <td class="left"><a href="#status.410" id="rfc.xref.status.410.1" title="410 Gone">Section 6.5.9</a></td> |
| 2338 | | </tr> |
| 2339 | | <tr> |
| 2340 | | <td class="left">411</td> |
| 2341 | | <td class="left">Length Required</td> |
| 2342 | | <td class="left"><a href="#status.411" id="rfc.xref.status.411.1" title="411 Length Required">Section 6.5.10</a></td> |
| 2343 | | </tr> |
| 2344 | | <tr> |
| 2345 | | <td class="left">412</td> |
| 2346 | | <td class="left">Precondition Failed</td> |
| 2347 | | <td id="status.412" class="left"><a href="p4-conditional.html#status.412" title="412 Precondition Failed">Section 4.2</a> of <a href="#Part4" id="rfc.xref.Part4.11"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests">[Part4]</cite></a></td> |
| 2348 | | </tr> |
| 2349 | | <tr> |
| 2350 | | <td class="left">413</td> |
| 2351 | | <td class="left">Payload Too Large</td> |
| 2352 | | <td class="left"><a href="#status.413" id="rfc.xref.status.413.1" title="413 Payload Too Large">Section 6.5.11</a></td> |
| 2353 | | </tr> |
| 2354 | | <tr> |
| 2355 | | <td class="left">414</td> |
| 2356 | | <td class="left">URI Too Long</td> |
| 2357 | | <td class="left"><a href="#status.414" id="rfc.xref.status.414.1" title="414 URI Too Long">Section 6.5.12</a></td> |
| 2358 | | </tr> |
| 2359 | | <tr> |
| 2360 | | <td class="left">415</td> |
| 2361 | | <td class="left">Unsupported Media Type</td> |
| 2362 | | <td class="left"><a href="#status.415" id="rfc.xref.status.415.1" title="415 Unsupported Media Type">Section 6.5.13</a></td> |
| 2363 | | </tr> |
| 2364 | | <tr> |
| 2365 | | <td class="left">416</td> |
| 2366 | | <td class="left">Range Not Satisfiable</td> |
| 2367 | | <td id="status.416" class="left"><a href="p5-range.html#status.416" title="416 Range Not Satisfiable">Section 4.4</a> of <a href="#Part5" id="rfc.xref.Part5.9"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a></td> |
| 2368 | | </tr> |
| 2369 | | <tr> |
| 2370 | | <td class="left">417</td> |
| 2371 | | <td class="left">Expectation Failed</td> |
| 2372 | | <td class="left"><a href="#status.417" id="rfc.xref.status.417.1" title="417 Expectation Failed">Section 6.5.14</a></td> |
| 2373 | | </tr> |
| 2374 | | <tr> |
| 2375 | | <td class="left">426</td> |
| 2376 | | <td class="left">Upgrade Required</td> |
| 2377 | | <td class="left"><a href="#status.426" id="rfc.xref.status.426.1" title="426 Upgrade Required">Section 6.5.15</a></td> |
| 2378 | | </tr> |
| 2379 | | <tr> |
| 2380 | | <td class="left">500</td> |
| 2381 | | <td class="left">Internal Server Error</td> |
| 2382 | | <td class="left"><a href="#status.500" id="rfc.xref.status.500.1" title="500 Internal Server Error">Section 6.6.1</a></td> |
| 2383 | | </tr> |
| 2384 | | <tr> |
| 2385 | | <td class="left">501</td> |
| 2386 | | <td class="left">Not Implemented</td> |
| 2387 | | <td class="left"><a href="#status.501" id="rfc.xref.status.501.1" title="501 Not Implemented">Section 6.6.2</a></td> |
| 2388 | | </tr> |
| 2389 | | <tr> |
| 2390 | | <td class="left">502</td> |
| 2391 | | <td class="left">Bad Gateway</td> |
| 2392 | | <td class="left"><a href="#status.502" id="rfc.xref.status.502.1" title="502 Bad Gateway">Section 6.6.3</a></td> |
| 2393 | | </tr> |
| 2394 | | <tr> |
| 2395 | | <td class="left">503</td> |
| 2396 | | <td class="left">Service Unavailable</td> |
| 2397 | | <td class="left"><a href="#status.503" id="rfc.xref.status.503.1" title="503 Service Unavailable">Section 6.6.4</a></td> |
| 2398 | | </tr> |
| 2399 | | <tr> |
| 2400 | | <td class="left">504</td> |
| 2401 | | <td class="left">Gateway Time-out</td> |
| 2402 | | <td class="left"><a href="#status.504" id="rfc.xref.status.504.1" title="504 Gateway Timeout">Section 6.6.5</a></td> |
| 2403 | | </tr> |
| 2404 | | <tr> |
| 2405 | | <td class="left">505</td> |
| 2406 | | <td class="left">HTTP Version Not Supported</td> |
| 2407 | | <td class="left"><a href="#status.505" id="rfc.xref.status.505.1" title="505 HTTP Version Not Supported">Section 6.6.6</a></td> |
| 2408 | | </tr> |
| 2409 | | </tbody> |
| 2410 | | </table> |
| | 2269 | and the risk of a user being identified against their wishes ("fingerprinting"). |
| | 2270 | </p> |
| | 2271 | <p id="rfc.section.5.5.3.p.9">Likewise, implementations are encouraged not to use the product tokens of other implementations in order to declare compatibility |
| | 2272 | with them, as this circumvents the purpose of the field. If a user agent masquerades as a different user agent, recipients |
| | 2273 | can assume that the user intentionally desires to see responses tailored for that identified user agent, even if they might |
| | 2274 | not work as well for the actual user agent being used. |
| | 2275 | </p> |
| | 2276 | </div> |
| | 2277 | </div> |
| 2412 | | <p id="rfc.section.6.1.p.3">Note that this list is not exhaustive — it does not include extension status codes defined in other specifications. The complete |
| 2413 | | list of status codes is maintained by IANA. See <a href="#status.code.registry" title="Status Code Registry">Section 8.2</a> for details. |
| 2414 | | </p> |
| 2415 | | <h2 id="rfc.section.6.2"><a href="#rfc.section.6.2">6.2</a> <a id="status.1xx" href="#status.1xx">Informational 1xx</a></h2> |
| 2416 | | <div id="rfc.iref.67"></div> |
| 2417 | | <div id="rfc.iref.s.3"></div> |
| 2418 | | <p id="rfc.section.6.2.p.1">The <dfn>1xx (Informational)</dfn> class of status code indicates an interim response for communicating connection status or request progress prior to completing |
| 2419 | | the requested action and sending a final response. All 1xx responses consist of only the status-line and optional header fields, |
| 2420 | | and thus are terminated by the empty line at the end of the header section. Since HTTP/1.0 did not define any 1xx status codes, |
| 2421 | | a server <em class="bcp14">MUST NOT</em> send a 1xx response to an HTTP/1.0 client. |
| 2422 | | </p> |
| 2423 | | <p id="rfc.section.6.2.p.2">A client <em class="bcp14">MUST</em> be able to parse one or more 1xx responses received prior to a final response, even if the client does not expect one. A user |
| 2424 | | agent <em class="bcp14">MAY</em> ignore unexpected 1xx responses. |
| 2425 | | </p> |
| 2426 | | <p id="rfc.section.6.2.p.3">A proxy <em class="bcp14">MUST</em> forward 1xx responses unless the proxy itself requested the generation of the 1xx response. For example, if a proxy adds an |
| 2427 | | "Expect: 100-continue" field when it forwards a request, then it need not forward the corresponding <a href="#status.100" class="smpl">100 (Continue)</a> response(s). |
| 2428 | | </p> |
| 2429 | | <div id="rfc.iref.68"></div> |
| 2430 | | <h3 id="rfc.section.6.2.1"><a href="#rfc.section.6.2.1">6.2.1</a> <a id="status.100" href="#status.100">100 Continue</a></h3> |
| 2431 | | <p id="rfc.section.6.2.1.p.1">The <dfn>100 (Continue)</dfn> status code indicates that the initial part of a request has been received and has not yet been rejected by the server. The |
| 2432 | | server intends to send a final response after the request has been fully received and acted upon. |
| 2433 | | </p> |
| 2434 | | <p id="rfc.section.6.2.1.p.2">When the request contains an <a href="#header.expect" class="smpl">Expect</a> header field that includes a <a href="#header.expect" class="smpl">100-continue</a> expectation, the 100 response indicates that the server wishes to receive the request payload body, as described in <a href="#header.expect" id="rfc.xref.header.expect.2" title="Expect">Section 5.1.1</a>. The client ought to continue sending the request and discard the 100 response. |
| 2435 | | </p> |
| 2436 | | <p id="rfc.section.6.2.1.p.3">If the request did not contain an <a href="#header.expect" class="smpl">Expect</a> header field containing the <a href="#header.expect" class="smpl">100-continue</a> expectation, the client can simply discard this interim response. |
| 2437 | | </p> |
| 2438 | | <div id="rfc.iref.68"></div> |
| 2439 | | <h3 id="rfc.section.6.2.2"><a href="#rfc.section.6.2.2">6.2.2</a> <a id="status.101" href="#status.101">101 Switching Protocols</a></h3> |
| 2440 | | <p id="rfc.section.6.2.2.p.1">The <dfn>101 (Switching Protocols)</dfn> status code indicates that the server understands and is willing to comply with the client's request, via the <a href="p1-messaging.html#header.upgrade" class="smpl">Upgrade</a> header field (<a href="p1-messaging.html#header.upgrade" title="Upgrade">Section 6.7</a> of <a href="#Part1" id="rfc.xref.Part1.23"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>), for a change in the application protocol being used on this connection. The server <em class="bcp14">MUST</em> generate an Upgrade header field in the response that indicates which protocol(s) will be switched to immediately after the |
| 2441 | | empty line that terminates the 101 response. |
| 2442 | | </p> |
| 2443 | | <p id="rfc.section.6.2.2.p.2">It is assumed that the server will only agree to switch protocols when it is advantageous to do so. For example, switching |
| 2444 | | to a newer version of HTTP might be advantageous over older versions, and switching to a real-time, synchronous protocol might |
| 2445 | | be advantageous when delivering resources that use such features. |
| 2446 | | </p> |
| 2447 | | <h2 id="rfc.section.6.3"><a href="#rfc.section.6.3">6.3</a> <a id="status.2xx" href="#status.2xx">Successful 2xx</a></h2> |
| 2448 | | <div id="rfc.iref.68"></div> |
| 2449 | | <div id="rfc.iref.s.4"></div> |
| 2450 | | <p id="rfc.section.6.3.p.1">The <dfn>2xx (Successful)</dfn> class of status code indicates that the client's request was successfully received, understood, and accepted. |
| 2451 | | </p> |
| 2452 | | <div id="rfc.iref.69"></div> |
| 2453 | | <h3 id="rfc.section.6.3.1"><a href="#rfc.section.6.3.1">6.3.1</a> <a id="status.200" href="#status.200">200 OK</a></h3> |
| 2454 | | <p id="rfc.section.6.3.1.p.1">The <dfn>200 (OK)</dfn> status code indicates that the request has succeeded. The payload sent in a 200 response depends on the request method. For |
| 2455 | | the methods defined by this specification, the intended meaning of the payload can be summarized as: |
| 2456 | | </p> |
| 2457 | | <dl> |
| 2458 | | <dt>GET</dt> |
| 2459 | | <dd>a representation of the <a href="#resources" class="smpl">target resource</a>; |
| 2460 | | </dd> |
| 2461 | | <dt>HEAD</dt> |
| 2462 | | <dd>the same representation as GET, but without the representation data;</dd> |
| 2463 | | <dt>POST</dt> |
| 2464 | | <dd>a representation of the status of, or results obtained from, the action;</dd> |
| 2465 | | <dt>PUT, DELETE</dt> |
| 2466 | | <dd>a representation of the status of the action;</dd> |
| 2467 | | <dt>OPTIONS</dt> |
| 2468 | | <dd>a representation of the communications options;</dd> |
| 2469 | | <dt>TRACE</dt> |
| 2470 | | <dd>a representation of the request message as received by the end server.</dd> |
| 2471 | | </dl> |
| 2472 | | <p id="rfc.section.6.3.1.p.2">Aside from responses to CONNECT, a 200 response always has a payload, though an origin server <em class="bcp14">MAY</em> generate a payload body of zero length. If no payload is desired, an origin server ought to send <dfn>204 (No Content)</dfn> instead. For CONNECT, no payload is allowed because the successful result is a tunnel, which begins immediately after the |
| 2473 | | 200 response header section. |
| 2474 | | </p> |
| 2475 | | <p id="rfc.section.6.3.1.p.3">A 200 response is cacheable unless otherwise indicated by the method definition or explicit cache controls (see <a href="p6-cache.html#heuristic.freshness" title="Calculating Heuristic Freshness">Section 4.2.2</a> of <a href="#Part6" id="rfc.xref.Part6.11"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| 2476 | | </p> |
| 2477 | | <div id="rfc.iref.69"></div> |
| 2478 | | <h3 id="rfc.section.6.3.2"><a href="#rfc.section.6.3.2">6.3.2</a> <a id="status.201" href="#status.201">201 Created</a></h3> |
| 2479 | | <p id="rfc.section.6.3.2.p.1">The <dfn>201 (Created)</dfn> status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. The |
| 2480 | | primary resource created by the request is identified by either a <a href="#header.location" class="smpl">Location</a> header field in the response or, if no <a href="#header.location" class="smpl">Location</a> field is received, by the effective request URI. |
| 2481 | | </p> |
| 2482 | | <p id="rfc.section.6.3.2.p.2">The 201 response payload typically describes and links to the resource(s) created. See <a href="#response.validator" title="Validator Header Fields">Section 7.2</a> for a discussion of the meaning and purpose of validator header fields, such as <a href="p4-conditional.html#header.etag" class="smpl">ETag</a> and <a href="p4-conditional.html#header.last-modified" class="smpl">Last-Modified</a>, in a 201 response. |
| 2483 | | </p> |
| 2484 | | <div id="rfc.iref.69"></div> |
| 2485 | | <h3 id="rfc.section.6.3.3"><a href="#rfc.section.6.3.3">6.3.3</a> <a id="status.202" href="#status.202">202 Accepted</a></h3> |
| 2486 | | <p id="rfc.section.6.3.3.p.1">The <dfn>202 (Accepted)</dfn> status code indicates that the request has been accepted for processing, but the processing has not been completed. The request |
| 2487 | | might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility |
| 2488 | | in HTTP for re-sending a status code from an asynchronous operation. |
| 2489 | | </p> |
| 2490 | | <p id="rfc.section.6.3.3.p.2">The 202 response is intentionally non-committal. Its purpose is to allow a server to accept a request for some other process |
| 2491 | | (perhaps a batch-oriented process that is only run once per day) without requiring that the user agent's connection to the |
| 2492 | | server persist until the process is completed. The representation sent with this response ought to describe the request's |
| 2493 | | current status and point to (or embed) a status monitor that can provide the user with an estimate of when the request will |
| 2494 | | be fulfilled. |
| 2495 | | </p> |
| 2496 | | <div id="rfc.iref.69"></div> |
| 2497 | | <h3 id="rfc.section.6.3.4"><a href="#rfc.section.6.3.4">6.3.4</a> <a id="status.203" href="#status.203">203 Non-Authoritative Information</a></h3> |
| 2498 | | <p id="rfc.section.6.3.4.p.1">The <dfn>203 (Non-Authoritative Information)</dfn> status code indicates that the request was successful but the enclosed payload has been modified from that of the origin server's <a href="#status.200" class="smpl">200 (OK)</a> response by a transforming proxy (<a href="p1-messaging.html#message.transformations" title="Transformations">Section 5.7.2</a> of <a href="#Part1" id="rfc.xref.Part1.24"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). This status code allows the proxy to notify recipients when a transformation has been applied, since that knowledge might |
| 2499 | | impact later decisions regarding the content. For example, future cache validation requests for the content might only be |
| 2500 | | applicable along the same request path (through the same proxies). |
| 2501 | | </p> |
| 2502 | | <p id="rfc.section.6.3.4.p.2">The 203 response is similar to the Warning code of 214 Transformation Applied (<a href="p6-cache.html#header.warning" title="Warning">Section 5.5</a> of <a href="#Part6" id="rfc.xref.Part6.12"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>), which has the advantage of being applicable to responses with any status code. |
| 2503 | | </p> |
| 2504 | | <p id="rfc.section.6.3.4.p.3">A 203 response is cacheable unless otherwise indicated by the method definition or explicit cache controls (see <a href="p6-cache.html#heuristic.freshness" title="Calculating Heuristic Freshness">Section 4.2.2</a> of <a href="#Part6" id="rfc.xref.Part6.13"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| 2505 | | </p> |
| 2506 | | <div id="rfc.iref.69"></div> |
| 2507 | | <h3 id="rfc.section.6.3.5"><a href="#rfc.section.6.3.5">6.3.5</a> <a id="status.204" href="#status.204">204 No Content</a></h3> |
| 2508 | | <p id="rfc.section.6.3.5.p.1">The <dfn>204 (No Content)</dfn> status code indicates that the server has successfully fulfilled the request and that there is no additional content to send |
| 2509 | | in the response payload body. Metadata in the response header fields refer to the <a href="#resources" class="smpl">target resource</a> and its <a href="#representations" class="smpl">selected representation</a> after the requested action was applied. |
| 2510 | | </p> |
| 2511 | | <p id="rfc.section.6.3.5.p.2">For example, if a 204 status code is received in response to a PUT request and the response contains an <a href="p4-conditional.html#header.etag" class="smpl">ETag</a> header field, then the PUT was successful and the ETag field-value contains the entity-tag for the new representation of that |
| 2512 | | target resource. |
| 2513 | | </p> |
| 2514 | | <p id="rfc.section.6.3.5.p.3">The 204 response allows a server to indicate that the action has been successfully applied to the target resource, while implying |
| 2515 | | that the user agent does not need to traverse away from its current "document view" (if any). The server assumes that the |
| 2516 | | user agent will provide some indication of the success to its user, in accord with its own interface, and apply any new or |
| 2517 | | updated metadata in the response to its active representation. |
| 2518 | | </p> |
| 2519 | | <p id="rfc.section.6.3.5.p.4">For example, a 204 status code is commonly used with document editing interfaces corresponding to a "save" action, such that |
| 2520 | | the document being saved remains available to the user for editing. It is also frequently used with interfaces that expect |
| 2521 | | automated data transfers to be prevalent, such as within distributed version control systems. |
| 2522 | | </p> |
| 2523 | | <p id="rfc.section.6.3.5.p.5">A 204 response is terminated by the first empty line after the header fields because it cannot contain a message body.</p> |
| 2524 | | <p id="rfc.section.6.3.5.p.6">A 204 response is cacheable unless otherwise indicated by the method definition or explicit cache controls (see <a href="p6-cache.html#heuristic.freshness" title="Calculating Heuristic Freshness">Section 4.2.2</a> of <a href="#Part6" id="rfc.xref.Part6.14"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| 2525 | | </p> |
| 2526 | | <div id="rfc.iref.69"></div> |
| 2527 | | <h3 id="rfc.section.6.3.6"><a href="#rfc.section.6.3.6">6.3.6</a> <a id="status.205" href="#status.205">205 Reset Content</a></h3> |
| 2528 | | <p id="rfc.section.6.3.6.p.1">The <dfn>205 (Reset Content)</dfn> status code indicates that the server has fulfilled the request and desires that the user agent reset the "document view", |
| 2529 | | which caused the request to be sent, to its original state as received from the origin server. |
| 2530 | | </p> |
| 2531 | | <p id="rfc.section.6.3.6.p.2">This response is intended to support a common data entry use case where the user receives content that supports data entry |
| 2532 | | (a form, notepad, canvas, etc.), enters or manipulates data in that space, causes the entered data to be submitted in a request, |
| 2533 | | and then the data entry mechanism is reset for the next entry so that the user can easily initiate another input action. |
| 2534 | | </p> |
| 2535 | | <p id="rfc.section.6.3.6.p.3">Since the 205 status code implies that no additional content will be provided, a server <em class="bcp14">MUST NOT</em> generate a payload in a 205 response. In other words, a server <em class="bcp14">MUST</em> do one of the following for a 205 response: a) indicate a zero-length body for the response by including a <a href="p1-messaging.html#header.content-length" class="smpl">Content-Length</a> header field with a value of 0; b) indicate a zero-length payload for the response by including a <a href="p1-messaging.html#header.transfer-encoding" class="smpl">Transfer-Encoding</a> header field with a value of chunked and a message body consisting of a single chunk of zero-length; or, c) close the connection |
| 2536 | | immediately after sending the blank line terminating the header section. |
| 2537 | | </p> |
| 2538 | | <h2 id="rfc.section.6.4"><a href="#rfc.section.6.4">6.4</a> <a id="status.3xx" href="#status.3xx">Redirection 3xx</a></h2> |
| 2539 | | <div id="rfc.iref.69"></div> |
| 2540 | | <div id="rfc.iref.s.5"></div> |
| 2541 | | <p id="rfc.section.6.4.p.1">The <dfn>3xx (Redirection)</dfn> class of status code indicates that further action needs to be taken by the user agent in order to fulfill the request. If |
| 2542 | | a <a href="#header.location" class="smpl">Location</a> header field (<a href="#header.location" id="rfc.xref.header.location.2" title="Location">Section 7.1.2</a>) is provided, the user agent <em class="bcp14">MAY</em> automatically redirect its request to the URI referenced by the Location field value, even if the specific status code is |
| 2543 | | not understood. Automatic redirection needs to done with care for methods not known to be <a href="#safe.methods" class="smpl">safe</a>, as defined in <a href="#safe.methods" title="Safe Methods">Section 4.2.1</a>, since the user might not wish to redirect an unsafe request. |
| 2544 | | </p> |
| 2545 | | <p id="rfc.section.6.4.p.2">There are several types of redirects: </p> |
| 2546 | | <ol> |
| 2547 | | <li> |
| 2548 | | <p>Redirects that indicate the resource might be available at a different URI, as provided by the <a href="#header.location" class="smpl">Location</a> field, as in the status codes <a href="#status.301" class="smpl">301 (Moved Permanently)</a>, <a href="#status.302" class="smpl">302 (Found)</a>, and <a href="#status.307" class="smpl">307 (Temporary Redirect)</a>. |
| 2549 | | </p> |
| 2550 | | </li> |
| 2551 | | <li> |
| 2552 | | <p>Redirection that offers a choice of matching resources, each capable of representing the original request target, as in the <a href="#status.300" class="smpl">300 (Multiple Choices)</a> status code. |
| 2553 | | </p> |
| 2554 | | </li> |
| 2555 | | <li> |
| 2556 | | <p>Redirection to a different resource, identified by the <a href="#header.location" class="smpl">Location</a> field, that can represent an indirect response to the request, as in the <a href="#status.303" class="smpl">303 (See Other)</a> status code. |
| 2557 | | </p> |
| 2558 | | </li> |
| 2559 | | <li> |
| 2560 | | <p>Redirection to a previously cached result, as in the <a href="p4-conditional.html#status.304" class="smpl">304 (Not Modified)</a> status code. |
| 2561 | | </p> |
| 2562 | | </li> |
| 2563 | | </ol> |
| 2564 | | <div class="note" id="rfc.section.6.4.p.3"> |
| 2565 | | <p><b>Note:</b> In HTTP/1.0, the status codes <a href="#status.301" class="smpl">301 (Moved Permanently)</a> and <a href="#status.302" class="smpl">302 (Found)</a> were defined for the first type of redirect (<a href="#RFC1945" id="rfc.xref.RFC1945.1"><cite title="Hypertext Transfer Protocol -- HTTP/1.0">[RFC1945]</cite></a>, <a href="http://tools.ietf.org/html/rfc1945#section-9.3">Section 9.3</a>). Early user agents split on whether the method applied to the redirect target would be the same as the original request |
| 2566 | | or would be rewritten as GET. Although HTTP originally defined the former semantics for <a href="#status.301" class="smpl">301</a> and <a href="#status.302" class="smpl">302</a> (to match its original implementation at CERN), and defined <a href="#status.303" class="smpl">303 (See Other)</a> to match the latter semantics, prevailing practice gradually converged on the latter semantics for <a href="#status.301" class="smpl">301</a> and <a href="#status.302" class="smpl">302</a> as well. The first revision of HTTP/1.1 added <a href="#status.307" class="smpl">307 (Temporary Redirect)</a> to indicate the former semantics without being impacted by divergent practice. Over 10 years later, most user agents still |
| 2567 | | do method rewriting for <a href="#status.301" class="smpl">301</a> and <a href="#status.302" class="smpl">302</a>; therefore, this specification makes that behavior conformant when the original request is POST. |
| 2568 | | </p> |
| 2569 | | </div> |
| 2570 | | <p id="rfc.section.6.4.p.4">A client <em class="bcp14">SHOULD</em> detect and intervene in cyclical redirections (i.e., "infinite" redirection loops). |
| 2571 | | </p> |
| 2572 | | <div class="note" id="rfc.section.6.4.p.5"> |
| 2573 | | <p><b>Note:</b> An earlier version of this specification recommended a maximum of five redirections (<a href="#RFC2068" id="rfc.xref.RFC2068.2"><cite title="Hypertext Transfer Protocol -- HTTP/1.1">[RFC2068]</cite></a>, <a href="http://tools.ietf.org/html/rfc2068#section-10.3">Section 10.3</a>). Content developers need to be aware that some clients might implement such a fixed limitation. |
| 2574 | | </p> |
| 2575 | | </div> |
| 2576 | | <div id="rfc.iref.70"></div> |
| 2577 | | <h3 id="rfc.section.6.4.1"><a href="#rfc.section.6.4.1">6.4.1</a> <a id="status.300" href="#status.300">300 Multiple Choices</a></h3> |
| 2578 | | <p id="rfc.section.6.4.1.p.1">The <dfn>300 (Multiple Choices)</dfn> status code indicates that the <a href="#resources" class="smpl">target resource</a> has more than one representation, each with its own more specific identifier, and information about the alternatives is being |
| 2579 | | provided so that the user (or user agent) can select a preferred representation by redirecting its request to one or more |
| 2580 | | of those identifiers. In other words, the server desires that the user agent engage in reactive negotiation to select the |
| 2581 | | most appropriate representation(s) for its needs (<a href="#content.negotiation" title="Content Negotiation">Section 3.4</a>). |
| 2582 | | </p> |
| 2583 | | <p id="rfc.section.6.4.1.p.2">If the server has a preferred choice, the server <em class="bcp14">SHOULD</em> generate a <a href="#header.location" class="smpl">Location</a> header field containing a preferred choice's URI reference. The user agent <em class="bcp14">MAY</em> use the Location field value for automatic redirection. |
| 2584 | | </p> |
| 2585 | | <p id="rfc.section.6.4.1.p.3">For request methods other than HEAD, the server <em class="bcp14">SHOULD</em> generate a payload in the 300 response containing a list of representation metadata and URI reference(s) from which the user |
| 2586 | | or user agent can choose the one most preferred. The user agent <em class="bcp14">MAY</em> make a selection from that list automatically, depending upon the list format, but this specification does not define a standard |
| 2587 | | for such automatic selection. |
| 2588 | | </p> |
| 2589 | | <p id="rfc.section.6.4.1.p.4">A 300 response is cacheable unless otherwise indicated by the method definition or explicit cache controls (see <a href="p6-cache.html#heuristic.freshness" title="Calculating Heuristic Freshness">Section 4.2.2</a> of <a href="#Part6" id="rfc.xref.Part6.15"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| 2590 | | </p> |
| 2591 | | <div class="note" id="rfc.section.6.4.1.p.5"> |
| 2592 | | <p><b>Note:</b> The original proposal for 300 defined the URI header field as providing a list of alternative representations, such that it |
| 2593 | | would be usable for 200, 300, and 406 responses and be transferred in responses to the HEAD method. However, lack of deployment |
| 2594 | | and disagreement over syntax led to both URI and Alternates (a subsequent proposal) being dropped from this specification. |
| 2595 | | It is possible to communicate the list using a set of Link header fields <a href="#RFC5988" id="rfc.xref.RFC5988.1"><cite title="Web Linking">[RFC5988]</cite></a>, each with a relationship of "alternate", though deployment is a chicken-and-egg problem. |
| 2596 | | </p> |
| 2597 | | </div> |
| 2598 | | <div id="rfc.iref.70"></div> |
| 2599 | | <h3 id="rfc.section.6.4.2"><a href="#rfc.section.6.4.2">6.4.2</a> <a id="status.301" href="#status.301">301 Moved Permanently</a></h3> |
| 2600 | | <p id="rfc.section.6.4.2.p.1">The <dfn>301 (Moved Permanently)</dfn> status code indicates that the <a href="#resources" class="smpl">target resource</a> has been assigned a new permanent URI and any future references to this resource ought to use one of the enclosed URIs. Clients |
| 2601 | | with link editing capabilities ought to automatically re-link references to the effective request URI to one or more of the |
| 2602 | | new references sent by the server, where possible. |
| 2603 | | </p> |
| 2604 | | <p id="rfc.section.6.4.2.p.2">The server <em class="bcp14">SHOULD</em> generate a <a href="#header.location" class="smpl">Location</a> header field in the response containing a preferred URI reference for the new permanent URI. The user agent <em class="bcp14">MAY</em> use the Location field value for automatic redirection. The server's response payload usually contains a short hypertext note |
| 2605 | | with a hyperlink to the new URI(s). |
| 2606 | | </p> |
| 2607 | | <div class="note" id="rfc.section.6.4.2.p.3"> |
| 2608 | | <p><b>Note:</b> For historic reasons, a user agent <em class="bcp14">MAY</em> change the request method from POST to GET for the subsequent request. If this behavior is undesired, the <a href="#status.307" class="smpl">307 (Temporary Redirect)</a> status code can be used instead. |
| 2609 | | </p> |
| 2610 | | </div> |
| 2611 | | <p id="rfc.section.6.4.2.p.4">A 301 response is cacheable unless otherwise indicated by the method definition or explicit cache controls (see <a href="p6-cache.html#heuristic.freshness" title="Calculating Heuristic Freshness">Section 4.2.2</a> of <a href="#Part6" id="rfc.xref.Part6.16"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| 2612 | | </p> |
| 2613 | | <div id="rfc.iref.70"></div> |
| 2614 | | <h3 id="rfc.section.6.4.3"><a href="#rfc.section.6.4.3">6.4.3</a> <a id="status.302" href="#status.302">302 Found</a></h3> |
| 2615 | | <p id="rfc.section.6.4.3.p.1">The <dfn>302 (Found)</dfn> status code indicates that the target resource resides temporarily under a different URI. Since the redirection might be altered |
| 2616 | | on occasion, the client ought to continue to use the effective request URI for future requests. |
| 2617 | | </p> |
| 2618 | | <p id="rfc.section.6.4.3.p.2">The server <em class="bcp14">SHOULD</em> generate a <a href="#header.location" class="smpl">Location</a> header field in the response containing a URI reference for the different URI. The user agent <em class="bcp14">MAY</em> use the Location field value for automatic redirection. The server's response payload usually contains a short hypertext note |
| 2619 | | with a hyperlink to the different URI(s). |
| 2620 | | </p> |
| 2621 | | <div class="note" id="rfc.section.6.4.3.p.3"> |
| 2622 | | <p><b>Note:</b> For historic reasons, a user agent <em class="bcp14">MAY</em> change the request method from POST to GET for the subsequent request. If this behavior is undesired, the <a href="#status.307" class="smpl">307 (Temporary Redirect)</a> status code can be used instead. |
| 2623 | | </p> |
| 2624 | | </div> |
| 2625 | | <div id="rfc.iref.70"></div> |
| 2626 | | <h3 id="rfc.section.6.4.4"><a href="#rfc.section.6.4.4">6.4.4</a> <a id="status.303" href="#status.303">303 See Other</a></h3> |
| 2627 | | <p id="rfc.section.6.4.4.p.1">The <dfn>303 (See Other)</dfn> status code indicates that the server is redirecting the user agent to a different resource, as indicated by a URI in the <a href="#header.location" class="smpl">Location</a> header field, that is intended to provide an indirect response to the original request. In order to satisfy the original request, |
| 2628 | | a user agent ought to perform a retrieval request using the Location URI (a GET or HEAD request if using HTTP), which can |
| 2629 | | itself be redirected further, and present the eventual result as an answer to the original request. Note that the new URI |
| 2630 | | in the Location header field is not considered equivalent to the effective request URI. |
| 2631 | | </p> |
| 2632 | | <p id="rfc.section.6.4.4.p.2">This status code is applicable to any HTTP method. It is primarily used to allow the output of a POST action to redirect the |
| 2633 | | user agent to a selected resource, since doing so provides the information corresponding to the POST response in a form that |
| 2634 | | can be separately identified, bookmarked, and cached independent of the original request. |
| 2635 | | </p> |
| 2636 | | <p id="rfc.section.6.4.4.p.3">A 303 response to a GET request indicates that the origin server does not have a representation of the <a href="#resources" class="smpl">target resource</a> that can be transferred by the server over HTTP. However, the <a href="#header.location" class="smpl">Location</a> field value refers to a resource that is descriptive of the target resource, such that making a retrieval request on that |
| 2637 | | other resource might result in a representation that is useful to recipients without implying that it represents the original |
| 2638 | | target resource. Note that answers to the questions of what can be represented, what representations are adequate, and what |
| 2639 | | might be a useful description are outside the scope of HTTP. |
| 2640 | | </p> |
| 2641 | | <p id="rfc.section.6.4.4.p.4">Except for responses to a HEAD request, the representation of a 303 response ought to contain a short hypertext note with |
| 2642 | | a hyperlink to the same URI reference provided in the <a href="#header.location" class="smpl">Location</a> header field. |
| 2643 | | </p> |
| 2644 | | <div id="rfc.iref.70"></div> |
| 2645 | | <h3 id="rfc.section.6.4.5"><a href="#rfc.section.6.4.5">6.4.5</a> <a id="status.305" href="#status.305">305 Use Proxy</a></h3> |
| 2646 | | <p id="rfc.section.6.4.5.p.1">The <dfn>305 (Use Proxy)</dfn> status code was defined in a previous version of this specification and is now deprecated (<a href="#changes.from.rfc.2616" title="Changes from RFC 2616">Appendix B</a>). |
| 2647 | | </p> |
| 2648 | | <div id="rfc.iref.70"></div> |
| 2649 | | <h3 id="rfc.section.6.4.6"><a href="#rfc.section.6.4.6">6.4.6</a> <a id="status.306" href="#status.306">306 (Unused)</a></h3> |
| 2650 | | <p id="rfc.section.6.4.6.p.1">The 306 status code was defined in a previous version of this specification, is no longer used, and the code is reserved.</p> |
| 2651 | | <div id="rfc.iref.70"></div> |
| 2652 | | <h3 id="rfc.section.6.4.7"><a href="#rfc.section.6.4.7">6.4.7</a> <a id="status.307" href="#status.307">307 Temporary Redirect</a></h3> |
| 2653 | | <p id="rfc.section.6.4.7.p.1">The <dfn>307 (Temporary Redirect)</dfn> status code indicates that the <a href="#resources" class="smpl">target resource</a> resides temporarily under a different URI and the user agent <em class="bcp14">MUST NOT</em> change the request method if it performs an automatic redirection to that URI. Since the redirection can change over time, |
| 2654 | | the client ought to continue using the original effective request URI for future requests. |
| 2655 | | </p> |
| 2656 | | <p id="rfc.section.6.4.7.p.2">The server <em class="bcp14">SHOULD</em> generate a <a href="#header.location" class="smpl">Location</a> header field in the response containing a URI reference for the different URI. The user agent <em class="bcp14">MAY</em> use the Location field value for automatic redirection. The server's response payload usually contains a short hypertext note |
| 2657 | | with a hyperlink to the different URI(s). |
| 2658 | | </p> |
| 2659 | | <div class="note" id="rfc.section.6.4.7.p.3"> |
| 2660 | | <p><b>Note:</b> This status code is similar to <a href="#status.302" class="smpl">302 (Found)</a>, except that it does not allow changing the request method from POST to GET. This specification defines no equivalent counterpart |
| 2661 | | for <a href="#status.301" class="smpl">301 (Moved |
| 2662 | | Permanently)</a> (<a href="#status-308" id="rfc.xref.status-308.1"><cite title="The Hypertext Transfer Protocol (HTTP) Status Code 308 (Permanent Redirect)">[status-308]</cite></a>, however, defines the status code 308 (Permanent Redirect) for this purpose). |
| 2663 | | </p> |
| 2664 | | </div> |
| 2665 | | <h2 id="rfc.section.6.5"><a href="#rfc.section.6.5">6.5</a> <a id="status.4xx" href="#status.4xx">Client Error 4xx</a></h2> |
| 2666 | | <div id="rfc.iref.70"></div> |
| 2667 | | <div id="rfc.iref.s.6"></div> |
| 2668 | | <p id="rfc.section.6.5.p.1">The <dfn>4xx (Client Error)</dfn> class of status code indicates that the client seems to have erred. Except when responding to a HEAD request, the server <em class="bcp14">SHOULD</em> send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition. |
| 2669 | | These status codes are applicable to any request method. User agents <em class="bcp14">SHOULD</em> display any included representation to the user. |
| 2670 | | </p> |
| 2671 | | <div id="rfc.iref.71"></div> |
| 2672 | | <h3 id="rfc.section.6.5.1"><a href="#rfc.section.6.5.1">6.5.1</a> <a id="status.400" href="#status.400">400 Bad Request</a></h3> |
| 2673 | | <p id="rfc.section.6.5.1.p.1">The <dfn>400 (Bad Request)</dfn> status code indicates that the server cannot or will not process the request due to something which is perceived to be a client |
| 2674 | | error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). |
| 2675 | | </p> |
| 2676 | | <div id="rfc.iref.71"></div> |
| 2677 | | <h3 id="rfc.section.6.5.2"><a href="#rfc.section.6.5.2">6.5.2</a> <a id="status.402" href="#status.402">402 Payment Required</a></h3> |
| 2678 | | <p id="rfc.section.6.5.2.p.1">The <dfn>402 (Payment Required)</dfn> status code is reserved for future use. |
| 2679 | | </p> |
| 2680 | | <div id="rfc.iref.71"></div> |
| 2681 | | <h3 id="rfc.section.6.5.3"><a href="#rfc.section.6.5.3">6.5.3</a> <a id="status.403" href="#status.403">403 Forbidden</a></h3> |
| 2682 | | <p id="rfc.section.6.5.3.p.1">The <dfn>403 (Forbidden)</dfn> status code indicates that the server understood the request but refuses to authorize it. A server that wishes to make public |
| 2683 | | why the request has been forbidden can describe that reason in the response payload (if any). |
| 2684 | | </p> |
| 2685 | | <p id="rfc.section.6.5.3.p.2">If authentication credentials were provided in the request, the server considers them insufficient to grant access. The client <em class="bcp14">SHOULD NOT</em> automatically repeat the request with the same credentials. The client <em class="bcp14">MAY</em> repeat the request with new or different credentials. However, a request might be forbidden for reasons unrelated to the credentials. |
| 2686 | | </p> |
| 2687 | | <p id="rfc.section.6.5.3.p.3">An origin server that wishes to "hide" the current existence of a forbidden <a href="#resources" class="smpl">target resource</a> <em class="bcp14">MAY</em> instead respond with a status code of <a href="#status.404" class="smpl">404 (Not Found)</a>. |
| 2688 | | </p> |
| 2689 | | <div id="rfc.iref.71"></div> |
| 2690 | | <h3 id="rfc.section.6.5.4"><a href="#rfc.section.6.5.4">6.5.4</a> <a id="status.404" href="#status.404">404 Not Found</a></h3> |
| 2691 | | <p id="rfc.section.6.5.4.p.1">The <dfn>404 (Not Found)</dfn> status code indicates that the origin server did not find a current representation for the <a href="#resources" class="smpl">target resource</a> or is not willing to disclose that one exists. A 404 status code does not indicate whether this lack of representation is |
| 2692 | | temporary or permanent; the <a href="#status.410" class="smpl">410 (Gone)</a> status code is preferred over 404 if the origin server knows, presumably through some configurable means, that the condition |
| 2693 | | is likely to be permanent. |
| 2694 | | </p> |
| 2695 | | <p id="rfc.section.6.5.4.p.2">A 404 response is cacheable unless otherwise indicated by the method definition or explicit cache controls (see <a href="p6-cache.html#heuristic.freshness" title="Calculating Heuristic Freshness">Section 4.2.2</a> of <a href="#Part6" id="rfc.xref.Part6.17"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| 2696 | | </p> |
| 2697 | | <div id="rfc.iref.71"></div> |
| 2698 | | <h3 id="rfc.section.6.5.5"><a href="#rfc.section.6.5.5">6.5.5</a> <a id="status.405" href="#status.405">405 Method Not Allowed</a></h3> |
| 2699 | | <p id="rfc.section.6.5.5.p.1">The <dfn>405 (Method Not Allowed)</dfn> status code indicates that the method received in the request-line is known by the origin server but not supported by the <a href="#resources" class="smpl">target resource</a>. The origin server <em class="bcp14">MUST</em> generate an <a href="#header.allow" class="smpl">Allow</a> header field in a 405 response containing a list of the target resource's currently supported methods. |
| 2700 | | </p> |
| 2701 | | <p id="rfc.section.6.5.5.p.2">A 405 response is cacheable unless otherwise indicated by the method definition or explicit cache controls (see <a href="p6-cache.html#heuristic.freshness" title="Calculating Heuristic Freshness">Section 4.2.2</a> of <a href="#Part6" id="rfc.xref.Part6.18"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| 2702 | | </p> |
| 2703 | | <div id="rfc.iref.71"></div> |
| 2704 | | <h3 id="rfc.section.6.5.6"><a href="#rfc.section.6.5.6">6.5.6</a> <a id="status.406" href="#status.406">406 Not Acceptable</a></h3> |
| 2705 | | <p id="rfc.section.6.5.6.p.1">The <dfn>406 (Not Acceptable)</dfn> status code indicates that the <a href="#resources" class="smpl">target resource</a> does not have a current representation that would be acceptable to the user agent, according to the <a href="#proactive.negotiation" class="smpl">proactive negotiation</a> header fields received in the request (<a href="#request.conneg" title="Content Negotiation">Section 5.3</a>), and the server is unwilling to supply a default representation. |
| 2706 | | </p> |
| 2707 | | <p id="rfc.section.6.5.6.p.2">The server <em class="bcp14">SHOULD</em> generate a payload containing a list of available representation characteristics and corresponding resource identifiers from |
| 2708 | | which the user or user agent can choose the one most appropriate. A user agent <em class="bcp14">MAY</em> automatically select the most appropriate choice from that list. However, this specification does not define any standard |
| 2709 | | for such automatic selection, as described in <a href="#status.300" id="rfc.xref.status.300.2" title="300 Multiple Choices">Section 6.4.1</a>. |
| 2710 | | </p> |
| 2711 | | <div id="rfc.iref.71"></div> |
| 2712 | | <h3 id="rfc.section.6.5.7"><a href="#rfc.section.6.5.7">6.5.7</a> <a id="status.408" href="#status.408">408 Request Timeout</a></h3> |
| 2713 | | <p id="rfc.section.6.5.7.p.1">The <dfn>408 (Request Timeout)</dfn> status code indicates that the server did not receive a complete request message within the time that it was prepared to wait. |
| 2714 | | A server <em class="bcp14">SHOULD</em> send the <a href="p1-messaging.html#header.connection" class="smpl">close</a> connection option (<a href="p1-messaging.html#header.connection" title="Connection">Section 6.1</a> of <a href="#Part1" id="rfc.xref.Part1.25"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>) in the response, since 408 implies that the server has decided to close the connection rather than continue waiting. If |
| 2715 | | the client has an outstanding request in transit, the client <em class="bcp14">MAY</em> repeat that request on a new connection. |
| 2716 | | </p> |
| 2717 | | <div id="rfc.iref.71"></div> |
| 2718 | | <h3 id="rfc.section.6.5.8"><a href="#rfc.section.6.5.8">6.5.8</a> <a id="status.409" href="#status.409">409 Conflict</a></h3> |
| 2719 | | <p id="rfc.section.6.5.8.p.1">The <dfn>409 (Conflict)</dfn> status code indicates that the request could not be completed due to a conflict with the current state of the target resource. |
| 2720 | | This code is used in situations where the user might be able to resolve the conflict and resubmit the request. The server <em class="bcp14">SHOULD</em> generate a payload that includes enough information for a user to recognize the source of the conflict. |
| 2721 | | </p> |
| 2722 | | <p id="rfc.section.6.5.8.p.2">Conflicts are most likely to occur in response to a PUT request. For example, if versioning were being used and the representation |
| 2723 | | being PUT included changes to a resource that conflict with those made by an earlier (third-party) request, the origin server |
| 2724 | | might use a 409 response to indicate that it can't complete the request. In this case, the response representation would likely |
| 2725 | | contain information useful for merging the differences based on the revision history. |
| 2726 | | </p> |
| 2727 | | <div id="rfc.iref.71"></div> |
| 2728 | | <h3 id="rfc.section.6.5.9"><a href="#rfc.section.6.5.9">6.5.9</a> <a id="status.410" href="#status.410">410 Gone</a></h3> |
| 2729 | | <p id="rfc.section.6.5.9.p.1">The <dfn>410 (Gone)</dfn> status code indicates that access to the <a href="#resources" class="smpl">target resource</a> is no longer available at the origin server and that this condition is likely to be permanent. If the origin server does not |
| 2730 | | know, or has no facility to determine, whether or not the condition is permanent, the status code <a href="#status.404" class="smpl">404 (Not Found)</a> ought to be used instead. |
| 2731 | | </p> |
| 2732 | | <p id="rfc.section.6.5.9.p.2">The 410 response is primarily intended to assist the task of web maintenance by notifying the recipient that the resource |
| 2733 | | is intentionally unavailable and that the server owners desire that remote links to that resource be removed. Such an event |
| 2734 | | is common for limited-time, promotional services and for resources belonging to individuals no longer associated with the |
| 2735 | | origin server's site. It is not necessary to mark all permanently unavailable resources as "gone" or to keep the mark for |
| 2736 | | any length of time — that is left to the discretion of the server owner. |
| 2737 | | </p> |
| 2738 | | <p id="rfc.section.6.5.9.p.3">A 410 response is cacheable unless otherwise indicated by the method definition or explicit cache controls (see <a href="p6-cache.html#heuristic.freshness" title="Calculating Heuristic Freshness">Section 4.2.2</a> of <a href="#Part6" id="rfc.xref.Part6.19"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| 2739 | | </p> |
| 2740 | | <div id="rfc.iref.71"></div> |
| 2741 | | <h3 id="rfc.section.6.5.10"><a href="#rfc.section.6.5.10">6.5.10</a> <a id="status.411" href="#status.411">411 Length Required</a></h3> |
| 2742 | | <p id="rfc.section.6.5.10.p.1">The <dfn>411 (Length Required)</dfn> status code indicates that the server refuses to accept the request without a defined <a href="p1-messaging.html#header.content-length" class="smpl">Content-Length</a> (<a href="p1-messaging.html#header.content-length" title="Content-Length">Section 3.3.2</a> of <a href="#Part1" id="rfc.xref.Part1.26"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). The client <em class="bcp14">MAY</em> repeat the request if it adds a valid Content-Length header field containing the length of the message body in the request |
| 2743 | | message. |
| 2744 | | </p> |
| 2745 | | <div id="rfc.iref.71"></div> |
| 2746 | | <h3 id="rfc.section.6.5.11"><a href="#rfc.section.6.5.11">6.5.11</a> <a id="status.413" href="#status.413">413 Payload Too Large</a></h3> |
| 2747 | | <p id="rfc.section.6.5.11.p.1">The <dfn>413 (Payload Too Large)</dfn> status code indicates that the server is refusing to process a request because the request payload is larger than the server |
| 2748 | | is willing or able to process. The server <em class="bcp14">MAY</em> close the connection to prevent the client from continuing the request. |
| 2749 | | </p> |
| 2750 | | <p id="rfc.section.6.5.11.p.2">If the condition is temporary, the server <em class="bcp14">SHOULD</em> generate a <a href="#header.retry-after" class="smpl">Retry-After</a> header field to indicate that it is temporary and after what time the client <em class="bcp14">MAY</em> try again. |
| 2751 | | </p> |
| 2752 | | <div id="rfc.iref.71"></div> |
| 2753 | | <h3 id="rfc.section.6.5.12"><a href="#rfc.section.6.5.12">6.5.12</a> <a id="status.414" href="#status.414">414 URI Too Long</a></h3> |
| 2754 | | <p id="rfc.section.6.5.12.p.1">The <dfn>414 (URI Too Long)</dfn> status code indicates that the server is refusing to service the request because the request-target (<a href="p1-messaging.html#request-target" title="Request Target">Section 5.3</a> of <a href="#Part1" id="rfc.xref.Part1.27"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>) is longer than the server is willing to interpret. This rare condition is only likely to occur when a client has improperly |
| 2755 | | converted a POST request to a GET request with long query information, when the client has descended into a "black hole" of |
| 2756 | | redirection (e.g., a redirected URI prefix that points to a suffix of itself), or when the server is under attack by a client |
| 2757 | | attempting to exploit potential security holes. |
| 2758 | | </p> |
| 2759 | | <p id="rfc.section.6.5.12.p.2">A 414 response is cacheable unless otherwise indicated by the method definition or explicit cache controls (see <a href="p6-cache.html#heuristic.freshness" title="Calculating Heuristic Freshness">Section 4.2.2</a> of <a href="#Part6" id="rfc.xref.Part6.20"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). |
| 2760 | | </p> |
| 2761 | | <div id="rfc.iref.71"></div> |
| 2762 | | <h3 id="rfc.section.6.5.13"><a href="#rfc.section.6.5.13">6.5.13</a> <a id="status.415" href="#status.415">415 Unsupported Media Type</a></h3> |
| 2763 | | <p id="rfc.section.6.5.13.p.1">The <dfn>415 (Unsupported Media Type)</dfn> status code indicates that the origin server is refusing to service the request because the payload is in a format not supported |
| 2764 | | by this method on the <a href="#resources" class="smpl">target resource</a>. The format problem might be due to the request's indicated <a href="#header.content-type" class="smpl">Content-Type</a> or <a href="#header.content-encoding" class="smpl">Content-Encoding</a>, or as a result of inspecting the data directly. |
| 2765 | | </p> |
| 2766 | | <div id="rfc.iref.71"></div> |
| 2767 | | <h3 id="rfc.section.6.5.14"><a href="#rfc.section.6.5.14">6.5.14</a> <a id="status.417" href="#status.417">417 Expectation Failed</a></h3> |
| 2768 | | <p id="rfc.section.6.5.14.p.1">The <dfn>417 (Expectation Failed)</dfn> status code indicates that the expectation given in the request's <a href="#header.expect" class="smpl">Expect</a> header field (<a href="#header.expect" id="rfc.xref.header.expect.3" title="Expect">Section 5.1.1</a>) could not be met by at least one of the inbound servers. |
| 2769 | | </p> |
| 2770 | | <div id="rfc.iref.71"></div> |
| 2771 | | <h3 id="rfc.section.6.5.15"><a href="#rfc.section.6.5.15">6.5.15</a> <a id="status.426" href="#status.426">426 Upgrade Required</a></h3> |
| 2772 | | <p id="rfc.section.6.5.15.p.1">The <dfn>426 (Upgrade Required)</dfn> status code indicates that the server refuses to perform the request using the current protocol but might be willing to do |
| 2773 | | so after the client upgrades to a different protocol. The server <em class="bcp14">MUST</em> send an <a href="p1-messaging.html#header.upgrade" class="smpl">Upgrade</a> header field in a 426 response to indicate the required protocol(s) (<a href="p1-messaging.html#header.upgrade" title="Upgrade">Section 6.7</a> of <a href="#Part1" id="rfc.xref.Part1.28"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). |
| 2774 | | </p> |
| 2775 | | <div id="rfc.figure.u.42"></div> |
| 2776 | | <p>Example:</p><pre class="text">HTTP/1.1 426 Upgrade Required |
| | 2279 | <div id="status.codes"> |
| | 2280 | <h1 id="rfc.section.6"><a href="#rfc.section.6">6.</a> <a href="#status.codes">Response Status Codes</a></h1> |
| | 2281 | <p id="rfc.section.6.p.1">The status-code element is a 3-digit integer code giving the result of the attempt to understand and satisfy the request.</p> |
| | 2282 | <p id="rfc.section.6.p.2">HTTP status codes are extensible. HTTP clients are not required to understand the meaning of all registered status codes, |
| | 2283 | though such understanding is obviously desirable. However, a client <em class="bcp14">MUST</em> understand the class of any status code, as indicated by the first digit, and treat an unrecognized status code as being equivalent |
| | 2284 | to the x00 status code of that class, with the exception that a recipient <em class="bcp14">MUST NOT</em> cache a response with an unrecognized status code. |
| | 2285 | </p> |
| | 2286 | <p id="rfc.section.6.p.3">For example, if an unrecognized status code of 471 is received by a client, the client can assume that there was something |
| | 2287 | wrong with its request and treat the response as if it had received a 400 status code. The response message will usually contain |
| | 2288 | a representation that explains the status. |
| | 2289 | </p> |
| | 2290 | <p id="rfc.section.6.p.4">The first digit of the status-code defines the class of response. The last two digits do not have any categorization role. |
| | 2291 | There are 5 values for the first digit: |
| | 2292 | </p> |
| | 2293 | <ul> |
| | 2294 | <li><a href="#status.1xx" class="smpl">1xx (Informational)</a>: The request was received, continuing process |
| | 2295 | </li> |
| | 2296 | <li><a href="#status.2xx" class="smpl">2xx (Successful)</a>: The request was successfully received, understood, and accepted |
| | 2297 | </li> |
| | 2298 | <li><a href="#status.3xx" class="smpl">3xx (Redirection)</a>: Further action needs to be taken in order to complete the request |
| | 2299 | </li> |
| | 2300 | <li><a href="#status.4xx" class="smpl">4xx (Client Error)</a>: The request contains bad syntax or cannot be fulfilled |
| | 2301 | </li> |
| | 2302 | <li><a href="#status.5xx" class="smpl">5xx (Server Error)</a>: The server failed to fulfill an apparently valid request |
| | 2303 | </li> |
| | 2304 | </ul> |
| | 2305 | <div id="overview.of.status.codes"> |
| | 2306 | <h2 id="rfc.section.6.1"><a href="#rfc.section.6.1">6.1</a> <a href="#overview.of.status.codes">Overview of Status Codes</a></h2> |
| | 2307 | <p id="rfc.section.6.1.p.1">The status codes listed below are defined in this specification, <a href="p4-conditional.html#status.code.definitions" title="Status Code Definitions">Section 4</a> of <a href="#Part4" id="rfc.xref.Part4.9"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests">[Part4]</cite></a>, <a href="p5-range.html#range.response" title="Responses to a Range Request">Section 4</a> of <a href="#Part5" id="rfc.xref.Part5.7"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a>, and <a href="p7-auth.html#status.code.definitions" title="Status Code Definitions">Section 3</a> of <a href="#Part7" id="rfc.xref.Part7.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">[Part7]</cite></a>. The reason phrases listed here are only recommendations — they can be replaced by local equivalents without affecting the |
| | 2308 | protocol. |
| | 2309 | </p> |
| | 2310 | <p id="rfc.section.6.1.p.2">Responses with status codes that are defined as cacheable by default (e.g., 200, 203, 206, 300, 301, and 410 in this specification) |
| | 2311 | can be reused by a cache with heuristic expiration unless otherwise indicated by the method definition or explicit cache controls <a href="#Part6" id="rfc.xref.Part6.10"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>; all other status codes are not cacheable by default. |
| | 2312 | </p> |
| | 2313 | <div id="rfc.table.u.9"> |
| | 2314 | <table class="tt full left" cellpadding="3" cellspacing="0"> |
| | 2315 | <thead> |
| | 2316 | <tr> |
| | 2317 | <th>code</th> |
| | 2318 | <th>reason-phrase</th> |
| | 2319 | <th>Defined in...</th> |
| | 2320 | </tr> |
| | 2321 | </thead> |
| | 2322 | <tbody> |
| | 2323 | <tr> |
| | 2324 | <td class="left">100</td> |
| | 2325 | <td class="left">Continue</td> |
| | 2326 | <td class="left"><a href="#status.100" id="rfc.xref.status.100.1" title="100 Continue">Section 6.2.1</a></td> |
| | 2327 | </tr> |
| | 2328 | <tr> |
| | 2329 | <td class="left">101</td> |
| | 2330 | <td class="left">Switching Protocols</td> |
| | 2331 | <td class="left"><a href="#status.101" id="rfc.xref.status.101.1" title="101 Switching Protocols">Section 6.2.2</a></td> |
| | 2332 | </tr> |
| | 2333 | <tr> |
| | 2334 | <td class="left">200</td> |
| | 2335 | <td class="left">OK</td> |
| | 2336 | <td class="left"><a href="#status.200" id="rfc.xref.status.200.1" title="200 OK">Section 6.3.1</a></td> |
| | 2337 | </tr> |
| | 2338 | <tr> |
| | 2339 | <td class="left">201</td> |
| | 2340 | <td class="left">Created</td> |
| | 2341 | <td class="left"><a href="#status.201" id="rfc.xref.status.201.1" title="201 Created">Section 6.3.2</a></td> |
| | 2342 | </tr> |
| | 2343 | <tr> |
| | 2344 | <td class="left">202</td> |
| | 2345 | <td class="left">Accepted</td> |
| | 2346 | <td class="left"><a href="#status.202" id="rfc.xref.status.202.1" title="202 Accepted">Section 6.3.3</a></td> |
| | 2347 | </tr> |
| | 2348 | <tr> |
| | 2349 | <td class="left">203</td> |
| | 2350 | <td class="left">Non-Authoritative Information</td> |
| | 2351 | <td class="left"><a href="#status.203" id="rfc.xref.status.203.1" title="203 Non-Authoritative Information">Section 6.3.4</a></td> |
| | 2352 | </tr> |
| | 2353 | <tr> |
| | 2354 | <td class="left">204</td> |
| | 2355 | <td class="left">No Content</td> |
| | 2356 | <td class="left"><a href="#status.204" id="rfc.xref.status.204.1" title="204 No Content">Section 6.3.5</a></td> |
| | 2357 | </tr> |
| | 2358 | <tr> |
| | 2359 | <td class="left">205</td> |
| | 2360 | <td class="left">Reset Content</td> |
| | 2361 | <td class="left"><a href="#status.205" id="rfc.xref.status.205.1" title="205 Reset Content">Section 6.3.6</a></td> |
| | 2362 | </tr> |
| | 2363 | <tr> |
| | 2364 | <td class="left">206</td> |
| | 2365 | <td class="left">Partial Content</td> |
| | 2366 | <td id="status.206" class="left"><a href="p5-range.html#status.206" title="206 Partial Content">Section 4.1</a> of <a href="#Part5" id="rfc.xref.Part5.8"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a></td> |
| | 2367 | </tr> |
| | 2368 | <tr> |
| | 2369 | <td class="left">300</td> |
| | 2370 | <td class="left">Multiple Choices</td> |
| | 2371 | <td class="left"><a href="#status.300" id="rfc.xref.status.300.1" title="300 Multiple Choices">Section 6.4.1</a></td> |
| | 2372 | </tr> |
| | 2373 | <tr> |
| | 2374 | <td class="left">301</td> |
| | 2375 | <td class="left">Moved Permanently</td> |
| | 2376 | <td class="left"><a href="#status.301" id="rfc.xref.status.301.1" title="301 Moved Permanently">Section 6.4.2</a></td> |
| | 2377 | </tr> |
| | 2378 | <tr> |
| | 2379 | <td class="left">302</td> |
| | 2380 | <td class="left">Found</td> |
| | 2381 | <td class="left"><a href="#status.302" id="rfc.xref.status.302.1" title="302 Found">Section 6.4.3</a></td> |
| | 2382 | </tr> |
| | 2383 | <tr> |
| | 2384 | <td class="left">303</td> |
| | 2385 | <td class="left">See Other</td> |
| | 2386 | <td class="left"><a href="#status.303" id="rfc.xref.status.303.1" title="303 See Other">Section 6.4.4</a></td> |
| | 2387 | </tr> |
| | 2388 | <tr> |
| | 2389 | <td class="left">304</td> |
| | 2390 | <td class="left">Not Modified</td> |
| | 2391 | <td id="status.304" class="left"><a href="p4-conditional.html#status.304" title="304 Not Modified">Section 4.1</a> of <a href="#Part4" id="rfc.xref.Part4.10"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests">[Part4]</cite></a></td> |
| | 2392 | </tr> |
| | 2393 | <tr> |
| | 2394 | <td class="left">305</td> |
| | 2395 | <td class="left">Use Proxy</td> |
| | 2396 | <td class="left"><a href="#status.305" id="rfc.xref.status.305.1" title="305 Use Proxy">Section 6.4.5</a></td> |
| | 2397 | </tr> |
| | 2398 | <tr> |
| | 2399 | <td class="left">307</td> |
| | 2400 | <td class="left">Temporary Redirect</td> |
| | 2401 | <td class="left"><a href="#status.307" id="rfc.xref.status.307.1" title="307 Temporary Redirect">Section 6.4.7</a></td> |
| | 2402 | </tr> |
| | 2403 | <tr> |
| | 2404 | <td class="left">400</td> |
| | 2405 | <td class="left">Bad Request</td> |
| | 2406 | <td class="left"><a href="#status.400" id="rfc.xref.status.400.1" title="400 Bad Request">Section 6.5.1</a></td> |
| | 2407 | </tr> |
| | 2408 | <tr> |
| | 2409 | <td class="left">401</td> |
| | 2410 | <td class="left">Unauthorized</td> |
| | 2411 | <td id="status.401" class="left"><a href="p7-auth.html#status.401" title="401 Unauthorized">Section 3.1</a> of <a href="#Part7" id="rfc.xref.Part7.6"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">[Part7]</cite></a></td> |
| | 2412 | </tr> |
| | 2413 | <tr> |
| | 2414 | <td class="left">402</td> |
| | 2415 | <td class="left">Payment Required</td> |
| | 2416 | <td class="left"><a href="#status.402" id="rfc.xref.status.402.1" title="402 Payment Required">Section 6.5.2</a></td> |
| | 2417 | </tr> |
| | 2418 | <tr> |
| | 2419 | <td class="left">403</td> |
| | 2420 | <td class="left">Forbidden</td> |
| | 2421 | <td class="left"><a href="#status.403" id="rfc.xref.status.403.1" title="403 Forbidden">Section 6.5.3</a></td> |
| | 2422 | </tr> |
| | 2423 | <tr> |
| | 2424 | <td class="left">404</td> |
| | 2425 | <td class="left">Not Found</td> |
| | 2426 | <td class="left"><a href="#status.404" id="rfc.xref.status.404.1" title="404 Not Found">Section 6.5.4</a></td> |
| | 2427 | </tr> |
| | 2428 | <tr> |
| | 2429 | <td class="left">405</td> |
| | 2430 | <td class="left">Method Not Allowed</td> |
| | 2431 | <td class="left"><a href="#status.405" id="rfc.xref.status.405.1" title="405 Method Not Allowed">Section 6.5.5</a></td> |
| | 2432 | </tr> |
| | 2433 | <tr> |
| | 2434 | <td class="left">406</td> |
| | 2435 | <td class="left">Not Acceptable</td> |
| | 2436 | <td class="left"><a href="#status.406" id="rfc.xref.status.406.1" title="406 Not Acceptable">Section 6.5.6</a></td> |
| | 2437 | </tr> |
| | 2438 | <tr> |
| | 2439 | <td class="left">407</td> |
| | 2440 | <td class="left">Proxy Authentication Required</td> |
| | 2441 | <td id="status.407" class="left"><a href="p7-auth.html#status.407" title="407 Proxy Authentication Required">Section 3.2</a> of <a href="#Part7" id="rfc.xref.Part7.7"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">[Part7]</cite></a></td> |
| | 2442 | </tr> |
| | 2443 | <tr> |
| | 2444 | <td class="left">408</td> |
| | 2445 | <td class="left">Request Time-out</td> |
| | 2446 | <td class="left"><a href="#status.408" id="rfc.xref.status.408.1" title="408 Request Timeout">Section 6.5.7</a></td> |
| | 2447 | </tr> |
| | 2448 | <tr> |
| | 2449 | <td class="left">409</td> |
| | 2450 | <td class="left">Conflict</td> |
| | 2451 | <td class="left"><a href="#status.409" id="rfc.xref.status.409.1" title="409 Conflict">Section 6.5.8</a></td> |
| | 2452 | </tr> |
| | 2453 | <tr> |
| | 2454 | <td class="left">410</td> |
| | 2455 | <td class="left">Gone</td> |
| | 2456 | <td class="left"><a href="#status.410" id="rfc.xref.status.410.1" title="410 Gone">Section 6.5.9</a></td> |
| | 2457 | </tr> |
| | 2458 | <tr> |
| | 2459 | <td class="left">411</td> |
| | 2460 | <td class="left">Length Required</td> |
| | 2461 | <td class="left"><a href="#status.411" id="rfc.xref.status.411.1" title="411 Length Required">Section 6.5.10</a></td> |
| | 2462 | </tr> |
| | 2463 | <tr> |
| | 2464 | <td class="left">412</td> |
| | 2465 | <td class="left">Precondition Failed</td> |
| | 2466 | <td id="status.412" class="left"><a href="p4-conditional.html#status.412" title="412 Precondition Failed">Section 4.2</a> of <a href="#Part4" id="rfc.xref.Part4.11"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests">[Part4]</cite></a></td> |
| | 2467 | </tr> |
| | 2468 | <tr> |
| | 2469 | <td class="left">413</td> |
| | 2470 | <td class="left">Payload Too Large</td> |
| | 2471 | <td class="left"><a href="#status.413" id="rfc.xref.status.413.1" title="413 Payload Too Large">Section 6.5.11</a></td> |
| | 2472 | </tr> |
| | 2473 | <tr> |
| | 2474 | <td class="left">414</td> |
| | 2475 | <td class="left">URI Too Long</td> |
| | 2476 | <td class="left"><a href="#status.414" id="rfc.xref.status.414.1" title="414 URI Too Long">Section 6.5.12</a></td> |
| | 2477 | </tr> |
| | 2478 | <tr> |
| | 2479 | <td class="left">415</td> |
| | 2480 | <td class="left">Unsupported Media Type</td> |
| | 2481 | <td class="left"><a href="#status.415" id="rfc.xref.status.415.1" title="415 Unsupported Media Type">Section 6.5.13</a></td> |
| | 2482 | </tr> |
| | 2483 | <tr> |
| | 2484 | <td class="left">416</td> |
| | 2485 | <td class="left">Range Not Satisfiable</td> |
| | 2486 | <td id="status.416" class="left"><a href="p5-range.html#status.416" title="416 Range Not Satisfiable">Section 4.4</a> of <a href="#Part5" id="rfc.xref.Part5.9"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a></td> |
| | 2487 | </tr> |
| | 2488 | <tr> |
| | 2489 | <td class="left">417</td> |
| | 2490 | <td class="left">Expectation Failed</td> |
| | 2491 | <td class="left"><a href="#status.417" id="rfc.xref.status.417.1" title="417 Expectation Failed">Section 6.5.14</a></td> |
| | 2492 | </tr> |
| | 2493 | <tr> |
| | 2494 | <td class="left">426</td> |
| | 2495 | <td class="left">Upgrade Required</td> |
| | 2496 | <td class="left"><a href="#status.426" id="rfc.xref.status.426.1" title="426 Upgrade Required">Section 6.5.15</a></td> |
| | 2497 | </tr> |
| | 2498 | <tr> |
| | 2499 | <td class="left">500</td> |
| | 2500 | <td class="left">Internal Server Error</td> |
| | 2501 | <td class="left"><a href="#status.500" id="rfc.xref.status.500.1" title="500 Internal Server Error">Section 6.6.1</a></td> |
| | 2502 | </tr> |
| | 2503 | <tr> |
| | 2504 | <td class="left">501</td> |
| | 2505 | <td class="left">Not Implemented</td> |
| | 2506 | <td class="left"><a href="#status.501" id="rfc.xref.status.501.1" title="501 Not Implemented">Section 6.6.2</a></td> |
| | 2507 | </tr> |
| | 2508 | <tr> |
| | 2509 | <td class="left">502</td> |
| | 2510 | <td class="left">Bad Gateway</td> |
| | 2511 | <td class="left"><a href="#status.502" id="rfc.xref.status.502.1" title="502 Bad Gateway">Section 6.6.3</a></td> |
| | 2512 | </tr> |
| | 2513 | <tr> |
| | 2514 | <td class="left">503</td> |
| | 2515 | <td class="left">Service Unavailable</td> |
| | 2516 | <td class="left"><a href="#status.503" id="rfc.xref.status.503.1" title="503 Service Unavailable">Section 6.6.4</a></td> |
| | 2517 | </tr> |
| | 2518 | <tr> |
| | 2519 | <td class="left">504</td> |
| | 2520 | <td class="left">Gateway Time-out</td> |
| | 2521 | <td class="left"><a href="#status.504" id="rfc.xref.status.504.1" title="504 Gateway Timeout">Section 6.6.5</a></td> |
| | 2522 | </tr> |
| | 2523 | <tr> |
| | 2524 | <td class="left">505</td> |
| | 2525 | <td class="left">HTTP Version Not Supported</td> |
| | 2526 | <td class="left"><a href="#status.505" id="rfc.xref.status.505.1" title="505 HTTP Version Not Supported">Section 6.6.6</a></td> |
| | 2527 | </tr> |
| | 2528 | </tbody> |
| | 2529 | </table> |
| | 2530 | </div> |
| | 2531 | <p id="rfc.section.6.1.p.3">Note that this list is not exhaustive — it does not include extension status codes defined in other specifications. The complete |
| | 2532 | list of status codes is maintained by IANA. See <a href="#status.code.registry" title="Status Code Registry">Section 8.2</a> for details. |
| | 2533 | </p> |
| | 2534 | </div> |
| | 2535 | <div id="status.1xx"> |
| | 2536 | <h2 id="rfc.section.6.2"><a href="#rfc.section.6.2">6.2</a> <a href="#status.1xx">Informational 1xx</a></h2> |
| | 2537 | <div id="rfc.iref.67"></div> |
| | 2538 | <div id="rfc.iref.s.3"></div> |
| | 2539 | <p id="rfc.section.6.2.p.1">The <dfn>1xx (Informational)</dfn> class of status code indicates an interim response for communicating connection status or request progress prior to completing |
| | 2540 | the requested action and sending a final response. All 1xx responses consist of only the status-line and optional header fields, |
| | 2541 | and thus are terminated by the empty line at the end of the header section. Since HTTP/1.0 did not define any 1xx status codes, |
| | 2542 | a server <em class="bcp14">MUST NOT</em> send a 1xx response to an HTTP/1.0 client. |
| | 2543 | </p> |
| | 2544 | <p id="rfc.section.6.2.p.2">A client <em class="bcp14">MUST</em> be able to parse one or more 1xx responses received prior to a final response, even if the client does not expect one. A user |
| | 2545 | agent <em class="bcp14">MAY</em> ignore unexpected 1xx responses. |
| | 2546 | </p> |
| | 2547 | <p id="rfc.section.6.2.p.3">A proxy <em class="bcp14">MUST</em> forward 1xx responses unless the proxy itself requested the generation of the 1xx response. For example, if a proxy adds an |
| | 2548 | "Expect: 100-continue" field when it forwards a request, then it need not forward the corresponding <a href="#status.100" class="smpl">100 (Continue)</a> response(s). |
| | 2549 | </p> |
| | 2550 | <div id="status.100"> |
| | 2551 | <div id="rfc.iref.68"></div> |
| | 2552 | <h3 id="rfc.section.6.2.1"><a href="#rfc.section.6.2.1">6.2.1</a> <a href="#status.100">100 Continue</a></h3> |
| | 2553 | <p id="rfc.section.6.2.1.p.1">The <dfn>100 (Continue)</dfn> status code indicates that the initial part of a request has been received and has not yet been rejected by the server. The |
| | 2554 | server intends to send a final response after the request has been fully received and acted upon. |
| | 2555 | </p> |
| | 2556 | <p id="rfc.section.6.2.1.p.2">When the request contains an <a href="#header.expect" class="smpl">Expect</a> header field that includes a <a href="#header.expect" class="smpl">100-continue</a> expectation, the 100 response indicates that the server wishes to receive the request payload body, as described in <a href="#header.expect" id="rfc.xref.header.expect.2" title="Expect">Section 5.1.1</a>. The client ought to continue sending the request and discard the 100 response. |
| | 2557 | </p> |
| | 2558 | <p id="rfc.section.6.2.1.p.3">If the request did not contain an <a href="#header.expect" class="smpl">Expect</a> header field containing the <a href="#header.expect" class="smpl">100-continue</a> expectation, the client can simply discard this interim response. |
| | 2559 | </p> |
| | 2560 | </div> |
| | 2561 | <div id="status.101"> |
| | 2562 | <div id="rfc.iref.68"></div> |
| | 2563 | <h3 id="rfc.section.6.2.2"><a href="#rfc.section.6.2.2">6.2.2</a> <a href="#status.101">101 Switching Protocols</a></h3> |
| | 2564 | <p id="rfc.section.6.2.2.p.1">The <dfn>101 (Switching Protocols)</dfn> status code indicates that the server understands and is willing to comply with the client's request, via the <a href="p1-messaging.html#header.upgrade" class="smpl">Upgrade</a> header field (<a href="p1-messaging.html#header.upgrade" title="Upgrade">Section 6.7</a> of <a href="#Part1" id="rfc.xref.Part1.23"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>), for a change in the application protocol being used on this connection. The server <em class="bcp14">MUST</em> generate an Upgrade header field in the response that indicates which protocol(s) will be switched to immediately after the |
| | 2565 | empty line that terminates the 101 response. |
| | 2566 | </p> |
| | 2567 | <p id="rfc.section.6.2.2.p.2">It is assumed that the server will only agree to switch protocols when it is advantageous to do so. For example, switching |
| | 2568 | to a newer version of HTTP might be advantageous over older versions, and switching to a real-time, synchronous protocol might |
| | 2569 | be advantageous when delivering resources that use such features. |
| | 2570 | </p> |
| | 2571 | </div> |
| | 2572 | </div> |
| | 2573 | <div id="status.2xx"> |
| | 2574 | <h2 id="rfc.section.6.3"><a href="#rfc.section.6.3">6.3</a> <a href="#status.2xx">Successful 2xx</a></h2> |
| | 2575 | <div id="rfc.iref.68"></div> |
| | 2576 | <div id="rfc.iref.s.4"></div> |
| | 2577 | <p id="rfc.section.6.3.p.1">The <dfn>2xx (Successful)</dfn> class of status code indicates that the client's request was successfully received, understood, and accepted. |
| | 2578 | </p> |
| | 2579 | <div id="status.200"> |
| | 2580 | <div id="rfc.iref.69"></div> |
| | 2581 | <h3 id="rfc.section.6.3.1"><a href="#rfc.section.6.3.1">6.3.1</a> <a href="#status.200">200 OK</a></h3> |
| | 2582 | <p id="rfc.section.6.3.1.p.1">The <dfn>200 (OK)</dfn> status code indicates that the request has succeeded. The payload sent in a 200 response depends on the request method. For |
| | 2583 | the methods defined by this specification, the intended meaning of the payload can be summarized as: |
| | 2584 | </p> |
| | 2585 | <dl> |
| | 2586 | <dt>GET</dt> |
| | 2587 | <dd>a representation of the <a href="#resources" class="smpl">target resource</a>; |
| | 2588 | </dd> |
| | 2589 | &nb |
![(please configure the [header_logo] section in trac.ini)](https://www.ietf.org/images/ietflogotrans.gif)