HTTP Headers

9 Method Definitions

The set of common methods for HTTP/1.1 is defined below. Although this set can be expanded, additional methods cannot be assumed to share the same semantics for separately extended clients and servers.

The Host request-header field (section 14.23) MUST accompany all HTTP/1.1 requests.

9.1 Safe and Idempotent Methods

9.1.1 Safe Methods

Implementors should be aware that the software represents the user in their interactions over the Internet, and should be careful to allow the user to be aware of any actions they might take which may have an unexpected significance to themselves or others.

In particular, the convention has been established that the GET and HEAD methods SHOULD NOT have the significance of taking an action other than retrieval. These methods ought to be considered "safe". This allows user agents to represent other methods, such as POST, PUT and DELETE, in a special way, so that the user is made aware of the fact that a possibly unsafe action is being requested.

Naturally, it is not possible to ensure that the server does not generate side-effects as a result of performing a GET request; in fact, some dynamic resources consider that a feature. The important distinction here is that the user did not request the side-effects, so therefore cannot be held accountable for them.

9.1.2 Idempotent Methods

Methods can also have the property of "idempotence" in that (aside from error or expiration issues) the side-effects of N > 0 identical requests is the same as for a single request. The methods GET, HEAD, PUT and DELETE share this property. Also, the methods OPTIONS and TRACE SHOULD NOT have side effects, and so are inherently idempotent.

However, it is possible that a sequence of several requests is non- idempotent, even if all of the methods executed in that sequence are idempotent. (A sequence is idempotent if a single execution of the entire sequence always yields a result that is not changed by a reexecution of all, or part, of that sequence.) For example, a sequence is non-idempotent if its result depends on a value that is later modified in the same sequence.

A sequence that never has side effects is idempotent, by definition (provided that no concurrent operations are being executed on the same set of resources).

9.2 OPTIONS

The OPTIONS method represents a request for information about the communication options available on the request/response chain identified by the Request-URI. This method allows the client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval.

Responses to this method are not cacheable.

If the OPTIONS request includes an entity-body (as indicated by the presence of Content-Length or Transfer-Encoding), then the media type MUST be indicated by a Content-Type field. Although this specification does not define any use for such a body, future extensions to HTTP might use the OPTIONS body to make more detailed queries on the server. A server that does not support such an extension MAY discard the request body.

If the Request-URI is an asterisk ("*"), the OPTIONS request is intended to apply 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 compliance (or lack thereof).

If the Request-URI is not an asterisk, the OPTIONS request applies only to the options that are available when communicating with that resource.

A 200 response SHOULD include any header fields that indicate optional features implemented by the server and applicable to that resource (e.g., Allow), possibly including extensions not defined by this specification. The response body, if any, SHOULD also include information about the communication options. The format for such a

body is not defined by this specification, but might be defined by future extensions to HTTP. Content negotiation MAY be used to select the appropriate response format. If no response body is included, the response MUST include a Content-Length field with a field-value of "0".

The Max-Forwards request-header field MAY be used to target a specific proxy in the request chain. When a proxy receives an OPTIONS request on an absoluteURI for which request forwarding is permitted, the proxy MUST check for a Max-Forwards field. If the Max-Forwards field-value is zero ("0"), the proxy MUST NOT forward the message; instead, the proxy SHOULD respond with its own communication options. If the Max-Forwards field-value is an integer greater than zero, the proxy MUST decrement the field-value when it forwards the request. If no Max-Forwards field is present in the request, then the forwarded request MUST NOT include a Max-Forwards field.

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.35. 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 cacheable if and only if it meets the requirements for HTTP caching described in section 13.

See section 15.1.3 for security considerations when used for forms.

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 cacheable 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 origin 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:

      - Annotation of existing resources; 

      - Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles; 

      - Providing a block of data, such as the result of submitting a form, to a data-handling process; 

      - 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 cacheable, 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 cacheable resource.

POST requests MUST obey the message transmission requirements set out in section 8.2.

