Home

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.

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

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

4. 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).

5. 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. One implementation using jQuery is to handle all forms and check for the form[method] attribute.

$('body').on('submit', 'form', function(event) {
    var $form = $(this),
        method = $form.attr('method'),
        action = $form.attr('action');

    // Process GET and POST methods as normal..
    if (!method || /(get|post)/i.test(method)) {
        return;
    }

    // Prevent default behavior and kick off a request
    // with the non-standard method.
    event.preventDefault();

    // The implementation is somewhat up in the air. An approach
    // could be to try and process the response as JSON (or whatever)
    // assuming a {"location": <href>} on success. Otherwise it would
    // be assumed to be an error and the fully rendered HTML page would
    // be the response. The sections of the document would be replaced
    // with the new response thus displaying the updated state of the form.
    var xhr = $.ajax({
        type: method,
        url: action,
        // This could be anything.. depending on what the server
        // accepts.
        data: $form.serialize(),
        // This does not need to be synchronous, but makes it _feel_
        // more like a normal request from the user's perspective.
        async: false,
        success: function(resp) {
            try {
                window.location.replace(JSON.parse(resp).location)
            } catch (e) {
                // This may need to be more specific if there are more than
                // one form on the page with the same action. Also there may
                // be more elements on the page that need to be replaced; updated
                // accordingly. (Note the andSelf() accounts for top-level elements
                // in the document)
                var $newform = $(resp).andSelf().find('form[action="'+ action + '"]');
                $form.replaceWith($newform);
            }
        }
    }); 
});

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.