API Console with ioDocs

Finally I had a chance to play around with Mashery’s ioDocs, which Mashery has open sourced some months back. ioDocs has a couple of prerequisites, namely Node.js, npm (Node package manager), and Redis (you can find full installation instructions on the ioDocs github project). Nevertheless, I struggled through the installation process, as I wanted to see how it compares with the API Console from Apigee which I wrote about a week ago.

I chose the USA TODAY Articles API as my guinea pig for this experiment because just yesterday I wrote a set of YQL tables for that API, so I already knew the API documentation pretty well.

After changing a couple of configuration settings (in JSON files) I had a new API Console running in ioDocs. It took me a bit of experimenting to get things running but all in all maybe 30 minutes, which is not bad at all. The image below shows how my ioDocs for the USA TODAY Articles API ended up.

Here a couple of notes I have about ioDocs:

1. plus
   • The UI of ioDocs is really slick, thumbs up! I especially like that there is plenty of room for documentation. Bonus points for the ability to provide pre-populated drop downs via EnumeratedList":["json", "rss"]. Very cool!
   • I am very surprised that USA TODAY does not have ioDocs on there Developer page. It would make experimenting with their API so much easier. So USA TODAY, if you are listening: Go and set up ioDocs!
2. minus
   • ioDocs requires the description of an API in a JSON configuration file. I believe that choosing a standard for this purpose (like WADL or WSDL 2.0) would have been better). Although I know that Apigee is competition for Mashery, so there might be other motives here to do things differently :)
   • I don’t think that the expressiveness of the current configuration files is high enough to model all APIs. Even some very commonly used URL patterns are not possible e.g. if I had an API that would require the replacement of the parameter section in the URL path like this http://someapi.com/v1/stories/{section}/?date=2011, then I don’t think that ioDocs would currently make this possible.
   • documentation is key for anything that is new! Currently the documentation of ioDocs on github is a bit tricky to ready.

All in all, I like ioDocs!

Suggestion: In my mind a mixture of the advantages of Apigee To-Go and ioDocs would make for the perfect API Console.

Code snippet of the ioDocs configuration file

"MethodName":"Search",
"Synopsis":"",
"HTTPMethod":"GET",
"URI":"/articles",
"RequiresOAuth":"N",
"parameters":[
   {
			"Name":"encoding",
			"Required":"N",
			"Default":"json",
			"Type":"enumerated",
			"EnumeratedList":["json", "rss"],
			"Description":"Format in which to return the results. Either 'json' or 'rss'."
   },
   {
			"Name":"search",
			"Required":"N",
			"Default":"",
			"Type":"",
			"Description":"The search string."
   },
	 ...
]