See section 15.1.3 for security considerations.

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 cacheable.

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 might 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 might 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 might 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.

Unless otherwise specified for a particular entity-header, the entity-headers in the PUT request SHOULD be applied to the resource created or modified by the PUT.

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 action has been enacted but the response 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 cacheable.

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.45) 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 the request is valid, 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.

9.9 CONNECT

This specification reserves the method name CONNECT for use with a proxy that can dynamically switch to being a tunnel (e.g. SSL tunneling [44]).

List of HTTP Response Status Codes

1xx Info / Informational

HTTP_INFO - Request received, continuing process.

Indicates a provisional response, consisting only of the Status-Line and optional headers, and is terminated by an empty line.

• 100 Continue - HTTP_CONTINUE
• 101 Switching Protocols - HTTP_SWITCHING_PROTOCOLS
• 102 Processing - HTTP_PROCESSING

2xx Success / OK

HTTP_SUCCESS - The action was successfully received, understood, and accepted.

Indicates that the client's request was successfully received, understood, and accepted.

• 200 OK - HTTP_OK
• 201 Created - HTTP_CREATED
• 202 Accepted - HTTP_ACCEPTED
• 203 Non-Authoritative Information - HTTP_NON_AUTHORITATIVE
• 204 No Content - HTTP_NO_CONTENT
• 205 Reset Content - HTTP_RESET_CONTENT
• 206 Partial Content - HTTP_PARTIAL_CONTENT
• 207 Multi-Status - HTTP_MULTI_STATUS

3xx Redirect

HTTP_REDIRECT - The client must take additional action to complete the request.

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.

• 300 Multiple Choices - HTTP_MULTIPLE_CHOICES
• 301 Moved Permanently - HTTP_MOVED_PERMANENTLY
• 302 Found - HTTP_MOVED_TEMPORARILY
• 303 See Other - HTTP_SEE_OTHER
• 304 Not Modified - HTTP_NOT_MODIFIED
• 305 Use Proxy - HTTP_USE_PROXY
• 306 unused - UNUSED
• 307 Temporary Redirect - HTTP_TEMPORARY_REDIRECT

4xx Client Error

HTTP_CLIENT_ERROR - The request contains bad syntax or cannot be fulfilled.

Indicates case where 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.

• 400 Bad Request - HTTP_BAD_REQUEST
• 401 Authorization Required - HTTP_UNAUTHORIZED
• 402 Payment Required - HTTP_PAYMENT_REQUIRED
• 403 Forbidden - HTTP_FORBIDDEN
• 404 Not Found - HTTP_NOT_FOUND
• 405 Method Not Allowed - HTTP_METHOD_NOT_ALLOWED
• 406 Not Acceptable - HTTP_NOT_ACCEPTABLE
• 407 Proxy Authentication Required - HTTP_PROXY_AUTHENTICATION_REQUIRED
• 408 Request Time-out - HTTP_REQUEST_TIME_OUT
• 409 Conflict - HTTP_CONFLICT
• 410 Gone - HTTP_GONE
• 411 Length Required - HTTP_LENGTH_REQUIRED
• 412 Precondition Failed - HTTP_PRECONDITION_FAILED
• 413 Request Entity Too Large - HTTP_REQUEST_ENTITY_TOO_LARGE
• 414 Request-URI Too Large - HTTP_REQUEST_URI_TOO_LARGE
• 415 Unsupported Media Type - HTTP_UNSUPPORTED_MEDIA_TYPE
• 416 Requested Range Not Satisfiable - HTTP_RANGE_NOT_SATISFIABLE
• 417 Expectation Failed - HTTP_EXPECTATION_FAILED
• 418 unused - UNUSED
• 419 unused - UNUSED
• 420 unused - UNUSED
• 421 unused - UNUSED
• 422 Unprocessable Entity - HTTP_UNPROCESSABLE_ENTITY
• 423 Locked - HTTP_LOCKED
• 424 Failed Dependency - HTTP_FAILED_DEPENDENCY
• 425 No code - HTTP_NO_CODE
• 426 Upgrade Required - HTTP_UPGRADE_REQUIRED

