The HTTP OPTIONS method and potential for self-describing RESTful APIs | Hacker News Reader

The HTTP OPTIONS method and potential for self-describing RESTful APIs

zacstewart.com

90 pointseloisius29 comments

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" }

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

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.

Oh, nice.

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

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.

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)

Like WSDL. except JSON instead of XML. :)

I think this bit is particularly relevant,

> Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types).

What are the "processing rules" for JSON? Do they depend on the application? Do we have a standard?

My first thought is something like this,

    { "resources":
      { "foo":
        { href:   'http://example.com/foo',
          method: 'get'
        },
        "bar":
        { href:   'http://example.com/bar',
          method: 'post'
        },
        "baz":
        { href:   'http://example.com/baz',
          method: 'put'
        },
      }
    }

Yes, to be useful for REST json really needs either a type for hyperlinks or a naming convention. Arguably then it is an extension of json and needs a new mime type...

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.

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.

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

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.

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!

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

http://json-ld.org

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.

I've never used svn, so I was unaware. Nice to know though. I want to see how it is being used so I have more ideas of how to push it further.

It's also used as part of the CORS handshake for cross-domain XHR calls.

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

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

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

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

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.

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?

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?

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.

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

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

Reply on news.ycombinator.com