Last modified: 6 Apr 2009 11:50:07 AM
The New York Times has opened up a RESTful API at their new DeveloperNetworkBETA site. I want to use it to demonstrate some concepts to the graduate Data Transformations class which I will be teaching here in the Spring Quarter. Towards this end, I am setting up some basic demonstrations using PHP, ECMAScript, and a simple three-tiered architectural appraach.
The data-store runs on a NY Times machine, the search service I present runs on an RIT server, and (eventually) the search-results presentation will run in a browser or other client. By running a service which allows me to request data without directly accessing their persistence store(s), the NY Times protects their data. By using PHP on an RIT machine to run the application tier rather than mushing the application and presentation tiers together there, I protect my API key from being visible (stop trying to look under the covers!) and I allow for the possibilty of multiple different presentatiion-layer clients (that's the students) using my same service without me caring how they are going to present things. Well, I actually do care (I am a teacher after all), but the application tier itself should not care.
See what happens? By separating the data, application, and presentation into seperate tiers, they become more "loosely-coupled". In Computerlandia this is seen as A Good Thing.
Almost nothing in Computerlandia ever works right the first time. Hell, almost nothing ever does anything at all the first time. But, RESTful interfaces like the one from the NY Times are so simple and easy to use that my first test program actually worked right immediately. Weird, huh?
Below you will find the code for my first attempt at a simple PHP application tier which searches and returns data through using the NY Times Article Search API to get at their data tier. At this point that particular API just returns results in JSON format, but they promise to support returning XML data Real Soon Now. This first simple demo just returns the JSON string to your browser without any parsing or formatting . I just wanted to see if it worked at all, and if so what the results looked like.
Note that this first test just uses one simple search term ("Bosnia") which has been "hardcoded" into the program. I wanted to make sure I had an easy time figuring out what went wrong with my first attempt at using their API, so I eliminated the possibility of a badly-formed search term messing things up. Imagine my surprise when nothing went wrong.
<?php // init variables $GETuri = "http://api.nytimes.com/svc/search/v1/article?query="; $keyWords = "Bosnia"; $APIkey = "&api-key=insert your own damned API key here"; // setup request $request = curl_init(); // CURLOPT_GET is the default curl_setopt( $request, CURLOPT_URL, $GETuri . $keyWords . $APIkey ); curl_setopt( $request, CURLOPT_RETURNTRANSFER, 1 ); // RETURN CONTENTS OF CALL curl_setopt( $request, CURLOPT_HEADER, 0 ); // DO NOT RETURN HTTP HEADERS $response = curl_exec( $request ); curl_close( $request ); print( $response ); ?>
I know, it is really simple and silly. But that was the point: start with KISS, and move on to explore the complexity and exciting possibilities of the NY Times Article Search API after I get something to work, to do anything at all. You can try kicking it yourself. See if you can figure out what the JSON results are all about.
<?php
// init variables
$GETuri = "http://api.nytimes.com/svc/search/v1/article?query=";
$keyWords = $_GET["keyWords"];
$APIkey = "&api-key=insert your own damned API key here";
// setup request
if (strlen ( $keyWords ) == 0 ) {
die( "please enter at least one keyword for which to search" );
}
else {
$request = curl_init(); // CURLOPT_GET is the default
curl_setopt( $request, CURLOPT_URL, $GETuri . urlencode( $keyWords ) . $APIkey ); // URLENCODE THE SEARCH TERMS
curl_setopt( $request, CURLOPT_RETURNTRANSFER, 1 ); // RETURN THE CONTENTS OF THE CALL
curl_setopt( $request, CURLOPT_HEADER, 0 ); // DO NOT RETURN HTTP HEADERS
$response = curl_exec( $request );
curl_close( $request );
print( $response );
}
?>
Or you can try the same middle-tier functionality with a bit of formatting for the returned results, if you don't want to try to understand the JSON:
Separation of Concerns is an old design idea in the world of computers. By disentangling the various concerns, one can create a more flexible and robust system, and the parts are more likely to be reusable in other contexts.
In our first iteration, hitting the "submit" button: sends us along to a PHP script on the server which then handles bothmaking the request and integrating the response into an XHTML page which is returned to the requesting browser. The script has too many concerns, and it should just deal with the middle-tier's area of concern: passing along a request from the client to the NYTimes server, and then passing the server-response back to the requesting client, period. And our old friends the JavaScript document.getElementById() function and XMLHttpRequest object make this work.
If we rewrite the middle-tier PHP so it only consists of the code in Section 2.2 (above), we end up with a simple middle-tier which is just concerned with providing a route for Web browsers to request a search be conducted. On the client side, We can now use AJAX to make the requests of our simple server, do the formatting work on the client-side, and use document.getElementById() on the client-side to put properly formatted query results into the Web page. Nothing changes on the client-side as a result of a search, other than the results of that search showing up within the already-loaded Webpage. the "back button" takes you back to the previous page (as you might expect), rather than the previous search. The only thing that changes on the Webpage displayed in the client browser is the search results, and no new page is made up for a particular search.
You can try the new system out here.
Content on this site is provided by Prof. Jeffrey Sonstein under a Creative Commons License. Please contact me, if you wish more information about this work.