RFC 2068
Hypertext Transfer Protocol -- HTTP/1.1
9.3 GET The GET method means retrieve whatever information (in the form of an entity) is identified by the Request-URI. If the Request-URI refers to a data-producing process, it is the produced data which shall be returned as the entity in the response and not the source text of the process, unless that text happens to be the output of the process. The semantics of the GET method change to a "conditional GET" if the request message includes an If-Modified-Since, If-Unmodified-Since, If-Match, If-None-Match, or If-Range header field. A conditional GET method requests that the entity be transferred only under the circumstances described by the conditional header field(s). The conditional GET method is intended to reduce unnecessary network usage by allowing cached entities to be refreshed without requiring multiple requests or transferring data already held by the client. The semantics of the GET method change to a "partial GET" if the request message includes a Range header field. A partial GET requests that only part of the entity be transferred, as described in section 14.36. The partial GET method is intended to reduce unnecessary network usage by allowing partially-retrieved entities to be completed without transferring data already held by the client. The response to a GET request is cachable if and only if it meets the requirements for HTTP caching described in section 13. 9.4 HEAD The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. The metainformation contained in the HTTP headers in response to a HEAD request SHOULD be identical to the information sent in response to a GET request. This method can be used for obtaining metainformation about the entity implied by the request without transferring the entity-body itself. This method is often used for testing hypertext links for validity, accessibility, and recent modification. The response to a HEAD request may be cachable in the sense that the information contained in the response may be used to update a previously cached entity from that resource. If the new field values indicate that the cached entity differs from the current entity (as would be indicated by a change in Content-Length, Content-MD5, ETag or Last-Modified), then the cache MUST treat the cache entry as stale.
9.5 POST The POST method is used to request that the destination server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line. POST is designed to allow a uniform method to cover the following functions: o Annotation of existing resources; o Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles; o Providing a block of data, such as the result of submitting a form, to a data-handling process; o Extending a database through an append operation. The actual function performed by the POST method is determined by the server and is usually dependent on the Request-URI. The posted entity is subordinate to that URI in the same way that a file is subordinate to a directory containing it, a news article is subordinate to a newsgroup to which it is posted, or a record is subordinate to a database. The action performed by the POST method might not result in a resource that can be identified by a URI. In this case, either 200 (OK) or 204 (No Content) is the appropriate response status, depending on whether or not the response includes an entity that describes the result. If a resource has been created on the origin server, the response SHOULD be 201 (Created) and contain an entity which describes the status of the request and refers to the new resource, and a Location header (see section 14.30). Responses to this method are not cachable, unless the response includes appropriate Cache-Control or Expires header fields. However, the 303 (See Other) response can be used to direct the user agent to retrieve a cachable resource. POST requests must obey the message transmission requirements set out in section 8.2.
9.6 PUT The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server. If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI. If a new resource is created, the origin server MUST inform the user agent via the 201 (Created) response. If an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request. If the resource could not be created or modified with the Request-URI, an appropriate error response SHOULD be given that reflects the nature of the problem. The recipient of the entity MUST NOT ignore any Content-* (e.g. Content-Range) headers that it does not understand or implement and MUST return a 501 (Not Implemented) response in such cases. If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries should be treated as stale. Responses to this method are not cachable. The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. That resource may be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource. If the server desires that the request be applied to a different URI, it MUST send a 301 (Moved Permanently) response; the user agent MAY then make its own decision regarding whether or not to redirect the request. A single resource MAY be identified by many different URIs. For example, an article may have a URI for identifying "the current version" which is separate from the URI identifying each particular version. In this case, a PUT request on a general URI may result in several other URIs being defined by the origin server. HTTP/1.1 does not define how a PUT method affects the state of an origin server. PUT requests must obey the message transmission requirements set out in section 8.2.
9.7 DELETE The DELETE method requests that the origin server delete the resource identified by the Request-URI. This method MAY be overridden by human intervention (or other means) on the origin server. The client cannot be guaranteed that the operation has been carried out, even if the status code returned from the origin server indicates that the action has been completed successfully. However, the server SHOULD not indicate success unless, at the time the response is given, it intends to delete the resource or move it to an inaccessible location. A successful response SHOULD be 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has not yet been enacted, or 204 (No Content) if the response is OK but does not include an entity. If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries should be treated as stale. Responses to this method are not cachable. 9.8 TRACE The TRACE method is used to invoke a remote, application-layer loop- back of the request message. The final recipient of the request SHOULD reflect the message received back to the client as the entity-body of a 200 (OK) response. The final recipient is either the origin server or the first proxy or gateway to receive a Max-Forwards value of zero (0) in the request (see section 14.31). A TRACE request MUST NOT include an entity. 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 14.44) 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. If successful, the response SHOULD contain the entire request message in the entity-body, with a Content-Type of "message/http". Responses to this method MUST NOT be cached. 10 Status Code Definitions Each Status-Code is described below, including a description of which method(s) it can follow and any metainformation required in the response.
10.1 Informational 1xx This class of status code indicates a provisional response, consisting only of the Status-Line and optional headers, and is terminated by an empty line. Since HTTP/1.0 did not define any 1xx status codes, servers MUST NOT send a 1xx response to an HTTP/1.0 client except under experimental conditions. 10.1.1 100 Continue The client may continue with its request. This interim response is used to inform the client that the initial part of the request has been received and has not yet been rejected by the server. The client SHOULD continue by sending the remainder of the request or, if the request has already been completed, ignore this response. The server MUST send a final response after the request has been completed. 10.1.2 101 Switching Protocols The server understands and is willing to comply with the client's request, via the Upgrade message header field (section 14.41), for a change in the application protocol being used on this connection. The server will switch protocols to those defined by the response's Upgrade header field immediately after the empty line which terminates the 101 response. The protocol should only be switched when it is advantageous to do so. For example, switching to a newer version of HTTP is advantageous over older versions, and switching to a real-time, synchronous protocol may be advantageous when delivering resources that use such features. 10.2 Successful 2xx This class of status code indicates that the client's request was successfully received, understood, and accepted. 10.2.1 200 OK The request has succeeded. The information returned with the response is dependent on the method used in the request, for example: GET an entity corresponding to the requested resource is sent in the response; HEAD the entity-header fields corresponding to the requested resource are sent in the response without any message-body;
POST an entity describing or containing the result of the action;
TRACE an entity containing the request message as received by the end
server.
10.2.2 201 Created
The request has been fulfilled and resulted in a new resource being
created. The newly created resource can be referenced by the URI(s)
returned in the entity of the response, with the most specific URL
for the resource given by a Location header field. The origin server
MUST create the resource before returning the 201 status code. If the
action cannot be carried out immediately, the server should respond
with 202 (Accepted) response instead.
10.2.3 202 Accepted
The request has been accepted for processing, but the processing has
not been completed. The request MAY or MAY NOT eventually be acted
upon, as it MAY be disallowed when processing actually takes place.
There is no facility for re-sending a status code from an
asynchronous operation such as this.
The 202 response is intentionally non-committal. 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 entity returned with this
response SHOULD include an indication of the request's current status
and either a pointer to a status monitor or some estimate of when the
user can expect the request to be fulfilled.
10.2.4 203 Non-Authoritative Information
The returned metainformation in the entity-header is not the
definitive set as available from the origin server, but is gathered
from a local or a third-party copy. The set presented MAY be a subset
or superset of the original version. For example, including local
annotation information about the resource MAY result in a superset of
the metainformation known by the origin server. Use of this response
code is not required and is only appropriate when the response would
otherwise be 200 (OK).
10.2.5 204 No Content
The server has fulfilled the request but there is no new information
to send back. If the client is a user agent, it SHOULD NOT change its
document view from that which caused the request to be sent. This
response is primarily intended to allow input for actions to take place without causing a change to the user agent's active document view. The response MAY include new metainformation in the form of entity-headers, which SHOULD apply to the document currently in the user agent's active view. The 204 response MUST NOT include a message-body, and thus is always terminated by the first empty line after the header fields. 10.2.6 205 Reset Content The server has fulfilled the request and the user agent SHOULD reset the document view which caused the request to be sent. This response is primarily intended to allow input for actions to take place via user input, followed by a clearing of the form in which the input is given so that the user can easily initiate another input action. The response MUST NOT include an entity. 10.2.7 206 Partial Content The server has fulfilled the partial GET request for the resource. The request must have included a Range header field (section 14.36) indicating the desired range. The response MUST include either a Content-Range header field (section 14.17) indicating the range included with this response, or a multipart/byteranges Content-Type including Content-Range fields for each part. If multipart/byteranges is not used, the Content-Length header field in the response MUST match the actual number of OCTETs transmitted in the message-body. A cache that does not support the Range and Content-Range headers MUST NOT cache 206 (Partial) responses. 10.3 Redirection 3xx This class of status code indicates that further action needs to be taken by the user agent in order to fulfill the request. The action required MAY be carried out by the user agent without interaction with the user if and only if the method used in the second request is GET or HEAD. A user agent SHOULD NOT automatically redirect a request more than 5 times, since such redirections usually indicate an infinite loop.
10.3.1 300 Multiple Choices The requested resource corresponds to any one of a set of representations, each with its own specific location, and agent- driven negotiation information (section 12) is being provided so that the user (or user agent) can select a preferred representation and redirect its request to that location. Unless it was a HEAD request, the response SHOULD include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content- Type header field. Depending upon the format and the capabilities of the user agent, selection of the most appropriate choice may be performed automatically. However, this specification does not define any standard for such automatic selection. If the server has a preferred choice of representation, it SHOULD include the specific URL for that representation in the Location field; user agents MAY use the Location field value for automatic redirection. This response is cachable unless indicated otherwise. 10.3.2 301 Moved Permanently The requested resource has been assigned a new permanent URI and any future references to this resource SHOULD be done using one of the returned URIs. Clients with link editing capabilities SHOULD automatically re-link references to the Request-URI to one or more of the new references returned by the server, where possible. This response is cachable unless indicated otherwise. If the new URI is a location, its URL SHOULD be given by the Location field in the response. Unless the request method was HEAD, the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s). If the 301 status code is received in response to a request other than GET or HEAD, the user agent MUST NOT automatically redirect the request unless it can be confirmed by the user, since this might change the conditions under which the request was issued. Note: When automatically redirecting a POST request after receiving a 301 status code, some existing HTTP/1.0 user agents will erroneously change it into a GET request.
10.3.3 302 Moved Temporarily The requested resource resides temporarily under a different URI. Since the redirection may be altered on occasion, the client SHOULD continue to use the Request-URI for future requests. This response is only cachable if indicated by a Cache-Control or Expires header field. If the new URI is a location, its URL SHOULD be given by the Location field in the response. Unless the request method was HEAD, the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s). If the 302 status code is received in response to a request other than GET or HEAD, the user agent MUST NOT automatically redirect the request unless it can be confirmed by the user, since this might change the conditions under which the request was issued. Note: When automatically redirecting a POST request after receiving a 302 status code, some existing HTTP/1.0 user agents will erroneously change it into a GET request. 10.3.4 303 See Other The response to the request can be found under a different URI and SHOULD be retrieved using a GET method on that resource. This method exists primarily to allow the output of a POST-activated script to redirect the user agent to a selected resource. The new URI is not a substitute reference for the originally requested resource. The 303 response is not cachable, but the response to the second (redirected) request MAY be cachable. If the new URI is a location, its URL SHOULD be given by the Location field in the response. Unless the request method was HEAD, the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s). 10.3.5 304 Not Modified If the client has performed a conditional GET request and access is allowed, but the document has not been modified, the server SHOULD respond with this status code. The response MUST NOT contain a message-body.
The response MUST include the following header fields:
o Date
o ETag and/or Content-Location, if the header would have been sent in
a 200 response to the same request
o Expires, Cache-Control, and/or Vary, if the field-value might
differ from that sent in any previous response for the same variant
If the conditional GET used a strong cache validator (see section
13.3.3), the response SHOULD NOT include other entity-headers.
Otherwise (i.e., the conditional GET used a weak validator), the
response MUST NOT include other entity-headers; this prevents
inconsistencies between cached entity-bodies and updated headers.
If a 304 response indicates an entity not currently cached, then the
cache MUST disregard the response and repeat the request without the
conditional.
If a cache uses a received 304 response to update a cache entry, the
cache MUST update the entry to reflect any new field values given in
the response.
The 304 response MUST NOT include a message-body, and thus is always
terminated by the first empty line after the header fields.
10.3.6 305 Use Proxy
The requested resource MUST be accessed through the proxy given by
the Location field. The Location field gives the URL of the proxy.
The recipient is expected to repeat the request via the proxy.
10.4 Client Error 4xx
The 4xx class of status code is intended for cases in which the
client seems to have erred. Except when responding to a HEAD request,
the server SHOULD include an entity 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 entity to the user.
Note: If the client is sending data, a server implementation using
TCP should be careful to ensure that the client acknowledges
receipt of the packet(s) containing the response, before the server
closes the input connection. If the client continues sending data
to the server after the close, the server's TCP stack will send a
reset packet to the client, which may erase the client's
unacknowledged input buffers before they can be read and
interpreted by the HTTP application.
10.4.1 400 Bad Request
The request could not be understood by the server due to malformed
syntax. The client SHOULD NOT repeat the request without
modifications.
10.4.2 401 Unauthorized
The request requires user authentication. The response MUST include a
WWW-Authenticate header field (section 14.46) containing a challenge
applicable to the requested resource. The client MAY repeat the
request with a suitable Authorization header field (section 14.8). If
the request already included Authorization credentials, then the 401
response indicates that authorization has been refused for those
credentials. If the 401 response contains the same challenge as the
prior response, and the user agent has already attempted
authentication at least once, then the user SHOULD be presented the
entity that was given in the response, since that entity MAY include
relevant diagnostic information. HTTP access authentication is
explained in section 11.
10.4.3 402 Payment Required
This code is reserved for future use.
10.4.4 403 Forbidden
The server understood the request, but is refusing to fulfill it.
Authorization will not help and the request SHOULD NOT be repeated.
If the request method was not HEAD and the server wishes to make
public why the request has not been fulfilled, it SHOULD describe the
reason for the refusal in the entity. This status code is commonly
used when the server does not wish to reveal exactly why the request
has been refused, or when no other response is applicable.
10.4.5 404 Not Found
The server has not found anything matching the Request-URI. No
indication is given of whether the condition is temporary or
permanent.
If the server does not wish to make this information available to the client, the status code 403 (Forbidden) can be used instead. The 410 (Gone) status code SHOULD be used if the server knows, through some internally configurable mechanism, that an old resource is permanently unavailable and has no forwarding address. 10.4.6 405 Method Not Allowed The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. The response MUST include an Allow header containing a list of valid methods for the requested resource. 10.4.7 406 Not Acceptable The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request. Unless it was a HEAD request, the response SHOULD include an entity containing a list of available entity characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. Depending upon the format and the capabilities of the user agent, selection of the most appropriate choice may be performed automatically. However, this specification does not define any standard for such automatic selection. Note: HTTP/1.1 servers are allowed to return responses which are not acceptable according to the accept headers sent in the request. In some cases, this may even be preferable to sending a 406 response. User agents are encouraged to inspect the headers of an incoming response to determine if it is acceptable. If the response could be unacceptable, a user agent SHOULD temporarily stop receipt of more data and query the user for a decision on further actions. 10.4.8 407 Proxy Authentication Required This code is similar to 401 (Unauthorized), but indicates that the client MUST first authenticate itself with the proxy. The proxy MUST return a Proxy-Authenticate header field (section 14.33) containing a challenge applicable to the proxy for the requested resource. The client MAY repeat the request with a suitable Proxy-Authorization header field (section 14.34). HTTP access authentication is explained in section 11.
10.4.9 408 Request Timeout The client did not produce a request within the time that the server was prepared to wait. The client MAY repeat the request without modifications at any later time. 10.4.10 409 Conflict The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. The response body SHOULD include enough information for the user to recognize the source of the conflict. Ideally, the response entity would include enough information for the user or user agent to fix the problem; however, that may not be possible and is not required. Conflicts are most likely to occur in response to a PUT request. If versioning is being used and the entity being PUT includes changes to a resource which conflict with those made by an earlier (third-party) request, the server MAY use the 409 response to indicate that it can't complete the request. In this case, the response entity SHOULD contain a list of the differences between the two versions in a format defined by the response Content-Type. 10.4.11 410 Gone The requested resource is no longer available at the server and no forwarding address is known. This condition SHOULD be considered permanent. Clients with link editing capabilities SHOULD delete references to the Request-URI after user approval. If the server does not know, or has no facility to determine, whether or not the condition is permanent, the status code 404 (Not Found) SHOULD be used instead. This response is cachable unless indicated otherwise. 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 working at the 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.
10.4.12 411 Length Required The server refuses to accept the request without a defined Content- Length. 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. 10.4.13 412 Precondition Failed The precondition given in one or more of the request-header fields evaluated to false when it was tested on the server. This response code allows the client to place preconditions on the current resource metainformation (header field data) and thus prevent the requested method from being applied to a resource other than the one intended. 10.4.14 413 Request Entity Too Large The server is refusing to process a request because the request entity 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 include a Retry- After header field to indicate that it is temporary and after what time the client may try again. 10.4.15 414 Request-URI Too Long The server is refusing to service the request because the Request-URI 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 URL "black hole" of redirection (e.g., a redirected URL prefix that points to a suffix of itself), or when the server is under attack by a client attempting to exploit security holes present in some servers using fixed-length buffers for reading or manipulating the Request-URI. 10.4.16 415 Unsupported Media Type The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.
10.5 Server Error 5xx Response status codes beginning with the digit "5" indicate cases in which the server is aware that it has erred or is incapable of performing the request. Except when responding to a HEAD request, the server SHOULD include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. User agents SHOULD display any included entity to the user. These response codes are applicable to any request method. 10.5.1 500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request. 10.5.2 501 Not Implemented 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. 10.5.3 502 Bad Gateway The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request. 10.5.4 503 Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay may be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response. Note: The existence of the 503 status code does not imply that a server must use it when becoming overloaded. Some servers may wish to simply refuse the connection. 10.5.5 504 Gateway Timeout The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server it accessed in attempting to complete the request.
10.5.6 505 HTTP Version Not Supported The server does not support, or refuses to support, the HTTP protocol version 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 3.1, other than with this error message. The response SHOULD contain an entity describing why that version is not supported and what other protocols are supported by that server. 11 Access Authentication HTTP provides a simple challenge-response authentication mechanism which MAY be used by a server to challenge a client request and by a client to provide authentication information. It uses an extensible, case-insensitive token to identify the authentication scheme, followed by a comma-separated list of attribute-value pairs which carry the parameters necessary for achieving authentication via that scheme. auth-scheme = token auth-param = token "=" quoted-string The 401 (Unauthorized) response message is used by an origin server to challenge the authorization of a user agent. This response MUST include a WWW-Authenticate header field containing at least one challenge applicable to the requested resource. challenge = auth-scheme 1*SP realm *( "," auth-param ) realm = "realm" "=" realm-value realm-value = quoted-string The realm attribute (case-insensitive) is required for all authentication schemes which issue a challenge. The realm value (case-sensitive), in combination with the canonical root URL (see section 5.1.2) of the server being accessed, defines the protection space. These realms allow the protected resources on a server to be partitioned into a set of protection spaces, each with its own authentication scheme and/or authorization database. The realm value is a string, generally assigned by the origin server, which may have additional semantics specific to the authentication scheme. A user agent that wishes to authenticate itself with a server-- usually, but not necessarily, after receiving a 401 or 411 response- -MAY do so by including an Authorization header field with the request. The Authorization field value consists of credentials
containing the authentication information of the user agent for the
realm of the resource being requested.
credentials = basic-credentials
| auth-scheme #auth-param
The domain over which credentials can be automatically applied by a
user agent is determined by the protection space. If a prior request
has been authorized, the same credentials MAY be reused for all other
requests within that protection space for a period of time determined
by the authentication scheme, parameters, and/or user preference.
Unless otherwise defined by the authentication scheme, a single
protection space cannot extend outside the scope of its server.
If the server does not wish to accept the credentials sent with a
request, it SHOULD return a 401 (Unauthorized) response. The response
MUST include a WWW-Authenticate header field containing the (possibly
new) challenge applicable to the requested resource and an entity
explaining the refusal.
The HTTP protocol does not restrict applications to this simple
challenge-response mechanism for access authentication. Additional
mechanisms MAY be used, such as encryption at the transport level or
via message encapsulation, and with additional header fields
specifying authentication information. However, these additional
mechanisms are not defined by this specification.
Proxies MUST be completely transparent regarding user agent
authentication. That is, they MUST forward the WWW-Authenticate and
Authorization headers untouched, and follow the rules found in
section 14.8.
HTTP/1.1 allows a client to pass authentication information to and
from a proxy via the Proxy-Authenticate and Proxy-Authorization
headers.
11.1 Basic Authentication Scheme
The "basic" authentication scheme is based on the model that the user
agent must authenticate itself with a user-ID and a password for each
realm. The realm value should be considered an opaque string which
can only be compared for equality with other realms on that server.
The server will service the request only if it can validate the
user-ID and password for the protection space of the Request-URI.
There are no optional authentication parameters.
Upon receipt of an unauthorized request for a URI within the
protection space, the server MAY respond with a challenge like the
following:
WWW-Authenticate: Basic realm="WallyWorld"
where "WallyWorld" is the string assigned by the server to identify
the protection space of the Request-URI.
To receive authorization, the client sends the userid and password,
separated by a single colon (":") character, within a base64 encoded
string in the credentials.
basic-credentials = "Basic" SP basic-cookie
basic-cookie = <base64 [7] encoding of user-pass,
except not limited to 76 char/line>
user-pass = userid ":" password
userid = *<TEXT excluding ":">
password = *TEXT
Userids might be case sensitive.
If the user agent wishes to send the userid "Aladdin" and password
"open sesame", it would use the following header field:
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
See section 15 for security considerations associated with Basic
authentication.
11.2 Digest Authentication Scheme
A digest authentication for HTTP is specified in RFC 2069 [32].
12 Content Negotiation
Most HTTP responses include an entity which contains information for
interpretation by a human user. Naturally, it is desirable to supply
the user with the "best available" entity corresponding to the
request. Unfortunately for servers and caches, not all users have
the same preferences for what is "best," and not all user agents are
equally capable of rendering all entity types. For that reason, HTTP
has provisions for several mechanisms for "content negotiation" --
the process of selecting the best representation for a given response
when there are multiple representations available.
Note: This is not called "format negotiation" because the alternate
representations may be of the same media type, but use different
capabilities of that type, be in different languages, etc.
Any response containing an entity-body MAY be subject to negotiation,
including error responses.
There are two kinds of content negotiation which are possible in
HTTP: server-driven and agent-driven negotiation. These two kinds of
negotiation are orthogonal and thus may be used separately or in
combination. One method of combination, referred to as transparent
negotiation, occurs when a cache uses the agent-driven negotiation
information provided by the origin server in order to provide
server-driven negotiation for subsequent requests.
12.1 Server-driven Negotiation
If the selection of the best representation for a response is made by
an algorithm located at the server, it is called server-driven
negotiation. Selection is based on the available representations of
the response (the dimensions over which it can vary; e.g. language,
content-coding, etc.) and the contents of particular header fields in
the request message or on other information pertaining to the request
(such as the network address of the client).
Server-driven negotiation is advantageous when the algorithm for
selecting from among the available representations is difficult to
describe to the user agent, or when the server desires to send its
"best guess" to the client 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, the user agent MAY include request header fields (Accept,
Accept-Language, Accept-Encoding, etc.) which describe its
preferences for such a response.
Server-driven negotiation has disadvantages:
1. 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?).
2. 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 violation of
the user's privacy. 3. It complicates the implementation of an origin server and the algorithms for generating responses to a request. 4. It may limit a public cache's ability to use the same response for multiple user's requests. HTTP/1.1 includes the following request-header fields for enabling server-driven negotiation through description of user agent capabilities and user preferences: Accept (section 14.1), Accept- Charset (section 14.2), Accept-Encoding (section 14.3), Accept- Language (section 14.4), and User-Agent (section 14.42). However, an origin server is not limited to these dimensions and MAY vary the response based on any aspect of the request, including information outside the request-header fields or within extension header fields not defined by this specification. HTTP/1.1 origin servers MUST include an appropriate Vary header field (section 14.43) in any cachable response based on server-driven negotiation. The Vary header field describes the dimensions over which the response might vary (i.e. the dimensions over which the origin server picks its "best guess" response from multiple representations). HTTP/1.1 public caches MUST recognize the Vary header field when it is included in a response and obey the requirements described in section 13.6 that describes the interactions between caching and content negotiation. 12.2 Agent-driven Negotiation With agent-driven negotiation, selection of the best representation for a response is performed by the user agent after receiving an initial response from the origin server. Selection is based on a list of the available representations of the response included within the header fields (this specification reserves the field-name Alternates, as described in appendix 19.6.2.1) or entity-body of the initial response, with each representation identified by its own URI. Selection from among the representations may be performed automatically (if the user agent is capable of doing so) or manually by the user selecting from a generated (possibly hypertext) menu. Agent-driven 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.
Agent-driven negotiation suffers from the disadvantage of needing a second request to obtain the best alternate representation. This second request is only efficient when caching is used. In addition, this specification does not define any mechanism for supporting automatic selection, though it also does not prevent any such mechanism from being developed as an extension and used within HTTP/1.1. HTTP/1.1 defines the 300 (Multiple Choices) and 406 (Not Acceptable) status codes for enabling agent-driven negotiation when the server is unwilling or unable to provide a varying response using server-driven negotiation. 12.3 Transparent Negotiation Transparent negotiation is a combination of both server-driven and agent-driven negotiation. When a cache is supplied with a form of the list of available representations of the response (as in agent-driven negotiation) and the dimensions of variance are completely understood by the cache, then the cache becomes capable of performing server- driven negotiation on behalf of the origin server for subsequent requests on that resource. Transparent negotiation has the advantage of distributing the negotiation work that would otherwise be required of the origin server and also removing the second request delay of agent-driven negotiation when the cache is able to correctly guess the right response. This specification does not define any mechanism for transparent negotiation, though it also does not prevent any such mechanism from being developed as an extension and used within HTTP/1.1. An HTTP/1.1 cache performing transparent negotiation MUST include a Vary header field in the response (defining the dimensions of its variance) if it is cachable to ensure correct interoperation with all HTTP/1.1 clients. The agent-driven negotiation information supplied by the origin server SHOULD be included with the transparently negotiated response. 13 Caching in HTTP HTTP is typically used for distributed information systems, where performance can be improved by the use of response caches. The HTTP/1.1 protocol includes a number of elements intended to make caching work as well as possible. Because these elements are inextricable from other aspects of the protocol, and because they interact with each other, it is useful to describe the basic caching design of HTTP separately from the detailed descriptions of methods,
headers, response codes, etc.
Caching would be useless if it did not significantly improve
performance. The goal of caching in HTTP/1.1 is to eliminate the need
to send requests in many cases, and to eliminate the need to send
full responses in many other cases. The former reduces the number of
network round-trips required for many operations; we use an
"expiration" mechanism for this purpose (see section 13.2). The
latter reduces network bandwidth requirements; we use a "validation"
mechanism for this purpose (see section 13.3).
Requirements for performance, availability, and disconnected
operation require us to be able to relax the goal of semantic
transparency. The HTTP/1.1 protocol allows origin servers, caches,
and clients to explicitly reduce transparency when necessary.
However, because non-transparent operation may confuse non-expert
users, and may be incompatible with certain server applications (such
as those for ordering merchandise), the protocol requires that
transparency be relaxed
o only by an explicit protocol-level request when relaxed by client
or origin server
o only with an explicit warning to the end user when relaxed by cache
or client
Therefore, the HTTP/1.1 protocol provides these important elements:
1. Protocol features that provide full semantic transparency when this
is required by all parties.
2. Protocol features that allow an origin server or user agent to
explicitly request and control non-transparent operation.
3. Protocol features that allow a cache to attach warnings to
responses that do not preserve the requested approximation of
semantic transparency.
A basic principle is that it must be possible for the clients to
detect any potential relaxation of semantic transparency.
Note: The server, cache, or client implementer may be faced with
design decisions not explicitly discussed in this specification. If
a decision may affect semantic transparency, the implementer ought
to err on the side of maintaining transparency unless a careful and
complete analysis shows significant benefits in breaking
transparency.
13.1.1 Cache Correctness
A correct cache MUST respond to a request with the most up-to-date
response held by the cache that is appropriate to the request (see
sections 13.2.5, 13.2.6, and 13.12) which meets one of the following
conditions:
1. It has been checked for equivalence with what the origin server
would have returned by revalidating the response with the origin
server (section 13.3);
2. It is "fresh enough" (see section 13.2). In the default case, this
means it meets the least restrictive freshness requirement of the
client, server, and cache (see section 14.9); if the origin server
so specifies, it is the freshness requirement of the origin server
alone.
3. It includes a warning if the freshness demand of the client or the
origin server is violated (see section 13.1.5 and 14.45).
4. It is an appropriate 304 (Not Modified), 305 (Proxy Redirect), or
error (4xx or 5xx) response message.
If the cache can not communicate with the origin server, then a
correct cache SHOULD respond as above if the response can be
correctly served from the cache; if not it MUST return an error or
warning indicating that there was a communication failure. If a cache receives a response (either an entire response, or a 304 (Not Modified) response) that it would normally forward to the requesting client, and the received response is no longer fresh, the cache SHOULD forward it to the requesting client without adding a new Warning (but without removing any existing Warning headers). A cache SHOULD NOT attempt to revalidate a response simply because that response became stale in transit; this might lead to an infinite loop. An user agent that receives a stale response without a Warning MAY display a warning indication to the user. 13.1.2 Warnings Whenever a cache returns a response that is neither first-hand nor "fresh enough" (in the sense of condition 2 in section 13.1.1), it must attach a warning to that effect, using a Warning response- header. This warning allows clients to take appropriate action. Warnings may be used for other purposes, both cache-related and otherwise. The use of a warning, rather than an error status code, distinguish these responses from true failures. Warnings are always cachable, because they never weaken the transparency of a response. This means that warnings can be passed to HTTP/1.0 caches without danger; such caches will simply pass the warning along as an entity-header in the response. Warnings are assigned numbers between 0 and 99. This specification defines the code numbers and meanings of each currently assigned warnings, allowing a client or cache to take automated action in some (but not all) cases. Warnings also carry a warning text. The text may be in any appropriate natural language (perhaps based on the client's Accept headers), and include an optional indication of what character set is used. Multiple warnings may be attached to a response (either by the origin server or by a cache), including multiple warnings with the same code number. For example, a server may provide the same warning with texts in both English and Basque. When multiple warnings are attached to a response, it may not be practical or reasonable to display all of them to the user. This version of HTTP does not specify strict priority rules for deciding which warnings to display and in what order, but does suggest some heuristics.
The Warning header and the currently defined warnings are described in section 14.45. 13.1.3 Cache-control Mechanisms The basic cache mechanisms in HTTP/1.1 (server-specified expiration times and validators) are implicit directives to caches. In some cases, a server or client may need to provide explicit directives to the HTTP caches. We use the Cache-Control header for this purpose. The Cache-Control header allows a client or server to transmit a variety of directives in either requests or responses. These directives typically override the default caching algorithms. As a general rule, if there is any apparent conflict between header values, the most restrictive interpretation should be applied (that is, the one that is most likely to preserve semantic transparency). However, in some cases, Cache-Control directives are explicitly specified as weakening the approximation of semantic transparency (for example, "max-stale" or "public"). The Cache-Control directives are described in detail in section 14.9. 13.1.4 Explicit User Agent Warnings Many user agents make it possible for users to override the basic caching mechanisms. For example, the user agent may allow the user to specify that cached entities (even explicitly stale ones) are never validated. Or the user agent might habitually add "Cache-Control: max-stale=3600" to every request. The user should have to explicitly request either non-transparent behavior, or behavior that results in abnormally ineffective caching. If the user has overridden the basic caching mechanisms, the user agent should explicitly indicate to the user whenever this results in the display of information that might not meet the server's transparency requirements (in particular, if the displayed entity is known to be stale). Since the protocol normally allows the user agent to determine if responses are stale or not, this indication need only be displayed when this actually happens. The indication need not be a dialog box; it could be an icon (for example, a picture of a rotting fish) or some other visual indicator. If the user has overridden the caching mechanisms in a way that would abnormally reduce the effectiveness of caches, the user agent should continually display an indication (for example, a picture of currency in flames) so that the user does not inadvertently consume excess resources or suffer from excessive latency.
13.1.5 Exceptions to the Rules and Warnings In some cases, the operator of a cache may choose to configure it to return stale responses even when not requested by clients. This decision should not be made lightly, but may be necessary for reasons of availability or performance, especially when the cache is poorly connected to the origin server. Whenever a cache returns a stale response, it MUST mark it as such (using a Warning header). This allows the client software to alert the user that there may be a potential problem. It also allows the user agent to take steps to obtain a first-hand or fresh response. For this reason, a cache SHOULD NOT return a stale response if the client explicitly requests a first-hand or fresh one, unless it is impossible to comply for technical or policy reasons. 13.1.6 Client-controlled Behavior While the origin server (and to a lesser extent, intermediate caches, by their contribution to the age of a response) are the primary source of expiration information, in some cases the client may need to control a cache's decision about whether to return a cached response without validating it. Clients do this using several directives of the Cache-Control header. A client's request may specify the maximum age it is willing to accept of an unvalidated response; specifying a value of zero forces the cache(s) to revalidate all responses. A client may also specify the minimum time remaining before a response expires. Both of these options increase constraints on the behavior of caches, and so cannot further relax the cache's approximation of semantic transparency. A client may also specify that it will accept stale responses, up to some maximum amount of staleness. This loosens the constraints on the caches, and so may violate the origin server's specified constraints on semantic transparency, but may be necessary to support disconnected operation, or high availability in the face of poor connectivity. 13.2 Expiration Model 13.2.1 Server-Specified Expiration HTTP caching works best when caches can entirely avoid making requests to the origin server. The primary mechanism for avoiding requests is for an origin server to provide an explicit expiration time in the future, indicating that a response may be used to satisfy subsequent requests. In other words, a cache can return a fresh
response without first contacting the server. Our expectation is that servers will assign future explicit expiration times to responses in the belief that the entity is not likely to change, in a semantically significant way, before the expiration time is reached. This normally preserves semantic transparency, as long as the server's expiration times are carefully chosen. The expiration mechanism applies only to responses taken from a cache and not to first-hand responses forwarded immediately to the requesting client. If an origin server wishes to force a semantically transparent cache to validate every request, it may assign an explicit expiration time in the past. This means that the response is always stale, and so the cache SHOULD validate it before using it for subsequent requests. See section 14.9.4 for a more restrictive way to force revalidation. If an origin server wishes to force any HTTP/1.1 cache, no matter how it is configured, to validate every request, it should use the "must-revalidate" Cache-Control directive (see section 14.9). Servers specify explicit expiration times using either the Expires header, or the max-age directive of the Cache-Control header. An expiration time cannot be used to force a user agent to refresh its display or reload a resource; its semantics apply only to caching mechanisms, and such mechanisms need only check a resource's expiration status when a new request for that resource is initiated. See section 13.13 for explanation of the difference between caches and history mechanisms. 13.2.2 Heuristic Expiration Since origin servers do not always provide explicit expiration times, HTTP caches typically assign heuristic expiration times, employing algorithms that use other header values (such as the Last-Modified time) to estimate a plausible expiration time. The HTTP/1.1 specification does not provide specific algorithms, but does impose worst-case constraints on their results. Since heuristic expiration times may compromise semantic transparency, they should be used cautiously, and we encourage origin servers to provide explicit expiration times as much as possible.
13.2.3 Age Calculations In order to know if a cached entry is fresh, a cache needs to know if its age exceeds its freshness lifetime. We discuss how to calculate the latter in section 13.2.4; this section describes how to calculate the age of a response or cache entry. In this discussion, we use the term "now" to mean "the current value of the clock at the host performing the calculation." Hosts that use HTTP, but especially hosts running origin servers and caches, should use NTP [28] or some similar protocol to synchronize their clocks to a globally accurate time standard. Also note that HTTP/1.1 requires origin servers to send a Date header with every response, giving the time at which the response was generated. We use the term "date_value" to denote the value of the Date header, in a form appropriate for arithmetic operations. HTTP/1.1 uses the Age response-header to help convey age information between caches. The Age header value is the sender's estimate of the amount of time since the response was generated at the origin server. In the case of a cached response that has been revalidated with the origin server, the Age value is based on the time of revalidation, not of the original response. In essence, the Age value is the sum of the time that the response has been resident in each of the caches along the path from the origin server, plus the amount of time it has been in transit along network paths. We use the term "age_value" to denote the value of the Age header, in a form appropriate for arithmetic operations. A response's age can be calculated in two entirely independent ways: 1. now minus date_value, if the local clock is reasonably well synchronized to the origin server's clock. If the result is negative, the result is replaced by zero. 2. age_value, if all of the caches along the response path implement HTTP/1.1. Given that we have two independent ways to compute the age of a response when it is received, we can combine these as corrected_received_age = max(now - date_value, age_value) and as long as we have either nearly synchronized clocks or all-
HTTP/1.1 paths, one gets a reliable (conservative) result.
Note that this correction is applied at each HTTP/1.1 cache along the
path, so that if there is an HTTP/1.0 cache in the path, the correct
received age is computed as long as the receiving cache's clock is
nearly in sync. We don't need end-to-end clock synchronization
(although it is good to have), and there is no explicit clock
synchronization step.
Because of network-imposed delays, some significant interval may pass
from the time that a server generates a response and the time it is
received at the next outbound cache or client. If uncorrected, this
delay could result in improperly low ages.
Because the request that resulted in the returned Age value must have
been initiated prior to that Age value's generation, we can correct
for delays imposed by the network by recording the time at which the
request was initiated. Then, when an Age value is received, it MUST
be interpreted relative to the time the request was initiated, not
the time that the response was received. This algorithm results in
conservative behavior no matter how much delay is experienced. So, we
compute:
corrected_initial_age = corrected_received_age
+ (now - request_time)
where "request_time" is the time (according to the local clock) when
the request that elicited this response was sent.
Summary of age calculation algorithm, when a cache receives a
response:
/*
* age_value
* is the value of Age: header received by the cache with
* this response.
* date_value
* is the value of the origin server's Date: header
* request_time
* is the (local) time when the cache made the request
* that resulted in this cached response
* response_time
* is the (local) time when the cache received the
* response
* now
* is the current (local) time
*/
apparent_age = max(0, response_time - date_value);
corrected_received_age = max(apparent_age, age_value);
response_delay = response_time - request_time;
corrected_initial_age = corrected_received_age + response_delay;
resident_time = now - response_time;
current_age = corrected_initial_age + resident_time;
When a cache sends a response, it must add to the
corrected_initial_age the amount of time that the response was
resident locally. It must then transmit this total age, using the Age
header, to the next recipient cache.
Note that a client cannot reliably tell that a response is first-
hand, but the presence of an Age header indicates that a response
is definitely not first-hand. Also, if the Date in a response is
earlier than the client's local request time, the response is
probably not first-hand (in the absence of serious clock skew).
13.2.4 Expiration Calculations
In order to decide whether a response is fresh or stale, we need to
compare its freshness lifetime to its age. The age is calculated as
described in section 13.2.3; this section describes how to calculate
the freshness lifetime, and to determine if a response has expired.
In the discussion below, the values can be represented in any form
appropriate for arithmetic operations.
We use the term "expires_value" to denote the value of the Expires
header. We use the term "max_age_value" to denote an appropriate
value of the number of seconds carried by the max-age directive of
the Cache-Control header in a response (see section 14.10.
The max-age directive takes priority over Expires, so if max-age is
present in a response, the calculation is simply:
freshness_lifetime = max_age_value
Otherwise, if Expires is present in the response, the calculation is:
freshness_lifetime = expires_value - date_value
Note that neither of these calculations is vulnerable to clock skew,
since all of the information comes from the origin server.
If neither Expires nor Cache-Control: max-age appears in the
response, and the response does not include other restrictions on
caching, the cache MAY compute a freshness lifetime using a
heuristic. If the value is greater than 24 hours, the cache must
attach Warning 13 to any response whose age is more than 24 hours if
such warning has not already been added.
Also, if the response does have a Last-Modified time, the heuristic
expiration value SHOULD be no more than some fraction of the interval
since that time. A typical setting of this fraction might be 10%.
The calculation to determine if a response has expired is quite
simple:
response_is_fresh = (freshness_lifetime > current_age)
13.2.5 Disambiguating Expiration Values
Because expiration values are assigned optimistically, it is possible
for two caches to contain fresh values for the same resource that are
different.
If a client performing a retrieval receives a non-first-hand response
for a request that was already fresh in its own cache, and the Date
header in its existing cache entry is newer than the Date on the new
response, then the client MAY ignore the response. If so, it MAY
retry the request with a "Cache-Control: max-age=0" directive (see
section 14.9), to force a check with the origin server.
If a cache has two fresh responses for the same representation with
different validators, it MUST use the one with the more recent Date
header. This situation may arise because the cache is pooling
responses from other caches, or because a client has asked for a
reload or a revalidation of an apparently fresh cache entry.
13.2.6 Disambiguating Multiple Responses
Because a client may be receiving responses via multiple paths, so
that some responses flow through one set of caches and other
responses flow through a different set of caches, a client may
receive responses in an order different from that in which the origin
server sent them. We would like the client to use the most recently
generated response, even if older responses are still apparently
fresh.
Neither the entity tag nor the expiration value can impose an
ordering on responses, since it is possible that a later response
intentionally carries an earlier expiration time. However, the
HTTP/1.1 specification requires the transmission of Date headers on
every response, and the Date values are ordered to a granularity of
one second.
When a client tries to revalidate a cache entry, and the response it
receives contains a Date header that appears to be older than the one
for the existing entry, then the client SHOULD repeat the request
unconditionally, and include
Cache-Control: max-age=0
to force any intermediate caches to validate their copies directly
with the origin server, or
Cache-Control: no-cache
to force any intermediate caches to obtain a new copy from the origin
server.
If the Date values are equal, then the client may use either response
(or may, if it is being extremely prudent, request a new response).
Servers MUST NOT depend on clients being able to choose
deterministically between responses generated during the same second,
if their expiration times overlap.
(page 81 continued on part 4)
