====== CNETAPI ======

[[http://clientside.cnet.com/cnet.gf/docs/files2/CNETAPI-js.html|docs]] | [[http://code.google.com/p/cnetjavascript/source|svn]]

[[http://api.cnet.com|CNET has a robust REST API]] that anyone can make use of to add data from CNET's catalog to their own web applications. The service is available as XML, but that's not very fun for us to work with in javascript land, so we've also added the ability to get back data as JSON.

Using our [[cnet-libraries:02-utilities#jsonp|JsonP]] class, which functions a lot like Ajax but will let you get data from another domain (and should only be used when you can trust the source completely), you can request data from the CNETAPI directly from the browser.

Here's a simple example (there's a bit more detail on the JsonP section if you follow the link above):

<code javascript exec>
new JsonP('http://api.cnet.com/restApi/v1.0/techProduct?productId=32069546&iod=none&viewType=json&partKey=19926949750937665684988687810562', {
  onComplete: function(data){
    alert(data.CNETResponse.TechProduct.EditorsRating.$);
  }
}).request(); //alerts 8.3 - the rating of the ipod
</code>

Getting data back from the API has some downsides though. You end up writing a lot of code to handle the results and turn them into something a little more useful.

For example, if it returns only one result the item is a single object, but if you get back more than one it's an array. So you always end up checking for this and it gets a little old.

Also, because of the way the xml transforms, you have to add ".$" to any key you want the value for, and some entries don't lend themselves to dot notation (TechProduct['@id']).

Additionally, the api contains instructions within the returned data on how to go get more data about a thing, but this just ends up requiring you to write more layers of code to take the results and merge them back into your result set.

Finally, you have to pass a partner key or partner tag in with every request. This is usually a very long number that is easy to misplace and then you have to hunt around for it. Not fun for development.



===== Enter CNETAPI.js =====
This set of helper classes makes lookups super-duper easy. Here's that same example above (where we got the Ipod rating) except using //CNETAPI.TechProduct//:

<code javascript exec>
//you have to do this only once on your page
//this is my dev key; get your own!
new CNETAPI(19926949750937665684988687810562);
//now our request:
new CNETAPI.TechProduct(32069546).chain(function(){
  dbug.log("got the Ipod, here's the data: ", this.data);
  alert(this.data.EditorsRating.$);
});
</code>

**Note:** The //.$// value is only replaced for items that contain no other children, so with //data.Name.$//, the //Name// object only contains a single member: //$//. We replace //Name// with the value of //Name.$//. But this doesn't always work. The easiest way to figure out what is in the item is to log it to firebug and inspect the object.

That's it. You're done. You can retrieve any product from our api (tech products, news stories, software downloads, etc). Keep in mind that it's asynchronous (like ajax) so you have to either user //.chain// to get at the data or use it's //onSuccess// event.

Here's the same thing using the event method:

<code javascript exec>
//you have to do this only once on your page
//this is my dev key; get your own!
new CNETAPI(19926949750937665684988687810562);
//now our request:
new CNETAPI.TechProduct(32069546, {
  onSuccess: function(instance, data, json){
   alert(data.EditorsRating.$);
  }
});
</code>

Using the event method provides the benefit of passing arguments to the method (the instance of the class, the data, and the raw json) so that you can bind your function to something else if you want. If you use //.chain// you can't bind the function to anything (it's bound to the instance of the class).




===== Searching with CNETAPI.Utils.* =====


You can also search the API on a string (or any number of other variables). This will always return an array of results to you, even if there's only one (unlike the default API response). Additionally, each item will be an instance of a //CNETAPI// object, not just the json value.

Examples:

<html><div id="apiResults" style="margin-left: 40px"></div></html>

<code javascript exec>
//you have to do this only once on your page
//this is my dev key; get your own!
new CNETAPI(19926949750937665684988687810562);
//now our request:
new CNETAPI.Utils.TechProduct({
  onSuccess: function(items){
    var ol = new Element('ol');
    items.each(function(item){
      ol.adopt(new Element('li').setHTML(item.data.Name));
    });
    $('apiResults').adopt(ol);
  }
}).search("Ipod");
</code>

The //CNETAPI.Utils.*// classes have the same namespaces as the object classes, so //CNETAPI.Utils.TechProduct// returns instances of //CNETAPI.TechProduct//.

Beyond that you just need to follow the docs.