This article has been created by Luís Filipe Couto (thanks!). Please feel free to add or correct.
 There's also an article here: IFD:WApplications/Vortraege/APIs_JSON

I'm assuming that you are familiar with HTML, CSS, JavaScript and PHP for this article.

JSON[[JSON|JavaScript Object Notation]] Format Introduction

JSON[[JSON|JavaScript Object Notation]] Format (acronym for JavaScript Object Notation) is a data interchange format, designed for human-readability. It's lightweight, text-based, open standard and usually serves as an alternative to XML to transmit data over a network or between a server and a web application.

JSON[[JSON|JavaScript Object Notation]] Format was a subset of the JavaScript programming language, but despite its relationship, it's considered to be language-independent, with parsers available for almost every language.

JSON[[JSON|JavaScript Object Notation]] Format Data Types, Syntax and Structure

JSON[[JSON|JavaScript Object Notation]] Format Data Types:

Number
Either as Integer: (…,-1,0,1,…) or as Real: (3,141592…)
String
double-quoted Unicode: "Jonh Doe"
Boolean
true or false
Array
an ordered sequence of values, comma-separated and enclosed in square brackets [ ]:
["Value1","Value2","Value2"]

Object

a collection of key:value pairs, comma-separated and enclosed in curly braces { }:
{"Key1":"Value1" , "Key2":"Value2" , "Key3":"Value3"}

Null Value
null


JSON[[JSON|JavaScript Object Notation]] Format Syntax and Structure

A typical JSON[[JSON|JavaScript Object Notation]] Format file could be presented like this:

{
	"firstName": "John", 						//String
	"lastName": "Doe",
	"age": 39,  							//Number
	"has_kids": false,  						//Boolean
	"Hobbies":["Reading","Skating","Music"]				//Array
	"address": { 							//Object
		"streetAddress": "Somewhere over the rainbow 2-1",
		"city": "New York",
		"postalCode": 10021
	},
	"phoneNumber": [						//Array and Object
		{ "type": "home", 
		  "number": 2125551234 },
		{ "type": "fax", 
		  "number": null					//null value 
		}],
}
However, like Javascript, JSON[[JSON|JavaScript Object Notation]] Format can be formatted to be single-line.

Pratical Examples with JavaScript

Fetch and Include JSON[[JSON|JavaScript Object Notation]] Format File

I will show now, how to use JavaScript to print JSON[[JSON|JavaScript Object Notation]] Format files on a HTML page. I will use the Twitter API to get a JSON[[JSON|JavaScript Object Notation]] Format file.

http://twitter.com/statuses/public_timeline.json this link allow us to download a JSON[[JSON|JavaScript Object Notation]] Format file with the last 20 public tweets on Twitter. Due security reasons (XSS), we can not fetch the file with using XmlHttpRequest (AJAX) directly as so, we include it directly in the HTML[[HTML|Hypertext Markup Language]] page:

<!DOCTYPE HTML>
<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
		<title>Your Website</title>
	</head>
	<body>
	
	<script type="text/javascript" src="http://twitter.com/statuses/public_timeline.json?
callback=public_timeline"></script>
	</body>
</html>

Print the JSON[[JSON|JavaScript Object Notation]] Format values

Notice the ?callback=public_timeline? We're using it, because if we download the file directly, we won't be able to use it sincee it's not assigned to any variable, or object or any other kind of javascript resource, so the Twitter API allow us to call the file with a callback function and so making the file usable for manipulation.

We now have the JSON[[JSON|JavaScript Object Notation]] Format file with a callback function to make it usable. We print its values by adding the following script:

<!DOCTYPE HTML>
<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
		<title>Your Website</title>
	</head>
	<body>
	
	<script type="text/javascript" src="http://twitter.com/statuses/public_timeline.json?
callback=public_timeline"></script>
	<script type="text/javascript">
		var tweet;
		function public_timeline(data){
			tweet = data;
			for(var i in tweet){
				document.write(tweet[i].user.name);
				document.write(tweet[i].text);
				document.write(tweet[i].created_at);
			}
		}
	</script>
	</body>
</html>

Because JSON[[JSON|JavaScript Object Notation]] Format is natively Javascript we don't need to parse it, in this particular example, and we can itinerate it's values directly using the dot syntax.


Create a JSON[[JSON|JavaScript Object Notation]] Format Object

So far we saw how to fetch and include an external JSON[[JSON|JavaScript Object Notation]] Format File and how to iterate and print a JSON[[JSON|JavaScript Object Notation]] Format object, but how do we create a JSON[[JSON|JavaScript Object Notation]] Format of our own? Since JSON[[JSON|JavaScript Object Notation]] Format was originally made from Javascript, to create an JSON[[JSON|JavaScript Object Notation]] Format all we need to do, it's to declare it:

