Using the Flickr API Explorer and Documentation

Using the Flickr API Explorer and Documentation
Prev	Chapter 6. Learning Web Services APIs Through Flickr	Next

The column on the right at http://www.flickr.com/services/api/ lists all the API methods available in the Flickr API. There are currently 106 methods in the API organized in the following 23 groups:

Activity
Auth
Blogs
Contacts
Favorites
Groups
Groups.pools
Interestingness
People
Photos
Photos.comments
Photos.geo
Photos.licenses
Photos.notes
Photos.transform
Photos.upload
Photosets
Photosets.comments
Prefs
Reflection
Tags
Test
URLs

I’ve already used two methods in the early parts of the chapter: flickr.test.echo (part of the test group) and flickr.photos.search (part of the photos group). In this section, I’ll show you how to exercise a specific API method in detail and return to looking at the full range of methods. Here I use flickr.photos.search for an example.

You can get the documentation for any method here:

http://www.flickr.com/services/api/{method-name}.html

For example:

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

Notice the following subsections in the documentation of each method:

A description of the method’s functionality.
Whether the method requires authentication and, if so, the minimum level of permission needed: one of none, read, write, or delete. read is permission to read private information; write is permission to add, edit, and delete metadata for photos in addition to the read permission; and delete is permission to delete photos in addition to the write and read permissions.
Whether the method needs to be signed. All methods that require authentication require signing. Some methods, such as all the ones belonging to the auth group (for example, flickr.auth.getToken) don’t need authentication but must be signed. I will describe the mechanics of signing later in the chapter.
A list of arguments, the name of each argument, whether it is required or mandatory, and a short description of the argument.
An example response.
The error codes.

In the documentation, there is a link to the Flickr API Explorer:

http://www.flickr.com/services/api/explore/?method={method-name}

For example:

http://www.flickr.com/services/api/explore/?method=flickr.photos.search

The Flickr API Explorer is my favorite part of the Flickr API documentation. Figure 6-1 shows the API Explorer for flickr.photos.getInfo. For each method, the API Explorer not only documents the arguments but lets you fill in arguments and call the method (with your argument values) right within the browser. You have three choices for how to sign the call:

You can leave the call unsigned.
You can sign it without attaching any user information.
You can sign it and grant the call write permission for yourself (as the logged-in user).

Figure 6.1. Figure 6-1.The Flickr API Explorer for flickr.photos.getInfo. (Reproduced with permission of Yahoo! Inc. ® 2007 by Yahoo! Inc. YAHOO! and the YAHOO! logo are trademarks of Yahoo! Inc.)

When you hit the Call Method button, the XML of the response is displayed in an iframe, and the URL for the call is displayed below the iframe. You can use the Flickr API Explorer to understand how a method works. In the case of the unsigned call, you can copy the URL and substitute your own API key to use it in your own programs.

For example, if you use the Flickr API Explorer to call flickr.photos.search with the tag set to puppy and then click the Do Not Sign Call button, you’ll get a URL similar to this:

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

Copy and paste the URL you get from the Flickr API Explorer into a web browser to convince yourself that in this case of searching for public images, you can now call the Flickr API through a simple URL that returns results to you in XML.

	Note
	The Flickr API Explorer uses an `api_key` that keeps changing. But that’s fine because you’re supposed to use your own API key in your own applications. Substituting your own key is not hard for an unsigned call.

Now when I click Sign Call As Raymond Yee with Full Permissions, I get the following URL:

http://api.flickr.com/services/rest/?method=flickr.photos.search&api_key={api_key}&tags=puppy&auth_token=72157601583650732-e30f91f3313b3d14&
         api_sig=3d7a2d1975e9699246a299d2deaf5b70

When I use that URL immediately—before the key expires—I get to perform searches for puppy-tagged photos with write permission for my user account. This URL is useful to test the functionality of the method. It’s not so useful for dropping into a program. Getting it to work is not simply a matter of substituting your own api_key but also getting a new auth_token and calculating the appropriate api_sig (that is, signing the call)—tasks that take a couple of more calls to the Flickr API and a bit of computing. It’s this set of calculations, which makes authorization one of the trickiest parts of the Flickr API, that I will show you how to do later in the chapter.

Prev	Up	Next
API Documentation, Community, and Policy	Home	Calling a Basic Flickr API Method from PHP