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
unserializemethod).
![[Note]](../docbook_images/note.png) | 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
GETorPOSTand 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:
http://api.flickr.com/services/rest/?method=flickr.test.echo&api_key={api-ky}&format={format}
where format = rest, xmlrpc, soap,
json, php_serial, or blank (for the default response
format).