{"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"
}
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).
> 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?
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.
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!
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 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.
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" }