This 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 example
Twitter 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:
jsonobj = simplejson.load(response)
As you can see, the information contained in the Twitter response has been loaded up as an object (
One of the best troubleshooting strategies is avoiding problems in the first place. When developing against REST APIs, you usually want to go with supported, tested libraries and follow sample code wherever possible. As in any other situation where your application relies on a service you don't control, you need to code defensively. The structure of the response could change, or the call could simply fail due to network or server issues. Your code needs to handle these unexpected issues gracefully. You can save yourself a lot of trouble by logging the responses you get locally. Most servers don't log the responses they send, so you may need that local log to figure out what happened when something goes wrong. And asking for support will be much easier if you can send along an example of the failing response.