HTTP OPTIONS And Self-Describing APIs 

Lets the client discover what it may do to a resource Potentially describes how a client may use a resource Does not imply resource action or retrieval Response is not cacheable What is the OPTIONS method? 

The Request 

Use OPTIONS just like any other verb Provide any pertinent headers, e.g. authorization Request body (e.g. JSON payload) is optional HTTP/1.1 200 OK Allow: GET,HEAD,OPTIONS Content-Type: application/json {"tacos": ["fish", "steak", "veggie"]} OPTIONS /food/mexican HTTP/1.1 Accept: application/json Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 

* (asterisk) corresponds to general server capabilities The response body may be apropos for a “site map” (HATEOAS!) HTTP/1.1 200 OK Allow: GET,HEAD,OPTIONS Content-Type: application/json {"tacos": ["fish", "steak", "veggie"]} OPTIONS * HTTP/1.1 Accept: application/json Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 

The Response 

Should respond with a 200 OK for a valid resource HTTP/1.1 200 OK Allow: GET,HEAD,OPTIONS Content-Type: application/json {"tacos": ["fish", "steak", "veggie"]} HTTP/1.1 200 OK Allow: GET,HEAD,OPTIONS Content-Type: application/json {"tacos": { "types": ["fish", "steak", "veggie"] }} response code 

Indicate any optional features for the resource Allow: HTTP methods this resource allows headers HTTP/1.1 200 OK Allow: GET,HEAD,OPTIONS Content-Type: application/json {"tacos": ["fish", "steak", "veggie"]} HTTP/1.1 200 OK Allow: GET,HEAD,OPTIONS Content-Type: application/json {"tacos": { "types": ["fish", "steak", "veggie"] }} 

HTTP/1.1 200 OK Allow: GET,HEAD,OPTIONS Content-Type: application/json {"tacos": { "types": ["fish", "steak", "veggie"] }} Optional, may include additional communication information for resource, i.e. documentation body 

HTTP/1.1 200 OK Allow: DELETE,GET,HEAD,OPTIONS,PUT Content-Type: application/json {"tacos": { "types": ["fish", "steak", "veggie", "shrimp"] }} Response may change according to request. For example, allowing more methods after authenticating mutability 

Who’s (not) using it? Hint: basically everybody 

OPTIONS /users/zacstewart HTTP/1.1 Host: api.github.com Accept: */* HTTP/1.1 500 Internal Server Error GitHub curl -v -X OPTIONS https://api.github.com/users/zacstewart 

wtf? 

Twitter curl -v -X OPTIONS https://api.twitter.com/1/statuses/ public_timeline.json OPTIONS /1/statuses/ public_timeline.json HTTP/1.1 Host: api.twitter.com Accept: */* HTTP/1.1 403 Forbidden 

@dache 

How they could be 

Service Overview (Site Map) Response body can indicate where your service’s resources live A good place to serve an ATOM service document, WADL schema, etc... OPTIONS * HTTP/1.1 

Resource Description OPTIONS /repos/:user/:repo/issues/:number / HTTP/1.1 Permissions: the Allow header conveys how a user may use the resource Documentation describing how to use each of the available methods and what kind of output to expect can reside in the response body Partial WADL schema or JSON equivalent 

Okay. So? 

Increased Discoverability Better for API-crawling robots to index your web service Better for other web services that make use of your web service Means increased resilience 

Less Glue Code Web services with an established convention for understanding one another means you spend less time making them play Horses will thank you. And unicorns. 

Finally, some Ruby! 

Rails As part of resourceful routes, extend CRUD to include member and collection options methods in the controller. But, until then... 

zacstewart github.com/ twitter.com/ .com } https://github.com/RestDoc http://www.w3.org/Submission/wadl/