5xx Server Error

HTTP_SERVER_ERROR - The server failed to fulfill an apparently valid request.

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.

• 500 Internal Server Error - HTTP_INTERNAL_SERVER_ERROR
• 501 Method Not Implemented - HTTP_NOT_IMPLEMENTED
• 502 Bad Gateway - HTTP_BAD_GATEWAY
• 503 Service Temporarily Unavailable - HTTP_SERVICE_UNAVAILABLE
• 504 Gateway Time-out - HTTP_GATEWAY_TIME_OUT
• 505 HTTP Version Not Supported - HTTP_VERSION_NOT_SUPPORTED
• 506 Variant Also Negotiates - HTTP_VARIANT_ALSO_VARIES
• 507 Insufficient Storage - HTTP_INSUFFICIENT_STORAGE
• 508 unused - UNUSED
• 509 unused - UNUSED
• 510 Not Extended - HTTP_NOT_EXTENDED

Helpful HTTP Links

1. HTTP specification, Section 10
2. TLS Upgrade within HTTP specification, Section 4
3. HTTP Status Code Registry
4. WebDAV specification, Section 11
5. IANA registry
6. Adobe Flash status code definitions (ie 408)
7. Microsoft Internet Information Server Status Codes and Sub-Codes
8. httplint
9. HTTP Headers, brief intro.
10. Common User-Agent Issues

DRP

"The HTTP Distribution and Replication Protocol"

DupSup

"Duplicate Suppression in HTTP"

EARL Schema

"Evaluation and Report Language (EARL) 1.0 Schema"

EDD

"An exploration of dynamic documents"

EdgeArch

"Edge Architecture Specification"

HttpClient

Jakarta Commons HttpClient

HTML4

"HTML 4.01 Specification"

JEPI

"White Paper: Joint Electronic Payment Initiative"

ObjectHeaders

"Object Header lines in HTTP"

OPS-OverHTTP

"Implementation of OPS Over HTTP"

OPTIONS messages

"Specification of HTTP/1.1 OPTIONS messages"

P3P

"The Platform for Privacy Preferences 1.0 (P3P1.0) Specification"

PEP

"PEP - an Extension Mechanism for HTTP"

PICSLabels

"PICS Label Distribution Label Syntax and Communication Protocols, Version 1.1"

Proxy Notification

"Notification for Proxy Caches"

RDF

"Resource Description Framework (RDF): Concepts and Abstract Syntax"

RDF-PRIMER

RDF Primer

RFC2068

"Hypertext Transfer Protocol -- HTTP/1.1"

RFC2109

"HTTP State Management Mechanism"

RFC2183

"Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field"

RFC2227

"Simple Hit-Metering and Usage-Limiting for HTTP"

RFC2295

"Transparent Content Negotiation in HTTP"

RFC2310

"The Safe Response Header Field"

RFC2324

"Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0)"

RFC2397

"The 'data' URL scheme"

RFC2518

"HTTP Extensions for Distributed Authoring -- WEBDAV"

RFC2616

"Hypertext Transfer Protocol -- HTTP/1.1"

RFC2617

"HTTP Authentication: Basic and Digest Access Authentication"

RFC2660

"The Secure HyperText Transfer Protocol"

RFC2774

"An HTTP Extension Framework"

RFC2965

"HTTP State Management Mechanism"

RFC3229

"Delta encoding in HTTP"

RFC3230

"Instance Digests in HTTP"

RFC3253

"Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning)"

RFC3648

"Web Distributed Authoring and Versioning (WebDAV) Ordered Collections Protocol"

RFC3986

"Uniform Resource Identifier (URI): Generic Syntax"

RFC4229

"HTTP Header Field Registrations"

SOAP1.1

"Simple Object Access Protocol (SOAP) 1.1"

UA Attributes

"User-Agent Display Attributes Headers"

WIRE

"WIRE - W3 Identifier Resolution Extensions"