The Facebook REST API can be described as a list of resources, with the corresponding HTTP methods to use and the parameters allowed in the request.

The snippet above describes the resource /me, which is located at the URL https://graph.facebook.com/me. The URL can be accessed using the HTTP verb GET, and it accepts two parameters - the optional fields param, and the required access_token param.

Outlining the REST API in JSON allows one to perform application-level request validation - for example it would be trivial to write validation code to make sure that we don’t try to accidentally send off a request to the resource without the access_token, since we know it would fail.

Since the APIs are so easily defined in JSON, I whipped up a quick client using node.js that can talk to any REST API that can be defined in JSON similarly to the Facebook and Twitter specs above. I published the client on npm and put it on Github. I called it unio.

You can install it using npm install unio, and start making requests to the Facebook API (I will soon implement the Twitter API with it). You can also import arbitrary JSON specs that look like the ones above. Example usage below:

12345678910111213141516171819202122232425262728

varunio=require('unio')varparams={q:'coffee',access_token:'FB_ACCESS_TOKEN'}// use the Facebook REST API and make a search queryunio().use('fb').get('search',params,function(err,reply){//...})// use the Twitter REST API and post a tweetunio().use('twitter').post('statuses/update',{status:'hello world'},function(err,reply){//...})// import a new REST API definition and query itunio().spec(jsonSpec).use('my-new-api').get('some/url',{foo:'bar'},function(err,reply){//...})

The idea of describing a web service in a machine-readable format is not new. For example, there is Web Services Description Language, which is an XML language used to describe the functionality offered by a web service.

There is nothing inherently wrong with WSDL - it gets the job done and has been used widely in the past. I simply advocate that we use a simplified JSON spec like the one above to describe REST APIs - this allows us to implement clients like unio, making the time required to test, use and re-use REST services minimal.

No matter what, nothing changes - there is always something to be kept up to date. Generally, REST services publish API docs online and delegate the writing of the client code to you. Instead, I propose keeping the JSON spec up-to-date (and even auto-generate your documentation) to avoid having to keep multiple things up-to-date. Then use a client that can auto-generate the code to talk to the service. I’d rather spend the time keeping a JSON file up-to-date than write a new REST API client each time a new online service pops up. Less work, more time playing with APIs.

So I propose that we build a list of JSON documents describing as many REST APIs as possible. We can then import these specs as needed into a simple client like the one I wrote above, and start making HTTP requests without wasting time implementing yet another REST API client. To help out and add more JSON API specs, fork and submit a pull request on the Github page for unio. I invite anyone and everyone to message me and collaborate to add more!