Chapter 6. Learning Web Services APIs Through Flickr

Table of Contents

An Introduction to the Flickr API
What Does This XML Response Mean?
What Can You Do with the XML Response?
API Documentation, Community, and Policy
Terms of Use for the API
Using the Flickr API Explorer and Documentation
Calling a Basic Flickr API Method from PHP
HTTP Clients
A Refresher on HTTP
XML Processing
Pulling It All Together: Generating Simple HTML Representations of the Photos
Where Does This Leave Us?
The Flickr API in General
Using flickr.reflection Methods
Querying the Flickr Reflection Methods with PHP
Request and Response Formats
Flickr Authorization
Why Passing Passwords Around Doesn’t Work Too Well
Authorization for Web Apps
Using Flickr API Kits
Limitations of the Flickr API

Flickr is an excellent playground for learning XML web services. Among other reasons, Flickr offers clear documentation, an instructive API Explorer that lets you try the API through a browser, and lots of prior art to study in terms of remixes and mashups. Hundreds of third-­party apps are using the Flickr API.

As I discussed in previous chapters (especially Chapter 2), application programming interfaces (APIs) are the preferred way of programming a website and accessing its data and services, although not all websites have APIs. We looked at a wide range of things you can do without doing much programming, which in many cases means not resorting to the API. But now we turn to using APIs. Don’t forget what you learned while looking at end-­user functionality, because you will need that knowledge in applying APIs.

By the end of this chapter, you will see that the Flickr API is an extensive API that can do many things using many options. The heart of the API is simple, though. I’ll start this chapter by presenting and analyzing perhaps the simplest immediately useful thing you can do with the Flickr API. I’ll walk you through that example in depth to show you conceptually how to use the search API and how to interpret the results you get. After walking you through how to make that specific request, I’ll outline the various ways in which the example can be generalized.

After an overview of the policy and terms of service surrounding the API, I’ll show you how to make sense of the Flickr documentation and how to use the excellent Flickr API Explorer to study the API. I’ll revisit in depth the mechanics of making a basic call of a Flickr API method, using it as an opportunity to provide a tutorial on two fundamental techniques: processing HTTP requests and parsing XML. I then demonstrate how to knit those two techniques to create a simple HTML interface based on the photo search API.

With an understanding of how to exercise a single method in hand, you’ll then look at all the API methods in Flickr. I’ll demonstrate how to use the reflection methods in the Flickr API to tell you about the API itself. I’ll next explain the ways in which you can choose alternative formats for the requests and responses in the API, laying the foundation for a discussion of REST and SOAP that I’ll revisit in the next chapter.

By that point in the chapter, you will have done almost everything you can do with authorization, the trickiest part of the API. Flickr authorization can confusing if you do not understand the motivation behind the steps in the authorization dance. I’ll explain the mechanics of the authorization scheme in terms of what Flickr must be accomplishing in authorization—and how all the technical pieces fit together to accomplish those design goals. It’s an involved story but one that might elucidate for you other authentication schemes out there with similar design constraints. After the narrative, I’ve included some PHP code that implements the ideas.

For practical use of the Flickr API to make mashups, you probably do not want to work so close to the API itself but instead use API kits or third-­party language-­specific wrappers. Therefore, I’ll survey briefly three of the PHP API kits for Flickr. I’ll conclude this chapter by pointing out some of the limitations of the Flickr API with respect to what’s possible with the Flickr user interface.

An Introduction to the Flickr API

It’s useful to start with a simple yet illustrative example of the Flickr API before diving into the complexities that can easily obscure the simple idea at the heart of the API. The API is designed for you as a programmer to send requests to the API and get responses that are easy for you to decipher with your program. In earlier chapters, especially Chapter 2, you learned about you can use the URL language of Flickr to access resources from Flickr. However, for a computer program to use that information, it would have to screen-­scrape the information. Screen-­scraping is a fragile and cumbersome process. The Flickr API sets a framework for both making requests and getting responses that are well defined, stable, and convenient for computer programs.

