Skip to content
This repository has been archived by the owner on Feb 21, 2020. It is now read-only.

Home

Jump to bottom
bruth edited this page Dec 29, 2012 · 8 revisions

Implementation Considerations

Required Methods

Section 2 of the HTTP/1.1 specification states:

The methods GET and HEAD MUST be supported by all general-purpose servers. All other methods are OPTIONAL;

The HEAD handler is already implemented on the Resource class, but requires the GET handler to be implemented. Although not required, the OPTIONS handler is also implemented.

Resource Identification

Response representations should follow the rules outlined in Section 5.1.

5.1 Identifying the Resource Associated with a Representation

It is sometimes necessary to determine an identifier for the resource associated with a representation.

An HTTP request representation, when present, is always associated with an anonymous (i.e., unidentified) resource.

In the common case, an HTTP response is a representation of the target resource (see Section 4.3 of [Part1]). However, this is not always the case. To determine the URI of the resource a response is associated with, the following rules are used (with the first applicable one being selected):

  1. If the response status code is 200 or 203 and the request method was GET, the response payload is a representation of the target resource.
  1. If the response status code is 204, 206, or 304 and the request method was GET or HEAD, the response payload is a partial representation of the target resource.
  1. If the response has a Content-Location header field, and that URI is the same as the effective request URI, the response payload is a representation of the target resource.
  1. If the response has a Content-Location header field, and that URI is not the same as the effective request URI, then the response asserts that its payload is a representation of the resource identified by the Content-Location URI. However, such an assertion cannot be trusted unless it can be verified by other means (not defined by HTTP).
  1. Otherwise, the response is a representation of an anonymous (i.e., unidentified) resource.

Safeness and Idempotency

Section 6.1 defines that GET, HEAD, OPTIONS and TRACE are considered safe methods, thus ensure the implementation of these methods do not have any side effects (see this article). In addition to the safe methods, PUT and DELETE are considered idempotent which means subsequent identical requests to the same resource does not result it different responses to the client.

Request Body

Request bodies on GET, HEAD, OPTIONS, and DELETE requests are ignored. The HTTP spec does not define any semantics surrounding this situation.

The Mysterious POST Method

Typical uses of POST requests are described in Section 6.5, but in most cases should be assumed by clients as black box, neither safe nor idempotent. If updating an existing resource, it is more appropriate to use PUT. Likewise with deleting a resource, the DELETE method should be used.

The one caveat here is dealing HTML forms where only GET and POST requests are supported. A workaround would be to use JavaScript and send a XMLHttpRequest request with the correct method.

Without using JavaScript, a hidden form parameter could be used to specify the real method this request represents. On the server-side, the parameter can be checked and the request can be routed to the appropriate handler.

2xx Responses

Section 7.2.1 defines that GET, HEAD, POST, and 'TRACE' should have a payload for status code of 200 OK. If not supplied, a different 2xx code may be more appropriate.

Clone this wiki locally