[Next] [Previous] [Up] [Top] [Full Contents] [Search]
5. Request
The Method token indicates the method to be performed on the resource identified by the Request-URI. The method is case-sensitive and extensible.
Method = "GET" | "HEAD" | "PUT" | "POST"
| "DELETE" | "LINK" | "UNLINK"
| extension-method
extension-method = token
The list of methods acceptable by a specific resource can be specified in an "Allow" Entity-Header (Section 7.1.1). However, the client is always notified through the return code of the response whether a method is currently allowed on a specific resource, as this can change dynamically. Servers should return the status code "405 Method Not Allowed" if the method is known by the server but not allowed for the requested resource, and "501 Not Implemented" if the method is unknown or not implemented by the server.
The set of common methods for HTTP/1.0 is described below. Although this set can be easily expanded, additional methods cannot be assumed to share the same semantics for separately extended clients and servers. In order to maintain compatibility, the semantic definition for extension methods should be registered with the IANA [17].
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 changes to a "conditional GET" if the request message includes an If-Modified-Since header field. A conditional GET method requests that the identified resource be transferred only if it has been modified since the date given by the If-Modified-Since header. The algorithm for determining this includes the following cases:
- a)
- If the request would normally result in anything other than a "200 OK" status, or if the passed If-Modified-Since date is invalid, the response is exactly the same as for a normal GET.
- b)
- If the resource has been modified since the If-Modified-Since date, the response is exactly the same as for a normal GET.
- c)
- If the resource has not been modified since the If-Modified-Since date, the server shall return a "304 Not Modified" response.
The conditional GET method is intended to reduce network usage by allowing cached entities to be refreshed without requiring multiple requests or transferring unnecessary data.
5.2.2 HEAD
The HEAD method is identical to GET except that the server must not return any Entity-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 resource identified by the Request-URI without transferring the Entity-Body itself. This method is often used for testing hypertext links for validity, accessibility, and recent modification.
There is no "conditional HEAD" requests analogous to the conditional GET. If an If-Modified-Since header field is included with a HEAD request, it should be ignored.
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:
- Annotation of existing resources;
- Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles;
- Providing a block of data (usually 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 considered to be 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 client can suggest a URI for identifying the new resource by including a URI-header field in the request. However, the server should treat that URI as advisory only and may store the entity under a different URI or without any URI.
The client may apply relationships between the new resource and other existing resources by including Link header fields, as described in Section 7.1.10. The server may use the Link information to perform other operations as a result of the new resource being added. For example, lists and indexes might be updated. However, no mandatory operation is imposed on the origin server. The origin server may also generate its own or additional links to other resources.
A successful POST does not require that the entity be created as a resource on the origin server or made accessible for future reference. That is, 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 the allocated URI, all applicable Link header fields, and an entity (preferably of type "text/html") which describes the status of the request and refers to the new resource.
5.2.4 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 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, the "200 OK" response 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 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 as an appendage. 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 requestor of a PUT knows what URI is intended and the receiver must not attempt to apply the request to some other resource. If the receiver desires that the request be applied to a different URI, it must send a "301 Moved Permanently" response; the requestor may then make its own decision regarding whether or not to redirect the request.
The client can create or modify relationships between the enclosed entity and other existing resources by including Link header fields, as described in Section 7.1.10. As with POST, the server may use the Link information to perform other operations as a result of the request. However, no mandatory operation is imposed on the origin server. The origin server may generate its own or additional links to other resources.
The actual method for determining how the resource is placed, and what happens to its predecessor, is defined entirely by the origin server. If version control is implemented by the origin server, the Version and Derived-From header fields should be used to help identify and control revisions to a resource.
5.2.5 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).
5.2.6 LINK
The LINK method establishes one or more Link relationships between the existing resource identified by the Request-URI and other existing resources. The difference between LINK and other methods allowing links to be established between resources is that the LINK method does not allow any Entity-Body to be sent in the request and does not result in the creation of new resources.
5.2.7 UNLINK
The UNLINK method removes one or more Link relationships from the existing resource identified by the Request-URI. These relationships may have been established using the LINK method or by any other method supporting the Link header. The removal of a link to a resource does not imply that the resource ceases to exist or becomes inaccessible for future references.
T. Berners-Lee, R. T. Fielding, H. Frystyk Nielsen - 12 MAR 95
[Next] [Previous] [Up] [Top] [Full Contents] [Search]
Generated with CERN WebMaker