Before you proceed any further, sign up for a Flickr API key so that you can follow along with this example (see “Obtaining a Flickr API Key”).

Once you have your key, let’s make the simplest possible call to the Flickr API. Drop the following URL in your browser:{api-key}

where api-key is your Flickr API key. For this request, there are two parameters: method, which indicates the part of the API to access, and api_key, which identifies the party making the API request. Flickr produces the following response corresponding to your request:

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">

Note that the entity body of the response is an XML document containing your key.

Let’s now consider a slightly more complicated call to the Flickr API that returns something more interesting. Let’s ask Flickr for photos with a given tag. You learned in Chapter 2 that the corresponding URL in the Flickr UI for pictures corresponding to a given tag (say, the tag puppy) is as follows:{tag}/

For example:

The corresponding way to get from the Flickr API to the most recently uploaded public photos for a tag is like so:{api_key}&tags={tag}&per_page={per_page}

When you substitute your API key, set tag to puppy, and set per_page to 3 to issue the following call:{api_key}&tags=puppy&per_page=3

you will get something similar to the following:

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
    <photos page="1" pages="96293" perpage="3" total="288877">
        <photo id="1153699093" owner="7841384@N07" secret="d1fba451c9" server="1023"
              farm="2" title="willy after bath and haircut" ispublic="1" isfriend="0"
              isfamily="0" />
        <photo id="1154506492" owner="7841384@N07" secret="881ff7c4bc" server="1058"
              farm="2" title="rocky with broken leg" ispublic="1" isfriend="0"
              isfamily="0" />
        <photo id="1153588011" owner="90877382@N00" secret="8a7a559e68" server="1288"
              farm="2" title="DSC 6503" ispublic="1" isfriend="0" isfamily="0" />

What happens in this Flickr API call? In the request, you ask for the three most recently uploaded public photos with the tag puppy via the method. You get back an XML document in the body of the response. I’ll show you later in the chapter the mechanics of how to parse the XML document in languages such as PHP. For the moment, notice the information you are getting in the XML response:

  • Within the rsp root element, you find a photos element containing three child photo elements.

  • Attributes in the photos element tell you a number of facts about the photo: the total attribute is the number of public photos tagged with puppy (288,877), the perpage attribute is the number of photo elements actually returned in this response (3), the page attribute tells you which page corresponds to this response (1), and the pages attribute is the total number of pages (96,293), assuming a page size of perpage.


    Just as with the human user interface of Flickr, you get API results as a series of pages. (Imagine if the API were to send you data about every puppy picture in one shot!) The default value for perpage is 100, and the maximum value is 500. I choose 3 in this example so that you can easily study the entire response.

  • Each of the photo elements has attributes that enable you to know a bit about what the photo is about (title), map them to the photo’s various URLs (id, owner, secret, server, and farm), and tell you about the photo’s visibility to classes of users (ispublic, isfriend, and isfamily).

Let’s now consider two related issues about this pattern of request and response:

  • What does this XML response mean?

  • What can you do with the XML response?

What Does This XML Response Mean?

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):

with the following:{api_key}&tags=puppy&per_page=3

What type of comparisons can you do?

  • You can compare the total numbers of photos in the UI and the API (which you might expect to be same but are not quite the same because of privacy options—see the “Why Are Flickr UI Results Not the Same As Those in the API?” sidebar).

  • You can map the information about the photo elements into the photo URLs in order to see what photos are actually being referred to by the API response.

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.

Table 6.1. Parameters Associated with Photo 1153699093
Parameter Value
photo-id 1153699093
farm-id 2
server-id 1023
photo-secret d1fba451c9
file-suffix jpg
user-id 7841384@N07

Remember, the URL templates for the context page of a photo is as follows:{user-id}/{photo-id}/

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


So, the following are the URLs:

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.)


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.

What Can You Do with the XML Response?

Now that you know that you can generate an HTML representation of each photo, let’s think about what you use 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 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:

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 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:{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.