Learn REST: A Tutorial

1. What is REST?

2008-02-12T23:00:00.000-08:00

REST stands for Representational State Transfer. (It is sometimes spelled "ReST".) It relies on a stateless, client-server, cacheable communications protocol -- and in virtually all cases, the HTTP protocol is used.REST is an architecture style for designing networked applications. The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to connect between machines,

2. REST as Lightweight Web Services

2008-02-12T22:00:00.000-08:00

As a programming approach, REST is a lightweight alternative to Web Services and RPC.Much like Web Services, a REST service is:Platform-independent (you don't care if the server is Unix, the client is a Mac, or anything else),Language-independent (C# can talk to Java, etc.),Standards-based (runs on top of HTTP), andCan easily be used in the presence of firewalls.Like Web Services, REST offers no

3. How Simple is REST?

2008-02-12T21:00:00.000-08:00

Let's take a simple web service as an example: querying a phonebook application for the details of a given user. All we have is the user's ID.Using Web Services and SOAP, the request would look something like this: ACME Boomerang Used by Coyote in Zoom at the Top, 1962 17.32 http://www.acme.com/parts/3322 ACME Dehydrated Boulders Used by Coyote in Scrambled Aches

6. Real REST Examples

2008-02-12T19:00:00.000-08:00
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:

7. AJAX and REST

2008-02-12T18:30:00.000-08:00
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

8. REST Architecture Components

2008-02-12T18:00:00.000-08:00
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

9. REST Design Guidelines

2008-02-12T17:00:00.000-08:00
Some soft guidelines for designing a REST architecture:Do not use "physical" URLs. A physical URL points at something physical -- e.g., an XML file: "http://www.acme.com/inventory/product003.xml". A logical URL does not imply a physical file: "http://www.acme.com/inventory/product/003".Sure, even with the .xml extension, the content could be dynamically generated. But it should be "humanly

10. ROA vs. SOA, REST vs. SOAP

2008-02-12T16:00:00.000-08:00
ROA (REST Oriented Architecture) is just a fancy name for a SOA (Service Based Architecture) using REST services.The main advantage of SOAP-based SOA over ROA is the more mature tool support; however, this could change over time. Another SOA advantages include the type-safety of XML requests (for responses, ROA can also use XML if the developers desire it).The main advantage of ROA is ease of

11. Documenting REST Services: WSDL and WADL

2008-02-12T15:00:00.000-08:00
WSDL, a W3C recommendation, is the Web Services Description Language. It is commonly used to spell out in detail the services offered by a SOAP server. While WSDL is flexible in service binding options (for example, services can be offered via SMTP mail servers), it did not originally support HTTP operations other than GET and POST. Since REST services often use other HTTP verbs, such as PUT and

12. REST Examples in Different Languages

2008-02-12T14:00:00.000-08:00
The following sections provide brief examples for accessing REST services in different programming languages. More than anything else, they present mechanisms for sending HTTP GET and/or POST requests in each language; the rest of using REST is simply a matter of architectural design.You might wish to skip directly to your language of choice (the list is alphabetical): C#

12.1. Using REST in C#

2008-02-12T13:00:00.001-08:00
Issuing HTTP GET RequestsThe key classes here are HttpWebRequest and HttpWebResponse from System.Net. The following method issues a request and returns the entire response as one long string: static string HttpGet(string url) { HttpWebRequest req = WebRequest.Create(url) as HttpWebRequest; string result = null; using (HttpWebResponse resp = req.GetResponse()

12.2. Using REST in Java

2008-02-12T12:00:00.000-08:00
Issuing HTTP GET RequestsThe key class here is HttpURLConnection, obtained by invoking openConnection on a URL object. Sadly, openConnection method's signature specifies that it returns the superclass type, URLConnection, and we have to downcast the result.The following method issues a request and returns the entire response as one long string: public static String httpGet(String urlStr) throws

12.3. Using REST in JavaScript

2008-02-12T11:00:00.001-08:00
The page discusses sending REST requests from client-side (in-browser) JavaScript. If you're using server-side JavaScript, see your server vendor's documentation for creating HTTP requests.If you have developed AJAX applications, all this will seem trivial to you: after all, every AJAX request is an HTTP request, and in many ways, AJAX applications are RESTful.Creating XMLHttpRequest

12.4. Using REST in Perl

2008-02-12T10:00:00.001-08:00
To work with HTTP in Perl, we will use LWP -- the Library for WWW in Perl.Issuing GET RequestsGET requests are pretty trivial with LWP, especially if you don't care much about setting headers in the request or reading headers in the response:use LWP::Simple; my $url = 'http://www.acme.com/products/3322'; # ACME boomerang my $response = get $url; die 'Error getting $url' unless defined

12.5. Using REST in PHP

2008-02-12T09:00:00.000-08:00
Issuing GET RequestsModern versions of PHP make it trivial to GET web pages: any file-access function (even include!) works seamlessly with URLs, too. Thus, you can use fopen, file_get_contents, and any other file-reading function to issue GET requests. For example:$url = "http://www.acme.com/products/3322"; $response = file_get_contents($url); echo $response;Any parameters passed to GET requests

12.6. Using REST in Python

2008-02-12T08:00:00.000-08:00
Issuing GET RequestsThe Python module urllib2 makes reading URLs trivial:import urllib2 url = 'http://www.acme.com/products/3322' response = urllib2.urlopen(url).read()Errors are reported as exceptions (urllib2.HTTPError or urllib2.URLError).Issuing POST RequestsA POST request is just as easy, simply passing (encoded) request data as an extra parameter to urlopen, thus:import urllib import

12.7. Using REST in Ruby

2008-02-12T07:00:00.000-08:00
As with Python, sending HTTP requests in Ruby is extremely easy.Issuing GET RequestsWe use the class Net::HTTP to do all the magic:require 'net/http' url = 'http://www.acme.com/products/3322' # ACME boomerang resp = Net::HTTP.get_response(URI.parse(url)) resp_text = resp.bodyThe response field code contains the HTTP response code. To make things simpler, the result object's very class indicates

13. For More About REST

2008-02-12T02:00:00.000-08:00
Purely academic: the notion of REST was created in the PhD dissertation of Roy T. Fielding.Mostly academic: the Wikipedia article about REST.JSR 311 is the Java Specification Request for "JAX-RS: The Java API for RESTful Web Services".At the time of writing (Feb '08), still in draft review stages.Check out this presentation for a good overview of the JSR.Restlet is suggesting an easier way to

14. Questions and Answers

2008-01-12T23:00:00.000-08:00
In this section, I'll be adding common questions about REST, or real issues I've encountered while developing RESTful services. If you have a question, feel free to post it as a comment on this page, or on any other relevant page in this tutorial. Questions posted so far: How do I perform atomic operations using REST? How do I delete items using a REST API? How do I handle authentication in

14.1. How do I perform atomic operations using REST?

2008-01-12T22:50:00.000-08:00
QUESTION: How do I perform atomic operations using REST? If I would like to execute multiple operations, but have them all appear as an single, atomic transaction, REST seems inappropriate.ANSWER: REST faces the exact same problem as SOAP-based web services with regards to atomic transactions. There is no stateful connection, and every operation is immediately committed; performing a series of

14.2. How do I delete items using a REST API?

2008-01-12T22:40:00.000-08:00
QUESTION: How do I provide a REST API for deleting resources in the system (e.g., a record from a database)? I was told that using a simple GET API, or even POST, is inappropriate, but I don't know why. ANSWER: There's a well-known story about a company that had its entire database wiped out by Google. Why? Because they had a "delete" link on every web page, and Googlebot crawled all links it

14.3. How do I handle authentication in REST?

2008-01-12T22:30:00.001-08:00
QUESTION: Most services require user to login before exploring further. If cookies are not recommended in REST, does it mean I have to go thru authentication on every single request (e.g., HTTP AUTH)? ANSWER: There are two basic approaches here. The first is, use HTTP AUTH. The (human) user will be prompted for the credential just once (or they will be loaded from file, depending on the system