This idea is sitting in my draft box for some time now. The idea I am proposing:
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:
- too strong focus on the SQL-like typing mode instead of the Query Wizard (see below)
- no documentation for the individual API parameters
- visual separation of Query Wizard and data generated by the API call
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 :)