Born on the Web

Before I worked on flapi viewer I had never worked with a web service, I tought it was something incredibly difficult. But it's not difficult at all, if you know how to use xml, you can work with web services. In this article I'll explain you how the REST web service works, how to use the flickr REST service, in the end I'll show you how to make a simple php web application that communicates with the flickr web service. After reading this article I hope you've overcome your fear for web services :-) . How does REST work? I'm going to keep this part simple, if you want more information about the rest web service you should check out this article. I will just talk about the practical side of the story. First of all a web service needs a communication channel. You need to be able to ask something to the service and the web service then needs to respond. In the REST web service you ask something just by typing a url. In the url you give certain parameters that define which information you want the web service to return to you (just like giving GET variables to a page). If you made the correct web service call, it will respond you with an XML page containing the information you've asked. An example: http://www.somecompany.com/webservice/?searchuser=yoursearchstring if the user of the string exists the xml will be something like this: yoursearchstring The web service responds and says, I've found a user with that username. You can check the stat="ok" parameter. If the web service didn't found a user with your search string it will respond something like this: stat="fail", with the error message "User not found". Your only task, as a programmer, is to catch that xml and parse it to usable data. And that's all there is to it. Yes, it's as simple as that. The flickr REST web service I chose the flickr web service, because it has a good documentation for its service and you have a lot of possibilities with this. Most of the popular sites provide a REST web service: amazon, del.icio.us, upcoming, ... First let's take a look at the flickr URL structure. This is your communication tool with the web service, you ask a question in the url, flickr returns you the data in xml form. http://www.flickr.com/services/rest/ ?method=flickr.people.findByUsername &api_key=b80873f756c260d85b8031757bffa3cf &username=SePPeR This is one url, I just put it below each other to make the structure visible.

1. http://www.flickr.com/services/rest/: This is the base url of the REST web service. Not really important it's just the location where the web service is located.
2. ?method=flickr.people.findByUsername: This is probably the most important part of the URL, you say to the web service that you want to find a username. The method will be different if you want other information. Example: if you want a user his recent photos the method will be ?method=flickr.people.getPublicPhotos. You can find a list of all methods on the flickr API documentation page
3. &username=SePPeR: This is an argument you're giving to the method. This is the username you want to look for. With a lot of methods it is obligated to give an argument. You can find it on the page of each method.
4. &api_key=b80873f756c260d85b8031757bffa3cf: this argument is obligated for almost every method. This is just for the purpose of security, if some user is abusing the flickr web service, they can cancel the api key. You can get one for free if you're a flickr member.

The "&" sign is the seperation sign between the different parts of the url. It's just like passing GET variables to a page. The first parameter starts with a "?" the following are seperated with a "&". If you've build the URL, flickr will return this page to you: SePPeR We now know how the REST service works and how you can use the flickr web service, so it's time to get our hands dirty. Simple application We're going to make a simple page in PHP that communicates with the flickr web service. You can enter a username in a form, we're going to look for the user his id number and display his recent photos. We'll be using 2 flickr methods:

1. findByUsername: before we can get the users photos we need to have the user id number. That's why we're using this method. To find the username's corresponding id number
2. getPublicPhotos: If we have the id number we can get his recent photos. We need to give the user id number as an argument together with this method.

The most difficult part is writing the code that parses the xml and puts it into an array. To make this a bit easier I used a class(from zend.com), most of the work has already been done by SolFolango. This makes life a lot easier. There are other classes available to parse an xml. Check out what the result looks like. Now open the full code, I'll explain the most important lines below. include("xml_parse.php"); I included this class, most of the work is done by this class. You can grab the code, credits go to the author, I've found this class on zend. You should use my version of the class because I fixed a few bugs from the zend version. $baseurl = "http://www.flickr.com/services/rest/"; $api_key = "b80873f756c260d85b8031757bffa3cf"; I'm putting the url and api key in a variable, just because this makes life easier. if(isset($_POST['submit'])){ If our form has been submit we're going to check for the username. $url=$baseurl."?method=flickr.people.findByUsername&api_key=".$api_key."&username=".$_POST['username']; This is the url that requests the flickr web service to look for the username that is the same as my post variable. This will return us an xml with the user id number. $xml = new XML($url); This activates the class, puts all the information of the xml in the $xml object. print_r($xml->nodes); To test if everything is put in the $xml object try this testline, they will nicely print the nodes. $test = $xml->nodes['0']->attributes['stat']; //if we found the user get his images if($test == "ok"){ The value of the stat attribute from the xml is put in the variable test, this checks if the username the user entered is found. Only if the username is found in the flickr database, the code that gets the recent photos will be executed. $userid = $xml->nodes['1']->attributes['id']; //now we're going to make the url of the user his recent pictures. $urlrecent=$baseurl."?method=flickr.people.getPublicPhotos&api_key=".$api_key."&user_id=".$userid; $photos = new XML($urlrecent); $userid becomes the id number of the user, we need it to create a new URL that requests the photos from that user. We use the XML parse class to put the xml data into the $photos object. for($i=0; $inodes); $i++){ This counts the nodes of the xml and makes a loop that passes each node. if($photos->nodes[$i]->name = = "photo/"){ If the node is a photo. $server = $photos->nodes[$i]->attributes['server']; $photoid = $photos->nodes[$i]->attributes['id']; $secret = $photos->nodes[$i]->attributes['secret']; $title = $photos->nodes[$i]->attributes['title']; //link it to the correct page print(""); //flickr has a fixes url structure, check http://www.flickr.com/services/api/misc.urls.html print("

"); print(""); print the photo thumbnail. The structure of the photo URL never changes, check the help page on the url structure. This will explain this part of the code. FILES: demo the code XML parse class So that's it... it's less then 100 lines of code. Again, this is a very straightforward way of using a web service, but it works and it should get you started. comments, bugs, remarks, ... shoot !