var jsonObject = {
	name: 'Luís',
	age: 23,
	student: true,
	hobbies: ['Reading', 'Sleeping', 'Procrastinating'],
	family_members: [
		{name: "Manuel", age: 50, relation: "father"},
		{name: "Maria", age: 47, relation "mother"}
	]
};

alert(jsonObject.family_members[0].relation); //returns "father"

Pratical Examples with PHP[[PHP|PHP Hypertext Processor]]

Create and Decode a JSON[[JSON|JavaScript Object Notation]] Format Object

PHP natively supports JSON[[JSON|JavaScript Object Notation]] Format which makes this process a no-effort task! So to create a JSON[[JSON|JavaScript Object Notation]] Format Object, we first define an array and populate it, then we encode the array to JSON[[JSON|JavaScript Object Notation]] Format:

<?php

$myTweet = array(
	"user" =>array(
		"id" => 123456,
		"name" => Username),
	"text" => "I'm going to be inside a JSON",
	"created_at" => "Wed Jul 07 18:12:12 +0000 2010"
);

$myJSONTweet = json_encode($myTweet);

$myTweets = json_decode($myJSONTweet, true); //if true it will decode to an associative array

?>

The json_encode() function actually takes care of the JSON[[JSON|JavaScript Object Notation]] Format syntax, and even makes the object "user" inside the JSON[[JSON|JavaScript Object Notation]] Format. To decode it, we just use the json_decode() and the PHP[[PHP|PHP Hypertext Processor]] will transform the JSON[[JSON|JavaScript Object Notation]] Format into an associative array, pretty much the opposite of the json_encode().

Twitter APIApplication Programming Interface Introduction

"Twitter is a real-time information network powered by people all around the world that lets you share and discover what’s happening now. Twitter asks “what’s happening” and makes the answer spread across the globe to millions, immediately."
in Twitter About Us page
The social web is not a fad, and itʼs not going away. Itʼs not an add-on to the web as we know it today. Itʼs a fundamental change, a re-architecture, and in hindsight its evolution is obvious. Make no mistake about this. Everyone in this room will need to learn how to design social features on websites. Whether you like it or not
in Paul Adams in The Real Social Network

An APIApplication Programming Interface (Application Programming Interface) it's a interface implemented by a service that allows programmers to interact with other software

When used in the context of web development, an APIApplication Programming Interface is typically a defined set of Hypertext Transfer Protocol (HTTPHyperText Transfer Protocol) request messages, along with a response message, usually in a Markup Language (like XML) or JSON[[JSON|JavaScript Object Notation]] Format, other formats that are also quite common are RSSRich Site Summary – a web feed format and ATOM

The use of APIApplication Programming Interface's, allowed web services to share content and create an open sharing arquitecture. A common example it's the video embedding through YouTube or Vimeo

My choice of using the Twitter APIApplication Programming Interface, is due to two reasons:

  • It's relatively easy, and pretty straightforward to use
  • It's well documented

What you need to know

Among several things, i believe that these three are essential to use the Twitter's APIApplication Programming Interface:

  • The APIApplication Programming Interface is entirely HTTPHyperText Transfer Protocol-based
    • Where methods to retrieve data use the GET request.
    • publishing, modifying or destroying data on Twitter requires the POST request.
  • A command-line is all you need to interact with the Twitter APIApplication Programming Interface
  • There are Twitter API libraries for almost any language

Create a Small Twitter Client

Since it's so easy to use the Twitter's APIApplication Programming Interface, i'm going to show here how to create a small twitter client. I'm going to do some extra steps so that i can refer a few more things about JSON[[JSON|JavaScript Object Notation]] Format and Twitter

So the process i'm going to use is:

  1. #Get the JSON File with PHP and cURL
  2. #Print the tweets
  3. #Serialize a form with JavaScript
  4. #Send the form to PHP with AJAX
  5. #Post the tweet using a PHP Twitter Library

Get the JSON[[JSON|JavaScript Object Notation]] Format with PHP and cURL

<?php
    $user = 'username'; 
    $password = 'password'; 
     
    $ch = curl_init("http://api.twitter.com/1/statuses/home_timeline.json?count=3"); 
     
    curl_setopt($ch,CURLOPT_TIMEOUT, 30); 
    curl_setopt($ch,CURLOPT_USERPWD,$user . ":" . $password); 
    curl_setopt($ch,CURLOPT_RETURNTRANSFER,1); 
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); 
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); 
    
	$result=curl_exec ($ch);
?>

The ability to use cURL, is what allows us to interact with Twitter with the command-line, the same commands exist in PHP[[PHP|PHP Hypertext Processor]] and we're using them right now to fetch the JSON[[JSON|JavaScript Object Notation]] Format.


