Sumber: RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content (rfc-editor.org)
[RFC Home] [TEXT|PDF|HTML] [Tracker] [IPR] [Errata] [Info page]
Obsoleted by: 9110 PROPOSED
STANDARD
Errata
Exist
Internet Engineering Task Force (IETF) R. Fielding, Ed.
Request for Comments: 7231 Adobe
Obsoletes: 2616 J. Reschke, Ed.
Updates: 2817
greenbytes
Category: Standards Track June 2014
ISSN: 2070-1721
Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content
Abstract
The Hypertext Transfer
Protocol (HTTP) is a stateless application-
level protocol for
distributed, collaborative, hypertext information
systems. This document defines the semantics of HTTP/1.1
messages,
as expressed by request
methods, request header fields, response
status codes, and
response header fields, along with the payload of
messages (metadata and
body content) and mechanisms for content
negotiation.
Status of This Memo
This is an Internet
Standards Track document.
This document is a
product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF
community. It has
received public review
and has been approved for publication by the
Internet Engineering
Steering Group (IESG). Further
information on
Internet Standards is
available in Section 2
of RFC 5741.
Information about the
current status of this document, any errata,
and how to provide
feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc7231.
Fielding & Reschke
Standards Track
[Page 1]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
Copyright Notice
Copyright (c) 2014 IETF
Trust and the persons identified as the
document authors. All rights reserved.
This document is subject
to BCP 78 and the IETF
Trust's Legal
Provisions Relating to
IETF Documents
(http://trustee.ietf.org/license-info)
in effect on the date of
publication of this
document. Please review these documents
carefully, as they
describe your rights and restrictions with respect
to this document. Code Components extracted from this document
must
include Simplified BSD License
text as described in Section 4.e of
the Trust Legal
Provisions and are provided without warranty as
described in the
Simplified BSD License.
This document may contain
material from IETF Documents or IETF
Contributions published
or made publicly available before November
10, 2008. The person(s) controlling the copyright in
some of this
material may not have
granted the IETF Trust the right to allow
modifications of such
material outside the IETF Standards Process.
Without obtaining an
adequate license from the person(s) controlling
the copyright in such
materials, this document may not be modified
outside the IETF
Standards Process, and derivative works of it may
not be created outside
the IETF Standards Process, except to format
it for publication as an
RFC or to translate it into languages other
than English.
Fielding & Reschke
Standards Track
[Page 2]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
Table of Contents
1. Introduction
....................................................6
1.1. Conformance
and Error Handling .............................6
1.2. Syntax
Notation ............................................6
2. Resources
.......................................................7
3. Representations
.................................................7
3.1.
Representation Metadata ....................................8
3.1.1.
Processing Representation Data ......................8
3.1.2. Encoding
for Compression or Integrity ..............11
3.1.3. Audience
Language ..................................13
3.1.4.
Identification .....................................14
3.2.
Representation Data .......................................17
3.3. Payload
Semantics .........................................17
3.4. Content
Negotiation .......................................18
3.4.1.
Proactive Negotiation ..............................19
3.4.2. Reactive
Negotiation ...............................20
4. Request Methods
................................................21
4.1. Overview
..................................................21
4.2. Common
Method Properties ..................................22
4.2.1. Safe
Methods .......................................22
4.2.2.
Idempotent Methods .................................23
4.2.3.
Cacheable Methods ..................................24
4.3. Method
Definitions ........................................24
4.3.1. GET
................................................24
4.3.2. HEAD
...............................................25
4.3.3. POST
...............................................25
4.3.4. PUT
................................................26
4.3.5. DELETE
.............................................29
4.3.6. CONNECT
............................................30
4.3.7. OPTIONS
............................................31
4.3.8. TRACE
..............................................32
5. Request Header
Fields ..........................................33
5.1. Controls
..................................................33
5.1.1. Expect
.............................................34
5.1.2.
Max-Forwards .......................................36
5.2. Conditionals
..............................................36
5.3. Content
Negotiation .......................................37
5.3.1. Quality
Values .....................................37
5.3.2. Accept
.............................................38
5.3.3.
Accept-Charset .....................................40
5.3.4.
Accept-Encoding ....................................41
5.3.5.
Accept-Language ....................................42
5.4.
Authentication Credentials ................................44
5.5. Request
Context ...........................................44
5.5.1. From
...............................................44
5.5.2. Referer
............................................45
5.5.3.
User-Agent .........................................46
Fielding & Reschke
Standards Track
[Page 3]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
6. Response Status
Codes ..........................................47
6.1. Overview of
Status Codes ..................................48
6.2. Informational
1xx .........................................50
6.2.1. 100
Continue .......................................50
6.2.2. 101
Switching Protocols ............................50
6.3. Successful
2xx ............................................51
6.3.1. 200 OK
.............................................51
6.3.2. 201
Created ........................................52
6.3.3. 202
Accepted .......................................52
6.3.4. 203
Non-Authoritative Information ..................52
6.3.5. 204 No
Content .....................................53
6.3.6. 205
Reset Content ..................................53
6.4. Redirection
3xx ...........................................54
6.4.1. 300
Multiple Choices ...............................55
6.4.2. 301
Moved Permanently ..............................56
6.4.3. 302
Found ..........................................56
6.4.4. 303 See
Other ......................................57
6.4.5. 305 Use
Proxy ......................................58
6.4.6. 306
(Unused) .......................................58
6.4.7. 307
Temporary Redirect .............................58
6.5. Client Error
4xx ..........................................58
6.5.1. 400 Bad
Request ....................................58
6.5.2. 402
Payment Required ...............................59
6.5.3. 403
Forbidden ......................................59
6.5.4. 404 Not
Found ......................................59
6.5.5. 405
Method Not Allowed .............................59
6.5.6. 406 Not
Acceptable .................................60
6.5.7. 408
Request Timeout ................................60
6.5.8. 409
Conflict .......................................60
6.5.9. 410 Gone
...........................................60
6.5.10. 411
Length Required ...............................61
6.5.11. 413
Payload Too Large .............................61
6.5.12. 414
URI Too Long ..................................61
6.5.13. 415
Unsupported Media Type ........................62
6.5.14. 417
Expectation Failed ............................62
6.5.15. 426
Upgrade Required ..............................62
6.6. Server Error
5xx ..........................................62
6.6.1. 500
Internal Server Error ..........................63
6.6.2. 501 Not
Implemented ................................63
6.6.3. 502 Bad
Gateway ....................................63
6.6.4. 503
Service Unavailable ............................63
6.6.5. 504
Gateway Timeout ................................63
6.6.6. 505 HTTP
Version Not Supported .....................64
7. Response Header
Fields .........................................64
7.1. Control Data
..............................................64
ed 7.1.1.
Origination Date ...................................65
7.1.2. Location
...........................................68
7.1.3.
Retry-After ........................................69
Fielding & Reschke
Standards Track
[Page 4]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
7.1.4. Vary
...............................................70
7.2. Validator
Header Fields ...................................71
7.3.
Authentication Challenges .................................72
7.4. Response
Context ..........................................72
7.4.1. Allow
..............................................72
7.4.2. Server
.............................................73
8. IANA
Considerations ............................................73
8.1. Method
Registry ...........................................73
8.1.1.
Procedure ..........................................74
8.1.2.
Considerations for New Methods .....................74
8.1.3.
Registrations ......................................75
8.2. Status Code
Registry ......................................75
8.2.1.
Procedure ..........................................75
8.2.2.
Considerations for New Status Codes ................76
8.2.3.
Registrations ......................................76
8.3. Header Field
Registry .....................................77
8.3.1.
Considerations for New Header Fields ...............78
8.3.2.
Registrations ......................................80
8.4. Content
Coding Registry ...................................81
8.4.1.
Procedure ..........................................81
8.4.2.
Registrations ......................................81
9. Security
Considerations ........................................81
9.1. Attacks
Based on File and Path Names ......................82
9.2. Attacks
Based on Command, Code, or Query Injection ........82
9.3. Disclosure
of Personal Information ........................83
9.4. Disclosure
of Sensitive Information in URIs ...............83
9.5. Disclosure
of Fragment after Redirects ....................84
9.6. Disclosure
of Product Information .........................84
9.7. Browser
Fingerprinting ....................................84
10.
Acknowledgments ...............................................85
11. References
....................................................85
11.1. Normative
References .....................................85
11.2.
Informative References ...................................86
Appendix A.
Differences between HTTP and MIME .....................89
A.1.
MIME-Version ..............................................89
A.2. Conversion
to Canonical Form ..............................89
A.3. Conversion
of Date Formats ................................90
A.4. Conversion
of Content-Encoding ............................90
A.5. Conversion
of Content-Transfer-Encoding ...................90
A.6. MHTML and
Line Length Limitations .........................90
Appendix B.
Changes from RFC 2616
.................................91
Appendix C.
Imported ABNF .........................................93
Appendix D.
Collected ABNF ........................................94
Index
.............................................................97
Fielding & Reschke
Standards Track
[Page 5]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
1. Introduction
Each Hypertext Transfer
Protocol (HTTP) message is either a request
or a response. A server listens on a connection for a
request,
parses each message
received, interprets the message semantics in
relation to the
identified request target, and responds to that
request with one or more
response messages. A client constructs
request messages to
communicate specific intentions, examines
received responses to see
if the intentions were carried out, and
determines how to
interpret the results. This document
defines
HTTP/1.1 request and
response semantics in terms of the architecture
defined in [RFC7230].
HTTP provides a uniform
interface for interacting with a resource
(Section 2),
regardless of its type, nature, or implementation, via
the manipulation and
transfer of representations (Section 3).
HTTP semantics include
the intentions defined by each request method
(Section 4),
extensions to those semantics that might be described in
request header fields (Section 5), the
meaning of status codes to
indicate a
machine-readable response (Section 6), and the
meaning of
other control data and
resource metadata that might be given in
response header fields (Section 7).
This document also
defines representation metadata that describe how
a payload is intended to
be interpreted by a recipient, the request
header fields that might
influence content selection, and the various
selection algorithms that
are collectively referred to as "content
negotiation" (Section 3.4).
1.1. Conformance and Error Handling
The key words
"MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT",
"SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this
document are to be
interpreted as described in [RFC2119].
Conformance criteria and
considerations regarding error handling are
defined in Section 2.5 of
[RFC7230].
1.2. Syntax Notation
This specification uses
the Augmented Backus-Naur Form (ABNF)
notation of [RFC5234]
with a list extension, defined in Section 7 of
[RFC7230], that allows for compact definition of comma-separated
lists using a '#'
operator (similar to how the '*' operator indicates
repetition). Appendix C describes
rules imported from other
documents. Appendix D shows
the collected grammar with all list
operators expanded to
standard ABNF notation.
Fielding & Reschke
Standards Track
[Page 6]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
This specification uses
the terms "character", "character encoding
scheme",
"charset", and "protocol element" as they are defined in
[RFC6365].
2. Resources
The target of an HTTP
request is called a "resource".
HTTP does not
limit the nature of a
resource; it merely defines an interface that
might be used to interact
with resources. Each resource is
identified by a Uniform
Resource Identifier (URI), as described in
When a client constructs
an HTTP/1.1 request message, it sends the
target URI in one of
various forms, as defined in (Section 5.3 of
[RFC7230]). When a request is
received, the server reconstructs an
effective request URI for
the target resource (Section 5.5 of
One design goal of HTTP
is to separate resource identification from
request semantics, which
is made possible by vesting the request
semantics in the request
method (Section 4)
and a few
request-modifying header
fields (Section 5). If there is a conflict
between the method
semantics and any semantic implied by the URI
itself, as described in Section 4.2.1,
the method semantics take
precedence.
3. Representations
Considering that a
resource could be anything, and that the uniform
interface provided by
HTTP is similar to a window through which one
can observe and act upon
such a thing only through the communication
of messages to some
independent actor on the other side, an
abstraction is needed to
represent ("take the place of") the current
or desired state of that
thing in our communications. That
abstraction is called a
representation [REST].
For the purposes of HTTP,
a "representation" is information that is
intended to reflect a
past, current, or desired state of a given
resource, in a format
that can be readily communicated via the
protocol, and that consists of a set of
representation metadata and a
potentially unbounded
stream of representation data.
An origin server might be
provided with, or be capable of generating,
multiple representations
that are each intended to reflect the
current state of a target
resource. In such cases, some algorithm
is
used by the origin server
to select one of those representations as
most applicable to a
given request, usually based on content
negotiation. This "selected representation" is
used to provide the
Fielding & Reschke
Standards Track
[Page 7]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
data and metadata for
evaluating conditional requests [RFC7232]
and
constructing the payload
for 200 (OK) and 304 (Not Modified)
responses to GET (Section 4.3.1).
3.1. Representation Metadata
Representation header
fields provide metadata about the
representation. When a message includes a payload body, the
representation header
fields describe how to interpret the
representation data
enclosed in the payload body. In a
response to a
HEAD request, the
representation header fields describe the
representation data that
would have been enclosed in the payload body
if the same request had
been a GET.
The following header
fields convey representation metadata:
+-------------------+-----------------+
| Header Field Name |
Defined in... |
+-------------------+-----------------+
| Content-Type | Section 3.1.1.5
|
| Content-Encoding | Section 3.1.2.2
|
| Content-Language | Section 3.1.3.2
|
| Content-Location | Section 3.1.4.2
|
+-------------------+-----------------+
3.1.1. Processing Representation Data
3.1.1.1. Media Type
HTTP uses Internet media
types [RFC2046]
in the Content-Type
(Section 3.1.1.5)
and Accept (Section
5.3.2) header fields in order
to provide open and
extensible data typing and type negotiation.
Media types define both a
data format and various processing models:
how to process that data
in accordance with each context in which it
is received.
media-type = type
"/" subtype *( OWS ";" OWS parameter )
type = token
subtype = token
The type/subtype MAY be
followed by parameters in the form of
name=value pairs.
parameter = token "=" ( token /
quoted-string )
Fielding & Reschke
Standards Track
[Page 8]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
The type, subtype, and
parameter name tokens are case-insensitive.
Parameter values might or
might not be case-sensitive, depending on
the semantics of the
parameter name. The presence or absence
of a
parameter might be significant
to the processing of a media-type,
depending on its
definition within the media type registry.
A parameter value that
matches the token production can be
transmitted either as a
token or within a quoted-string. The
quoted
and unquoted values are
equivalent. For example, the following
examples are all
equivalent, but the first is preferred for
consistency:
text/html;charset=utf-8
text/html;charset=UTF-8
Text/HTML;Charset="utf-8"
text/html; charset="utf-8"
Internet media types
ought to be registered with IANA according to
the procedures defined in
[BCP13].
Note: Unlike some similar constructs in other
header fields, media
type parameters do not
allow whitespace (even "bad" whitespace)
around the
"=" character.
3.1.1.2. Charset
HTTP uses charset names
to indicate or negotiate the character
encoding scheme of a
textual representation [RFC6365]. A charset is
identified by a
case-insensitive token.
charset = token
Charset names ought to be
registered in the IANA "Character Sets"
registry (<http://www.iana.org/assignments/character-sets>)
according
to the procedures defined
in [RFC2978].
3.1.1.3. Canonicalization and Text Defaults
Internet media types are
registered with a canonical form in order to
be interoperable among
systems with varying native encoding formats.
Representations selected
or transferred via HTTP ought to be in
canonical form, for many
of the same reasons described by the
Multipurpose Internet
Mail Extensions (MIME) [RFC2045]. However, the
performance
characteristics of email deployments (i.e., store and
forward messages to
peers) are significantly different from those
common to HTTP and the
Web (server-based information services).
Furthermore, MIME's
constraints for the sake of compatibility with
older mail transfer
protocols do not apply to HTTP (see Appendix A).
Fielding & Reschke
Standards Track [Page 9]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
MIME's canonical form
requires that media subtypes of the "text" type
use CRLF as the text line
break. HTTP allows the transfer of text
media with plain CR or LF
alone representing a line break, when such
line breaks are
consistent for an entire representation.
An HTTP
sender MAY generate, and
a recipient MUST be able to parse, line
breaks in text media that
consist of CRLF, bare CR, or bare LF. In
addition, text media in
HTTP is not limited to charsets that use
octets 13 and 10 for CR
and LF, respectively. This flexibility
regarding line breaks
applies only to text within a representation
that has been assigned a
"text" media type; it does not apply to
"multipart"
types or HTTP elements outside the payload body (e.g.,
header fields).
If a representation is
encoded with a content-coding, the underlying
data ought to be in a
form defined above prior to being encoded.
3.1.1.4. Multipart Types
MIME provides for a
number of "multipart" types -- encapsulations of
one or more
representations within a single message body.
All
multipart types share a
common syntax, as defined in Section 5.1.1
of
[RFC2046], and include a boundary parameter as part of the media type
value. The message body is itself a protocol
element; a sender MUST
generate only CRLF to
represent line breaks between body parts.
HTTP message framing does
not use the multipart boundary as an
indicator of message body
length, though it might be used by
implementations that
generate or process the payload. For example,
the
"multipart/form-data" type is often used for carrying form data
in a request, as
described in [RFC2388],
and the "multipart/
byteranges" type is defined by this
specification for use in some 206
(Partial Content)
responses [RFC7233].
3.1.1.5. Content-Type
The
"Content-Type" header field indicates the media type of the
associated
representation: either the representation enclosed in the
message payload or the
selected representation, as determined by the
message semantics. The indicated media type defines both the
data
format and how that data
is intended to be processed by a recipient,
within the scope of the
received message semantics, after any content
codings indicated by
Content-Encoding are decoded.
Content-Type =
media-type
Fielding & Reschke
Standards Track
[Page 10]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
Media types are defined
in Section
3.1.1.1. An example of the field
is
Content-Type:
text/html; charset=ISO-8859-4
A sender that generates a
message containing a payload body SHOULD
generate a Content-Type
header field in that message unless the
intended media type of
the enclosed representation is unknown to the
sender. If a Content-Type header field is not
present, the recipient
MAY either assume a media
type of "application/octet-stream"
([RFC2046],
Section 4.5.1) or examine the data to determine its type.
In practice, resource
owners do not always properly configure their
origin server to provide
the correct Content-Type for a given
representation, with the
result that some clients will examine a
payload's content and
override the specified type. Clients
that do
so risk drawing incorrect
conclusions, which might expose additional
security risks (e.g.,
"privilege escalation").
Furthermore, it is
impossible to determine
the sender's intent by examining the data
format: many data formats
match multiple media types that differ only
in processing
semantics. Implementers are encouraged
to provide a
means of disabling such
"content sniffing" when it is used.
3.1.2. Encoding for Compression or Integrity
3.1.2.1. Content Codings
Content coding values
indicate an encoding transformation that has
been or can be applied to
a representation. Content codings are
primarily used to allow a
representation to be compressed or
otherwise usefully
transformed without losing the identity of its
underlying media type and
without loss of information. Frequently,
the representation is
stored in coded form, transmitted directly, and
only decoded by the final
recipient.
content-coding = token
All content-coding values
are case-insensitive and ought to be
registered within the
"HTTP Content Coding Registry", as defined in
Section 8.4. They are used in the Accept-Encoding (Section 5.3.4)
and Content-Encoding (Section 3.1.2.2)
header fields.
Fielding & Reschke
Standards Track
[Page 11]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
The following
content-coding values are defined by this
specification:
compress (and
x-compress): See Section 4.2.1
of [RFC7230].
deflate: See Section 4.2.2
of [RFC7230].
gzip (and x-gzip): See
Section 4.2.3
of [RFC7230].
3.1.2.2. Content-Encoding
The
"Content-Encoding" header field indicates what content codings
have been applied to the
representation, beyond those inherent in the
media type, and thus what
decoding mechanisms have to be applied in
order to obtain data in
the media type referenced by the Content-Type
header field. Content-Encoding is primarily used to allow a
representation's data to
be compressed without losing the identity of
its underlying media
type.
Content-Encoding =
1#content-coding
An example of its use is
Content-Encoding: gzip
If one or more encodings
have been applied to a representation, the
sender that applied the
encodings MUST generate a Content-Encoding
header field that lists
the content codings in the order in which
they were applied. Additional information about the encoding
parameters can be
provided by other header fields not defined by this
specification.
Unlike Transfer-Encoding
(Section 3.3.1
of [RFC7230]), the codings
listed in
Content-Encoding are a characteristic of the
representation; the
representation is defined in terms of the coded
form, and all other
metadata about the representation is about the
coded form unless
otherwise noted in the metadata definition.
Typically, the
representation is only decoded just prior to rendering
or analogous usage.
If the media type
includes an inherent encoding, such as a data
format that is always
compressed, then that encoding would not be
restated in
Content-Encoding even if it happens to be the same
algorithm as one of the
content codings. Such a content coding
would
only be listed if, for
some bizarre reason, it is applied a second
time to form the
representation. Likewise, an origin
server might
choose to publish the
same data as multiple representations that
differ only in whether
the coding is defined as part of Content-Type
Fielding & Reschke
Standards Track
[Page 12]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
or Content-Encoding,
since some user agents will behave differently
in their handling of each
response (e.g., open a "Save as ..." dialog
instead of automatic
decompression and rendering of content).
An origin server MAY respond
with a status code of 415 (Unsupported
Media Type) if a
representation in the request message has a content
coding that is not
acceptable.
3.1.3. Audience Language
3.1.3.1. Language Tags
A language tag, as
defined in [RFC5646], identifies a
natural
language spoken, written,
or otherwise conveyed by human beings for
communication of
information to other human beings.
Computer
languages are explicitly
excluded.
HTTP uses language tags
within the Accept-Language and
Content-Language header
fields. Accept-Language uses the broader
language-range production
defined in Section
5.3.5, whereas
Content-Language uses the
language-tag production defined below.
language-tag = <Language-Tag, see [RFC5646],
Section 2.1>
A language tag is a
sequence of one or more case-insensitive subtags,
each separated by a
hyphen character ("-", %x2D).
In most cases, a
language tag consists of
a primary language subtag that identifies a
broad family of related
languages (e.g., "en" = English), which is
optionally followed by a
series of subtags that refine or narrow that
language's range (e.g.,
"en-CA" = the variety of English as
communicated in
Canada). Whitespace is not allowed
within a language
tag. Example tags include:
fr, en-US, es-419,
az-Arab, x-pig-latin, man-Nkoo-GN
See [RFC5646] for further
information.
3.1.3.2. Content-Language
The
"Content-Language" header field describes the natural language(s)
of the intended audience
for the representation. Note that this
might not be equivalent
to all the languages used within the
representation.
Content-Language =
1#language-tag
Fielding & Reschke
Standards Track
[Page 13]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
Language tags are defined
in Section
3.1.3.1. The primary purpose of
Content-Language is to
allow a user to identify and differentiate
representations according
to the users' own preferred language.
Thus, if the content is
intended only for a Danish-literate audience,
the appropriate field is
Content-Language: da
If no Content-Language is
specified, the default is that the content
is intended for all
language audiences. This might mean that
the
sender does not consider
it to be specific to any natural language,
or that the sender does
not know for which language it is intended.
Multiple languages MAY be
listed for content that is intended for
multiple audiences. For example, a rendition of the "Treaty
of
Waitangi", presented
simultaneously in the original Maori and English
versions, would call for
Content-Language: mi,
en
However, just because
multiple languages are present within a
representation does not
mean that it is intended for multiple
linguistic
audiences. An example would be a
beginner's language
primer, such as "A
First Lesson in Latin", which is clearly intended
to be used by an
English-literate audience. In this case,
the
Content-Language would
properly only include "en".
Content-Language MAY be
applied to any media type -- it is not
limited to textual
documents.
3.1.4. Identification
3.1.4.1. Identifying a Representation
When a complete or
partial representation is transferred in a message
payload, it is often
desirable for the sender to supply, or the
recipient to determine,
an identifier for a resource corresponding to
that representation.
For a request message:
o If the request has a Content-Location header
field, then the
sender asserts that
the payload is a representation of the
resource identified by
the Content-Location field-value.
However,
such an assertion
cannot be trusted unless it can be verified by
other means (not
defined by this specification). The
information
might still be useful
for revision history links.
Fielding & Reschke
Standards Track
[Page 14]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
o Otherwise, the payload is unidentified.
For a response message,
the following rules are applied in order
until a match is found:
1. If the request method is GET or HEAD and the
response status code
is 200 (OK), 204 (No
Content), 206 (Partial Content), or 304 (Not
Modified), the
payload is a representation of the resource
identified by the
effective request URI (Section 5.5 of
2. If the request method is GET or HEAD and the
response status code
is 203
(Non-Authoritative Information), the payload is a
potentially modified
or enhanced representation of the target
resource as provided
by an intermediary.
3. If the response has a Content-Location header
field and its
field-value is a
reference to the same URI as the effective
request URI, the
payload is a representation of the resource
identified by the
effective request URI.
4. If the response has a Content-Location header
field and its
field-value is a
reference to a URI different from the effective
request URI, then the
sender asserts that the payload is a
representation of the
resource identified by the Content-Location
field-value. However, such an assertion cannot be trusted
unless
it can be verified by
other means (not defined by this
specification).
5. Otherwise, the payload is unidentified.
3.1.4.2. Content-Location
The
"Content-Location" header field references a URI that can be used
as an identifier for a
specific resource corresponding 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 of this
message's generation,
then a 200 (OK) response would contain the same
representation that is
enclosed as payload in this message.
Content-Location =
absolute-URI / partial-URI
The Content-Location
value is not a replacement for the effective
Request URI (Section 5.5 of
[RFC7230]). It is representation
metadata. It has the same syntax and semantics as the
header field
of the same name defined
for MIME body parts in Section 4 of
[RFC2557]. However, its appearance
in an HTTP message has some
special implications for
HTTP recipients.
Fielding & Reschke
Standards Track
[Page 15]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
If Content-Location is
included in a 2xx (Successful) response
message and its value
refers (after conversion to absolute form) to a
URI that is the same as
the effective request URI, then the recipient
MAY consider the payload
to be a current representation of that
resource at the time
indicated by the message origination date.
For
a GET (Section 4.3.1)
or HEAD (Section
4.3.2) request, this is the
same as the default
semantics when no Content-Location is provided by
the server. For a state-changing request like PUT (Section 4.3.4)
or
POST (Section 4.3.3),
it implies that the server's response contains
the new representation of
that resource, thereby distinguishing it
from representations that
might only report about the action (e.g.,
"It worked!"). This allows authoring applications to update
their
local copies without the
need for a subsequent GET request.
If Content-Location is
included in a 2xx (Successful) response
message and its
field-value refers to a URI that differs from the
effective request URI,
then the origin server claims that the URI is
an identifier for a
different resource corresponding to the enclosed
representation. Such a claim can only be trusted if both
identifiers
share the same resource
owner, which cannot be programmatically
determined via HTTP.
o For a response to a GET or HEAD request, this
is an indication
that the effective
request URI refers to a resource that is
subject to content negotiation and the
Content-Location
field-value is a more
specific identifier for the selected
representation.
o For a 201 (Created) response to a
state-changing method, a
Content-Location
field-value that is identical to the Location
field-value indicates
that this payload is a current
representation of the
newly created resource.
o Otherwise, such a Content-Location indicates
that this payload is
a representation
reporting on the requested action's status and
that the same report
is available (for future access with GET) at
the given URI. For example, a purchase transaction made via
a
POST request might
include a receipt document as the payload of
the 200 (OK) response;
the Content-Location field-value provides
an identifier for
retrieving a copy of that same receipt in the
future.
A user agent that sends
Content-Location in a request message is
stating that its value
refers to where the user agent originally
obtained the content of
the enclosed representation (prior to any
modifications made by
that user agent). In other words, the
user
agent is providing a back
link to the source of the original
representation.
Fielding & Reschke
Standards Track
[Page 16]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
An origin server that
receives a Content-Location field in a request
message MUST treat the
information as transitory request context
rather than as metadata
to be saved verbatim as part of the
representation. An origin server MAY use that context to
guide in
processing the request or
to save it for other uses, such as within
source links or
versioning metadata. However, an origin
server MUST
NOT use such context
information to alter the request semantics.
For example, if a client
makes a PUT request on a negotiated resource
and the origin server
accepts that PUT (without redirection), then
the new state of that
resource is expected to be consistent with the
one representation
supplied in that PUT; the Content-Location cannot
be used as a form of
reverse content selection identifier to update
only one of the
negotiated representations. If the user
agent had
wanted the latter
semantics, it would have applied the PUT directly
to the Content-Location
URI.
3.2. Representation Data
The representation data
associated with an HTTP message is either
provided as the payload
body of the message or referred to by the
message semantics and the
effective request URI. The
representation
data is in a format and
encoding defined by the representation
metadata header fields.
The data type of the
representation data is determined via the header
fields Content-Type and
Content-Encoding. These define a
two-layer,
ordered encoding model:
representation-data :=
Content-Encoding( Content-Type( bits ) )
3.3. Payload Semantics
Some HTTP messages
transfer a complete or partial representation as
the message
"payload". In some cases, a
payload might contain only
the associated
representation's header fields (e.g., responses to
HEAD) or only some
part(s) of the representation data (e.g., the 206
(Partial Content) status
code).
The purpose of a payload
in a request is defined by the method
semantics. For example, a representation in the payload
of a PUT
request (Section 4.3.4)
represents the desired state of the target
resource if the request
is successfully applied, whereas a
representation in the
payload of a POST request (Section 4.3.3)
represents information to
be processed by the target resource.
Fielding & Reschke Standards Track [Page 17]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
In a response, the
payload's purpose is defined by both the request
method and the response
status code. For example, the payload of
a
200 (OK) response to GET
(Section 4.3.1)
represents the current state
of the target resource,
as observed at the time of the message
origination date (Section 7.1.1.2),
whereas the payload of the same
status code in a response
to POST might represent either the
processing result or the
new state of the target resource after
applying the processing. Response messages with an error status code
usually contain a payload
that represents the error condition, such
that it describes the
error state and what next steps are suggested
for resolving it.
Header fields that
specifically describe the payload, rather than the
associated
representation, are referred to as "payload header
fields". Payload header fields are defined in other
parts of this
specification, due to
their impact on message parsing.
+-------------------+----------------------------+
| Header Field Name |
Defined in... |
+-------------------+----------------------------+
| Content-Length | Section 3.3.2
of [RFC7230] |
| Content-Range | Section 4.2 of
[RFC7233] |
| Trailer | Section 4.4 of
[RFC7230] |
| Transfer-Encoding | Section 3.3.1
of [RFC7230] |
+-------------------+----------------------------+
3.4. Content Negotiation
When responses convey
payload information, whether indicating a
success or an error, the
origin server often has different ways of
representing that
information; for example, in different formats,
languages, or
encodings. Likewise, different users or
user agents
might have differing
capabilities, characteristics, or preferences
that could influence
which representation, among those available,
would be best to
deliver. For this reason, HTTP provides
mechanisms
for content negotiation.
This specification
defines two patterns of content negotiation that
can be made visible
within the protocol: "proactive", where the
server selects the
representation based upon the user agent's stated
preferences, and
"reactive" negotiation, where the server provides a
list of representations
for the user agent to choose from. Other
patterns of content
negotiation include "conditional content", where
the representation
consists of multiple parts that are selectively
rendered based on user
agent parameters, "active content", where the
representation contains a
script that makes additional (more
specific) requests based
on the user agent characteristics, and
"Transparent Content
Negotiation" ([RFC2295]),
where content
Fielding & Reschke
Standards Track
[Page 18]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
selection is performed by
an intermediary. These patterns are not
mutually exclusive, and
each has trade-offs in applicability and
practicality.
Note that, in all cases,
HTTP is not aware of the resource semantics.
The consistency with
which an origin server responds to requests,
over time and over the
varying dimensions of content negotiation, and
thus the
"sameness" of a resource's observed representations over
time, is determined
entirely by whatever entity or algorithm selects
or generates those
responses. HTTP pays no attention to the
man
behind the curtain.
3.4.1. Proactive Negotiation
When content negotiation
preferences are sent by the user agent in a
request to encourage an
algorithm located at the server to select the
preferred representation,
it is called proactive negotiation (a.k.a.,
server-driven
negotiation). Selection is based on the
available
representations for a
response (the dimensions over which it might
vary, such as language,
content-coding, etc.) compared to various
information supplied in
the request, including both the explicit
negotiation fields of Section 5.3 and
implicit characteristics, such
as the client's network
address or parts of the User-Agent field.
Proactive negotiation is
advantageous when the algorithm for
selecting from among the
available representations is difficult 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 (hoping
to avoid the round trip delay
of a subsequent request if the "best
guess" is good
enough for the user). In order to
improve the
server's guess, a user
agent MAY send request header fields that
describe its preferences.
Proactive negotiation has
serious disadvantages:
o It is impossible for the server to accurately
determine what might
be "best"
for any given user, since that would require complete
knowledge of both the
capabilities of the user agent and the
intended use for the
response (e.g., does the user want to view it
on screen or print it
on paper?);
o Having the user agent describe its
capabilities in every request
can be both very
inefficient (given that only a small percentage
of responses have
multiple representations) and a potential risk
to the user's privacy;
o It complicates the implementation of an
origin server and the
algorithms for
generating responses to a request; and,
Fielding & Reschke
Standards Track [Page
19]
RFC 7231
HTTP/1.1 Semantics and
Content June 2014
o It limits the reusability of responses for
shared caching.
A user agent cannot rely
on proactive negotiation preferences being
consistently honored,
since the origin server might not implement
proactive negotiation for
the requested resource or might decide that
sending a response that
doesn't conform to the user agent's
preferences is better
than sending a 406 (Not Acceptable) response.
A Vary header field (Section 7.1.4)
is often sent in a response
subject to proactive
negotiation to indicate what parts of the
request information were
used in the selection algorithm.
3.4.2. Reactive Negotiation
With reactive negotiation
(a.k.a., agent-driven negotiation),
selection of the best
response representation (regardless of the
status code) is performed
by the user agent after receiving an
initial response from the
origin server that contains a list of
resources for alternative
representations. If the user agent is
not
satisfied by the initial
response representation, it can perform a
GET request on one or
more of the alternative resources, selected
based on metadata
included in the list, to obtain a different form of
representation for that
response. Selection of alternatives
might be
performed automatically
by the user agent or manually by the user
selecting from a
generated (possibly hypertext) menu.
Note that the above
refers to representations of the response, in
general, not
representations of the resource. The
alternative
representations are only
considered representations of the target
resource if the response
in which those alternatives are provided has
the semantics of being a
representation of the target resource (e.g.,
a 200 (OK) response to a
GET request) or has the semantics of
providing links to
alternative representations for the target
resource (e.g., a 300
(Multiple Choices) response to a GET request).
A server might choose not
to send an initial representation, other
than the list of
alternatives, and thereby indicate that reactive
negotiation by the user
agent is preferred. For example, the
alternatives listed in
responses with the 300 (Multiple Choices) and
406 (Not Acceptable)
status codes include information about the
available representations
so that the user or user agent can react by
making a selection.
Reactive negotiation is
advantageous when the response would vary
over commonly used
dimensions (such as type, language, or encoding),
when the origin server is
unable to determine a user agent's
capabilities from
examining the request, and generally when public
caches are used to
distribute server load and reduce network usage.
Fielding & Reschke
Standards Track
[Page 20]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
Reactive negotiation
suffers from the disadvantages of transmitting a
list of alternatives to
the user agent, which degrades user-perceived
latency if transmitted in
the header section, and needing a second
request to obtain an
alternate representation. Furthermore,
this
specification does not
define a mechanism for supporting automatic
selection, though it does
not prevent such a mechanism from being
developed as an
extension.
4. Request Methods
4.1. Overview
The request method token
is the primary source of request semantics;
it indicates the purpose
for which the client has made this request
and what is expected by
the client as a successful result.
The request method's
semantics might be further specialized by the
semantics of some header
fields when present in a request (Section 5)
if those additional
semantics do not conflict with the method.
For
example, a client can
send conditional request header fields
(Section 5.2) to
make the requested action conditional on the current
state of the target
resource ([RFC7232]).
method = token
HTTP was originally
designed to be usable as an interface to
distributed object
systems. The request method was
envisioned as
applying semantics to a
target resource in much the same way as
invoking a defined method
on an identified object would apply
semantics. The method token is case-sensitive because it
might be
used as a gateway to
object-based systems with case-sensitive method
names.
Unlike distributed
objects, the standardized request methods in HTTP
are not
resource-specific, since uniform interfaces provide for
better visibility and
reuse in network-based systems [REST]. Once
defined, a standardized
method ought to have the same semantics when
applied to any resource,
though each resource determines for itself
whether those semantics
are implemented or allowed.
This specification
defines a number of standardized methods that are
commonly used in HTTP, as
outlined by the following table. By
convention, standardized
methods are defined in all-uppercase
US-ASCII letters.
Fielding & Reschke
Standards Track
[Page 21]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
+---------+-------------------------------------------------+-------+
| Method | Description |
Sec. |
+---------+-------------------------------------------------+-------+
| GET | Transfer a current representation of the
target | 4.3.1 |
| | resource. | |
| HEAD | Same as GET, but only transfer the status
line | 4.3.2 |
| | and header section. | |
| POST | Perform resource-specific processing on
the | 4.3.3 |
| | request payload. | |
| PUT | Replace all current representations of
the | 4.3.4 |
| | target resource with the request
payload. | |
| DELETE | Remove all current representations of
the | 4.3.5 |
| | target resource. | |
| CONNECT | Establish a
tunnel to the server identified by |
4.3.6 |
| | the target resource. | |
| OPTIONS | Describe the
communication options for the |
4.3.7 |
| | target resource. |
|
| TRACE | Perform a message loop-back test along the
path | 4.3.8 |
| | to the target resource. | |
+---------+-------------------------------------------------+-------+
All general-purpose
servers MUST support the methods GET and HEAD.
All other methods are
OPTIONAL.
Additional methods,
outside the scope of this specification, have
been standardized for use
in HTTP. All such methods ought to be
registered within the
"Hypertext Transfer Protocol (HTTP) Method
Registry" maintained
by IANA, as defined in Section 8.1.
The set of methods
allowed by a target resource can be listed in an
Allow header field (Section 7.4.1). However, the set of allowed
methods can change
dynamically. When a request method is
received
that is unrecognized or
not implemented by an origin server, the
origin server SHOULD
respond with the 501 (Not Implemented) status
code. When a request method is received that is
known by an origin
server but not allowed
for the target resource, the origin server
SHOULD respond with the
405 (Method Not Allowed) status code.
4.2. Common Method Properties
4.2.1. Safe Methods
Request methods are
considered "safe" if their defined semantics are
essentially read-only;
i.e., the client does not request, and does
not expect, any state
change on the origin server as a result of
applying a safe method to
a target resource. Likewise, reasonable
use of a safe method is
not expected to cause any harm, loss of
property, or unusual
burden on the origin server.
Fielding & Reschke
Standards Track
[Page 22]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
This definition of safe
methods does not prevent an implementation
from including behavior
that is potentially harmful, that is not
entirely read-only, or
that causes side effects while invoking a safe
method. What is important, however, is that the
client did not
request that additional
behavior and cannot be held accountable for
it. For example, most servers append request
information to access
log files at the
completion of every response, regardless of the
method, and that is
considered safe even though the log storage might
become full and crash the
server. Likewise, a safe request
initiated
by selecting an
advertisement on the Web will often have the side
effect of charging an
advertising account.
Of the request methods
defined by this specification, the GET, HEAD,
OPTIONS, and TRACE
methods are defined to be safe.
The purpose of
distinguishing between safe and unsafe methods is to
allow automated retrieval
processes (spiders) and cache performance
optimization
(pre-fetching) to work without fear of causing harm. In
addition, it allows a
user agent to apply appropriate constraints on
the automated use of
unsafe methods when processing potentially
untrusted content.
A user agent SHOULD
distinguish between safe and unsafe methods when
presenting potential
actions to a user, such that the user can be
made aware of an unsafe
action before it is requested.
When a resource is
constructed such that parameters within the
effective request URI
have the effect of selecting an action, it is
the resource owner's
responsibility to ensure that the action is
consistent with the
request method semantics. For example,
it is
common for Web-based
content editing software to use actions within
query parameters, such as
"page?do=delete". If the
purpose of such a
resource is to perform an
unsafe action, then the resource owner MUST
disable or disallow that
action when it is accessed using a safe
request method. Failure to do so will result in unfortunate
side
effects when automated
processes perform a GET on every URI reference
for the sake of link
maintenance, pre-fetching, building a search
index, etc.
4.2.2. Idempotent Methods
A request method is
considered "idempotent" if the intended effect on
the server of multiple
identical requests with that method is the
same as the effect for a
single such request. Of the request
methods
defined by this
specification, PUT, DELETE, and safe request methods
are idempotent.
Fielding & Reschke
Standards Track
[Page 23]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
Like the definition of
safe, the idempotent property only applies to
what has been requested
by the user; a server is free to log each
request separately,
retain a revision control history, or implement
other non-idempotent side
effects for each idempotent request.
Idempotent methods are
distinguished because the request can be
repeated automatically if
a communication failure occurs before the
client is able to read
the server's response. For example, if a
client sends a PUT
request and the underlying connection is closed
before any response is
received, then the client can establish a new
connection and retry the
idempotent request. It knows that
repeating
the request will have the
same intended effect, even if the original
request succeeded, though
the response might differ.
4.2.3. Cacheable Methods
Request methods can be
defined as "cacheable" to indicate that
responses to them are
allowed to be stored for future reuse; for
specific requirements see
[RFC7234]. In general, safe methods that
do not depend on a
current or authoritative response are defined as
cacheable; this
specification defines GET, HEAD, and POST as
cacheable, although the
overwhelming majority of cache
implementations only
support GET and HEAD.
4.3. Method Definitions
4.3.1. GET
The GET method requests
transfer of a current selected representation
for the target
resource. GET is the primary mechanism
of information
retrieval and the focus
of almost all performance optimizations.
Hence, when people speak
of retrieving some identifiable information
via HTTP, they are
generally referring to making a GET request.
It is tempting to think
of resource identifiers as remote file system
pathnames and of
representations as being a copy of the contents of
such files. In fact, that is how many resources are
implemented (see
Section 9.1 for
related security considerations).
However, there are
no such limitations in
practice. The HTTP interface for a
resource
is just as likely to be
implemented as a tree of content objects, a
programmatic view on
various database records, or a gateway to other
information systems. Even when the URI mapping mechanism is tied
to
a file system, an origin
server might be configured to execute the
files with the request as
input and send the output as the
representation rather
than transfer the files directly.
Regardless,
only the origin server
needs to know how each of its resource
Fielding & Reschke
Standards Track
[Page 24]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
identifiers corresponds
to an implementation and how each
implementation manages to
select and send a current representation of
the target resource in a
response to GET.
A client can alter the
semantics of GET to be a "range request",
requesting transfer of
only some part(s) of the selected
representation, by
sending a Range header field in the request
([RFC7233]).
A payload within a GET
request message has no defined semantics;
sending a payload body on
a GET request might cause some existing
implementations to reject
the request.
The response to a GET
request is cacheable; a cache MAY use it to
satisfy subsequent GET
and HEAD requests unless otherwise indicated
by the Cache-Control
header field (Section 5.2
of [RFC7234]).
4.3.2. HEAD
The HEAD method is
identical to GET except that the server MUST NOT
send a message body in
the response (i.e., the response terminates at
the end of the header
section). The server SHOULD send the
same
header fields in response
to a HEAD request as it would have sent if
the request had been a
GET, except that the payload header fields
(Section 3.3) MAY
be omitted. This method can be used for
obtaining
metadata about the
selected representation without transferring the
representation data and
is often used for testing hypertext links for
validity, accessibility,
and recent modification.
A payload within a HEAD
request message has no defined semantics;
sending a payload body on
a HEAD request might cause some existing
implementations to reject
the request.
The response to a HEAD
request is cacheable; a cache MAY use it to
satisfy subsequent HEAD
requests unless otherwise indicated by the
Cache-Control header
field (Section 5.2
of [RFC7234]). A HEAD
response might also have
an effect on previously cached responses to
GET; see Section 4.3.5
of [RFC7234].
4.3.3. POST
The POST method requests
that the target resource process the
representation enclosed
in the request according to the resource's
own specific
semantics. For example, POST is used for
the following
functions (among others):
o Providing a block of data, such as the fields
entered into an HTML
form, to a
data-handling process;
Fielding & Reschke
Standards Track
[Page 25]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
o Posting a message to a bulletin board,
newsgroup, mailing list,
blog, or similar group
of articles;
o Creating a new resource that has yet to be
identified by the
origin server; and
o Appending data to a resource's existing
representation(s).
An origin server
indicates response semantics by choosing an
appropriate status code
depending on the result of processing the
POST request; almost all
of the status codes defined by this
specification might be
received in a response to POST (the exceptions
being 206 (Partial
Content), 304 (Not Modified), and 416 (Range Not
Satisfiable)).
If one or more resources
has been created on the origin server as a
result of successfully
processing a POST request, the origin server
SHOULD send a 201
(Created) response containing a Location header
field that provides an
identifier for the primary resource created
(Section 7.1.2)
and a representation that describes the status of the
request while referring
to the new resource(s).
Responses to POST
requests are only cacheable when they include
explicit freshness
information (see Section 4.2.1
of [RFC7234]).
However, POST caching is
not widely implemented. For cases where
an
origin server wishes the
client to be able to cache the result of a
POST in a way that can be
reused by a later GET, the origin server
MAY send a 200 (OK)
response containing the result and a
Content-Location header
field that has the same value as the POST's
effective request URI (Section 3.1.4.2).
If the result of
processing a POST would be equivalent to a
representation of an
existing resource, an origin server MAY redirect
the user agent to that
resource by sending a 303 (See Other) response
with the existing
resource's identifier in the Location field.
This
has the benefits of
providing the user agent a resource identifier
and transferring the
representation via a method more amenable to
shared caching, though at
the cost of an extra request if the user
agent does not already
have the representation cached.
4.3.4. PUT
The PUT method requests
that the state of the target resource be
created or replaced with
the state defined by the representation
enclosed in the request
message payload. A successful PUT of a
given
representation would
suggest that a subsequent GET on that same
target resource will
result in an equivalent representation being
sent in a 200 (OK)
response. However, there is no guarantee
that
Fielding & Reschke
Standards Track
[Page 26]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
such a state change will
be observable, since the target resource
might be acted upon by
other user agents in parallel, or might be
subject to dynamic
processing by the origin server, before any
subsequent GET is
received. A successful response only
implies that
the user agent's intent
was achieved at the time of its processing by
the origin server.
If the target resource
does not have a current representation and the
PUT successfully creates
one, then the origin server MUST inform the
user agent by sending a
201 (Created) response. If the target
resource does have a current representation
and that representation
is successfully modified
in accordance with the state of the enclosed
representation, then the
origin server MUST send either a 200 (OK) or
a 204 (No Content)
response to indicate successful completion of the
request.
An origin server SHOULD
ignore unrecognized header fields received in
a PUT request (i.e., do
not save them as part of the resource state).
An origin server SHOULD
verify that the PUT representation is
consistent with any
constraints the server has for the target
resource that cannot or
will not be changed by the PUT. This is
particularly important
when the origin server uses internal
configuration information
related to the URI in order to set the
values for representation
metadata on GET responses. When a PUT
representation is
inconsistent with the target resource, the origin
server SHOULD either make
them consistent, by transforming the
representation or
changing the resource configuration, or respond
with an appropriate error
message containing sufficient information
to explain why the
representation is unsuitable. The 409
(Conflict)
or 415 (Unsupported Media
Type) status codes are suggested, with the
latter being specific to
constraints on Content-Type values.
For example, if the
target resource is configured to always have a
Content-Type of
"text/html" and the representation being PUT has a
Content-Type of
"image/jpeg", the origin server ought to do one of:
a. reconfigure the target resource to reflect
the new media type;
b. transform the PUT representation to a format
consistent with that
of the resource
before saving it as the new resource state; or,
c. reject the request with a 415 (Unsupported
Media Type) response
indicating that the
target resource is limited to "text/html",
perhaps including a
link to a different resource that would be a
suitable target for
the new representation.
Fielding & Reschke
Standards Track
[Page 27]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
HTTP does not define
exactly how a PUT method affects the state of an
origin server beyond what
can be expressed by the intent of the user
agent request and the
semantics of the origin server response.
It
does not define what a
resource might be, in any sense of that word,
beyond the interface
provided via HTTP. It does not define
how
resource state is
"stored", nor how such storage might change as a
result of a change in
resource state, nor how the origin server
translates resource state
into representations. Generally
speaking,
all implementation details
behind the resource interface are
intentionally hidden by
the server.
An origin server MUST NOT
send a validator header field
(Section 7.2),
such as an ETag or Last-Modified field, in a
successful response to
PUT unless the request's representation data
was saved without any
transformation applied to the body (i.e., the
resource's new
representation data is identical to the representation
data received in the PUT
request) and the validator field value
reflects the new
representation. This requirement allows
a user
agent to know when the
representation body it has in memory remains
current as a result of
the PUT, thus not in need of being retrieved
again from the origin
server, and that the new validator(s) received
in the response can be
used for future conditional requests in order
to prevent accidental
overwrites (Section
5.2).
The fundamental
difference between the POST and PUT methods is
highlighted by the
different intent for the enclosed representation.
The target resource in a
POST request is intended to handle the
enclosed representation
according to the resource's own semantics,
whereas the enclosed
representation in a PUT request is defined as
replacing the state of
the target resource. Hence, the intent
of PUT
is idempotent and visible
to intermediaries, even though the exact
effect is only known by
the origin server.
Proper interpretation of
a PUT request presumes that the user agent
knows which target
resource is desired. A service that
selects a
proper URI on behalf of
the client, after receiving a state-changing
request, SHOULD be
implemented using the POST method rather than PUT.
If the origin server will
not make the requested PUT state change to
the target resource and
instead wishes to have it applied to a
different resource, such
as when the resource has been moved to a
different URI, then the
origin server MUST send an appropriate 3xx
(Redirection) response;
the user agent MAY then make its own decision
regarding whether or not
to redirect the request.
A PUT request applied to
the target resource can have side effects on
other resources. For example, an article might have a URI for
identifying "the
current version" (a resource) that is separate from
the URIs identifying each
particular version (different resources
Fielding & Reschke
Standards Track
[Page 28]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
that at one point shared
the same state as the current version
resource). A successful PUT request on "the current
version" URI
might therefore create a
new version resource in addition to changing
the state of the target
resource, and might also cause links to be
added between the related
resources.
An origin server that
allows PUT on a given target resource MUST send
a 400 (Bad Request)
response to a PUT request that contains a
Content-Range header
field (Section 4.2
of [RFC7233]), since the
payload is likely to be
partial content that has been mistakenly PUT
as a full
representation. Partial content updates
are possible by
targeting a separately
identified resource with state that overlaps a
portion of the larger
resource, or by using a different method that
has been specifically
defined for partial updates (for example, the
PATCH method defined in [RFC5789]).
Responses to the PUT method
are not cacheable. If a successful PUT
request passes through a
cache that has one or more stored responses
for the effective request
URI, those stored responses will be
invalidated (see Section 4.4 of
[RFC7234]).
4.3.5. DELETE
The DELETE method
requests that the origin server remove the
association between the
target resource and its current
functionality. In effect, this method is similar to the rm
command
in UNIX: it expresses a
deletion operation on the URI mapping of the
origin server rather than
an expectation that the previously
associated information be
deleted.
If the target resource
has one or more current representations, they
might or might not be
destroyed by the origin server, and the
associated storage might
or might not be reclaimed, depending
entirely on the nature of
the resource and its implementation by the
origin server (which are
beyond the scope of this specification).
Likewise, other
implementation aspects of a resource might need to be
deactivated or archived
as a result of a DELETE, such as database or
gateway connections. In general, it is assumed that the origin
server will only allow
DELETE on resources for which it has a
prescribed mechanism for
accomplishing the deletion.
Relatively few resources
allow the DELETE method -- its primary use
is for remote authoring
environments, where the user has some
direction regarding its
effect. For example, a resource that was
previously created using
a PUT request, or identified via the
Location header field
after a 201 (Created) response to a POST
request, might allow a
corresponding DELETE request to undo those
actions. Similarly, custom user agent implementations
that implement
Fielding & Reschke
Standards Track
[Page 29]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
an authoring function,
such as revision control clients using HTTP
for remote operations,
might use DELETE based on an assumption that
the server's URI space
has been crafted to correspond to a version
repository.
If a DELETE method is
successfully applied, the origin server SHOULD
send a 202 (Accepted)
status code if the action will likely succeed
but has not yet been
enacted, a 204 (No Content) status code if the
action has been enacted
and no further information is to be supplied,
or a 200 (OK) status code
if the action has been enacted and the
response message includes
a representation describing the status.
A payload within a DELETE
request message has no defined semantics;
sending a payload body on
a DELETE request might cause some existing
implementations to reject
the request.
Responses to the DELETE
method are not cacheable. If a DELETE
request passes through a
cache that has one or more stored responses
for the effective request
URI, those stored responses will be
invalidated (see Section 4.4 of
[RFC7234]).
4.3.6. CONNECT
The CONNECT method requests that the recipient
establish a tunnel to
the destination origin
server identified by the request-target and,
if successful, thereafter
restrict its behavior to blind forwarding
of packets, in both
directions, until the tunnel is closed.
Tunnels
are commonly used to
create an end-to-end virtual connection, through
one or more proxies,
which can then be secured using TLS (Transport
Layer Security, [RFC5246]).
CONNECT is intended only
for use in requests to a proxy. An
origin
server that receives a
CONNECT request for itself MAY respond with a
2xx (Successful) status
code to indicate that a connection is
established. However, most origin servers do not implement
CONNECT.
A client sending a
CONNECT request MUST send the authority form of
request-target (Section 5.3 of
[RFC7230]); i.e., the request-target
consists of only the host
name and port number of the tunnel
destination, separated by
a colon. For example,
CONNECT server.example.com:80
HTTP/1.1
Host:
server.example.com:80
The recipient proxy can
establish a tunnel either by directly
connecting to the
request-target or, if configured to use another
proxy, by forwarding the
CONNECT request to the next inbound proxy.
Any 2xx (Successful)
response indicates that the sender (and all
Fielding & Reschke
Standards Track
[Page 30]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
inbound proxies) will
switch to tunnel mode immediately after the
blank line that concludes
the successful response's header section;
data received after that
blank line is from the server identified by
the request-target. Any response other than a successful response
indicates that the tunnel
has not yet been formed and that the
connection remains
governed by HTTP.
A tunnel is closed when a
tunnel intermediary detects that either
side has closed its
connection: the intermediary MUST attempt to send
any outstanding data that
came from the closed side to the other
side, close both
connections, and then discard any remaining data
left undelivered.
Proxy authentication
might be used to establish the authority to
create a tunnel. For example,
CONNECT server.example.com:80 HTTP/1.1
Host:
server.example.com:80
Proxy-Authorization:
basic aGVsbG86d29ybGQ=
There are significant
risks in establishing a tunnel to arbitrary
servers, particularly
when the destination is a well-known or
reserved TCP port that is
not intended for Web traffic. For
example,
a CONNECT to a
request-target of "example.com:25" would suggest that
the proxy connect to the
reserved port for SMTP traffic; if allowed,
that could trick the
proxy into relaying spam email. Proxies
that
support CONNECT SHOULD
restrict its use to a limited set of known
ports or a configurable
whitelist of safe request targets.
A server MUST NOT send
any Transfer-Encoding or Content-Length header
fields in a 2xx
(Successful) response to CONNECT. A
client MUST
ignore any Content-Length
or Transfer-Encoding header fields received
in a successful response
to CONNECT.
A payload within a
CONNECT request message has no defined semantics;
sending a payload body on
a CONNECT request might cause some existing
implementations to reject
the request.
Responses to the CONNECT
method are not cacheable.
4.3.7. OPTIONS
The OPTIONS method
requests information about the communication
options available for the
target resource, at either the origin
server or an intervening
intermediary. This method allows a
client
to determine the options
and/or requirements associated with a
resource, or the
capabilities of a server, without implying a
resource action.
Fielding & Reschke
Standards Track
[Page 31]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
An OPTIONS request with
an asterisk ("*") as the request-target
(Section 5.3 of
[RFC7230]) applies to the server in general rather
than to a specific
resource. Since a server's communication
options
typically depend on the
resource, the "*" request is only useful as a
"ping" or
"no-op" type of method; it does nothing beyond allowing the
client to test the
capabilities of the server. For example,
this can
be used to test a proxy
for HTTP/1.1 conformance (or lack thereof).
If the request-target is
not an asterisk, the OPTIONS request applies
to the options that are
available when communicating with the target
resource.
A server generating a
successful response to OPTIONS SHOULD send any
header fields that might
indicate optional features implemented by
the server and applicable
to the target resource (e.g., Allow),
including potential
extensions not defined by this specification.
The response payload, if
any, might also describe the communication
options in a machine or
human-readable representation. A
standard
format for such a
representation is not defined by this
specification, but might
be defined by future extensions to HTTP.
A
server MUST generate a Content-Length
field with a value of "0" if no
payload body is to be
sent in the response.
A client MAY send a
Max-Forwards header field in an OPTIONS request
to target a specific
recipient in the request chain (see
Section 5.1.2). A proxy MUST NOT generate a Max-Forwards
header
field while forwarding a
request unless that request was received
with a Max-Forwards
field.
A client that generates
an OPTIONS request containing a payload body
MUST send a valid
Content-Type header field describing the
representation media
type. Although this specification does
not
define any use for such a
payload, future extensions to HTTP might
use the OPTIONS body to
make more detailed queries about the target
resource.
Responses to the OPTIONS
method are not cacheable.
4.3.8. TRACE
The TRACE method requests
a remote, application-level loop-back of
the request message. The final recipient of the request SHOULD
reflect the message
received, excluding some fields described below,
back to the client as the
message body of a 200 (OK) response with a
Content-Type of
"message/http" (Section 8.3.1
of [RFC7230]). The
final recipient is either
the origin server or the first server to
receive a Max-Forwards
value of zero (0) in the request
Fielding & Reschke
Standards Track
[Page 32]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
A client MUST NOT
generate header fields in a TRACE request
containing sensitive data
that might be disclosed by the response.
For example, it would be
foolish for a user agent to send stored user
credentials [RFC7235]
or cookies [RFC6265] in a TRACE request. The
final recipient of the
request SHOULD exclude any request header
fields that are likely to
contain sensitive data when that recipient
generates the response
body.
TRACE allows the client
to see what is being received at the other
end of the request chain
and use that data for testing or diagnostic
information. The value of the Via header field (Section 5.7.1
of
[RFC7230]) is of particular interest, since it acts as a trace of the
request chain. Use of the Max-Forwards header field allows
the
client to limit the
length of the request chain, which is useful for
testing a chain of
proxies forwarding messages in an infinite loop.
A client MUST NOT send a
message body in a TRACE request.
Responses to the TRACE
method are not cacheable.
5. Request Header Fields
A client sends request
header fields to provide more information
about the request
context, make the request conditional based on the
target resource state,
suggest preferred formats for the response,
supply authentication
credentials, or modify the expected request
processing. These fields act as request modifiers,
similar to the
parameters on a
programming language method invocation.
5.1. Controls
Controls are request
header fields that direct specific handling of
the request.
+-------------------+--------------------------+
| Header Field Name |
Defined in... |
+-------------------+--------------------------+
| Cache-Control | Section 5.2 of
[RFC7234] |
| Expect | Section 5.1.1 |
| Host | Section 5.4 of
[RFC7230] |
| Max-Forwards | Section 5.1.2 |
| Pragma | Section 5.4 of
[RFC7234] |
| Range | Section 3.1 of
[RFC7233] |
| TE | Section 4.3 of
[RFC7230] |
+-------------------+--------------------------+
Fielding & Reschke
Standards Track
[Page 33]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
5.1.1. Expect
The "Expect"
header field in a request indicates a certain set of
behaviors (expectations)
that need to be supported by the server in
order to properly handle
this request. The only such expectation
defined by this
specification is 100-continue.
Expect = "100-continue"
The Expect field-value is
case-insensitive.
A server that receives an
Expect field-value other than 100-continue
MAY respond with a 417
(Expectation Failed) status code to indicate
that the unexpected
expectation cannot be met.
A 100-continue
expectation informs recipients that the client is
about to send a
(presumably large) message body in this request and
wishes to receive a 100
(Continue) interim response if the
request-line and header
fields are not sufficient to cause an
immediate success,
redirect, or error response. This allows
the
client to wait for an
indication that it is worthwhile to send the
message body before
actually doing so, which can improve efficiency
when the message body is
huge or when the client anticipates that an
error is likely (e.g.,
when sending a state-changing method, for the
first time, without
previously verified authentication credentials).
For example, a request
that begins with
PUT /somewhere/fun
HTTP/1.1
Host:
origin.example.com
Content-Type:
video/h264
Content-Length:
1234567890987
Expect: 100-continue
allows the origin server
to immediately respond with an error
message, such as 401
(Unauthorized) or 405 (Method Not Allowed),
before the client starts
filling the pipes with an unnecessary data
transfer.
Requirements for clients:
o A client MUST NOT generate a 100-continue
expectation in a request
that does not include
a message body.
o A client that will wait for a 100 (Continue)
response before
sending the request
message body MUST send an Expect header field
containing a
100-continue expectation.
Fielding & Reschke
Standards Track [Page 34]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
o A client that sends a 100-continue
expectation is not required to
wait for any specific
length of time; such a client MAY proceed to
send the message body
even if it has not yet received a response.
Furthermore, since 100
(Continue) responses cannot be sent through
an HTTP/1.0
intermediary, such a client SHOULD NOT wait for an
indefinite period
before sending the message body.
o A client that receives a 417 (Expectation
Failed) status code in
response to a request
containing a 100-continue expectation SHOULD
repeat that request
without a 100-continue expectation, since the
417 response merely
indicates that the response chain does not
support expectations
(e.g., it passes through an HTTP/1.0 server).
Requirements for servers:
o A server that receives a 100-continue
expectation in an HTTP/1.0
request MUST ignore
that expectation.
o A server MAY omit sending a 100 (Continue)
response if it has
already received some
or all of the message body for the
corresponding request,
or if the framing indicates that there is
no message body.
o A server that sends a 100 (Continue) response
MUST ultimately send
a final status code,
once the message body is received and
processed, unless the
connection is closed prematurely.
o A server that responds with a final status
code before reading the
entire message body
SHOULD indicate in that response whether it
intends to close the
connection or continue reading and discarding
the request message
(see Section 6.6
of [RFC7230]).
An origin server MUST,
upon receiving an HTTP/1.1 (or later)
request-line and a
complete header section that contains a
100-continue expectation
and indicates a request message body will
follow, either send an
immediate response with a final status code,
if that status can be
determined by examining just the request-line
and header fields, or
send an immediate 100 (Continue) response to
encourage the client to
send the request's message body. The
origin
server MUST NOT wait for
the message body before sending the 100
(Continue) response.
A proxy MUST, upon
receiving an HTTP/1.1 (or later) request-line and
a complete header section
that contains a 100-continue expectation
and indicates a request
message body will follow, either send an
immediate response with a
final status code, if that status can be
determined by examining
just the request-line and header fields, or
begin forwarding the
request toward the origin server by sending a
Fielding & Reschke
Standards Track
[Page 35]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
corresponding
request-line and header section to the next inbound
server. If the proxy believes (from configuration or
past
interaction) that the
next inbound server only supports HTTP/1.0, the
proxy MAY generate an
immediate 100 (Continue) response to encourage
the client to begin
sending the message body.
Note: The Expect
header field was added after the original
publication of
HTTP/1.1 [RFC2068] as
both the means to request an
interim 100 (Continue)
response and the general mechanism for
indicating
must-understand extensions. However, the
extension
mechanism has not been
used by clients and the must-understand
requirements have not
been implemented by many servers, rendering
the extension
mechanism useless. This specification
has removed
the extension
mechanism in order to simplify the definition and
processing of
100-continue.
5.1.2. Max-Forwards
The
"Max-Forwards" header field provides a mechanism with the TRACE
(Section 4.3.8)
and OPTIONS (Section
4.3.7) request methods to limit
the number of times that
the request is forwarded by proxies.
This
can be useful when the
client is attempting to trace a request that
appears to be failing or
looping mid-chain.
Max-Forwards = 1*DIGIT
The Max-Forwards value is
a decimal integer indicating the remaining
number of times this
request message can be forwarded.
Each intermediary that
receives a TRACE or OPTIONS request containing
a Max-Forwards header
field MUST check and update its value prior to
forwarding the
request. If the received value is zero
(0), the
intermediary MUST NOT
forward the request; instead, the intermediary
MUST respond as the final
recipient. If the received Max-Forwards
value is greater than
zero, the intermediary MUST generate an updated
Max-Forwards field in the
forwarded message with a field-value that
is the lesser of a) the
received value decremented by one (1) or b)
the recipient's maximum
supported value for Max-Forwards.
A recipient MAY ignore a
Max-Forwards header field received with any
other request methods.
5.2. Conditionals
The HTTP conditional
request header fields [RFC7232]
allow a client
to place a precondition
on the state of the target resource, so that
the action corresponding
to the method semantics will not be applied
if the precondition
evaluates to false. Each precondition
defined by
Fielding & Reschke
Standards Track
[Page 36]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
this specification
consists of a comparison between a set of
validators obtained from
prior representations of the target resource
to the current state of
validators for the selected representation
(Section 7.2). Hence, these preconditions evaluate whether
the state
of the target resource
has changed since a given state known by the
client. The effect of such an evaluation depends on
the method
semantics and choice of
conditional, as defined in Section 5 of
+---------------------+--------------------------+
| Header Field Name | Defined in... |
+---------------------+--------------------------+
| If-Match | Section 3.1 of
[RFC7232] |
| If-None-Match | Section 3.2 of
[RFC7232] |
| If-Modified-Since | Section 3.3 of
[RFC7232] |
| If-Unmodified-Since | Section 3.4 of
[RFC7232] |
| If-Range | Section 3.2 of
[RFC7233] |
+---------------------+--------------------------+
5.3. Content Negotiation
The following request
header fields are sent by a user agent to
engage in proactive
negotiation of the response content, as defined
in Section 3.4.1. The preferences sent in these fields apply to
any
content in the response,
including representations of the target
resource, representations
of error or processing status, and
potentially even the
miscellaneous text strings that might appear
within the protocol.
+-------------------+---------------+
| Header Field Name |
Defined in... |
+-------------------+---------------+
| Accept | Section 5.3.2 |
| Accept-Charset | Section 5.3.3 |
| Accept-Encoding | Section 5.3.4 |
| Accept-Language | Section 5.3.5 |
+-------------------+---------------+
5.3.1. Quality Values
Many of the request
header fields for proactive negotiation use a
common parameter, named
"q" (case-insensitive), to assign a relative
"weight" to the
preference for that associated kind of content.
This
weight is referred to as
a "quality value" (or "qvalue") because the
same parameter name is
often used within server configurations to
assign a weight to the
relative quality of the various
representations that can be selected for a
resource.
Fielding & Reschke
Standards Track
[Page 37]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
The weight is normalized
to a real number in the range 0 through 1,
where 0.001 is the least
preferred and 1 is the most preferred; a
value of 0 means
"not acceptable". If no
"q" parameter is present,
the default weight is 1.
weight = OWS ";"
OWS "q=" qvalue
qvalue = (
"0" [ "." 0*3DIGIT ] )
/ (
"1" [ "." 0*3("0") ] )
A sender of qvalue MUST
NOT generate more than three digits after the
decimal point. User configuration of these values ought to
be
limited in the same
fashion.
5.3.2. Accept
The "Accept"
header field can be used by user agents to specify
response media types that
are acceptable. Accept header fields can
be used to indicate that
the request is specifically limited to a
small set of desired
types, as in the case of a request for an
in-line image.
Accept = #( media-range
[ accept-params ] )
media-range = ( "*/*"
/ ( type "/" "*" )
/ (
type "/" subtype )
) *(
OWS ";" OWS parameter )
accept-params = weight *( accept-ext )
accept-ext = OWS
";" OWS token [ "=" ( token / quoted-string ) ]
The asterisk
"*" character is used to group media types into ranges,
with "*/*"
indicating all media types and "type/*" indicating all
subtypes of that
type. The media-range can include media
type
parameters that are
applicable to that range.
Each media-range might be
followed by zero or more applicable media
type parameters (e.g.,
charset), an optional "q" parameter for
indicating a relative
weight (Section
5.3.1), and then zero or more
extension
parameters. The "q" parameter
is necessary if any
extensions (accept-ext)
are present, since it acts as a separator
between the two parameter
sets.
Note: Use of the
"q" parameter name to separate media type
parameters from Accept
extension parameters is due to historical
practice. Although this prevents any media type
parameter named
"q" from
being used with a media range, such an event is believed
to be unlikely given
the lack of any "q" parameters in the IANA
Fielding & Reschke
Standards Track
[Page 38]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
media type registry
and the rare usage of any media type
parameters in
Accept. Future media types are
discouraged from
registering any
parameter named "q".
The example
Accept: audio/*; q=0.2,
audio/basic
is interpreted as "I
prefer audio/basic, but send me any audio type
if it is the best
available after an 80% markdown in quality".
A request without any
Accept header field implies that the user agent
will accept any media
type in response. If the header field is
present in a request and
none of the available representations for
the response have a media
type that is listed as acceptable, the
origin server can either
honor the header field by sending a 406 (Not
Acceptable) response or
disregard the header field by treating the
response as if it is not
subject to content negotiation.
A more elaborate example
is
Accept: text/plain;
q=0.5, text/html,
text/x-dvi;
q=0.8, text/x-c
Verbally, this would be
interpreted as "text/html and text/x-c are
the equally preferred
media types, but if they do not exist, then
send the text/x-dvi
representation, and if that does not exist, send
the text/plain
representation".
Media ranges can be
overridden by more specific media ranges or
specific media
types. If more than one media range
applies to a
given type, the most
specific reference has precedence. For
example,
Accept: text/*,
text/plain, text/plain;format=flowed, */*
have the following
precedence:
1. text/plain;format=flowed
2. text/plain
3. text/*
4. */*
The media type quality
factor associated with a given type is
determined by finding the
media range with the highest precedence
that matches the
type. For example,
Fielding & Reschke
Standards Track [Page 39]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
Accept: text/*;q=0.3,
text/html;q=0.7, text/html;level=1,
text/html;level=2;q=0.4, */*;q=0.5
would cause the following
values to be associated:
+-------------------+---------------+
| Media Type | Quality Value |
+-------------------+---------------+
| text/html;level=1 |
1 |
| text/html | 0.7 |
| text/plain | 0.3 |
| image/jpeg | 0.5
|
| text/html;level=2 |
0.4 |
| text/html;level=3 |
0.7 |
+-------------------+---------------+
Note: A user agent might
be provided with a default set of quality
values for certain media
ranges. However, unless the user agent
is a
closed system that cannot
interact with other rendering agents, this
default set ought to be
configurable by the user.
5.3.3. Accept-Charset
The
"Accept-Charset" header field can be sent by a user agent to
indicate what charsets
are acceptable in textual response content.
This field allows user
agents capable of understanding more
comprehensive or
special-purpose charsets to signal that capability
to an origin server that
is capable of representing information in
those charsets.
Accept-Charset = 1#( (
charset / "*" ) [ weight ] )
Charset names are defined
in Section
3.1.1.2. A user agent MAY
associate a quality value
with each charset to indicate the user's
relative preference for
that charset, as defined in Section 5.3.1.
An example is
Accept-Charset:
iso-8859-5, unicode-1-1;q=0.8
The special value
"*", if present in the Accept-Charset field,
matches every charset
that is not mentioned elsewhere in the
Accept-Charset
field. If no "*" is present in
an Accept-Charset
field, then any charsets
not explicitly mentioned in the field are
considered "not
acceptable" to the client.
A request without any
Accept-Charset header field implies that the
user agent will accept any
charset in response. Most
general-purpose
user agents do not send
Accept-Charset, unless specifically
Fielding & Reschke
Standards Track
[Page 40]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
configured to do so,
because a detailed list of supported charsets
makes it easier for a
server to identify an individual by virtue of
the user agent's request
characteristics (Section
9.7).
If an Accept-Charset
header field is present in a request and none of
the available
representations for the response has a charset that is
listed as acceptable, the
origin server can either honor the header
field, by sending a 406
(Not Acceptable) response, or disregard the
header field by treating
the resource as if it is not subject to
content negotiation.
5.3.4. Accept-Encoding
The
"Accept-Encoding" header field can be used by user agents to
indicate what response
content-codings (Section 3.1.2.1)
are
acceptable in the
response. An "identity" token
is used as a synonym
for "no
encoding" in order to communicate when no encoding is
preferred.
Accept-Encoding = #( codings [ weight ] )
codings = content-coding /
"identity" / "*"
Each codings value MAY be
given an associated quality value
representing the
preference for that encoding, as defined in
Section 5.3.1. The asterisk "*" symbol in an
Accept-Encoding field
matches any available
content-coding not explicitly listed in the
header field.
For example,
Accept-Encoding:
compress, gzip
Accept-Encoding:
Accept-Encoding: *
Accept-Encoding:
compress;q=0.5, gzip;q=1.0
Accept-Encoding:
gzip;q=1.0, identity; q=0.5, *;q=0
A request without an
Accept-Encoding header field implies that the
user agent has no
preferences regarding content-codings.
Although
this allows the server to
use any content-coding in a response, it
does not imply that the
user agent will be able to correctly process
all encodings.
A server tests whether a
content-coding for a given representation is
acceptable using these
rules:
1. If no Accept-Encoding field is in the
request, any content-coding
is considered
acceptable by the user agent.
Fielding & Reschke
Standards Track
[Page 41]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
2. If the representation has no content-coding,
then it is
acceptable by default
unless specifically excluded by the
Accept-Encoding field
stating either "identity;q=0" or "*;q=0"
without a more
specific entry for "identity".
3. If the representation's content-coding is one
of the
content-codings
listed in the Accept-Encoding field, then it is
acceptable unless it
is accompanied by a qvalue of 0. (As
defined in Section 5.3.1,
a qvalue of 0 means "not acceptable".)
4. If multiple content-codings are acceptable,
then the acceptable
content-coding with
the highest non-zero qvalue is preferred.
An Accept-Encoding header
field with a combined field-value that is
empty implies that the
user agent does not want any content-coding in
response. If an Accept-Encoding header field is present
in a request
and none of the available
representations for the response have a
content-coding that is
listed as acceptable, the origin server SHOULD
send a response without
any content-coding.
Note: Most HTTP/1.0
applications do not recognize or obey qvalues
associated with
content-codings. This means that qvalues
might
not work and are not
permitted with x-gzip or x-compress.
5.3.5. Accept-Language
The
"Accept-Language" header field can be used by user agents to
indicate the set of
natural languages that are preferred in the
response. Language tags are defined in Section 3.1.3.1.
Accept-Language = 1#(
language-range [ weight ] )
language-range =
<language-range, see [RFC4647],
Section 2.1>
Each language-range can
be given an associated quality value
representing an estimate
of the user's preference for the languages
specified by that range,
as defined in Section
5.3.1. For example,
Accept-Language: da,
en-gb;q=0.8, en;q=0.7
would mean: "I
prefer Danish, but will accept British English and
other types of
English".
A request without any
Accept-Language header field implies that the
user agent will accept
any language in response. If the header
field
is present in a request
and none of the available representations for
the response have a
matching language tag, the origin server can
either disregard the
header field by treating the response as if it
Fielding & Reschke
Standards Track
[Page 42]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
is not subject to content
negotiation or honor the header field by
sending a 406 (Not
Acceptable) response. However, the
latter is not
encouraged, as doing so
can prevent users from accessing content that
they might be able to use
(with translation software, for example).
Note that some recipients
treat the order in which language tags are
listed as an indication
of descending priority, particularly for tags
that are assigned equal
quality values (no value is the same as q=1).
However, this behavior
cannot be relied upon. For consistency
and to
maximize
interoperability, many user agents assign each language tag
a unique quality value
while also listing them in order of decreasing
quality. Additional discussion of language priority
lists can be
found in Section 2.3 of
[RFC4647].
For matching, Section 3 of
[RFC4647] defines several matching
schemes. Implementations can offer the most
appropriate matching
scheme for their
requirements. The "Basic
Filtering" scheme
([RFC4647],
Section 3.3.1) is identical to the matching scheme that
was previously defined
for HTTP in Section 14.4
of [RFC2616].
It might be contrary to
the privacy expectations of the user to send
an Accept-Language header
field with the complete linguistic
preferences of the user
in every request (Section
9.7).
Since intelligibility is
highly dependent on the individual user,
user agents need to allow
user control over the linguistic preference
(either through
configuration of the user agent itself or by
defaulting to a user
controllable system setting). A user
agent that
does not provide such
control to the user MUST NOT send an
Accept-Language header
field.
Note: User agents
ought to provide guidance to users when setting
a preference, since
users are rarely familiar with the details of
language matching as
described above. For example, users
might
assume that on
selecting "en-gb", they will be served any kind of
English document if
British English is not available. A user
agent might suggest,
in such a case, to add "en" to the list for
better matching
behavior.
Fielding & Reschke
Standards Track
[Page 43]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
5.4. Authentication Credentials
Two header fields are
used for carrying authentication credentials,
as defined in [RFC7235]. Note that various custom mechanisms for
user authentication use
the Cookie header field for this purpose, as
defined in [RFC6265].
+---------------------+--------------------------+
| Header Field Name | Defined in... |
+---------------------+--------------------------+
| Authorization | Section 4.2 of
[RFC7235] |
| Proxy-Authorization | Section 4.4 of
[RFC7235] |
+---------------------+--------------------------+
5.5. Request Context
The following request
header fields provide additional information
about the request
context, including information about the user, user
agent, and resource
behind the request.
+-------------------+---------------+
| Header Field Name |
Defined in... |
+-------------------+---------------+
| From | Section 5.5.1 |
| Referer | Section 5.5.2 |
| User-Agent | Section 5.5.3 |
+-------------------+---------------+
5.5.1. From
The "From"
header field contains an Internet email address for a
human user who controls
the requesting user agent. The address
ought
to be machine-usable, as
defined by "mailbox" in Section 3.4 of
From = mailbox
mailbox = <mailbox,
see [RFC5322],
Section 3.4>
An example is:
From:
webmaster@example.org
The From header field is
rarely sent by non-robotic user agents.
A
user agent SHOULD NOT
send a From header field without explicit
configuration by the
user, since that might conflict with the user's
privacy interests or
their site's security policy.
Fielding & Reschke
Standards Track [Page 44]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
A robotic user agent
SHOULD send a valid From header field so that
the person responsible
for running the robot can be contacted if
problems occur on
servers, such as if the robot is sending excessive,
unwanted, or invalid
requests.
A server SHOULD NOT use
the From header field for access control or
authentication, since most
recipients will assume that the field
value is public
information.
5.5.2. Referer
The "Referer"
[sic] header field allows the user agent to specify a
URI reference for the
resource from which the target URI was obtained
(i.e., the
"referrer", though the field name is misspelled). A user
agent MUST NOT include
the fragment and userinfo components of the
URI reference [RFC3986],
if any, when generating the Referer field
value.
Referer = absolute-URI
/ partial-URI
The Referer header field
allows servers to generate back-links to
other resources for
simple analytics, logging, optimized caching,
etc. It also allows obsolete or mistyped links to
be found for
maintenance. Some servers use the Referer header field as
a means of
denying links from other
sites (so-called "deep linking") or
restricting cross-site
request forgery (CSRF), but not all requests
contain it.
Example:
Referer:
http://www.example.org/hypertext/Overview.html
If the target URI was
obtained from a source that does not have its
own URI (e.g., input from
the user keyboard, or an entry within the
user's
bookmarks/favorites), the user agent MUST either exclude the
Referer field or send it
with a value of "about:blank".
The Referer field has the
potential to reveal information about the
request context or
browsing history of the user, which is a privacy
concern if the referring
resource's identifier reveals personal
information (such as an
account name) or a resource that is supposed
to be confidential (such as behind a firewall
or internal to a
secured service). Most general-purpose user agents do not send
the
Referer header field when
the referring resource is a local "file" or
"data"
URI. A user agent MUST NOT send a
Referer header field in an
unsecured HTTP request if
the referring page was received with a
secure protocol. See Section 9.4 for
additional security
considerations.
Fielding & Reschke
Standards Track
[Page 45]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
Some intermediaries have
been known to indiscriminately remove
Referer header fields
from outgoing requests. This has the
unfortunate side effect
of interfering with protection against CSRF
attacks, which can be far
more harmful to their users.
Intermediaries and user
agent extensions that wish to limit
information disclosure in
Referer ought to restrict their changes to
specific edits, such as
replacing internal domain names with
pseudonyms or truncating
the query and/or path components. An
intermediary SHOULD NOT
modify or delete the Referer header field
when the field value shares
the same scheme and host as the request
target.
5.5.3. User-Agent
The
"User-Agent" header field contains information about the user
agent originating the
request, which is often used by servers to help
identify the scope of
reported interoperability problems, to work
around or tailor
responses to avoid particular user agent
limitations, and for
analytics regarding browser or operating system
use. A user agent SHOULD send a User-Agent field
in each request
unless specifically
configured not to do so.
User-Agent = product *(
RWS ( product / comment ) )
The User-Agent
field-value consists of one or more product
identifiers, each followed
by zero or more comments (Section 3.2 of
[RFC7230]), which together identify the user agent software and its
significant
subproducts. By convention, the product
identifiers are
listed in decreasing
order of their significance for identifying the
user agent software. Each product identifier consists of a name
and
optional version.
product = token ["/" product-version]
product-version = token
A sender SHOULD limit
generated product identifiers to what is
necessary to identify the
product; a sender MUST NOT generate
advertising or other
nonessential information within the product
identifier. A sender SHOULD NOT generate information in
product-version that is
not a version identifier (i.e., successive
versions of the same
product name ought to differ only in the
product-version portion
of the product identifier).
Example:
User-Agent:
CERN-LineMode/2.15 libwww/2.17b3
Fielding & Reschke
Standards Track
[Page 46]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
A user agent SHOULD NOT
generate a User-Agent field containing
needlessly fine-grained
detail and SHOULD limit the addition of
subproducts by third
parties. Overly long and detailed
User-Agent
field values increase
request latency and the risk of a user being
identified against their
wishes ("fingerprinting").
Likewise, implementations
are encouraged not to use the product
tokens of other
implementations in order to declare compatibility
with them, as this
circumvents the purpose of the field. If
a user
agent masquerades as a
different user agent, recipients can assume
that the user
intentionally desires to see responses tailored for
that identified user
agent, even if they might not work as well for
the actual user agent
being used.
6. Response Status Codes
The status-code element
is a three-digit integer code giving the
result of the attempt to
understand and satisfy the request.
HTTP status codes are
extensible. HTTP clients are not
required to
understand the meaning of
all registered status codes, though such
understanding is
obviously desirable. However, a client
MUST
understand the class of
any status code, as indicated by the first
digit, and treat an
unrecognized status code as being equivalent to
the x00 status code of
that class, with the exception that a
recipient MUST NOT cache
a response with an unrecognized status code.
For example, if an
unrecognized status code of 471 is received by a
client, the client can
assume that there was something wrong with its
request and treat the
response as if it had received a 400 (Bad
Request) status
code. The response message will usually
contain a
representation that
explains the status.
The first digit of the
status-code defines the class of response.
The last two digits do
not have any categorization role. There
are
five values for the first
digit:
o 1xx (Informational): The request was
received, continuing process
o 2xx (Successful): The request was
successfully received,
understood, and
accepted
o 3xx (Redirection): Further action needs to be
taken in order to
complete the request
o 4xx (Client Error): The request contains bad
syntax or cannot be
fulfilled
Fielding & Reschke
Standards Track
[Page 47]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
o 5xx (Server Error): The server failed to
fulfill an apparently
valid request
6.1. Overview of Status Codes
The status codes listed
below are defined in this specification,
Section 4 of
[RFC7232], Section 4
of [RFC7233], and Section 3
of
[RFC7235]. The reason phrases listed
here are only recommendations
-- they can be replaced
by local equivalents without affecting the
protocol.
Responses with status
codes that are defined as cacheable by default
(e.g., 200, 203, 204,
206, 300, 301, 404, 405, 410, 414, and 501 in
this specification) can
be reused by a cache with heuristic
expiration unless
otherwise indicated by the method definition or
explicit cache controls [RFC7234];
all other status codes are not
cacheable by default.
Fielding & Reschke
Standards Track
[Page 48]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
+------+-------------------------------+--------------------------+
| Code |
Reason-Phrase | Defined
in... |
+------+-------------------------------+--------------------------+
| 100 | Continue | Section 6.2.1 |
| 101 | Switching Protocols | Section 6.2.2 |
| 200 | OK | Section 6.3.1 |
| 201 | Created | Section 6.3.2 |
| 202 | Accepted | Section 6.3.3 |
| 203 | Non-Authoritative Information | Section 6.3.4 |
| 204 | No Content | Section 6.3.5 |
| 205 | Reset Content | Section 6.3.6 |
| 206 | Partial Content | Section 4.1 of
[RFC7233] |
| 300 | Multiple Choices | Section 6.4.1 |
| 301 | Moved Permanently | Section 6.4.2 |
| 302 | Found | Section 6.4.3 |
| 303 | See Other | Section 6.4.4 |
| 304 | Not Modified | Section 4.1 of [RFC7232]
|
| 305 | Use Proxy | Section 6.4.5 |
| 307 | Temporary Redirect | Section 6.4.7 |
| 400 | Bad Request | Section 6.5.1 |
| 401 | Unauthorized | Section 3.1 of
[RFC7235] |
| 402 | Payment Required | Section 6.5.2 |
| 403 | Forbidden | Section 6.5.3 |
| 404 | Not Found | Section 6.5.4 |
| 405 | Method Not Allowed | Section 6.5.5 |
| 406 | Not Acceptable | Section 6.5.6 |
| 407 | Proxy Authentication Required | Section 3.2 of
[RFC7235] |
| 408 | Request Timeout | Section 6.5.7 |
| 409 | Conflict | Section 6.5.8 |
| 410 | Gone | Section 6.5.9 |
| 411 | Length Required | Section 6.5.10 |
| 412 | Precondition Failed | Section 4.2 of
[RFC7232] |
| 413 | Payload Too Large | Section 6.5.11 |
| 414 | URI Too Long | Section 6.5.12 |
| 415 | Unsupported Media Type | Section 6.5.13 |
| 416 | Range Not Satisfiable | Section 4.4 of
[RFC7233] |
| 417 | Expectation Failed | Section 6.5.14 |
| 426 | Upgrade Required | Section 6.5.15 |
| 500 | Internal Server Error | Section 6.6.1 |
| 501 | Not Implemented | Section 6.6.2 |
| 502 | Bad Gateway | Section 6.6.3 |
| 503 | Service Unavailable | Section 6.6.4 |
| 504 | Gateway Timeout | Section 6.6.5 |
| 505 | HTTP Version Not Supported | Section 6.6.6 |
+------+-------------------------------+--------------------------+
Fielding & Reschke
Standards Track [Page 49]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
Note that this list is
not exhaustive -- it does not include
extension status codes
defined in other specifications. The
complete
list of status codes is
maintained by IANA. See Section 8.2 for
details.
6.2. Informational 1xx
The 1xx (Informational)
class of status code indicates an interim
response for communicating connection status
or request progress
prior to completing the
requested action and sending a final
response. 1xx responses
are terminated by the first empty line after
the status-line (the
empty line signaling the end of the header
section). Since HTTP/1.0 did not define any 1xx status
codes, a
server MUST NOT send a
1xx response to an HTTP/1.0 client.
A client MUST be able to
parse one or more 1xx responses received
prior to a final
response, even if the client does not expect one. A
user agent MAY ignore
unexpected 1xx responses.
A proxy MUST forward 1xx
responses unless the proxy itself requested
the generation of the 1xx
response. For example, if a proxy adds
an
"Expect:
100-continue" field when it forwards a request, then it need
not forward the
corresponding 100 (Continue) response(s).
6.2.1. 100 Continue
The 100 (Continue) status
code indicates that the initial part of a
request has been received
and has not yet been rejected by the
server. The server intends to send a final response
after the
request has been fully
received and acted upon.
When the request contains
an Expect header field that includes a
100-continue expectation,
the 100 response indicates that the server
wishes to receive the
request payload body, as described in
Section 5.1.1. The client ought to continue sending the
request and
discard the 100 response.
If the request did not
contain an Expect header field containing the
100-continue expectation,
the client can simply discard this interim
response.
6.2.2. 101 Switching Protocols
The 101 (Switching
Protocols) status code indicates that the server
understands and is
willing to comply with the client's request, via
the Upgrade header field
(Section 6.7
of [RFC7230]), for a change in
the application protocol
being used on this connection. The
server
Fielding & Reschke
Standards Track [Page 50]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
MUST generate an Upgrade
header field in the response that indicates
which protocol(s) will be
switched to immediately after the empty
line that terminates the
101 response.
It is assumed that the
server will only agree to switch protocols
when it is advantageous
to do so. For example, switching to a
newer
version of HTTP might be
advantageous over older versions, and
switching to a real-time,
synchronous protocol might be advantageous
when delivering resources
that use such features.
6.3. Successful 2xx
The 2xx (Successful)
class of status code indicates that the client's
request was successfully
received, understood, and accepted.
6.3.1. 200 OK
The 200 (OK) status code
indicates that the request has succeeded.
The payload sent in a 200
response depends on the request method.
For the methods defined
by this specification, the intended meaning
of the payload can be
summarized as:
GET a representation of the target resource;
HEAD the same representation as GET, but without
the representation
data;
POST a representation of the status of, or results
obtained from,
the action;
PUT, DELETE a representation of the status of the action;
OPTIONS a representation of the communications
options;
TRACE a representation of the request message as
received by the end
server.
Aside from responses to
CONNECT, a 200 response always has a payload,
though an origin server
MAY generate a payload body of zero length.
If no payload is desired,
an origin server ought to send 204 (No
Content) instead. For CONNECT, no payload is allowed because
the
successful result is a
tunnel, which begins immediately after the 200
response header section.
A 200 response is
cacheable by default; i.e., unless otherwise
indicated by the method
definition or explicit cache controls (see
Fielding & Reschke
Standards Track
[Page 51]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
6.3.2. 201 Created
The 201 (Created) status
code indicates that the request has been
fulfilled and has
resulted in one or more new resources being
created. The primary resource created by the request
is identified
by either a Location
header field in the response or, if no Location
field is received, by the
effective request URI.
The 201 response payload
typically describes and links to the
resource(s) created. See Section 7.2 for a
discussion of the meaning
and purpose of validator
header fields, such as ETag and
Last-Modified, in a 201
response.
6.3.3. 202 Accepted
The 202 (Accepted) status
code indicates that the request has been
accepted for processing,
but the processing has not been completed.
The request might or
might not eventually be acted upon, as it might
be disallowed when
processing actually takes place. There
is no
facility in HTTP for
re-sending a status code from an asynchronous
operation.
The 202 response is
intentionally noncommittal. Its purpose
is to
allow a server to accept
a request for some other process (perhaps a
batch-oriented process
that is only run once per day) without
requiring that the user
agent's connection to the server persist
until the process is
completed. The representation sent with
this
response ought to
describe the request's current status and point to
(or embed) a status
monitor that can provide the user with an
estimate of when the
request will be fulfilled.
6.3.4. 203 Non-Authoritative Information
The 203
(Non-Authoritative Information) status code indicates that
the request was
successful but the enclosed payload has been modified
from that of the origin
server's 200 (OK) response by a transforming
proxy (Section 5.7.2
of [RFC7230]). This status code
allows the
proxy to notify
recipients when a transformation has been applied,
since that knowledge
might impact later decisions regarding the
content. For example, future cache validation requests
for the
content might only be
applicable along the same request path (through
the same proxies).
The 203 response is
similar to the Warning code of 214 Transformation
Applied (Section 5.5 of
[RFC7234]), which has the advantage of being
applicable to responses
with any status code.
Fielding & Reschke
Standards Track
[Page 52]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
A 203 response is
cacheable by default; i.e., unless otherwise
indicated by the method
definition or explicit cache controls (see
6.3.5. 204 No Content
The 204 (No Content)
status code indicates that the server has
successfully fulfilled
the request and that there is no additional
content to send in the
response payload body. Metadata in the
response header fields
refer to the target resource and its selected
representation after the
requested action was applied.
For example, if a 204
status code is received in response to a PUT
request and the response
contains an ETag header field, then the PUT
was successful and the
ETag field-value contains the entity-tag for
the new representation of
that target resource.
The 204 response allows a
server to indicate that the action has been
successfully applied to
the target resource, while implying that the
user agent does not need
to traverse away from its current "document
view" (if any). The server assumes that the user agent will
provide
some indication of the
success to its user, in accord with its own
interface, and apply any
new or updated metadata in the response to
its active
representation.
For example, a 204 status
code is commonly used with document editing
interfaces corresponding
to a "save" action, such that the document
being saved remains
available to the user for editing. It is
also
frequently used with
interfaces that expect automated data transfers
to be prevalent, such as
within distributed version control systems.
A 204 response is
terminated by the first empty line after the header
fields because it cannot
contain a message body.
A 204 response is
cacheable by default; i.e., unless otherwise
indicated by the method
definition or explicit cache controls (see
6.3.6. 205 Reset Content
The 205 (Reset Content)
status code indicates that the server has
fulfilled the request and
desires that the user agent reset the
"document
view", which caused the request to be sent, to its original
state as received from
the origin server.
This response is intended
to support a common data entry use case
where the user receives
content that supports data entry (a form,
notepad, canvas, etc.),
enters or manipulates data in that space,
Fielding & Reschke
Standards Track [Page 53]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
causes the entered data
to be submitted in a request, and then the
data entry mechanism is
reset for the next entry so that the user can
easily initiate another
input action.
Since the 205 status code
implies that no additional content will be
provided, a server MUST
NOT generate a payload in a 205 response.
In
other words, a server
MUST do one of the following for a 205
response: a) indicate a
zero-length body for the response by
including a
Content-Length header field with a value of 0; b)
indicate a zero-length
payload for the response by including a
Transfer-Encoding header
field with a value of chunked and a message
body consisting of a
single chunk of zero-length; or, c) close the
connection immediately
after sending the blank line terminating the
header section.
6.4. Redirection 3xx
The 3xx (Redirection)
class of status code indicates that further
action needs to be taken
by the user agent in order to fulfill the
request. If a Location header field (Section 7.1.2)
is provided, the
user agent MAY
automatically redirect its request to the URI
referenced by the
Location field value, even if the specific status
code is not
understood. Automatic redirection needs
to done with
care for methods not known
to be safe, as defined in Section 4.2.1,
since the user might not
wish to redirect an unsafe request.
There are several types
of redirects:
1. Redirects that indicate the resource might be
available at a
different URI, as
provided by the Location field, as in the
status codes 301
(Moved Permanently), 302 (Found), and 307
(Temporary Redirect).
2. Redirection that offers a choice of matching
resources, each
capable of
representing the original request target, as in the
300 (Multiple
Choices) status code.
3. Redirection to a different resource,
identified by the Location
field, that can
represent an indirect response to the request, as
in the 303 (See
Other) status code.
4. Redirection to a previously cached result, as
in the 304 (Not
Modified) status
code.
Note: In HTTP/1.0, the
status codes 301 (Moved Permanently) and
302 (Found) were defined for the first type
of redirect
([RFC1945],
Section 9.3). Early user agents
split on whether the
method applied to the
redirect target would be the same as the
Fielding & Reschke
Standards Track
[Page 54]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
original request or
would be rewritten as GET. Although HTTP
originally defined the
former semantics for 301 and 302 (to match
its original
implementation at CERN), and defined 303 (See Other)
to match the latter
semantics, prevailing practice gradually
converged on the
latter semantics for 301 and 302 as well.
The
first revision of
HTTP/1.1 added 307 (Temporary Redirect) to
indicate the former
semantics without being impacted by divergent
practice. Over 10 years later, most user agents still
do method
rewriting for 301 and
302; therefore, this specification makes
that behavior
conformant when the original request is POST.
A client SHOULD detect
and intervene in cyclical redirections (i.e.,
"infinite"
redirection loops).
Note: An earlier
version of this specification recommended a
maximum of five
redirections ([RFC2068],
Section 10.3). Content
developers need to be
aware that some clients might implement such
a fixed limitation.
6.4.1. 300 Multiple Choices
The 300 (Multiple
Choices) status code indicates that the target
resource has more than
one representation, each with its own more
specific identifier, and
information about the alternatives is being
provided so that the user
(or user agent) can select a preferred
representation by
redirecting its request to one or more of those
identifiers. In other words, the server desires that the
user agent
engage in reactive
negotiation to select the most appropriate
representation(s) for its
needs (Section 3.4).
If the server has a
preferred choice, the server SHOULD generate a
Location header field
containing a preferred choice's URI reference.
The user agent MAY use
the Location field value for automatic
redirection.
For request methods other
than HEAD, the server SHOULD generate a
payload in the 300
response containing a list of representation
metadata and URI
reference(s) from which the user or user agent can
choose the one most
preferred. The user agent MAY make a
selection
from that list
automatically if it understands the provided media
type. A specific format for automatic selection is
not defined by
this specification
because HTTP tries to remain orthogonal to the
definition of its
payloads. In practice, the representation
is
provided in some easily
parsed format believed to be acceptable to
the user agent, as
determined by shared design or content
negotiation, or in some
commonly accepted hypertext format.
Fielding & Reschke
Standards Track [Page 55]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
A 300 response is
cacheable by default; i.e., unless otherwise
indicated by the method
definition or explicit cache controls (see
Note: The original
proposal for the 300 status code defined the
URI header field as
providing a list of alternative
representations, such
that it would be usable for 200, 300, and
406 responses and be
transferred in responses to the HEAD method.
However, lack of
deployment and disagreement over syntax led to
both URI and
Alternates (a subsequent proposal) being dropped from
this
specification. It is possible to
communicate the list using
a set of Link header
fields [RFC5988],
each with a relationship of
"alternate",
though deployment is a chicken-and-egg problem.
6.4.2. 301 Moved Permanently
The 301 (Moved
Permanently) status code indicates that the target
resource has been
assigned a new permanent URI and any future
references to this
resource ought to use one of the enclosed URIs.
Clients with link-editing
capabilities ought to automatically re-link
references to the
effective request URI to one or more of the new
references sent by the
server, where possible.
The server SHOULD
generate a Location header field in the response
containing a preferred
URI reference for the new permanent URI.
The
user agent MAY use the
Location field value for automatic
redirection. The server's response payload usually
contains a short
hypertext note with a
hyperlink to the new URI(s).
Note: For historical
reasons, a user agent MAY change the request
method from POST to
GET for the subsequent request. If this
behavior is undesired,
the 307 (Temporary Redirect) status code
can be used instead.
A 301 response is
cacheable by default; i.e., unless otherwise
indicated by the method
definition or explicit cache controls (see
6.4.3. 302 Found
The 302 (Found) status
code indicates that the target resource
resides temporarily under
a different URI. Since the redirection
might be altered on
occasion, the client ought to continue to use the
effective request URI for
future requests.
Fielding & Reschke
Standards Track
[Page 56]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
The server SHOULD
generate a Location header field in the response
containing a URI
reference for the different URI. The
user agent MAY
use the Location field
value for automatic redirection. The
server's
response payload usually
contains a short hypertext note with a
hyperlink to the
different URI(s).
Note: For historical
reasons, a user agent MAY change the request
method from POST to
GET for the subsequent request. If this
behavior is undesired,
the 307 (Temporary Redirect) status code
can be used instead.
6.4.4. 303 See Other
The 303 (See Other)
status code indicates that the server is
redirecting the user
agent to a different resource, as indicated by a
URI in the Location
header field, which is intended to provide an
indirect response to the
original request. A user agent can
perform
a retrieval request
targeting that URI (a GET or HEAD request if
using HTTP), which might
also be redirected, and present the eventual
result as an answer to
the original request. Note that the new
URI
in the Location header
field is not considered equivalent to the
effective request URI.
This status code is
applicable to any HTTP method. It is
primarily
used to allow the output
of a POST action to redirect the user agent
to a selected resource,
since doing so provides the information
corresponding to the POST
response in a form that can be separately
identified, bookmarked,
and cached, independent of the original
request.
A 303 response to a GET
request indicates that the origin server does
not have a representation
of the target resource that can be
transferred by the server
over HTTP. However, the Location field
value refers to a
resource that is descriptive of the target
resource, such that
making a retrieval request on that other resource
might result in a
representation that is useful to recipients without
implying that it
represents the original target resource.
Note that
answers to the questions
of what can be represented, what
representations are
adequate, and what might be a useful description
are outside the scope of
HTTP.
Except for responses to a
HEAD request, the representation of a 303
response ought to contain
a short hypertext note with a hyperlink to
the same URI reference
provided in the Location header field.
Fielding & Reschke
Standards Track
[Page 57]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
6.4.5. 305 Use Proxy
The 305 (Use Proxy)
status code was defined in a previous version of
this specification and is
now deprecated (Appendix B).
6.4.6. 306 (Unused)
The 306 status code was
defined in a previous version of this
specification, is no
longer used, and the code is reserved.
6.4.7. 307 Temporary Redirect
The 307 (Temporary
Redirect) status code indicates that the target
resource resides
temporarily under a different URI and the user agent
MUST NOT change the
request method if it performs an automatic
redirection to that
URI. Since the redirection can change
over time,
the client ought to
continue using the original effective request URI
for future requests.
The server SHOULD
generate a Location header field in the response
containing a URI
reference for the different URI. The
user agent MAY
use the Location field
value for automatic redirection. The
server's
response payload usually
contains a short hypertext note with a
hyperlink to the
different URI(s).
Note: This status code
is similar to 302 (Found), except that it
does not allow
changing the request method from POST to GET.
This
specification defines
no equivalent counterpart for 301 (Moved
Permanently) ([RFC7238],
however, defines the status code 308
(Permanent Redirect)
for this purpose).
6.5. Client Error 4xx
The 4xx (Client Error)
class of status code indicates that the client
seems to have erred. Except when responding to a HEAD request, the
server SHOULD send a
representation containing an explanation of the
error situation, and
whether it is a temporary or permanent
condition. These status codes are applicable to any
request method.
User agents SHOULD
display any included representation to the user.
6.5.1. 400 Bad Request
The 400 (Bad Request)
status code indicates that the server cannot or
will not process the
request due to something that is perceived to be
a client error (e.g.,
malformed request syntax, invalid request
message framing, or
deceptive request routing).
Fielding & Reschke
Standards Track
[Page 58]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
6.5.2. 402 Payment Required
The 402 (Payment
Required) status code is reserved for future use.
6.5.3. 403 Forbidden
The 403 (Forbidden)
status code indicates that the server understood
the request but refuses
to authorize it. A server that wishes to
make public why the
request has been forbidden can describe that
reason in the response
payload (if any).
If authentication
credentials were provided in the request, the
server considers them
insufficient to grant access. The client
SHOULD NOT automatically
repeat the request with the same
credentials. The client MAY repeat the request with new or
different
credentials. However, a request might be forbidden for
reasons
unrelated to the
credentials.
An origin server that
wishes to "hide" the current existence of a
forbidden target resource
MAY instead respond with a status code of
404 (Not Found).
6.5.4. 404 Not Found
The 404 (Not Found)
status code indicates that the origin server did
not find a current
representation for the target resource or is not
willing to disclose that
one exists. A 404 status code does not
indicate whether this
lack of representation is temporary or
permanent; the 410 (Gone)
status code is preferred over 404 if the
origin server knows,
presumably through some configurable means, that
the condition is likely
to be permanent.
A 404 response is
cacheable by default; i.e., unless otherwise
indicated by the method
definition or explicit cache controls (see
6.5.5. 405 Method Not Allowed
The 405 (Method Not
Allowed) status code indicates that the method
received in the
request-line is known by the origin server but not
supported by the target
resource. The origin server MUST
generate an
Allow header field in a
405 response containing a list of the target
resource's currently
supported methods.
A 405 response is
cacheable by default; i.e., unless otherwise
indicated by the method
definition or explicit cache controls (see
Fielding & Reschke
Standards Track
[Page 59]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
6.5.6. 406 Not Acceptable
The 406 (Not Acceptable)
status code indicates that the target
resource does not have a
current representation that would be
acceptable to the user
agent, according to the proactive negotiation
header fields received in
the request (Section
5.3), and the server
is unwilling to supply a
default representation.
The server SHOULD
generate a payload containing a list of available
representation
characteristics and corresponding resource identifiers
from which the user or
user agent can choose the one most
appropriate. A user agent MAY automatically select the
most
appropriate choice from
that list. However, this specification
does
not define any standard
for such automatic selection, as described in
6.5.7. 408 Request Timeout
The 408 (Request Timeout)
status code indicates that the server did
not receive a complete
request message within the time that it was
prepared to wait. A server SHOULD send the "close"
connection option
(Section 6.1 of
[RFC7230]) in the response, since 408 implies that
the server has decided to
close the connection rather than continue
waiting. If the client has an outstanding request in
transit, the
client MAY repeat that
request on a new connection.
6.5.8. 409 Conflict
The 409 (Conflict) status
code indicates that the request could not
be completed due to a
conflict with the current state of the target
resource. This code is used in situations where the
user might be
able to resolve the
conflict and resubmit the request. The
server
SHOULD generate a payload
that includes enough information for a user
to recognize the source
of the conflict.
Conflicts are most likely
to occur in response to a PUT request.
For
example, if versioning
were being used and the representation being
PUT included changes to a
resource that conflict with those made by
an earlier (third-party)
request, the origin server might use a 409
response to indicate that
it can't complete the request. In this
case, the response
representation would likely contain information
useful for merging the
differences based on the revision history.
6.5.9. 410 Gone
The 410 (Gone) status
code indicates that access to the target
resource is no longer
available at the origin server and that this
condition is likely to be
permanent. If the origin server does not
Fielding & Reschke
Standards Track
[Page 60]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
know, or has no facility
to determine, whether or not the condition
is permanent, the status
code 404 (Not Found) ought to be used
instead.
The 410 response is
primarily intended to assist the task of web
maintenance by notifying
the recipient that the resource is
intentionally unavailable
and that the server owners desire that
remote links to that
resource be removed. Such an event is
common
for limited-time,
promotional services and for resources belonging to
individuals no longer
associated with the origin server's site.
It
is not necessary to mark
all permanently unavailable resources as
"gone" or to
keep the mark for any length of time -- that is left to
the discretion of the
server owner.
A 410 response is
cacheable by default; i.e., unless otherwise
indicated by the method
definition or explicit cache controls (see
6.5.10. 411 Length Required
The 411 (Length Required)
status code indicates that the server
refuses to accept the
request without a defined Content-Length
(Section 3.3.2
of [RFC7230]). The client MAY repeat
the request if
it adds a valid
Content-Length header field containing the length of
the message body in the
request message.
6.5.11. 413 Payload Too Large
The 413 (Payload Too
Large) status code indicates that the server is
refusing to process a
request because the request payload is larger
than the server is
willing or able to process. The server
MAY close
the connection to prevent
the client from continuing the request.
If the condition is
temporary, the server SHOULD generate a
Retry-After header field
to indicate that it is temporary and after
what time the client MAY
try again.
6.5.12. 414 URI Too Long
The 414 (URI Too Long)
status code indicates that the server is
refusing to service the
request because the request-target (Section
5.3 of [RFC7230])
is longer than the server is willing to interpret.
This rare condition is
only likely to occur when a client has
improperly converted a
POST request to a GET request with long query
information, when the
client has descended into a "black hole" of
redirection (e.g., a
redirected URI prefix that points to a suffix of
itself) or when the
server is under attack by a client attempting to
exploit potential
security holes.
Fielding & Reschke
Standards Track
[Page 61]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
A 414 response is
cacheable by default; i.e., unless otherwise
indicated by the method
definition or explicit cache controls (see
6.5.13. 415 Unsupported Media Type
The 415 (Unsupported
Media Type) status code indicates that the
origin server is refusing
to service the request because the payload
is in a format not
supported by this method on the target resource.
The format problem might
be due to the request's indicated
Content-Type or
Content-Encoding, or as a result of inspecting the
data directly.
6.5.14. 417 Expectation Failed
The 417 (Expectation
Failed) status code indicates that the
expectation given in the
request's Expect header field
(Section 5.1.1)
could not be met by at least one of the inbound
servers.
6.5.15. 426 Upgrade Required
The 426 (Upgrade
Required) status code indicates that the server
refuses to perform the
request using the current protocol but might
be willing to do so after
the client upgrades to a different
protocol. The server MUST send an Upgrade header field
in a 426
response to indicate the
required protocol(s) (Section 6.7 of
Example:
HTTP/1.1 426 Upgrade
Required
Upgrade: HTTP/3.0
Connection: Upgrade
Content-Length: 53
Content-Type:
text/plain
This service requires
use of the HTTP/3.0 protocol.
6.6. Server Error 5xx
The 5xx (Server Error)
class of status code indicates that the server
is aware that it has
erred or is incapable of performing the
requested method. Except when responding to a HEAD request, the
server SHOULD send a
representation containing an explanation of the
error situation, and
whether it is a temporary or permanent
Fielding & Reschke
Standards Track
[Page 62]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
condition. A user agent SHOULD display any included
representation
to the user. These response codes are applicable to any
request
method.
6.6.1. 500 Internal Server Error
The 500 (Internal Server
Error) status code indicates that the server
encountered an unexpected
condition that prevented it from fulfilling
the request.
6.6.2. 501 Not Implemented
The 501 (Not Implemented)
status code indicates that the server does
not support the
functionality required to fulfill the request.
This
is the appropriate
response when the server does not recognize the
request method and is not
capable of supporting it for any resource.
A 501 response is
cacheable by default; i.e., unless otherwise
indicated by the method
definition or explicit cache controls (see
6.6.3. 502 Bad Gateway
The 502 (Bad Gateway)
status code indicates that the server, while
acting as a gateway or
proxy, received an invalid response from an
inbound server it
accessed while attempting to fulfill the request.
6.6.4. 503 Service Unavailable
The 503 (Service
Unavailable) status code indicates that the server
is currently unable to
handle the request due to a temporary overload
or scheduled maintenance,
which will likely be alleviated after some
delay. The server MAY send a Retry-After header
field
(Section 7.1.3)
to suggest an appropriate amount of time for the
client to wait before
retrying the request.
Note: The existence of the 503 status code
does not imply that a
server has to use it
when becoming overloaded. Some servers
might
simply refuse the
connection.
6.6.5. 504 Gateway Timeout
The 504 (Gateway Timeout)
status code indicates that the server,
while acting as a gateway
or proxy, did not receive a timely response
from an upstream server
it needed to access in order to complete the
request.
Fielding & Reschke
Standards Track
[Page 63]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
6.6.6. 505 HTTP Version Not Supported
The 505 (HTTP Version Not
Supported) status code indicates that the
server does not support,
or refuses to support, the major version of
HTTP that was used in the
request message. The server is
indicating
that it is unable or
unwilling to complete the request using the same
major version as the
client, as described in Section 2.6 of
[RFC7230], other than with this error message. The server SHOULD
generate a representation
for the 505 response that describes why
that version is not
supported and what other protocols are supported
by that server.
7. Response Header Fields
The response header
fields allow the server to pass additional
information about the
response beyond what is placed in the
status-line. These header fields give information about
the server,
about further access to
the target resource, or about related
resources.
Although each response
header field has a defined meaning, in
general, the precise
semantics might be further refined by the
semantics of the request
method and/or response status code.
7.1. Control Data
Response header fields
can supply control data that supplements the
status code, directs
caching, or instructs the client where to go
next.
+-------------------+--------------------------+
| Header Field Name |
Defined in... |
+-------------------+--------------------------+
| Age | Section 5.1 of
[RFC7234] |
| Cache-Control | Section 5.2 of
[RFC7234] |
| Expires | Section 5.3 of
[RFC7234] |
| Date | Section 7.1.1.2 |
| Location | Section 7.1.2 |
| Retry-After | Section 7.1.3 |
| Vary | Section 7.1.4 |
| Warning | Section 5.5 of
[RFC7234] |
+-------------------+--------------------------+
Fielding & Reschke
Standards Track
[Page 64]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
7.1.1. Origination Date
7.1.1.1. Date/Time Formats
Prior to 1995, there were
three different formats commonly used by
servers to communicate
timestamps. For compatibility with old
implementations, all
three are defined here. The preferred
format is
a fixed-length and
single-zone subset of the date and time
specification used by the
Internet Message Format [RFC5322].
HTTP-date = IMF-fixdate / obs-date
An example of the
preferred format is
Sun, 06 Nov 1994
08:49:37 GMT ; IMF-fixdate
Examples of the two
obsolete formats are
Sunday, 06-Nov-94
08:49:37 GMT ; obsolete RFC 850 format
Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format
A recipient that parses a
timestamp value in an HTTP header field
MUST accept all three
HTTP-date formats. When a sender
generates a
header field that
contains one or more timestamps defined as
HTTP-date, the sender
MUST generate those timestamps in the
IMF-fixdate format.
An HTTP-date value
represents time as an instance of Coordinated
Universal Time
(UTC). The first two formats indicate
UTC by the
three-letter abbreviation
for Greenwich Mean Time, "GMT", a
predecessor of the UTC
name; values in the asctime format are assumed
to be in UTC. A sender that generates HTTP-date values from
a local
clock ought to use NTP ([RFC5905])
or some similar protocol to
synchronize its clock to
UTC.
Preferred format:
IMF-fixdate = day-name "," SP date1 SP
time-of-day SP GMT
; fixed
length/zone/capitalization subset of the format
; see Section 3.3 of
[RFC5322]
day-name = %x4D.6F.6E ; "Mon",
case-sensitive
/
%x54.75.65 ; "Tue", case-sensitive
/
%x57.65.64 ; "Wed", case-sensitive
/
%x54.68.75 ; "Thu", case-sensitive
/
%x46.72.69 ; "Fri", case-sensitive
/
%x53.61.74 ; "Sat", case-sensitive
/
%x53.75.6E ; "Sun", case-sensitive
Fielding & Reschke
Standards Track [Page 65]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
date1 =
day SP month SP year
; e.g., 02
Jun 1982
day = 2DIGIT
month = %x4A.61.6E ; "Jan",
case-sensitive
/
%x46.65.62 ; "Feb", case-sensitive
/
%x4D.61.72 ; "Mar", case-sensitive
/ %x41.70.72 ;
"Apr", case-sensitive
/
%x4D.61.79 ; "May", case-sensitive
/
%x4A.75.6E ; "Jun", case-sensitive
/
%x4A.75.6C ; "Jul", case-sensitive
/
%x41.75.67 ; "Aug", case-sensitive
/
%x53.65.70 ; "Sep", case-sensitive
/
%x4F.63.74 ; "Oct", case-sensitive
/
%x4E.6F.76 ; "Nov", case-sensitive
/
%x44.65.63 ; "Dec", case-sensitive
year = 4DIGIT
GMT = %x47.4D.54 ; "GMT",
case-sensitive
time-of-day = hour ":" minute ":"
second
; 00:00:00
- 23:59:60 (leap second)
hour = 2DIGIT
minute = 2DIGIT
second = 2DIGIT
Obsolete formats:
obs-date = rfc850-date / asctime-date
rfc850-date = day-name-l "," SP date2 SP
time-of-day SP GMT
date2 = day "-" month "-"
2DIGIT
; e.g.,
02-Jun-82
day-name-l = %x4D.6F.6E.64.61.79 ; "Monday", case-sensitive
/
%x54.75.65.73.64.61.79 ;
"Tuesday", case-sensitive
/
%x57.65.64.6E.65.73.64.61.79 ; "Wednesday", case-sensitive
/
%x54.68.75.72.73.64.61.79 ;
"Thursday", case-sensitive
/
%x46.72.69.64.61.79 ;
"Friday", case-sensitive
/
%x53.61.74.75.72.64.61.79 ;
"Saturday", case-sensitive
/
%x53.75.6E.64.61.79 ;
"Sunday", case-sensitive
asctime-date = day-name
SP date3 SP time-of-day SP year
date3 = month SP ( 2DIGIT / ( SP 1DIGIT ))
; e.g.,
Jun 2
Fielding & Reschke
Standards Track
[Page 66]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
HTTP-date is case
sensitive. A sender MUST NOT generate
additional
whitespace in an
HTTP-date beyond that specifically included as SP in
the grammar. The semantics of day-name, day, month, year,
and
time-of-day are the same
as those defined for the Internet Message
Format constructs with
the corresponding name ([RFC5322], Section
3.3).
Recipients of a timestamp
value in rfc850-date
format, which uses a
two-digit year, MUST
interpret a timestamp that appears to be more
than 50 years in the
future as representing the most recent year in
the past that had the
same last two digits.
Recipients of timestamp values are encouraged
to be robust in parsing
timestamps unless
otherwise restricted by the field definition.
For
example, messages are
occasionally forwarded over HTTP from a
non-HTTP source that
might generate any of the date and time
specifications defined by
the Internet Message Format.
Note: HTTP
requirements for the date/time stamp format apply only
to their usage within
the protocol stream. Implementations are
not required to use
these formats for user presentation, request
logging, etc.
7.1.1.2. Date
The "Date"
header field represents the date and time at which the
message was originated,
having the same semantics as the Origination
Date Field (orig-date)
defined in Section 3.6.1
of [RFC5322]. The
field value is an
HTTP-date, as defined in Section 7.1.1.1.
Date = HTTP-date
An example is
Date: Tue, 15 Nov 1994
08:12:31 GMT
When a Date header field
is generated, the sender SHOULD generate its
field value as the best
available approximation of the date and time
of message
generation. In theory, the date ought to
represent the
moment just before the
payload is generated. In practice, the
date
can be generated at any
time during message origination.
An origin server MUST NOT
send a Date header field if it does not
have a clock capable of
providing a reasonable approximation of the
current instance in
Coordinated Universal Time. An origin
server MAY
send a Date header field if
the response is in the 1xx
(Informational) or 5xx
(Server Error) class of status codes. An
origin server MUST send a
Date header field in all other cases.
Fielding & Reschke
Standards Track
[Page 67]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
A recipient with a clock
that receives a response message without a
Date header field MUST
record the time it was received and append a
corresponding Date header
field to the message's header section if it
is cached or forwarded
downstream.
A user agent MAY send a
Date header field in a request, though
generally will not do so
unless it is believed to convey useful
information to the
server. For example, custom applications
of HTTP
might convey a Date if
the server is expected to adjust its
interpretation of the
user's request based on differences between the
user agent and server
clocks.
7.1.2. Location
The "Location"
header field is used in some responses to refer to a
specific resource in
relation to the response. The type of
relationship is defined
by the combination of request method and
status code semantics.
Location =
URI-reference
The field value consists
of a single URI-reference. When it has
the
form of a relative
reference ([RFC3986],
Section 4.2), the final
value is computed by
resolving it against the effective request URI
For 201 (Created)
responses, the Location value refers to the primary
resource created by the
request. For 3xx (Redirection)
responses,
the Location value refers
to the preferred target resource for
automatically redirecting
the request.
If the Location value
provided in a 3xx (Redirection) response does
not have a fragment
component, a user agent MUST process the
redirection as if the
value inherits the fragment component of the
URI reference used to
generate the request target (i.e., the
redirection inherits the
original reference's fragment, if any).
For example, a GET
request generated for the URI reference
"http://www.example.org/~tim" might result in a 303 (See
Other)
response containing the
header field:
Location:
/People.html#tim
which suggests that the
user agent redirect to
"http://www.example.org/People.html#tim"
Fielding & Reschke
Standards Track
[Page 68]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
Likewise, a GET request
generated for the URI reference
"http://www.example.org/index.html#larry"
might result in a 301
(Moved Permanently)
response containing the header field:
Location:
http://www.example.net/index.html
which suggests that the
user agent redirect to
"http://www.example.net/index.html#larry", preserving the
original
fragment identifier.
There are circumstances
in which a fragment identifier in a Location
value would not be
appropriate. For example, the Location
header
field in a 201 (Created)
response is supposed to provide a URI that
is specific to the
created resource.
Note: Some recipients
attempt to recover from Location fields that
are not valid URI
references. This specification does not
mandate
or define such processing, but does allow
it for the sake of
robustness.
Note: The
Content-Location header field (Section 3.1.4.2)
differs
from Location in that
the Content-Location refers to the most
specific resource
corresponding to the enclosed representation.
It is therefore
possible for a response to contain both the
Location and
Content-Location header fields.
7.1.3. Retry-After
Servers send the
"Retry-After" header field to indicate how long the
user agent ought to wait
before making a follow-up request. When
sent with a 503 (Service
Unavailable) response, Retry-After indicates
how long the service is
expected to be unavailable to the client.
When sent with any 3xx
(Redirection) response, Retry-After indicates
the minimum time that the
user agent is asked to wait before issuing
the redirected request.
The value of this field
can be either an HTTP-date or a number of
seconds to delay after
the response is received.
Retry-After = HTTP-date
/ delay-seconds
A delay-seconds value is
a non-negative decimal integer, representing
time in seconds.
delay-seconds = 1*DIGIT
Fielding & Reschke
Standards Track
[Page 69]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
Two examples of its use
are
Retry-After: Fri, 31
Dec 1999 23:59:59 GMT
Retry-After: 120
In the latter example,
the delay is 2 minutes.
7.1.4. Vary
The "Vary"
header field in a response describes what parts of a
request message, aside
from the method, Host header field, and
request target, might
influence the origin server's process for
selecting and
representing this response. The value
consists of
either a single asterisk
("*") or a list of header field names
(case-insensitive).
Vary = "*" /
1#field-name
A Vary field value of
"*" signals that anything about the request
might play a role in
selecting the response representation, possibly
including elements
outside the message syntax (e.g., the client's
network address). A recipient will not be able to determine
whether
this response is
appropriate for a later request without forwarding
the request to the origin
server. A proxy MUST NOT generate a Vary
field with a
"*" value.
A Vary field value
consisting of a comma-separated list of names
indicates that the named
request header fields, known as the
selecting header fields,
might have a role in selecting the
representation. The potential selecting header fields are not
limited to those defined
by this specification.
For example, a response
that contains
Vary: accept-encoding,
accept-language
indicates that the origin
server might have used the request's
Accept-Encoding and
Accept-Language fields (or lack thereof) as
determining factors while
choosing the content for this response.
An origin server might
send Vary with a list of fields for two
purposes:
1. To inform cache recipients that they MUST NOT
use this response
to satisfy a later
request unless the later request has the same
values for the listed
fields as the original request (Section 4.1
of [RFC7234]). In other words, Vary
expands the cache key
required to match a
new request to the stored cache entry.
Fielding & Reschke
Standards Track
[Page 70]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
2. To inform user agent recipients that this
response is subject to
content negotiation (Section 5.3) and
that a different
representation might
be sent in a subsequent request if
additional parameters
are provided in the listed header fields
(proactive
negotiation).
An origin server SHOULD
send a Vary header field when its algorithm
for selecting a
representation varies based on aspects of the request
message other than the
method and request target, unless the variance
cannot be crossed or the
origin server has been deliberately
configured to prevent
cache transparency. For example, there
is no
need to send the
Authorization field name in Vary because reuse
across users is
constrained by the field definition (Section 4.2 of
[RFC7235]). Likewise, an origin
server might use Cache-Control
directives (Section 5.2 of
[RFC7234]) to supplant Vary if it
considers the variance
less significant than the performance cost of
Vary's impact on caching.
7.2. Validator Header Fields
Validator header fields
convey metadata about the selected
representation (Section 3). In responses to safe requests, validator
fields describe the
selected representation chosen by the origin
server while handling the
response. Note that, depending on the
status code semantics,
the selected representation for a given
response is not
necessarily the same as the representation enclosed
as response payload.
In a successful response
to a state-changing request, validator
fields describe the new
representation that has replaced the prior
selected representation
as a result of processing the request.
For example, an ETag
header field in a 201 (Created) response
communicates the
entity-tag of the newly created resource's
representation, so that
it can be used in later conditional requests
to prevent the "lost
update" problem [RFC7232].
+-------------------+--------------------------+
| Header Field Name |
Defined in... |
+-------------------+--------------------------+
| ETag | Section 2.3 of
[RFC7232] |
| Last-Modified | Section 2.2 of
[RFC7232] |
+-------------------+--------------------------+
Fielding & Reschke
Standards Track
[Page 71]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
7.3. Authentication Challenges
Authentication challenges
indicate what mechanisms are available for
the client to provide authentication
credentials in future requests.
+--------------------+--------------------------+
| Header Field Name | Defined in... |
+--------------------+--------------------------+
| WWW-Authenticate | Section 4.1 of
[RFC7235] |
| Proxy-Authenticate | Section 4.3 of
[RFC7235] |
+--------------------+--------------------------+
7.4. Response Context
The remaining response
header fields provide more information about
the target resource for
potential use in later requests.
+-------------------+--------------------------+
| Header Field Name |
Defined in... |
+-------------------+--------------------------+
| Accept-Ranges | Section 2.3 of
[RFC7233] |
| Allow | Section 7.4.1 |
| Server | Section 7.4.2 |
+-------------------+--------------------------+
7.4.1. Allow
The "Allow"
header field lists the set of methods advertised as
supported by the target
resource. The purpose of this field is
strictly to inform the
recipient of valid request methods associated
with the resource.
Allow = #method
Example of use:
Allow: GET, HEAD, PUT
The actual set of allowed
methods is defined by the origin server at
the time of each
request. An origin server MUST generate
an Allow
field in a 405 (Method
Not Allowed) response and MAY do so in any
other response. An empty Allow field value indicates that the
resource allows no
methods, which might occur in a 405 response if
the resource has been
temporarily disabled by configuration.
A proxy MUST NOT modify
the Allow header field -- it does not need to
understand all of the
indicated methods in order to handle them
according to the generic
message handling rules.
Fielding & Reschke
Standards Track
[Page 72]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
7.4.2. Server
The "Server"
header field contains information about the software
used by the origin server
to handle the request, which is often used
by clients to help
identify the scope of reported interoperability
problems, to work around
or tailor requests to avoid particular
server limitations, and
for analytics regarding server or operating
system use. An origin server MAY generate a Server field
in its
responses.
Server = product *( RWS
( product / comment ) )
The Server field-value
consists of one or more product identifiers,
each followed by zero or
more comments (Section 3.2
of [RFC7230]),
which together identify
the origin server software and its
significant
subproducts. By convention, the product
identifiers are
listed in decreasing
order of their significance for identifying the
origin server
software. Each product identifier consists
of a name
and optional version, as
defined in Section
5.5.3.
Example:
Server: CERN/3.0
libwww/2.17
An origin server SHOULD
NOT generate a Server field containing
needlessly fine-grained
detail and SHOULD limit the addition of
subproducts by third
parties. Overly long and detailed Server
field
values increase response
latency and potentially reveal internal
implementation details
that might make it (slightly) easier for
attackers to find and
exploit known security holes.
8. IANA Considerations
8.1. Method Registry
The "Hypertext
Transfer Protocol (HTTP) Method Registry" defines the
namespace for the request
method token (Section
4). The method
registry has been created
and is now maintained at
<http://www.iana.org/assignments/http-methods>.
Fielding & Reschke
Standards Track
[Page 73]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
8.1.1. Procedure
HTTP method registrations
MUST include the following fields:
o Method Name (see Section 4)
o Safe ("yes" or "no", see Section 4.2.1)
o Idempotent ("yes" or
"no", see Section 4.2.2)
o Pointer to specification text
Values to be added to
this namespace require IETF Review (see
8.1.2. Considerations for New Methods
Standardized methods are
generic; that is, they are potentially
applicable to any
resource, not just one particular media type, kind
of resource, or
application. As such, it is preferred
that new
methods be registered in
a document that isn't specific to a single
application or data
format, since orthogonal technologies deserve
orthogonal specification.
Since message parsing (Section 3.3 of
[RFC7230]) needs to be
independent of method
semantics (aside from responses to HEAD),
definitions of new
methods cannot change the parsing algorithm or
prohibit the presence of
a message body on either the request or the
response message. Definitions of new methods can specify that
only a
zero-length message body
is allowed by requiring a Content-Length
header field with a value
of "0".
A new method definition
needs to indicate whether it is safe
(Section 4.2.1),
idempotent (Section
4.2.2), cacheable
(Section 4.2.3),
what semantics are to be associated with the payload
body if any is present in
the request and what refinements the method
makes to header field or
status code semantics. If the new method
is
cacheable, its definition
ought to describe how, and under what
conditions, a cache can
store a response and use it to satisfy a
subsequent request. The new method ought to describe whether it
can
be made conditional (Section 5.2) and,
if so, how a server responds
when the condition is
false. Likewise, if the new method might
have
some use for partial
response semantics ([RFC7233]),
it ought to
document this, too.
Note: Avoid defining a
method name that starts with "M-", since
that prefix might be
misinterpreted as having the semantics
assigned to it by [RFC2774].
Fielding & Reschke
Standards Track
[Page 74]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
8.1.3. Registrations
The "Hypertext
Transfer Protocol (HTTP) Method Registry" has been
populated with the
registrations below:
+---------+------+------------+---------------+
| Method | Safe | Idempotent | Reference |
+---------+------+------------+---------------+
| CONNECT | no | no
| Section
4.3.6 |
| DELETE | no
| yes | Section 4.3.5 |
| GET | yes
| yes | Section 4.3.1 |
| HEAD | yes
| yes | Section 4.3.2 |
| OPTIONS | yes | yes
| Section
4.3.7 |
| POST | no
| no | Section 4.3.3 |
| PUT | no
| yes | Section 4.3.4 |
| TRACE | yes
| yes | Section 4.3.8 |
+---------+------+------------+---------------+
8.2. Status Code Registry
The "Hypertext
Transfer Protocol (HTTP) Status Code Registry" defines
the namespace for the
response status-code token (Section 6). The
status code registry is
maintained at
<http://www.iana.org/assignments/http-status-codes>.
This section replaces the
registration procedure for HTTP Status
Codes previously defined
in Section 7.1
of [RFC2817].
8.2.1. Procedure
A registration MUST
include the following fields:
o Status Code (3 digits)
o Short Description
o Pointer to specification text
Values to be added to the
HTTP status code namespace require IETF
Review (see [RFC5226],
Section 4.1).
Fielding & Reschke
Standards Track
[Page 75]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
8.2.2. Considerations for New Status Codes
When it is necessary to
express semantics for a response that are not
defined by current status
codes, a new status code can be registered.
Status codes are generic;
they are potentially applicable to any
resource, not just one
particular media type, kind of resource, or
application of HTTP. As such, it is preferred that new status
codes
be registered in a
document that isn't specific to a single
application.
New status codes are
required to fall under one of the categories
defined in Section 6. To allow existing parsers to process the
response message, new
status codes cannot disallow a payload,
although they can mandate
a zero-length payload body.
Proposals for new status
codes that are not yet widely deployed ought
to avoid allocating a
specific number for the code until there is
clear consensus that it
will be registered; instead, early drafts can
use a notation such as
"4NN", or "3N0" .. "3N9", to indicate the
class of the proposed
status code(s) without consuming a number
prematurely.
The definition of a new
status code ought to explain the request
conditions that would
cause a response containing that status code
(e.g., combinations of
request header fields and/or method(s)) along
with any dependencies on
response header fields (e.g., what fields
are required, what fields
can modify the semantics, and what header
field semantics are
further refined when used with the new status
code).
The definition of a new
status code ought to specify whether or not
it is cacheable. Note that all status codes can be cached if
the
response they occur in
has explicit freshness information; however,
status codes that are
defined as being cacheable are allowed to be
cached without explicit
freshness information. Likewise, the
definition of a status
code can place constraints upon cache
behavior. See [RFC7234]
for more information.
Finally, the definition
of a new status code ought to indicate
whether the payload has
any implied association with an identified
resource (Section 3.1.4.1).
8.2.3. Registrations
The status code registry
has been updated with the registrations
below:
Fielding & Reschke
Standards Track [Page 76]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
+-------+-------------------------------+----------------+
| Value |
Description |
Reference |
+-------+-------------------------------+----------------+
| 100 | Continue | Section 6.2.1 |
| 101 | Switching Protocols | Section 6.2.2 |
| 200 | OK | Section 6.3.1 |
| 201 | Created | Section 6.3.2 |
| 202 | Accepted | Section 6.3.3 |
| 203 | Non-Authoritative Information | Section 6.3.4 |
| 204 | No Content | Section 6.3.5 |
| 205 | Reset Content | Section 6.3.6 |
| 300 | Multiple Choices | Section 6.4.1 |
| 301 | Moved Permanently | Section 6.4.2 |
| 302 | Found | Section 6.4.3 |
| 303 | See Other | Section 6.4.4 |
| 305 | Use Proxy | Section 6.4.5 |
| 306 | (Unused) | Section 6.4.6 |
| 307 | Temporary Redirect | Section 6.4.7 |
| 400 | Bad Request | Section 6.5.1 |
| 402 | Payment Required | Section 6.5.2 |
| 403 | Forbidden | Section 6.5.3 |
| 404 | Not Found | Section 6.5.4 |
| 405 | Method Not Allowed | Section 6.5.5 |
| 406 | Not Acceptable | Section 6.5.6 |
| 408 | Request Timeout | Section 6.5.7 |
| 409 | Conflict | Section 6.5.8 |
| 410 | Gone | Section 6.5.9 |
| 411 | Length Required | Section 6.5.10
|
| 413 | Payload Too Large | Section 6.5.11
|
| 414 | URI Too Long | Section 6.5.12
|
| 415 | Unsupported Media Type | Section 6.5.13
|
| 417 | Expectation Failed | Section 6.5.14
|
| 426 | Upgrade Required | Section 6.5.15
|
| 500 | Internal Server Error | Section 6.6.1 |
| 501 | Not Implemented | Section 6.6.2 |
| 502 | Bad Gateway | Section 6.6.3 |
| 503 | Service Unavailable | Section 6.6.4 |
| 504 | Gateway Timeout | Section 6.6.5 |
| 505 | HTTP Version Not Supported | Section 6.6.6 |
+-------+-------------------------------+----------------+
8.3. Header Field Registry
HTTP header fields are
registered within the "Message Headers"
registry located at
<http://www.iana.org/assignments/message-headers>,
as defined by
[BCP90].
Fielding & Reschke
Standards Track
[Page 77]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
8.3.1. Considerations for New Header Fields
Header fields are
key:value pairs that can be used to communicate
data about the message,
its payload, the target resource, or the
connection (i.e., control
data). See Section 3.2 of
[RFC7230] for a
general definition of
header field syntax in HTTP messages.
The requirements for
header field names are defined in [BCP90].
Authors of specifications
defining new fields are advised to keep the
name as short as
practical and not to prefix the name with "X-"
unless the header field
will never be used on the Internet. (The
"X-" prefix
idiom has been extensively misused in practice; it was
intended to only be used as
a mechanism for avoiding name collisions
inside proprietary
software or intranet processing, since the prefix
would ensure that private
names never collide with a newly registered
Internet name; see [BCP178] for further information).
New header field values
typically have their syntax defined using
ABNF ([RFC5234]),
using the extension defined in Section 7 of
[RFC7230] as necessary, and are usually constrained to the range of
US-ASCII characters. Header fields needing a greater range of
characters can use an
encoding such as the one defined in [RFC5987].
Leading and trailing
whitespace in raw field values is removed upon
field parsing (Section 3.2.4
of [RFC7230]). Field definitions
where
leading or trailing
whitespace in values is significant will have to
use a container syntax
such as quoted-string (Section 3.2.6
of
Because commas
(",") are used as a generic delimiter between
field-values, they need
to be treated with care if they are allowed
in the field-value. Typically, components that might contain a
comma
are protected with
double-quotes using the quoted-string ABNF
production.
For example, a textual
date and a URI (either of which might contain
a comma) could be safely
carried in field-values like these:
Example-URI-Field:
"http://example.com/a.html,foo",
"http://without-a-comma.example.com/"
Example-Date-Field:
"Sat, 04 May 1996", "Wed, 14 Sep 2005"
Note that double-quote
delimiters almost always are used with the
quoted-string production;
using a different syntax inside
double-quotes will likely
cause unnecessary confusion.
Fielding & Reschke
Standards Track
[Page 78]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
Many header fields use a
format including (case-insensitively) named
parameters (for instance,
Content-Type, defined in Section 3.1.1.5).
Allowing both unquoted
(token) and quoted (quoted-string) syntax for
the parameter value
enables recipients to use existing parser
components. When allowing both forms, the meaning of a
parameter
value ought to be
independent of the syntax used for it (for an
example, see the notes on
parameter handling for media types in
Authors of specifications
defining new header fields are advised to
consider documenting:
o Whether the field is a single value or
whether it can be a list
(delimited by commas;
see Section 3.2
of [RFC7230]).
If it does not use the
list syntax, document how to treat messages
where the field occurs
multiple times (a sensible default would be
to ignore the field,
but this might not always be the right
choice).
Note that
intermediaries and software libraries might combine
multiple header field
instances into a single one, despite the
field's definition not
allowing the list syntax. A robust
format
enables recipients to
discover these situations (good example:
"Content-Type", as the comma can only appear inside quoted
strings; bad example:
"Location", as a comma can occur inside a
URI).
o Under what conditions the header field can be
used; e.g., only in
responses or requests,
in all messages, only on responses to a
particular request
method, etc.
o Whether the field should be stored by origin
servers that
understand it upon a
PUT request.
o Whether the field semantics are further
refined by the context,
such as by existing
request methods or status codes.
o Whether it is appropriate to list the
field-name in the Connection
header field (i.e., if
the header field is to be hop-by-hop; see
o Under what conditions intermediaries are
allowed to insert,
delete, or modify the
field's value.
Fielding & Reschke
Standards Track
[Page 79]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
o Whether it is appropriate to list the
field-name in a Vary
response header field
(e.g., when the request header field is used
by an origin server's
content selection algorithm; see
o Whether the header field is useful or
allowable in trailers (see
o Whether the header field ought to be
preserved across redirects.
o Whether it introduces any additional security
considerations, such
as disclosure of
privacy-related data.
8.3.2. Registrations
The "Message
Headers" registry has been updated with the following
permanent registrations:
+-------------------+----------+----------+-----------------+
| Header Field Name |
Protocol | Status | Reference |
+-------------------+----------+----------+-----------------+
| Accept | http | standard | Section 5.3.2 |
| Accept-Charset | http
| standard | Section 5.3.3 |
| Accept-Encoding | http
| standard | Section 5.3.4 |
| Accept-Language | http
| standard | Section 5.3.5 |
| Allow | http | standard | Section 7.4.1 |
| Content-Encoding | http
| standard | Section 3.1.2.2
|
| Content-Language | http
| standard | Section 3.1.3.2
|
| Content-Location | http
| standard | Section 3.1.4.2
|
| Content-Type | http
| standard | Section 3.1.1.5
|
| Date | http | standard | Section 7.1.1.2
|
| Expect | http | standard | Section 5.1.1 |
| From | http | standard | Section 5.5.1 |
| Location | http | standard | Section 7.1.2 |
| Max-Forwards | http
| standard | Section 5.1.2 |
| MIME-Version | http
| standard | Appendix A.1 |
| Referer | http | standard | Section 5.5.2 |
| Retry-After | http | standard | Section 7.1.3 |
| Server | http | standard | Section 7.4.2 |
| User-Agent | http | standard | Section 5.5.3 |
| Vary | http | standard | Section 7.1.4 |
+-------------------+----------+----------+-----------------+
The change controller for
the above registrations is: "IETF
(iesg@ietf.org) -
Internet Engineering Task Force".
Fielding & Reschke
Standards Track
[Page 80]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
8.4. Content Coding Registry
The "HTTP Content
Coding Registry" defines the namespace for content
coding names (Section 4.2 of
[RFC7230]). The content coding
registry
is maintained at <http://www.iana.org/assignments/http-parameters>.
8.4.1. Procedure
Content coding
registrations MUST include the following fields:
o Name
o Description
o Pointer to specification text
Names of content codings
MUST NOT overlap with names of transfer
codings (Section 4 of
[RFC7230]), unless the encoding transformation
is identical (as is the
case for the compression codings defined in
Values to be added to
this namespace require IETF Review (see Section
4.1 of [RFC5226])
and MUST conform to the purpose of content coding
defined in this section.
8.4.2. Registrations
The "HTTP Content
Coding Registry" has been updated with the
registrations below:
+----------+----------------------------------------+---------------+
| Name | Description | Reference |
+----------+----------------------------------------+---------------+
| identity | Reserved
(synonym for "no encoding" in | Section 5.3.4 |
| | Accept-Encoding) | |
+----------+----------------------------------------+---------------+
9. Security Considerations
This section is meant to
inform developers, information providers,
and users of known
security concerns relevant to HTTP semantics and
its use for transferring
information over the Internet.
Considerations related to
message syntax, parsing, and routing are
discussed in Section 9 of
[RFC7230].
The list of
considerations below is not exhaustive.
Most security
concerns related to HTTP
semantics are about securing server-side
applications (code behind
the HTTP interface), securing user agent
Fielding & Reschke
Standards Track
[Page 81]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
processing of payloads
received via HTTP, or secure use of the
Internet in general,
rather than security of the protocol.
Various
organizations maintain
topical information and links to current
research on Web
application security (e.g., [OWASP]).
9.1. Attacks Based on File and Path Names
Origin servers frequently
make use of their local file system to
manage the mapping from
effective request URI to resource
representations. Most file systems are not designed to protect
against malicious file or
path names. Therefore, an origin server
needs to avoid accessing
names that have a special significance to
the system when mapping
the request target to files, folders, or
directories.
For example, UNIX,
Microsoft Windows, and other operating systems use
".." as a path
component to indicate a directory level above the
current one, and they use
specially named paths or file names to send
data to system
devices. Similar naming conventions
might exist
within other types of
storage systems. Likewise, local storage
systems have an annoying
tendency to prefer user-friendliness over
security when handling
invalid or unexpected characters,
recomposition of
decomposed characters, and case-normalization of
case-insensitive names.
Attacks based on such
special names tend to focus on either denial-
of-service (e.g., telling
the server to read from a COM port) or
disclosure of
configuration and source files that are not meant to be
served.
9.2. Attacks Based on Command, Code, or Query
Injection
Origin servers often use
parameters within the URI as a means of
identifying system
services, selecting database entries, or choosing
a data source. However, data received in a request cannot be
trusted. An attacker could construct any of the
request data
elements (method,
request-target, header fields, or body) to contain
data that might be
misinterpreted as a command, code, or query when
passed through a command
invocation, language interpreter, or
database interface.
For example, SQL
injection is a common attack wherein additional
query language is
inserted within some part of the request-target or
header fields (e.g.,
Host, Referer, etc.). If the received
data is
used directly within a
SELECT statement, the query language might be
interpreted as a database
command instead of a simple string value.
This type of
implementation vulnerability is extremely common, in
spite of being easy to
prevent.
Fielding & Reschke
Standards Track
[Page 82]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
In general, resource
implementations ought to avoid use of request
data in contexts that are
processed or interpreted as instructions.
Parameters ought to be
compared to fixed strings and acted upon as a
result of that comparison,
rather than passed through an interface
that is not prepared for
untrusted data. Received data that isn't
based on fixed parameters
ought to be carefully filtered or encoded
to avoid being
misinterpreted.
Similar considerations
apply to request data when it is stored and
later processed, such as
within log files, monitoring tools, or when
included within a data
format that allows embedded scripts.
9.3. Disclosure of Personal Information
Clients are often privy
to large amounts of personal information,
including both
information provided by the user to interact with
resources (e.g., the
user's name, location, mail address, passwords,
encryption keys, etc.)
and information about the user's browsing
activity over time (e.g.,
history, bookmarks, etc.).
Implementations
need to prevent
unintentional disclosure of personal information.
9.4. Disclosure of Sensitive Information in URIs
URIs are intended to be
shared, not secured, even when they identify
secure resources. URIs are often shown on displays, added to
templates when a page is
printed, and stored in a variety of
unprotected bookmark
lists. It is therefore unwise to include
information within a URI
that is sensitive, personally identifiable,
or a risk to disclose.
Authors of services ought
to avoid GET-based forms for the submission
of sensitive data because
that data will be placed in the
request-target. Many existing servers, proxies, and user
agents log
or display the
request-target in places where it might be visible to
third parties. Such services ought to use POST-based form
submission
instead.
Since the Referer header
field tells a target site about the context
that resulted in a
request, it has the potential to reveal
information about the
user's immediate browsing history and any
personal information that
might be found in the referring resource's
URI. Limitations on the Referer header field are
described in
Section 5.5.2
to address some of its security considerations.
Fielding & Reschke
Standards Track
[Page 83]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
9.5. Disclosure of Fragment after Redirects
Although fragment
identifiers used within URI references are not sent
in requests, implementers
ought to be aware that they will be visible
to the user agent and any
extensions or scripts running as a result
of the response. In particular, when a redirect occurs and the
original request's
fragment identifier is inherited by the new
reference in Location (Section 7.1.2),
this might have the effect of
disclosing one site's
fragment to another site. If the first
site
uses personal information
in fragments, it ought to ensure that
redirects to other sites
include a (possibly empty) fragment
component in order to block
that inheritance.
9.6. Disclosure of Product Information
The User-Agent (Section 5.5.3),
Via (Section 5.7.1
of [RFC7230]), and
Server (Section 7.4.2)
header fields often reveal information about
the respective sender's
software systems. In theory, this can
make
it easier for an attacker
to exploit known security holes; in
practice, attackers tend
to try all potential holes regardless of the
apparent software
versions being used.
Proxies that serve as a
portal through a network firewall ought to
take special precautions
regarding the transfer of header information
that might identify hosts
behind the firewall. The Via header
field
allows intermediaries to
replace sensitive machine names with
pseudonyms.
9.7. Browser Fingerprinting
Browser fingerprinting is
a set of techniques for identifying a
specific user agent over
time through its unique set of
characteristics. These characteristics might include
information
related to its TCP
behavior, feature capabilities, and scripting
environment, though of
particular interest here is the set of unique
characteristics that
might be communicated via HTTP.
Fingerprinting
is considered a privacy
concern because it enables tracking of a user
agent's behavior over
time without the corresponding controls that
the user might have over
other forms of data collection (e.g.,
cookies). Many general-purpose user agents (i.e., Web
browsers) have
taken steps to reduce
their fingerprints.
There are a number of
request header fields that might reveal
information to servers
that is sufficiently unique to enable
fingerprinting. The From header field is the most obvious,
though it
is expected that From
will only be sent when self-identification is
desired by the user. Likewise, Cookie header fields are
deliberately
Fielding & Reschke
Standards Track
[Page 84]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
designed to enable
re-identification, so fingerprinting concerns only
apply to situations where
cookies are disabled or restricted by the
user agent's
configuration.
The User-Agent header
field might contain enough information to
uniquely identify a
specific device, usually when combined with other
characteristics,
particularly if the user agent sends excessive
details about the user's
system or extensions. However, the
source
of unique information
that is least expected by users is proactive
negotiation (Section 5.3),
including the Accept, Accept-Charset,
Accept-Encoding, and
Accept-Language header fields.
In addition to the
fingerprinting concern, detailed use of the
Accept-Language header
field can reveal information the user might
consider to be of a private
nature. For example, understanding a
given language set might
be strongly correlated to membership in a
particular ethnic
group. An approach that limits such loss
of
privacy would be for a
user agent to omit the sending of
Accept-Language except
for sites that have been whitelisted, perhaps
via interaction after
detecting a Vary header field that indicates
language negotiation
might be useful.
In environments where
proxies are used to enhance privacy, user
agents ought to be
conservative in sending proactive negotiation
header fields. General-purpose user agents that provide a
high
degree of header field
configurability ought to inform users about
the loss of privacy that
might result if too much detail is provided.
As an extreme privacy
measure, proxies could filter the proactive
negotiation header fields
in relayed requests.
10. Acknowledgments
11. References
11.1. Normative References
[RFC2045] Freed, N. and N. Borenstein,
"Multipurpose Internet Mail
Extensions
(MIME) Part One: Format of Internet Message
Bodies", RFC 2045, November 1996.
[RFC2046] Freed, N. and N. Borenstein,
"Multipurpose Internet Mail
Extensions
(MIME) Part Two: Media Types", RFC 2046,
November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs
to Indicate
Requirement
Levels", BCP 14, RFC 2119, March 1997.
Fielding & Reschke
Standards Track
[Page 85]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
[RFC3986] Berners-Lee, T., Fielding, R., and L.
Masinter, "Uniform
Resource
Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[RFC4647] Phillips, A., Ed. and M. Davis, Ed.,
"Matching of Language
Tags", BCP 47, RFC 4647, September 2006.
[RFC5234] Crocker, D., Ed. and P. Overell,
"Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5646] Phillips, A., Ed. and M. Davis, Ed.,
"Tags for Identifying
Languages", BCP 47,
RFC 5646, September 2009.
[RFC6365] Hoffman, P. and J. Klensin, "Terminology
Used in
Internationalization in the IETF", BCP 166, RFC 6365,
September
2011.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed.,
"Hypertext Transfer
Protocol
(HTTP/1.1): Message Syntax and Routing",
RFC 7230, June 2014.
[RFC7232] Fielding, R., Ed. and J. Reschke, Ed.,
"Hypertext Transfer
Protocol
(HTTP/1.1): Conditional Requests", RFC 7232,
June 2014.
[RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J.
Reschke, Ed.,
"Hypertext Transfer Protocol (HTTP/1.1): Range Requests",
RFC 7233, June 2014.
[RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and
J. Reschke,
Ed.,
"Hypertext Transfer Protocol (HTTP/1.1): Caching",
RFC 7234, June 2014.
[RFC7235] Fielding, R., Ed. and J. Reschke, Ed.,
"Hypertext Transfer
Protocol
(HTTP/1.1): Authentication", RFC 7235, June 2014.
11.2. Informative References
[BCP13] Freed, N., Klensin, J., and T. Hansen,
"Media Type
Specifications
and Registration Procedures", BCP 13,
RFC 6838, January 2013.
[BCP178] Saint-Andre, P., Crocker, D., and M.
Nottingham,
"Deprecating the "X-" Prefix and Similar Constructs in
Application
Protocols", BCP 178, RFC 6648, June 2012.
Fielding & Reschke
Standards Track
[Page 86]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
[BCP90] Klyne, G., Nottingham, M., and J. Mogul,
"Registration
Procedures for
Message Header Fields", BCP
90, RFC 3864,
September
2004.
[OWASP] van der Stock, A., Ed., "A Guide to
Building Secure Web
Applications
and Web Services", The Open Web Application
Security
Project (OWASP) 2.0.1, July 2005,
[REST] Fielding, R., "Architectural Styles
and the Design of
Network-based
Software Architectures",
Doctoral
Dissertation, University of California, Irvine,
September
2000,
<http://roy.gbiv.com/pubs/dissertation/top.htm>.
[RFC1945] Berners-Lee, T., Fielding, R., and H.
Nielsen, "Hypertext
Transfer
Protocol -- HTTP/1.0", RFC
1945, May 1996.
[RFC2049] Freed, N. and N. Borenstein,
"Multipurpose Internet Mail
Extensions
(MIME) Part Five: Conformance Criteria and
Examples", RFC
2049, November 1996.
[RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen,
H., and T.
Berners-Lee,
"Hypertext Transfer Protocol -- HTTP/1.1",
RFC 2068, January 1997.
[RFC2295] Holtman, K. and A. Mutz, "Transparent
Content Negotiation
in HTTP",
RFC 2295, March 1998.
[RFC2388] Masinter, L., "Returning Values from
Forms: multipart/
form-data", RFC
2388, August 1998.
[RFC2557] Palme, F., Hopmann, A., Shelness, N., and E.
Stefferud,
"MIME
Encapsulation of Aggregate Documents, such as HTML
(MHTML)",
RFC 2557, March 1999.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk,
H.,
Masinter, L.,
Leach, P., and T. Berners-Lee, "Hypertext
Transfer
Protocol -- HTTP/1.1", RFC
2616, June 1999.
[RFC2774] Frystyk, H., Leach, P., and S. Lawrence,
"An HTTP
Extension
Framework", RFC 2774,
February 2000.
[RFC2817] Khare, R. and S. Lawrence, "Upgrading to
TLS Within
HTTP/1.1", RFC
2817, May 2000.
[RFC2978] Freed, N. and J. Postel, "IANA Charset
Registration
Procedures", BCP 19,
RFC 2978, October 2000.
Fielding & Reschke
Standards Track
[Page 87]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
[RFC5226] Narten, T. and H. Alvestrand,
"Guidelines for Writing an
IANA
Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[RFC5246] Dierks, T. and E. Rescorla, "The
Transport Layer Security
(TLS) Protocol
Version 1.2", RFC 5246,
August 2008.
[RFC5322] Resnick, P., "Internet Message
Format", RFC 5322,
October 2008.
[RFC5789] Dusseault, L. and J. Snell, "PATCH
Method for HTTP",
RFC 5789, March 2010.
[RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and
W. Kasch,
"Network
Time Protocol Version 4: Protocol and Algorithms
Specification", RFC
5905, June 2010.
[RFC5987] Reschke, J., "Character Set and Language
Encoding for
Hypertext
Transfer Protocol (HTTP) Header Field
Parameters", RFC
5987, August 2010.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
[RFC6265] Barth, A., "HTTP State Management
Mechanism", RFC 6265,
April 2011.
[RFC6266] Reschke, J., "Use of the
Content-Disposition Header Field
in the
Hypertext Transfer Protocol (HTTP)", RFC 6266,
June 2011.
[RFC7238] Reschke, J., "The Hypertext Transfer
Protocol (HTTP)
Status Code
308 (Permanent Redirect)", RFC
7238,
June 2014.
Fielding & Reschke
Standards Track
[Page 88]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
Appendix A. Differences between HTTP and MIME
HTTP/1.1 uses many of the
constructs defined for the Internet Message
Format [RFC5322]
and the Multipurpose Internet Mail Extensions (MIME)
[RFC2045]
to allow a message body to be transmitted in an open
variety of
representations and with extensible header fields.
However, RFC 2045 is focused only on
email; applications of HTTP have
many characteristics that
differ from email; hence, HTTP has features
that differ from
MIME. These differences were carefully
chosen to
optimize performance over
binary connections, to allow greater
freedom in the use of new
media types, to make date comparisons
easier, and to
acknowledge the practice of some early HTTP servers
and clients.
This appendix describes
specific areas where HTTP differs from MIME.
Proxies and gateways to and
from strict MIME environments need to be
aware of these
differences and provide the appropriate conversions
where necessary.
A.1. MIME-Version
HTTP is not a MIME-compliant
protocol. However, messages can include
a single MIME-Version
header field to indicate what version of the
MIME protocol was used to
construct the message. Use of the
MIME-Version header field
indicates that the message is in full
conformance with the MIME
protocol (as defined in [RFC2045]).
Senders are responsible
for ensuring full conformance (where
possible) when exporting
HTTP messages to strict MIME environments.
A.2. Conversion to Canonical Form
MIME requires that an
Internet mail body part be converted to
canonical form prior to
being transferred, as described in Section 4
of [RFC2049]. Section 3.1.1.3
of this document describes the forms
allowed for subtypes of
the "text" media type when transmitted over
HTTP. [RFC2046]
requires that content with a type of "text"
represent line breaks as
CRLF and forbids the use of CR or LF outside
of line break
sequences. HTTP allows CRLF, bare CR,
and bare LF to
indicate a line break
within text content.
A proxy or gateway from
HTTP to a strict MIME environment ought to
translate all line breaks
within the text media types described in
Section 3.1.1.3
of this document to the RFC
2049 canonical form of
CRLF. Note, however, this might be complicated by
the presence of a
Content-Encoding and by
the fact that HTTP allows the use of some
charsets that do not use
octets 13 and 10 to represent CR and LF,
respectively.
Fielding & Reschke
Standards Track
[Page 89]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
Conversion will break any
cryptographic checksums applied to the
original content unless
the original content is already in canonical
form. Therefore, the canonical form is recommended
for any content
that uses such checksums
in HTTP.
A.3. Conversion of Date Formats
HTTP/1.1 uses a
restricted set of date formats (Section 7.1.1.1)
to
simplify the process of
date comparison. Proxies and gateways
from
other protocols ought to
ensure that any Date header field present in
a message conforms to one
of the HTTP/1.1 formats and rewrite the
date if necessary.
A.4. Conversion of Content-Encoding
MIME does not include any
concept equivalent to HTTP/1.1's
Content-Encoding header
field. Since this acts as a modifier on
the
media type, proxies and
gateways from HTTP to MIME-compliant
protocols ought to either
change the value of the Content-Type header
field or decode the
representation before forwarding the message.
(Some experimental
applications of Content-Type for Internet mail
have used a media-type
parameter of ";conversions=<content-coding>"
to perform a function
equivalent to Content-Encoding. However,
this
parameter is not part of the
MIME standards).
A.5. Conversion of Content-Transfer-Encoding
HTTP does not use the
Content-Transfer-Encoding field of MIME.
Proxies and gateways from
MIME-compliant protocols to HTTP need to
remove any
Content-Transfer-Encoding prior to delivering the response
message to an HTTP
client.
Proxies and gateways from
HTTP to MIME-compliant protocols are
responsible for ensuring
that the message is in the correct format
and encoding for safe
transport on that protocol, where "safe
transport" is
defined by the limitations of the protocol being used.
Such a proxy or gateway
ought to transform and label the data with an
appropriate
Content-Transfer-Encoding if doing so will improve the
likelihood of safe
transport over the destination protocol.
A.6. MHTML and Line Length Limitations
HTTP implementations that
share code with MHTML [RFC2557]
implementations need to
be aware of MIME line length limitations.
Since HTTP does not have
this limitation, HTTP does not fold long
lines. MHTML messages being transported by HTTP
follow all
conventions of MHTML,
including line length limitations and folding,
canonicalization, etc.,
since HTTP transfers message-bodies as
Fielding & Reschke
Standards Track
[Page 90]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
payload and, aside from
the "multipart/byteranges" type (Appendix A
of [RFC7233]),
does not interpret the content or any MIME header
lines that might be
contained therein.
Appendix B. Changes from RFC 2616
The primary changes in
this revision have been editorial in nature:
extracting the messaging
syntax and partitioning HTTP semantics into
separate documents for
the core features, conditional requests,
partial requests,
caching, and authentication. The
conformance
language has been revised
to clearly target requirements and the
terminology has been
improved to distinguish payload from
representations and
representations from resources.
A new requirement has
been added that semantics embedded in a URI be
disabled when those
semantics are inconsistent with the request
method, since this is a
common cause of interoperability failure.
An algorithm has been
added for determining if a payload is
associated with a
specific identifier. (Section 3.1.4.1)
The default charset of
ISO-8859-1 for text media types has been
removed; the default is
now whatever the media type definition says.
Likewise, special
treatment of ISO-8859-1 has been removed from the
Accept-Charset header
field. (Section 3.1.1.3
and Section
5.3.3)
The definition of
Content-Location has been changed to no longer
affect the base URI for
resolving relative URI references, due to
poor implementation
support and the undesirable effect of potentially
breaking relative links
in content-negotiated resources.
To be consistent with the
method-neutral parsing algorithm of
[RFC7230],
the definition of GET has been relaxed so that requests
can have a body, even
though a body has no meaning for GET.
Servers are no longer
required to handle all Content-* header fields
and use of Content-Range
has been explicitly banned in PUT requests.
Definition of the CONNECT
method has been moved from [RFC2817] to
this specification. (Section 4.3.6)
The OPTIONS and TRACE
request methods have been defined as being
safe. (Section 4.3.7
and Section
4.3.8)
Fielding & Reschke
Standards Track [Page 91]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
The Expect header field's
extension mechanism has been removed due to
widely-deployed broken
implementations. (Section 5.1.1)
The Max-Forwards header
field has been restricted to the OPTIONS and
TRACE methods;
previously, extension methods could have used it as
well. (Section 5.1.2)
The
"about:blank" URI has been suggested as a value for the Referer
header field when no
referring URI is applicable, which distinguishes
that case from others
where the Referer field is not sent or has been
removed. (Section 5.5.2)
The following status
codes are now cacheable (that is, they can be
stored and reused by a
cache without explicit freshness information
present): 204, 404, 405,
414, 501. (Section 6)
The 201 (Created) status
description has been changed to allow for
the possibility that more
than one resource has been created.
The definition of 203
(Non-Authoritative Information) has been
broadened to include
cases of payload transformations as well.
The set of request
methods that are safe to automatically redirect is
no longer closed; user agents
are able to make that determination
based upon the request
method semantics. The redirect status
codes
301, 302, and 307 no
longer have normative requirements on response
payloads and user
interaction. (Section 6.4)
The status codes 301 and
302 have been changed to allow user agents
to rewrite the method
from POST to GET. (Sections 6.4.2 and 6.4.3)
The description of the
303 (See Other) status code has been changed
to allow it to be cached
if explicit freshness information is given,
and a specific definition
has been added for a 303 response to GET.
The 305 (Use Proxy)
status code has been deprecated due to security
concerns regarding in-band
configuration of a proxy. (Section 6.4.5)
The 400 (Bad Request)
status code has been relaxed so that it isn't
limited to syntax
errors. (Section 6.5.1)
The 426 (Upgrade
Required) status code has been incorporated from
[RFC2817]. (Section 6.5.15)
Fielding & Reschke
Standards Track
[Page 92]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
The target of
requirements on HTTP-date and the Date header field
have been reduced to
those systems generating the date, rather than
all systems sending a
date. (Section 7.1.1)
The syntax of the
Location header field has been changed to allow all
URI references, including
relative references and fragments, along
with some clarifications
as to when use of fragments would not be
appropriate. (Section 7.1.2)
Allow has been
reclassified as a response header field, removing the
option to specify it in a
PUT request. Requirements relating to
the
content of Allow have
been relaxed; correspondingly, clients are not
required to always trust
its value. (Section 7.4.1)
A Method Registry has
been defined. (Section 8.1)
The Status Code Registry
has been redefined by this specification;
previously, it was
defined in Section 7.1
of [RFC2817].
Registration of content
codings has been changed to require IETF
Review. (Section 8.4)
The Content-Disposition
header field has been removed since it is now
defined by [RFC6266].
The Content-MD5 header
field has been removed because it was
inconsistently
implemented with respect to partial responses.
Appendix C. Imported ABNF
The following core rules are included by
reference, as defined in
Appendix B.1 of
[RFC5234]: ALPHA (letters), CR (carriage return),
CRLF (CR LF), CTL
(controls), DIGIT (decimal 0-9), DQUOTE (double
quote), HEXDIG
(hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF
(line feed), OCTET (any
8-bit sequence of data), SP (space), and
VCHAR (any visible
US-ASCII character).
The rules below are
defined in [RFC7230]:
BWS = <BWS, see [RFC7230],
Section 3.2.3>
OWS = <OWS, see [RFC7230],
Section 3.2.3>
RWS = <RWS, see [RFC7230],
Section 3.2.3>
URI-reference =
<URI-reference, see [RFC7230],
Section 2.7>
absolute-URI = <absolute-URI, see [RFC7230],
Section 2.7>
comment = <comment, see [RFC7230],
Section 3.2.6>
field-name = <comment, see [RFC7230],
Section 3.2>
partial-URI = <partial-URI, see [RFC7230],
Section 2.7>
Fielding & Reschke
Standards Track [Page
93]
RFC 7231
HTTP/1.1 Semantics and
Content June 2014
quoted-string =
<quoted-string, see [RFC7230],
Section 3.2.6>
token = <token, see [RFC7230],
Section 3.2.6>
Appendix D. Collected ABNF
In the collected ABNF
below, list rules are expanded as per Section
Accept = [ (
"," / ( media-range [ accept-params ] ) ) *( OWS "," [
OWS ( media-range [
accept-params ] ) ] ) ]
Accept-Charset = *(
"," OWS ) ( ( charset / "*" ) [ weight ] ) *( OWS
"," [ OWS ( (
charset / "*" ) [ weight ] ) ] )
Accept-Encoding = [ (
"," / ( codings [ weight ] ) ) *( OWS "," [ OWS
( codings [ weight ] ) ]
) ]
Accept-Language = *(
"," OWS ) ( language-range [ weight ] ) *( OWS
"," [ OWS (
language-range [ weight ] ) ] )
Allow = [ ( ","
/ method ) *( OWS "," [ OWS method ] ) ]
BWS = <BWS, see [RFC7230],
Section 3.2.3>
Content-Encoding = *(
"," OWS ) content-coding *( OWS "," [ OWS
content-coding ] )
Content-Language = *(
"," OWS ) language-tag *( OWS "," [ OWS
language-tag ] )
Content-Location =
absolute-URI / partial-URI
Content-Type = media-type
Date = HTTP-date
Expect =
"100-continue"
From = mailbox
GMT = %x47.4D.54 ; GMT
HTTP-date = IMF-fixdate /
obs-date
IMF-fixdate = day-name
"," SP date1 SP time-of-day SP GMT
Location = URI-reference
Max-Forwards = 1*DIGIT
OWS = <OWS, see [RFC7230],
Section 3.2.3>
RWS = <RWS, see [RFC7230],
Section 3.2.3>
Referer = absolute-URI /
partial-URI
Retry-After = HTTP-date /
delay-seconds
Fielding & Reschke
Standards Track
[Page 94]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
Server = product *( RWS (
product / comment ) )
URI-reference =
<URI-reference, see [RFC7230],
Section 2.7>
User-Agent = product *(
RWS ( product / comment ) )
Vary = "*" / (
*( "," OWS ) field-name *( OWS "," [ OWS field-name ]
) )
absolute-URI =
<absolute-URI, see [RFC7230],
Section 2.7>
accept-ext = OWS
";" OWS token [ "=" ( token / quoted-string ) ]
accept-params = weight
*accept-ext
asctime-date = day-name
SP date3 SP time-of-day SP year
charset = token
codings = content-coding
/ "identity" / "*"
comment = <comment, see
[RFC7230],
Section 3.2.6>
content-coding = token
date1 = day SP month SP
year
date2 = day "-"
month "-" 2DIGIT
date3 = month SP ( 2DIGIT
/ ( SP DIGIT ) )
day = 2DIGIT
day-name = %x4D.6F.6E ;
Mon
/ %x54.75.65 ; Tue
/ %x57.65.64 ; Wed
/ %x54.68.75 ; Thu
/ %x46.72.69 ; Fri
/ %x53.61.74 ; Sat
/ %x53.75.6E ; Sun
day-name-l =
%x4D.6F.6E.64.61.79 ; Monday
/ %x54.75.65.73.64.61.79
; Tuesday
/
%x57.65.64.6E.65.73.64.61.79 ; Wednesday
/
%x54.68.75.72.73.64.61.79 ; Thursday
/ %x46.72.69.64.61.79 ;
Friday
/
%x53.61.74.75.72.64.61.79 ; Saturday
/ %x53.75.6E.64.61.79 ;
Sunday
delay-seconds = 1*DIGIT
field-name = <comment,
see [RFC7230],
Section 3.2>
hour = 2DIGIT
language-range =
<language-range, see [RFC4647], Section 2.1>
language-tag =
<Language-Tag, see [RFC5646],
Section 2.1>
mailbox = <mailbox,
see [RFC5322], Section 3.4>
media-range = (
"*/*" / ( type "/*" ) / ( type "/" subtype ) ) *(
OWS
";" OWS
parameter )
Fielding & Reschke
Standards Track
[Page 95]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
media-type = type
"/" subtype *( OWS ";" OWS parameter )
method = token
minute = 2DIGIT
month = %x4A.61.6E ; Jan
/ %x46.65.62 ; Feb
/ %x4D.61.72 ; Mar
/ %x41.70.72 ; Apr
/ %x4D.61.79 ; May
/ %x4A.75.6E ; Jun
/ %x4A.75.6C ; Jul
/ %x41.75.67 ; Aug
/ %x53.65.70 ; Sep
/ %x4F.63.74 ; Oct
/ %x4E.6F.76 ; Nov
/ %x44.65.63 ; Dec
obs-date = rfc850-date / asctime-date
parameter = token
"=" ( token / quoted-string )
partial-URI =
<partial-URI, see [RFC7230],
Section 2.7>
product = token [
"/" product-version ]
product-version = token
quoted-string =
<quoted-string, see [RFC7230],
Section 3.2.6>
qvalue = ( "0"
[ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ]
)
rfc850-date = day-name-l
"," SP date2 SP time-of-day SP GMT
second = 2DIGIT
subtype = token
time-of-day = hour
":" minute ":" second
token = <token, see [RFC7230],
Section 3.2.6>
type = token
weight = OWS
";" OWS "q=" qvalue
year = 4DIGIT
Fielding & Reschke
Standards Track
[Page 96]
RFC 7231 HTTP/1.1 Semantics and Content June 2014
Index
1
1xx Informational
(status code class) 50
2
2xx Successful (status
code class) 51
3
3xx Redirection
(status code class) 54
4
4xx Client Error
(status code class) 58
5
5xx Server Error
(status code class) 62
1
100 Continue (status
code) 50
100-continue (expect
value) 34
101 Switching
Protocols (status code) 50
2
200 OK (status code) 51
201 Created (status
code) 52
202 Accepted (status
code) 52
203 Non-Authoritative
Information (status code) 52
204 No Content (status
code) 53
205 Reset Content
(status code) 53
3
300 Multiple Choices
(status code) 55
301 Moved Permanently
(status code) 56
302 Found (status
code) 56
303 See Other (status
code) 57
305 Use Proxy (status
code) 58
306 (Unused) (status
code) 58
307 Temporary Redirect
(status code) 58
4
400 Bad Request
(status code) 58
402 Payment Required
(status code) 59
403 Forbidden (status
code) 59
404 Not Found (status
code) 59
405 Method Not Allowed
(status code) 59
406 Not Acceptable
(status code) 59
408 Request Timeout (status code) 60
409 Conflict (status
code) 60
Fielding & Reschke
Standards Track
[Page 97]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
410 Gone (status
code) 60
411 Length Required
(status code) 61
413 Payload Too Large
(status code) 61
414 URI Too Long
(status code) 61
415 Unsupported Media
Type (status code) 62
417 Expectation Failed
(status code) 62
426 Upgrade Required
(status code) 62
5
500 Internal Server
Error (status code) 63
501 Not Implemented
(status code) 63
502 Bad Gateway
(status code) 63
503 Service
Unavailable (status code) 63
504 Gateway Timeout
(status code) 63
505 HTTP Version Not
Supported (status code) 64
A
Accept header
field 38
Accept-Charset header
field 40
Accept-Encoding header
field 41
Accept-Language header
field 42
Allow header
field 72
C
cacheable 24
compress (content
coding) 11
conditional
request 36
CONNECT method 30
content coding 11
content
negotiation 6
Content-Encoding
header field 12
Content-Language
header field 13
Content-Location
header field 15
Content-Transfer-Encoding header field
89
Content-Type header
field 10
D
Date header field 67
deflate (content
coding) 11
DELETE method 29
E
Expect header
field 34
F
From header field 44
Fielding & Reschke
Standards Track
[Page 98]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
G
GET method 24
Grammar
Accept 38
Accept-Charset 40
Accept-Encoding 41
accept-ext
38
Accept-Language 42
accept-params 38
Allow 72
asctime-date 66
charset 9
codings 41
content-coding 11
Content-Encoding 12
Content-Language 13
Content-Location 15
Content-Type 10
Date 67
date1 65
day 65
day-name 65
day-name-l 65
delay-seconds 69
Expect 34
From 44
GMT 65
hour 65
HTTP-date
65
IMF-fixdate 65
language-range 42
language-tag 13
Location 68
Max-Forwards 36
media-range 38
media-type 8
method 21
minute 65
month 65
obs-date
66
parameter 8
product 46
product-version 46
qvalue 38
Referer 45
Retry-After 69
rfc850-date 66
second 65
Fielding & Reschke
Standards Track
[Page 99]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
Server 73
subtype 8
time-of-day 65
type 8
User-Agent 46
Vary 70
weight
38
year 65
gzip (content
coding) 11
H
HEAD method 25
I
idempotent 23
L
Location header
field 68
M
Max-Forwards header
field 36
MIME-Version header
field 89
O
OPTIONS method 31
P
payload 17
POST method 25
PUT method 26
R
Referer header
field 45
representation 7
Retry-After header
field 69
S
safe 22
selected
representation 7, 71
Server header
field 73
Status Codes Classes
1xx
Informational 50
2xx Successful 51
3xx
Redirection 54
4xx Client
Error 58
5xx Server
Error 62
Fielding & Reschke
Standards Track [Page
100]
RFC 7231 HTTP/1.1 Semantics and
Content June 2014
T
TRACE method 32
U
User-Agent header
field 46
V
Vary header field 70
X
x-compress (content
coding) 11
x-gzip (content
coding) 11
Authors' Addresses
Roy T. Fielding (editor)
Adobe Systems
Incorporated
345 Park Ave
San Jose, CA 95110
USA
EMail: fielding@gbiv.com
URI: http://roy.gbiv.com/
Julian F. Reschke
(editor)
greenbytes GmbH
Hafenweg 16
Muenster, NW 48155
Germany
EMail:
julian.reschke@greenbytes.de
URI: http://greenbytes.de/tech/webdav/
Fielding & Reschke
Standards Track
[Page 101]
