Loading External JSON into your Application


For our example, we are going to use the Twitter API. For those of you who haven't tried to interface with Twitter, it is extremely easy to comprehend. Let's say that you absolutely adore me. So much, in fact, that you would love to put my latest tweets on your very own web site. Bless your heart.

Step 1 - Get the Object


If you look over the Twitter API, you can read over all of the wonderful method calls they provide for you, including one that lets you retrieve a user's timeline in JSON format. The format of the URI is as follows:

http://twitter.com/statuses/user_timeline/franklakatos.json

If you try to load this URI in your browser, it will prompt you to download a file. Why a file, and what is inside of it? Since JSON is a front-end technology, it would violate Cross-Site Scripting (XSS) rules to make calls to another domain using the XMLHttpRequest object, the object that powers other asynchronous calls as with AJAX. To work around doing this, you will include this file call in your HTML as a javascript include file:

  1. <script type="text/javascript"
  2. src="http://twitter.com/statuses/user_timeline/franklakatos.json">
  3. </script>


The API request commonly makes available a varying number of parameters to control the output of your request, such as a limit to how many to return.

  1. <script type="text/javascript"
  2. src="http://twitter.com/statuses/user_timeline/franklakatos.json?count=1">
  3. </script>


If you make a call to this JSON file, you will be returned a file that contains an object that looks like this:

  1. [{
  2. "text":"Just handed in my last project ever for my masters, all I have now is finals next week. Goodbye, school. Hello, life.",
  3. "in_reply_to_screen_name":null,
  4. "user":{
  5. "profile_background_color":"9ae4e8",
  6. "followers_count":10,
  7. "profile_image_url":"http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/110871907\/me_copy_normal.jpg",
  8. "description":null,
  9. "utc_offset":null,
  10. "friends_count":6,
  11. "profile_text_color":"000000",
  12. "screen_name":"franklakatos",
  13. "following":null,
  14. "profile_background_image_url":"http:\/\/static.twitter.com\/images\/themes\/theme1\/bg.gif",
  15. "profile_link_color":"0000ff",
  16. "url":null,
  17. "name":"franklakatos",
  18. "favourites_count":0,
  19. "protected":false,
  20. "profile_sidebar_fill_color":"e0ff92",
  21. "time_zone":null,
  22. "profile_sidebar_border_color":"87bc44",
  23. "profile_background_tile":false,
  24. "location":null,
  25. "id":18163247,
  26. "notifications":null,
  27. "statuses_count":67,
  28. "created_at":"Tue Dec 16 14:44:59 +0000 2008"
  29. },
  30. "truncated":false,
  31. "in_reply_to_status_id":null,
  32. "in_reply_to_user_id":null,
  33. "id":1731244194,
  34. "favorited":false,
  35. "source":"<a href=\"http:\/\/twitterfon.net\/\">TwitterFon<\/a>",
  36. "created_at":"Thu May 07 21:36:12 +0000 2009"
  37. }]


Look at all that great content! A quick glance will show that the object is an array of objects (notice the string begins and ends with square brackets). Therefore, if we assigned this string to a variable myTweets, we can access our first object with myTweets[0], for instance.

Here are some examples of accessing the data:
  1. myTweets[0].text // "Just handed in my last project ever for ..."
  2. myTweets[0].created_at // "Thu May 07 21:36:12 +0000 2009"
  3. myTweets[0].user.name // "franklakatos"


Step 2 - Access the Data Using Callbacks


The astute reader may have noticed that the object included in the API file has no variable assigned to it, and since we include the JSON object in an external javascript file, there is no way for us to assign one to it. So how are we suppose to access this data?

The answer, callbacks. Most APIs using JSON will implement a callback system, where you tell it a name of one of your functions and when your site is done downloading the JSON file, it will automatically call that function and pass the object as an argument.

  1. <script type="text/javascript"
  2. src="http://twitter.com/statuses/user_timeline/franklakatos.json?callback=cb&count=1">
  3. </script>


Inside your function, you can assign it to a variable, use the data as needed, et cetera. All you need to do is create the function with one parameter, which will be used to pass the object along.

  1. var myTweets;
  2. function cb(data){
  3.     myTweets = data;
  4. }


Now you can access the objects data whenever you would like, using the myTweets global variable. Here is an example of how you can implement the Twitter API to use in production:

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  2. "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  3. <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  4. <head>
  5. <title>Twitter API w\ JSON</title>
  6. <script type="text/javascript">
  7. var myTweets
  8. function cb(data){
  9.     myTweets = data;
  10.     document.write(myTweets[0].user.name + " says:<br/>\"" + myTweets[0].text + "\"");
  11. }
  12. </script>
  13. <script type="text/javascript"
  14. src="http://twitter.com/statuses/user_timeline/franklakatos.json?callback=cb&count=1">
  15. </script>
  16. </head>
  17. <body>
  18. </body>
  19. </html>

...which would output..

  1. franklakatos says:
  2. "Just handed in my last project ever for my masters, all I have now is finals next week. Goodbye, school. Hello, life."


Next, we will get into the true power of using JSON: implementing client and server communication.