August 23, 2012, 3:39 PM — These days, REST APIs are available to integrate your application or website with thousands of platforms -- Web 2.0 properties such as Twitter, Facebook, and Foursquare, as well as old-school companies like USA Today, Best Buy, and Edmunds.com. Unfortunately, tapping this dizzying buffet of options isn't always easy.
Most API documentation assumes an understanding of the foundational technology, and while REST API architecture gives developers enormous freedom to innovate, that freedom comes at a price -- namely, fewer guidelines for application behavior. But because these APIs are based on HTTP, a mature protocol, there are numerous strategies you can use to develop and debug your application. First, though, you need a comprehension of the basics of HTTP, a grasp of REST architecture, and some tools for inspecting traffic and strategies for debugging problems.
[ FREE DOWNLOAD: 6 things every IT person should know ]
[ Experts explain all key HTML5 specs, from canvas to local storage, plus the latest browser benchmarks and report cards on HTML5 support in InfoWorld's megaguide to HTML5. Download the PDF today! | Keep up with the latest developer news with InfoWorld's Developer World newsletter. ]
HTTPHyperText Transfer Protocol (HTTP) -- the protocol used throughout the Internet for transactions between Web servers and clients -- is simple, tested, and supported by libraries in every modern programming language. HTTP includes methods supporting all of the necessary actions for a server/client transaction: PUT, GET, POST, and DELETE. It has a rich set of status codes to cover success and error situations, and headers and query parameters make it possible to send additional information about the transaction or request to the server.
To better illustrate how HTTP works, let's take a look at a simple transaction. This is a basic request from a Chrome browser on a Macintosh to Google's home page.
Looking over the request, you can see that the method sent (1) was GET -- a read operation on an HTTP resource. The URL (2) indicates the full path being retrieved -- in this case, the document at the root of http://www.google.com. The request gets a little more interesting with the headers (3). An HTTP transaction can have any number of headers, and these allow the client to send information about the transaction to the server.
In addition to the types of headers seen here, headers can also be used to send user-specific information such as cookies. Servers aren't under any obligation to use information passed along via headers, but they frequently use the information to craft the response appropriately -- HTML that will display nicely on a specific browser, or content in the language the user prefers.
The response from Google includes information that is useful to the client -- and that can be useful to you too. The first and most important piece is (4) the HTTP Status code. This code is returned with every response from an HTTP server. Understanding these codes makes it a lot easier to figure out what's happening between the client and the server.
- 50x: Something went wrong with the server.
- 40x: The developer did something unexpected.
- 30x: These codes are used for redirects.
- 20x: Cool, your request succeeded.
Watching HTTP trafficWith a basic understanding of how these transactions work, it's time to take it to the next level and watch some actual traffic. Fortunately, because HTTP is so widely used, it's easy to find traffic to inspect even before you start accessing the APIs. Many modern Web browsers provide a Web inspector function that allows you to see the browser's traffic. However, since the focus of this article is on software development using REST APIs, you'll need to use an application that lets you watch all of the HTTP traffic flowing to and from your system -- not just your browsing activity.
HTTP sniffersHTTP sniffers are applications that provide a console to view the Web traffic on your system. All of them report on the transaction information detailed above: the URL, headers, method, and body of the request; and the status, headers, and body of the response. On the Macintosh, HTTP Scoop works quite well. On Windows, I suggest Fiddler, and for Linux/Unix systems there's Wireshark.
As an example, here are a few screenshots from HTTP Scoop. The first one shows the summary view with basic information about the request.
Double-clicking on one of the log lines gives a more detailed view of that particular transaction.
In the case of HTTP Scoop, you're provided with different tabs to explore specific aspects of the transaction. The Headers tab is frequently useful in understanding the request and response.
Being able to inspect the headers for the transaction gives you a lot more information about how the client and server are communicating. Another particularly useful tab in this tool is Request/Response, which shows the GET parameters and POST body as well as the body of the server response.
You can almost always figure out what's going wrong with a request using a combination of the Headers and Request/Response tabs (or the equivalent in one of the other sniffers). If you can create a successful request, and compare the values to your failing request, it's generally fairly easy to figure out what you need to change in order to fix the issue.
Install one of these sniffers on your system and experiment with it a bit. Visit a Web page and make sure you can find all of the important components of the requests and responses listed above.
RESTThis section provides a very high level (and somewhat abstract) overview of REST API architecture. If you want to dig a little deeper into REST, there's a fantastic tutorial at rest.elkstein.org. REST, for "Representational State Transfer," is a lightweight architecture for network applications that use HTTP requests to read and write data. Because REST services are built on this well-supported standard, these APIs are platform independent, and standard libraries for facilitating these simple Web requests are available in all modern programming languages. Because REST exposes data rather than methods, it gives developers the freedom to create new and innovative uses of the architecture. However, because it is so open-ended, some amount of caution is needed in the design. Most important, a REST API should be designed so that a GET request can never change the state of any resource in the system. Good REST API design protects against accidental deletion or change by third-party applications or overzealous Web crawlers.
REST APIs generally format the responses in JSON or XML. Both formats are well supported, with libraries available in most any modern programming language. Using one of these libraries, you'll find it relatively straightforward to convert the response into an object that you can manipulate in your application.
A REST exampleTwitter has a great API to use for testing. Because some of Twitter's resources don't require authentication, you can see them right in the browser. As an example, click on the following link: http://search.twitter.com/search.json?q=synedra&count=1
The response you see in your browser is the JSON representation of the search for "synedra" in the Twitter Search API. Using the JSON library for your programming language of choice, you can convert this response into a usable object. For instance, in Python you could do the following:
As you can see, the information contained in the Twitter response has been loaded up as an object (jsonobj).