The user interface (UI) and the API give you much of the same information in different forms, meant for different purposes. The requests for the UI and the API are both HTTP GETs—but with their corresponding URLs and parameters. In the UI, the body of the response is HTML + JavaScript for display in a web browser. In the API, the response body is XML, meant for consumption by a computer program. (Remember, you learned about XML feeds in Chapter 4. The format of the XML is not the same as RSS or Atom, but you get the benefits of stuff coming back in XML instead of HTML—you don’t have to screen-­scrape the information. Also remember from the discussion in Chapter 2 that it is possible to screen-­scrape HTML + JavaScript, but it’s not ideal.)

Let’s see how to convince ourselves of the correspondence of the information in the UI and the API. It’s very powerful to see this correspondence—the same information is in the UI and from the API—because you’ll get a vivid visual confirmation that you understand what’s happening in the API. Let’s return to comparing the following (when you are logged out of Flickr—to make sure you see only public photos):

http://www.flickr.com/photos/tags/puppy/

with the following:

http://api.flickr.com/services/rest/?method=flickr.photos.search&api_key={api_key}&tags=puppy&per_page=3

What type of comparisons can you do?

With what you learned in Chapter 2 and with the attributes from the photo element, you can generate the URL for the photo. Take, for instance, the first photo element:

<photo id="1153699093" owner="7841384@N07" secret="d1fba451c9" server="1023"
       farm="2" title="willy after bath and haircut" ispublic="1" isfriend="0"
       isfamily="0" />
         

With this you can tabulate the parameters listed in Table 6-1.

Remember, the URL templates for the context page of a photo is as follows:

http://www.flickr.com/photos/{user-id}/{photo-id}/

And the link to the medium-sized photo is as follows:

http://farm{farm-id}.static.flickr.com/{server-id}/{photo-id}_{photo-secret}.jpg

So, the following are the URLs:

http://www.flickr.com/photos/7841384@N07/1153699093/

http://farm2.static.flickr.com/1023/1153699093_d1fba451c9.jpg

You can follow the same procedure for all the photos—but one would probably be enough for you to use to compare with the photos in the UI. (You’re likely to see the same photo from the API in the UI and hence confirm that the results are the same.)

	Note
	You might wonder how you derive the URL for the original image. Assuming that the original photo is publicly accessible at all, you add &extras=original_format to the query to get the originalsecret and originalformat attributes.

Now that you know that you can generate an HTML representation of each photo, let’s think about what you use flickr.photos.search for. Later in the chapter, I’ll walk you through the details of how to generate a simple HTML interface written in PHP. Using that method alone and a bit of web programming, you can generate a simple Flickr search engine that lets you page through search results. You can do many other things as well. For example, you could generate an XML feed from this data. With feeds coming out the API, you’d be able to use all the techniques you learned in Chapter 4 (including mashing up feeds with Yahoo! Pipes). You might not have all the information you could ever want; there are other methods in the Flickr API that will give you more information about the photos, and I will show you how to use those methods later in the chapter.

Where to go from here? First, you won’t be surprised to learn that many other parameters are available to you for flickr.photos.search given how many search options there are in the Flickr UI for search (see Chapter 2 for a review). You can learn more about those parameters by reading the documentation for the method here:

http://www.flickr.com/services/api/flickr.photos.search.html

Here you will see documented all the possible arguments you can pass to the method. In addition, you see an example response that, not surprisingly, should look similar to the XML response we studied earlier. In addition, you will see mention of two topics that I glossed over in my example:

Error handling: The carefully constructed simple request should work as described here. But errors do happen, and Flickr uses an error-­handling process that includes the use of error codes and error messages. Any robust source code you write should take into account this error handling.

Authorization: The example we looked at involved only public photos. Things get a lot messier once you work with private photos. In the UI, that means having to establish a user account and being logged in. With the API, there is a conceptually parallel process with one twist. Three parties are involved in Flickr authentication; in addition to the user and Flickr, there is a third-­party application that uses the API. To avoid users having to give their passwords to the third-­party application to log in on their behalf, there’s a complicated dance that could easily obscure the core ideas behind the API. We’ll look at authentication later in this chapter.

As interesting as flickr.photos.search is (and it is probably the single most useful and functionally rich Flickr method), you’ll want to see what other methods there are in the API. I’ll show you how to learn about the diversity of functionality available in the Flickr API by using, among other things, the very cool Flickr API Explorer.

You’ll find that a good understanding of Flickr’s functionality will come in handy when you learn how to use the API. (This is a point I was stressing in Chapter 2.) There’s the ad hoc method of learning the API that is to start with a specific problem you want to solve—and then look for a specific piece of functionality in the API that will solve it. You can consult the Flickr API documentation when you need it and use the Flickr API Explorer. You can also try to take a more systematic approach to outlining what’s available in the Flickr API (a bit like the detailed discussion of Flickr’s URL language I presented in Chapter 2). I will outline a method for doing this. This is cool, because such a method will involve the Flickr API telling us about itself! I will use that as an opportunity to talk about APIs in general.

A large part of this chapter will cover some of the programming details you will encounter working with the Flickr API and other APIs. The way I showed you to formulate the Flickr API through the use of the following:

http://api.flickr.com/services/rest/?method=flickr.photos.search&api_key={api_key}&tags=puppy&per_page=3

is only one way of three ways to do so. There are also other formats for the response that Flickr can generate. I’ll cover the different request and response formats in the “Request and Response Formats” section later in this chapter.

When working with these Flickr web services, you find that a detailed understanding of HTTP, XML, and request and response formats is helpful—but you’re likely to want to work at a higher level of abstraction once you get down to doing some serious programming. That’s when third-­party wrappers to the API, what Flickr calls API kits, come into play. I will cover how to use a number of the PHP Flickr API kits later in this chapter.

There is a lot of complexity in using APIs, but just don’t forget the essential pattern that you find in the Flickr API: you make an HTTP request formatted with the correct parameters, and you get back in your response XML that you can then parse. The rest is detail.

The bottom line is that you can learn a lot by using and studying the Flickr API. It’s extremely well designed in so many ways. It’s certainly not perfect—and there are other, sometimes better, ways of instantiating the certain functionality of an API. A close study of the Flickr API will help you understand the APIs of other systems—as you will see in Chapter 7.