RESTful API methods; HEAD & OPTIONS
Solution 1
As per: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
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.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.
Solution 2
OPTIONS
method returns info about API (methods/content type)
HEAD
method returns info about resource (version/length/type)
Server response
OPTIONS
HTTP/1.1 200 OK
Allow: GET,HEAD,POST,OPTIONS,TRACE
Content-Type: text/html; charset=UTF-8
Date: Wed, 08 May 2013 10:24:43 GMT
Content-Length: 0
HEAD
HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: text/html; charset=UTF-8
Date: Wed, 08 May 2013 10:12:29 GMT
ETag: "780602-4f6-4db31b2978ec0"
Last-Modified: Thu, 25 Apr 2013 16:13:23 GMT
Content-Length: 1270
OPTIONS
Identifying which HTTP methods a resource supports, e.g. can we DELETE it or update it via a PUT?HEAD
Checking whether a resource has changed. This is useful when maintaining a cached version of a resourceHEAD
Retrieving metadata about the resource, e.g. its media type or its size, before making a possibly costly retrievalHEAD, OPTIONS
Testing whether a resource exists and is accessible. For example, validating user-submitted links in an application
Here is nice and concise article about how HEAD and OPTIONS fit into RESTful architecture.
Solution 3
OPTIONS tells you things such as "What methods are allowed for this resource".
HEAD gets the HTTP header you would get if you made a GET request, but without the body. This lets the client determine caching information, what content-type would be returned, what status code would be returned. The availability is only a small part of it.
Comments
-
Dan Lugg about 3 years
I'm writing a RESTful API module for an application in PHP, and I'm a bit mixed on the verbs
HEAD
andOPTIONS
.OPTIONS
Used to retrieve the available HTTP verbs for a given resource?HEAD
Used to determine whether a given resource is available?
If someone could clarify* these verbs, that would be much appreciated.
* The clarification was with respect to RESTful API architectures re-purposing HTTP verbs. I've since come to the realization that both
HEAD
andOPTIONS
should not be re-purposed, and instead behave predictably as any HTTP application should. Oh, how we grow in 2 years. -
Dan Lugg almost 13 yearsThanks @sdolgy for the comprehensive quote; however, in practice do (should) many successful RESTful API modules adhere to all of these HTTP standards, or is there an acceptable slim response for these operations? Not out of laziness, but merely curiosity; I'll likely implement everything necessary to adhere.
-
Dan Lugg almost 13 yearsThanks @Quentin;
OPTIONS
was what I figured, and such implementation will be easy with my existing approach. As per sdolgy's RFC quote,OPTIONS
defines no standard in the format. Is it assumed that the response format is the same as other responses? (eg; JSON, XML, etc.) -
sdolgy almost 13 yearsif you are building your own, which i assume you are, you should try to maintain some alignment with documented standards to make your life easier ... and that of people consuming your api... don't follow Microsoft. RFC's are a good thing to align with
-
Dan Lugg almost 13 yearsThanks @sdolgy. Having briefed the linked doc, I noticed at the end the
CONNECT
verb. Would it be a poor choice to consume that method for RESTful authentication? -
sdolgy almost 13 yearsNot sure that was the intended purpose "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]). " ... may be helpful to post another question on one of the stackexchange.com sites about it...
-
Dan Lugg almost 13 yearsThanks @sdolgy. I understand that wasn't the intended use, however that functionality will not be used in this application at any point, and it would be a nice verb to use for resource based authentication. I'll look into it, and ask around if necessary. Thanks a ton for your insight :)
-
Gordon almost 13 years@Tomcat Quoting the RFC: "Content negotiation MAY be used to select the appropriate response format." In other words: the response should be what the Request asked for in the header.
-
Steve Buzonas about 10 years@DanLugg Your application may not be utilizing
CONNECT
in a manner of SSL tunneling, but imagine what would happen if a consumer of your application had a proxy that implementedCONNECT
in the way it was specified in the RFC, the requests might not get passed on to your application. -
Dan Lugg about 10 years@SteveBuzonas Absolutely; thankfully, I've long abandoned the idea of repurposing methods :-)
-
Steve Buzonas about 10 years@DanLugg I'm currently considering leveraging an
OPTIONS
body as mentioned by future extensions opposed to havingrel
links in the entity body and providing them when requested withOPTIONS
-
David Betz over 8 yearsAll you did was copy the docs. That's not helping. Give commentary. Provide a TL;DR summary. Give an example. The other answer is an actual helpful answers.
-
Todd Menier over 6 yearsGreat answer, too bad it will pay the late-to-the-party penalty. The copy-pasted accepted answer doesn't even begin to address these verbs' place in a RESTful architecture specifically.
-
kolobok over 5 yearsYour link is dead. Here's its last snapshot: web.archive.org/web/20160528151316/https://…