Print the Tweets

<?php
    $user = 'username'; 
    $password = 'password'; 
     
    $ch = curl_init("http://api.twitter.com/1/statuses/home_timeline.json?count=3"); 
     
    curl_setopt($ch,CURLOPT_TIMEOUT, 30); 
    curl_setopt($ch,CURLOPT_USERPWD,$user . ":" . $password); 
    curl_setopt($ch,CURLOPT_RETURNTRANSFER,1); 
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); 
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); 
    
	$result=curl_exec ($ch);
	$resultado = json_decode($result, true);
     
    foreach ($resultado as $value) {
        echo $value["user"]["name"];
        echo $value["text"];
        echo $value["created_at"];
    }
?>

In the hightlighted area we decode the json into an array and then iterate and print the values of that array, with a little bit of CSS[[CSS|Cascading Style Sheets]] we can achieve something like this: Screen shot 2010-07-07 at 7.24.39 PM.png


Serialize a form with JavaScript

This is the part, where i want to show a few more things about JSON[[JSON|JavaScript Object Notation]] Format which is the JSON[[JSON|JavaScript Object Notation]] Format Parsers. JSON[[JSON|JavaScript Object Notation]] Format usually travels between web app and the server as a string, javascript has a really nice (and dangerous!) function which is eval() this function reads string values and interprets it as javascript, which is quite convenient if the JSON[[JSON|JavaScript Object Notation]] Format file comes from a secure source, however we can't assure the security of an external service like twitter, so i'm going to use a parser to convert the values of our form into a JSON[[JSON|JavaScript Object Notation]] Format, while i'm also going to show the opposite, convert a JSON[[JSON|JavaScript Object Notation]] Format into a Javascript Object with the parser

To save a few lines i'll be using the jQuery Framework
<form action="sendTweet.php" method="post" accept-charset="utf-8">
	<input type="text" name="username" value="" id="username">
	<input type="pasword" name="password" value="" id="password">
	<textarea name="tweet" value="tweet"></textarea>
	<p><input type="submit" id="submit" value="Continue &rarr;"></p>
</form>

<script type="text/javascript" charset="utf-8" src="json2.js"></script>
<script type="text/javascript" charset="utf-8" src="jquery-1.4.2.min.js"></script>
	
<script type="text/javascript" charset="utf-8">
	$(document).ready(function(){
		$('form').submit(function(e){
			e.preventDefault();
			obj = new Object;	//Going to do an object only to use the parser
			obj.username = $('#username').val();
			obj.password = $('#password').val()
			obj.tweet = $('#tweet').val();
			obj2string = JSON.stringify(obj);	//convert object to json string
		});
	});
</script>

As you can see, i'm using the parser to safely convert a javascript object to a JSON[[JSON|JavaScript Object Notation]] Format String


Send the form to PHP[[PHP|PHP Hypertext Processor]] with AJAXAsynchronous Javascript and XML

Here i'm sending the previous JSON[[JSON|JavaScript Object Notation]] Format string to a PHP[[PHP|PHP Hypertext Processor]] file with AJAXAsynchronous Javascript and XML, and parsing the twitter answer into a javascript object. To every request, Twitter responds with a JSON[[JSON|JavaScript Object Notation]] Format, in this case, the JSON[[JSON|JavaScript Object Notation]] Format file contains the info about the tweet we posted using PHP[[PHP|PHP Hypertext Processor]].

	$.post("sendTweet.php",{"sendedTweet":obj2string},function(data)){
		tweet = JSON.parse(data);	//convert json string to object
	}

Post the tweet using a PHP Twitter Library

On the other side in PHP[[PHP|PHP Hypertext Processor]], we get the values, and we use a PHP[[PHP|PHP Hypertext Processor]] Library to send the tweet, libraries change according to its programmer, so it's always a good idea to read the instructions.

On the other hand, if you don't want to use a library you can always use the cURL method showed above to do an authenticated post

<?php
//Currently using the Tijs Verkoyen library http://classes.verkoyen.eu/twitter/

if(isset($_POST['sendedTweet'])){

	$tweet = json_decode($_POST['sendedTweet']); #decode the JSON string

	$username = $tweet['username'];
	$password = $tweet['password'];
	$tweet = $tweet['tweet'];

	include "twitter_library.php";

	$twi_user = new Twitter("$username","$password");
	$user_text = $tweet;
	$twi_user->updateStatus($user_text);

	echo $twi_user
}
?>

And that's pretty much it. I hope i was able to make myself clear during this article, however if you have any doubt please feel free to contact me to here

Resources

--Couto 21:07, 7 July 2010 (UTC)