Many companies want to create their own APIs. Building an API can be a complex task, irrespective of whether the API will be used internally as an integration point between different units of the same company, or externally for 3rd party integration. This article discusses how YQL can help to find possible weaknesses in your API implementation.
A lot of APIs that are built these days are RESTful APIs. Without further qualifying what makes an API RESTful – which is a religious discussion in the development community – RESTful APIs make for a majority of the APIs in the ProgrammableWeb API directory already. This article will focus on RESTful APIs exclusively.
When saying earlier that building an API can be complex, I rather meant that it is difficult to get it “right”. So how can you find out if you got it right or not? In this article I am proposing to use YQL as a tool to assess the quality of your RESTful API, in terms of following best practices and standards.
To understand why YQL can be useful for testing your API, I need to talk a bit more about YQL itself. Lets assume you are building a RESTful API for yourproduct. You might expose the data of a great_resource in yourproduct via URLs of the below format. Such URLs would then be used in applications to make direct calls to your API. The illustration above shows the interaction between application and API, in case of such direct API calls.
When using YQL, the API call is made indirectly via the YQL infrastructure. A YQL call for the same great_resource of yourproduct would look similar to this:
SELECT * FROM yourproduct.great_resource WHERE id="1"
In this case the application sends a YQL query to the YQL server, who then translate this YQL query into a normal RESTful query, which is then forwarded to your API server. The illustration below shows this indirect API call via YQL.
So YQL is like a mediator between application and your API. In order for YQL to be able to translate a YQL query into the syntax of your API, you need to write a mapping between theses two formats. This mapping is called a YQL table.
The YQL team had to look at a lot of APIs and the most common syntax variations, in order to come up with a sufficiently expressive description language for the YQL tables. By now there are more than 1000 YQL tables contributed by the developer community, so it is fair to say that the YQL tables are apparently able to map to a lot of APIs.
So how does all of this help you?
If your create a YQL table for your own API, and you experience major difficulties with that, then this is a fairly strong indication that you have designed your API and URL syntax in a rather non-standard way. This does not necessarily mean that you have to change your API all over but it should at least get your thinking.
Creating a YQL table is not that difficult e.g. a YQL table for the great_resource of yourproduct discussed above could be as simple as this:
The second way in which YQL can help you is by looking at a lot of other YQL tables, and hence at a lot of other APIs. Try to mash up your content with the content of other providers and see how easy/difficult that is. The YQL Community Tables are hosted on github and you can get a very quick overview of the APIs of Twitter, Flickr, ProgrammableWeb, and others.
I would love to hear the thoughts of other YQL users and API creators on this proposal for testing a RESTful API with YQL. If you try this approach, please share your experiences in the comments section below.