5. REST Server Responses

A server response in REST is often an XML file; for example,

<parts-list>
 <part id="3322">
  <name>ACME Boomerang</name>
  <desc>
   Used by Coyote in <i>Zoom at the Top</i>, 1962
  </desc>
  <price currency="usd" quantity="1">17.32</price>
  <uri>http://www.acme.com/parts/3322</uri>
 </part>
 <part id="783">
  <name>ACME Dehydrated Boulders</name>
  <desc>
   Used by Coyote in <i>Scrambled Aches</i>, 1957
  </desc>
  <price currency="usd" quantity="pack">19.95</price>
  <uri>http://www.acme.com/parts/783</uri>
 </part>
</parts-list>

However, other formats can also be used; unlike SOAP services, REST is not bound to XML in any way. Possible formats include CSV (comma-separated values) and JSON (JavaScript Object Notation).

Each format has its own advantages and disadvantages. XML is easy to expand (clients should ignore unfamiliar fields) and is type-safe; CSV is more compact; and JSON is trivial to parse in JavaScript clients (and easy to parse in other languages, too).

One option is not acceptable as a REST response format, except in very specific cases: HTML, or any other format which is meant for human consumption and is not easily processed by clients. The specific exception is, of course, when the REST service is documented to return a human-readable document; and when viewing the entire WWW as a RESTful application, we find that HTML is in fact the most common REST response format...

6. Real REST Examples

Here's a very partial list of service providers that use a REST API. Note that some of them also support a WSDL (Web Services) API, in addition, so you can pick which to use; but in most cases, when both alternatives are available, REST calls are easier to create, the results are easier to parse and use, and it's also less resource-heavy on your system.
So without further ado, some REST services:

• The Google Glass API, known as "Mirror API", is a pure REST API. Here is an excellent video talk about this API. (The actual API discussion starts after 16 minutes or so.)
• Twitter has a REST API (in fact, this was their original API and, so far as I can tell, it's still the main API used by Twitter application developers),
• Flickr,
• Amazon.com offer several REST services, e.g., for their S3 storage solution,
• Atom is a RESTful alternative to RSS,
• Tesla Model S uses an (undocumented) REST API between the car systems and its Android/iOS apps.

(This is far from an exhaustive list.)

7. AJAX and REST

AJAX is a popular web development technique that makes web pages interactive using JavaScript.

In AJAX, requests are sent to the server using XMLHttpRequest objects. The response is used by the JavaScript code to dynamically change the current page.

In many ways, AJAX applications follow the REST design principles. Each XMLHttpRequest can be viewed as a REST service request, sent using GET. And the response is often in JSON, a popular response format for REST. (See REST Server Responses, above.)

To make your AJAX application truly RESTful, follow the standard REST design principles (discussed later). You will find that most of them contribute to a good design, even if you don't think of your architecture in terms of REST.

A later section provides code samples for issuing HTTP requests in JavaScript, but if you've done any AJAX programming, you are already familiar with all that.

8. REST Architecture Components

Key components of a REST architecture:

• Resources, which are identified by logical URLs. Both state and functionality are represented using resources.
  • The logical URLs imply that the resources are universally addressable by other parts of the system.
  • Resources are the key element of a true RESTful design, as opposed to "methods" or "services" used in RPC and SOAP Web Services, respectively. You do not issue a "getProductName" and then a "getProductPrice" RPC calls in REST; rather, you view the product data as a resource -- and this resource should contain all the required information (or links to it).
• A web of resources, meaning that a single resource should not be overwhelmingly large and contain too fine-grained details. Whenever relevant, a resource should contain links to additional information -- just as in web pages.
• The system has a client-server, but of course one component's server can be another component's client.
• There is no connection state; interaction is stateless (although the servers and resources can of course be stateful). Each new request should carry all the information required to complete it, and must not rely on previous interactions with the same client.
• Resources should be cachable whenever possible (with an expiration date/time). The protocol must allow the server to explicitly specify which resources may be cached, and for how long.
  • Since HTTP is universally used as the REST protocol, the HTTP cache-control headers are used for this purpose.
  • Clients must respect the server's cache specification for each resource.
• Proxy servers can be used as part of the architecture, to improve performance and scalability. Any standard HTTP proxy can be used.

Note that your application can use REST services (as a client) without being a REST architecture by itself; e.g., a single-machine, non-REST program can access 3rd-party REST services.