Request and Response Formats

So far in this chapter, I have limited myself to one particular way of formulating a
request to call a Flickr API method and the corresponding default format for the
response. The Flickr API actually supports three different ways of packaging a request
and five different formats for the response. In this section, I describe the choices you
have with respect to request and response formats. Understanding these choices will help
you make sense of APIs other than Flickr’s since you will face similar choices in
working with them.

Regardless of the request or response format used, the Flickr API rests on HTTP.
Hence, we need to remember that making a Flickr API call involves two steps, which is a
reflection of the request and response pattern of the underlying HTTP protocol of the
API:

You formulate an HTTP request corresponding to API method
and parameters you want to use. With Flickr, you have a choice of three formats
for the request format: REST (what we have used so far), XML-­RPC, and
SOAP.

You process the HTTP response that includes a payload
that is by default XML but that also can contain JavaScript (JSON) or PHP (input
for the PHP unserialize method).

Note

Although web services are not necessarily tied to HTTP (for instance, SOAP can be
bound to SMTP), HTTP is the only transport protocol supported for the Flickr API.
However, the vast majority of web services used, especially for mashups, are made
over HTTP. Hence, I don’t cover the use of transport protocols other than HTTP
in this book.

Flickr supports three different request formats to call the methods of the API (REST,
SOAP, and XML-­RPC):

The REST request format, the simplest one to work with, is similar
conceptually and practically to submitting a request through an HTML form. (That
is, you submit a request through either HTTP GET or
POST and use named parameters.) In the simplest cases, that
could be equivalent to setting parameters for a URL to which you get back some
XML that you can parse. Think about the examples I have presented so far to
confirm that this is what has been happening. For Flickr, I recommend starting
with its REST request format.

Note

In Chapter 7, I revisit and refine the term REST. What Flickr calls the
REST approach is a commonly used pattern of structuring web services but is
more accurately described as a REST-­RPC hybrid.

SOAP has an envelope around the request and enables higher levels of
abstraction, but it is more complicated and typically takes more specialized
libraries and tools to deal with than REST. We will return to this subject in
the next chapter, both in the context of Flickr’s SOAP request format and
in other APIs’ SOAP interfaces. SOAP is an important web services
technique, especially among folks who use web services for enterprise work.[102]

Note

In version 1.1 of SOAP, SOAP is an acronym for Simple Object Access
Protocol. Version 1.2 of the SOAP specification indicates that SOAP is no
longer an acronym.

XML-RPC was, in many ways, the proto-­SOAP. It’s most convenient to
use XML-­RPC from a library, of which there are many in a variety of
languages.

There are current five different formats for Flickr responses: the three corresponding
default response formats (REST, XML-­RPC, SOAP) and two specialized response
formats (json and php_serial). In other words, a
REST-­formatted request generates by default a REST-­formatted response. You
can change the format for the response by using the format
parameter.

The default behavior of tying the request and request format is typical for web APIs.
With the exception of the REST-­to-JSON pairing, which we will return to in our
discussion of Ajax programming in Chapter 8, the ability to decouple the request format
from the response format is unusual. For instance, with the Flickr API, you issue a
SOAP-­formatted request that asks for a REST-­formatted response. I’m
not aware of any standard SOAP libraries that can handle such a pairing.

You can see for yourself these five formats in action through a simple
REST-­formatted request: