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.

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.

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!

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.

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."},...]