I was curious about all the great sites I know of releasing their API. Twitter, Google, Facebook, Yelp, are only a few examples of websites providing a way to access their services in a programmatic way. In this post, I have investigated a simple but very interesting API, offered by Rotten Tomatoes, a website about movies.
Apparently, most if not all the websites offering API access to their services, require you to register as a developer, in order to provide you with an API key. The registration form for Rotten Tomatoes can be found, for example, at the Developers’ page. Once you register an account and request an API key, you can use it to access the API. This kind of accountability is important, because the damage you can do by making tons of requests to a website can easily become an example of DoS attacks. The number of requests is limited, as well (5 per seconds and 10,000 per day).
In order to more easily manipulate HTTP requests and response, I have tried out the POCO libraries, a nice set of wrappers around extremely useful features, that range from Base64 encoding/decoding to socket programming, to XML manipulation, to DBMS interactions. The simple code I provide here uses the Net classes, that offer useful abstractions like
HTMLForm, and the likes.
Let’s examine this code from closer. The complete source code is provided as a Github gist.
Let’s dissect the code presented above.
We make an
HTTP GET request in order to retrieve data from the web service by passing the proper parameters in a query string. The POCO libraries give us access to an
HTTPRequest, that is constructed by passing it the HTTP method, the last part of the query url, and the version of HTTP, for which two enum values are provided,
HTTP_1_1, for versions 1.0 and 1.1.
HTMLForm is useful for passing parameters to the request. This
is just done by providing key-value pairs for each relevant parameter. As you
see, when we are done, we call a
prepareSubmit() method to pass
the values to the request object.
In order to call the API service, we need to instantiate a
HTTPClientSession object, that is initialized with the name of the host providing the service.
The request is sent by calling the method
sendRequest(). It is interesting that, in case we wanted to pass a body (for example in a POST request), we could have simply called the get
s.sendRequest() << req_body;.
Finally, we want to get the response. We instantiate an object of type
HTTPResponse, not surprisingly, and then call the
receiveResponse() on the client-initiated session object. The
StreamCopier is useful to print the result into an output stream, that we can then parse at will.
The resulting file looks something like the following:
The POCO libraries have been an interesting surprise. They are very well documented, and simplify several tasks which prove fundamental when dealing with the network.
I have tried also to access the Twitter API, but that deserves a post apart, because I had some problems with the authentication that is more sophisticated than Rotten Tomatoes’, also because of the huge amount of data that you can query. A great tool for debugging your programs can be found at the IO Docs page, that generates the request string according to the parameter provided in a form, executes the request, and finally displays the result; a similar tool is present also for Twitter.