
The HTTP OPTIONS method and potential for self-describing RESTful APIs - eloisius
http://zacstewart.com/2012/04/14/http-options-method.html
======
po
If you look at the Django REST Framework project you can see this kind of
behavior by default. For example:

<http://rest.ep.io/pygments/>

Notice the OPTIONS button on the top right of the browse-able interface. For
example:

$ curl -X OPTIONS <http://rest.ep.io/pygments/>

{"fields": { "lexer": "ChoiceField", "code": "CharField", "style":
"ChoiceField", "linenos": "BooleanField", "title": "CharField"}, "parses":
["application/json", "application/x-www-form-urlencoded", "multipart/form-
data", "application/xml", "application/yaml"], "renders": ["application/json",
"application/json-p", "text/html", "application/xhtml+xml", "text/plain",
"application/xml", "application/yaml"], "name": "Pygments Root",
"description": "\nThis example demonstrates a simple RESTful Web API around
the awesome pygments library.\nThis top level resource is used to create
highlighted code snippets, and to list all the existing code snippets.\n" }

~~~
eloisius
Awesome! I had no idea Django was doing this already.

~~~
wahnfrieden
It doesn't, this is the name of the project: "Django REST Framework".
<https://github.com/tomchristie/django-rest-framework> :) It deserves more
attention, it's put together well.

~~~
eloisius
Oh, nice.

------
pornel
That is a way to make non-REST API be more like REST.

REST APIs _must_ be self-describing from the start. Those kinds of responses
should be sent for GET requests!

This is a must-read clarification from Roy, as most "REST" APIs are less
RESTful than HTML pages built on top of them:

[http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hyperte...](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven)

~~~
eloisius
Sure. I'm not so interested in arguing about the nuances of what REST really
is. Even Leonard Richardson gracefully sidesteps the arguments by talking
about resource oriented architecture.

The part the interestes me most is documenting the parameters so that web
services can better understand how to work with each other, instead of someone
like me pouring over the docs and writing mundane glue code to tie Twitter
search features into a service.

~~~
detst
Check out Google's API Discovery Service[1] and a video from the 2010 I/O
Conference[2]. It may not be the best basis for developing a RESTful standard
but there's some good stuff there. I especially like how they demonstrate
building an API in that video. I'd like to see some open source projects built
around this concept (instead we keep seeing similar services that aren't open,
often incomplete and unusable).

[1] <https://developers.google.com/discovery/>

[2] <http://www.youtube.com/watch?v=nyu5ZxGUfgs> (~35:30 is where they
actually demonstrate building an API)

------
bobwaycott
I have for quite some time wanted to see self-describing
information/functionality akin to WSDLs for JSON-based web services/APIs.

There's something quite nice about being able to have a program intelligently
build up knowledge of how to interact with an API, and be able to build a set
of objects from a definition to facilitate that interaction. It's a serious
weakness in non-XML APIs.

Full disclosure: I particularly do not like XML-based web services, so please
don't misread this as a cheap shot at JSON APIs. I prefer JSON, but
programming against APIs would be so much nicer if there were a WSDL for JSON
APIs.

------
_walkermatt
I was thinking a little today about self documenting web APIs in a similar
vein to command line tools. An example of web service APIs that currently
expose capabilities in a machine readable manner are the OGC Web Map and Web
Feature Services (WMS, WFS) which accept a GET with a request parameter of
GetCapabilities and return service metadata as XML.

------
taf2
Web browsers will send an OPTIONS request when you try to send an xhr to a
different domain. See the Mozilla post on this:
[http://hacks.mozilla.org/2009/07/cross-site-
xmlhttprequest-w...](http://hacks.mozilla.org/2009/07/cross-site-
xmlhttprequest-with-cors/)

~~~
jtheory
Yes; the info that returns is in headers, though, which could work just the
same even if the OPTIONS response also includes REST action details in the
body and/or other headers.

------
richbradshaw
Funnily enough I saw this for the first time today when doing an XHR to a
different domain and was intrigued. Amazing how even with tools/tech you use
every day, you can still learn new things!

------
lgierth
It would be really interesting to see this in combination with JSON-LD for
linking (meta)data.

<http://json-ld.org>

------
andrewaylett
The OP says almost no-one uses it, but as a concrete (admittedly non-RESTful)
example of one of the few users, Subversion does use OPTIONS.

~~~
kelnos
Pretty sure Subversion's HTTP access "inherits" the use of OPTIONS from its
WebDAV roots, actually.

------
xefer
Anything worthy of a document should have its own URL. OPTIONS could
potentially be used to provide that URL:

[http://lists.w3.org/Archives/Public/www-
tag/2003Feb/0138.htm...](http://lists.w3.org/Archives/Public/www-
tag/2003Feb/0138.html)

------
Scotchy
I discovered this when I was debugging a Netbeans generated REST Webservices.
The web UI makes clever use of OPTIONS in order to list the available services
and their parameters automatically :).

~~~
eloisius
I'd be interested in seeing the format it uses. I want to start working on a
standard.

------
cpg
I noticed before that some times the Safari in iOS (5.1) will send OPTIONS
requests. In Rails, the router will simply route them, so they are definitely
easy to use, however, the issue is that most apps will handle them as GETs, so
it may break things. I rebooted the iPad when it was doing this and the
behavior stopped, never finding out why this was taking place. I have not
noticed it again.

------
marquis
Given a series of increasingly sophisticated verbs and language processing,
there should be no practical reason why machines could not use and write APIs
to talk among themselves and build their own interactive services. Too sci-fi
for now?

~~~
TOGoS
With sufficient metadata about resources this would be perfectly feasible. My
thought, though, is that maintaining that metadata (so-and-so needs access to
such-and-such, which changes oh-so-often and which is typically a binary blob
0.5-3MB, or whatever) would in the short term be more work than just writing
the interfaces by hand. For large systems it might work, but man, who's going
to want to fix the system that writes the APIs when it breaks?

~~~
eloisius
What I'm trying to write for Sinatra would generate that documentation
automatically. You just make your resources and endpoints like you always
would and (hopefully) the gem will generate an appropriate JSON object
describing them.

------
eloisius
We've started working on a spec for the response body.
<https://github.com/anodejs/RestDoc>

------
jsprinkles
I'd personally like to see some form of JSON-RPC catch on, which could then be
used here.

