A browsable JSON API (and the graphical browser)
- Hello group,
Here's the documentation, source, and (most importantly) live demo of the browser:
After reading Ruby and Richardson's "RESTful Web Services", my mind was absolutely swimming with the heady possibilities of an XHTML-based API that would be completely browsable in a normal web browser. However, because of troubled web browser support and my personal preference for JSON over XML formats, I started to think about JSON-based alternatives.
After some evenings and weekends, I completed the hm-json (hypermedia JSON) Browser. I've put it under the permissive MIT license so that anyone can use it and modify it for their own project.
I particularly value any insights or comments from this group because I *think* this is a neat application of the REST concept, but I'm a little afraid to say so without more feedback from "serious REST people".
How it works:
The hm-json Browser uses the OPTIONS HTTP method to request the hypermedia representation of a resource at a URI. It parses the server's response and displays it in a simple graphical menu containing the document's title, description, and list of related links. The links, in turn, may describe other methods available on *that* resource, or other related resources altogether such as parent or child resources.
The links are composed of a URI, a rel(ated) property, the HTTP method supported (such as GET, POST, OPTIONS, DELETE, PUT), and also a title and description to display to a human user. The browser turns these into clickable menu items which make the appropriate request to the server. Some links, such as PUT or POST (or templated URIs) will need some additional input, so the browser presents input fields for these as needed.
As you can see, the whole thing is very simple. But with just these few properties, the hm-json Browser allows anyone to start at a single entry URI anywhere in the API and browse their way through the rest of the API, discovering all of the resources and methods available on the server (as permissions may dictate). Thus, the API is completely self-documenting and requires absolutely no programming to use.
This isn't just an aimless experiment. The whole reason I started to seriously explore REST is because I'm designing the API for a commercial web application (which is completed and live but currently has no client-facing API). I'm not embarrassed to admit that I was drawn to the REST style because of the "pretty URLs". But as I learned more, the thing that really excited me about REST was the hypermedia element. And I was really surprised to find so few actual working examples of that out in the wild.
I hate buzzwords and I am very aware that REST is often used as one. Therefore, when our commercial product uses this browser to expose the API to client developers, I want it to be a "good example" of REST, not yet another bad one.
Thanks in advance for any feedback you can give me. Criticism welcome!