HTTP OPTIONS Method And Self-Describing APIs

Slide from my presentation at the ATLRUG on using the HTTP OPTIONS method making APIs more restful.

Transcript

1. HTTP OPTIONS And Self-Describing APIs
2. 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?
3. The Request
4. 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==
5. * (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==
6. The Response
7. 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
8. 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"] }}
9. 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
10. 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
11. Who’s (not) using it? Hint: basically everybody
12. 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
13. wtf?
14. 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
15. @dache
16. How they could be
17. 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
18. 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
19. Okay. So?
20. 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
21. 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.
22. Finally, some Ruby!
23. Rails As part of resourceful routes, extend CRUD to include member and collection options methods in the controller. But, until then...
24. zacstewart github.com/ twitter.com/ .com } https://github.com/RestDoc http://www.w3.org/Submission/wadl/