Making YQL Tables an API Query Wizard

July 25, 2011

This idea is sitting in my draft box for some time now. The idea I am proposing:

Take a YQL table and automatically transform it into an API Query Wizard. This Wizard is a web interface that is used for querying and documenting the API wrapped by this YQL table.

So why did I get back to this idea just now? Today Mashey launched an interesting new offering called Mashery I/O Docs, which they call “the next generation of API documentation”. I recommend watching the introductory video over at their site. See below how I/O Docs looks like in action by the example of the I/O Docs for the Klout API. I think it looks pretty neat, as they do a good job in bringing together the input parameters for the API calls with their corresponding documentation.

Mashery I/O Docs for the Klout API


Now all of you who know YQL might say: “Hey, this looks much like the YQL console.” Well I would say yes and no (see screenshots of the YQl console further below). While the YQL console does a decent job in letting you create API calls without too much typing, it also has a couple of shortcomings.

These shortcomings are mainly:

YQL Console - Query Wizard


YQL Console - Results


So now back to my idea. Transforming a YQL table into an API Query Wizard. Without taking anything away from the wonderful job that Mashery did with I/O Docs, it is not all that hard, is it? All that it takes is a somewhat appealing UI, syntax highlighting for the API output (mainly JSON/XML) and of course proper documentation of the different API endpoints and query parameters.

From a technical standpoint that would be reasonably easy. I would probably use XSLT to automatically transform the XML of the YQL table into the HTML for the Wizard. Then one would be able to just point the web browser to any given YQL table on the internet, which would then get displayed as an API Query Wizard to the underlying API.

So YAHOO! / YQL Team, why not just do this? It might take a couple of minor changes to your XML schema, mainly to allow for the ability to add description to the different input parameters. Also grouping multiple YQL tables into one wizard, like Mashery does it, would be a bit trickier but still possible. I guess you can still pull it off, it is not too late :)