3. How Simple is REST?

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:

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
 <soap:body pb="http://www.acme.com/phonebook">
  <pb:GetUserDetails>
   <pb:UserID>12345</pb:UserID>
  </pb:GetUserDetails>
 </soap:Body>
</soap:Envelope>

(The details are not important; this is just an example.) The entire shebang now has to be sent (using an HTTP POST request) to the server. The result is probably an XML file, but it will be embedded, as the "payload", inside a SOAP response envelope.

And with REST? The query will probably look like this:

http://www.acme.com/phonebook/UserDetails/12345

Note that this isn't the request body -- it's just a URL. This URL is sent to the server using a simpler GET request, and the HTTP reply is the raw result data -- not embedded inside anything, just the data you need in a way you can directly use.

  • It's easy to see why Web Services are often used with libraries that create the SOAP/HTTP request and send it over, and then parse the SOAP response.
  • With REST, a simple network connection is all you need. You can even test the API directly, using your browser.
  • Still, REST libraries (for simplifying things) do exist, and we will discuss some of these later.

Note how the URL's "method" part is not called "GetUserDetails", but simply "UserDetails". It is a common convention in REST design to use nouns rather than verbs to denote simple resources.

The letter analogy
A nice analogy for REST vs. SOAP is mailing a letter: with SOAP, you're using an envelope; with REST, it's a postcard. Postcards are easier to handle (by the receiver), waste less paper (i.e., consume less bandwidth), and have a short content. (Of course, REST requests aren't really limited in length, esp. if they use POST rather than GET.)

But don't carry the analogy too far: unlike letters-vs.-postcards, REST is every bit as secure as SOAP. In particular, REST can be carried over secure sockets (using the HTTPS protocol), and content can be encrypted using any mechanism you see fit. Without encryption, REST and SOAP are both insecure; with proper encryption in place, both are equally secure.

22 comments:

Unknown said...

thanks for a great article.

So even a query needs to be sent to a server via a HTTP POST? Why is that? Why is it not using a GET?

GET's are not supposed to have any side effects. Why is that not appropriate to use here?

Dr. M. Elkstein said...

Not at all -- with REST, queries are normally send using GET. You can use POST, but you rarely have to (e.g., for requests which contain a large amount of data, such as detailed form submissions.)

Demetris Kyriacou said...

Hello Dr

In this example, where is method UserDetails located?

http://www.acme.com/phonebook/UserDetails

1)http://www.acme.com/phonebook/ is the directory

2)UserDetails is the method...but where is this method located? if it exists in (for example) the java file Test.java then how can i construct the URL? is it going to be:

http://www.acme.com/phonebook/Test/UserDetails?

please help me out with this because it's a little bit confusing to me...thank you

Dr. M. Elkstein said...

Most web development languages are geared towards the path?query URL format (e.g., http://www.acme.com/phonebook/UserDetails?id=12345). And in most cases, the easiest way to support cleaner, more elegant URLs (like .../UserDetails/12345) is by URL rewriting. The trick is to configure your web server (e.g., Apache httpd) to internally process any request formatted in one way (.../UserDetails/12345) as if it was formatted in another way (.../UserDetails?id=12345). The rewriting translation from one format to the other is normally a trivial regular-expression conversion.

nileshw said...

Hello Elkstein,

Its really a nice blog to understand REST. Thanks for writing it.

For the letter analogy you have given, I have one question. In case you use envelope, your message is hidden. While for postcards, it's open. Does this apply to REST vs. SOAP?

Thank you.

Dr. M. Elkstein said...

Hello nileshw,

That's a very important question. The envelope/postcard analogy is in fact broken with regard to security, since both SOAP and REST are equally secure (or insecure -- depending on how you use them). I've updated the text in this page to reflect this fact. Thank you!

admin said...

Hi Dr. Elkstein,
Can I have your email? I have some REST web devlopment questions which I'm currently stuck. I need someone to shed some light on the problems I face.

Thanks,
John Maxim

Dr. M. Elkstein said...

Dear John,

I'm sorry, but I can't personally support developers. I recommend that you try posting your questions on a community Q&A service like StackOverflow.

admin said...

ok sure, thanks Dr. Elkstein.

Unknown said...

Thanks for your wonderful article.

Can u provide some information about PUT operation in REST. Is it actually refers to update or overwrite the value?

Dr. M. Elkstein said...

Hello nickai,

The HTTP standard defines PUT as a request, by the client, to store a resource as the given URL (see RFC 2616). So, in the context of REST, it can be used for updating existing objects, or creating new ones.

Of course, the HTTP protocol "makes damn sure [that a server has] absolute authority over its own resources" (see Understanding HTTP Put). This means that PUT does not force the server to do anything -- it can reject the request.

I repeat that I personally prefer to use only GET or, at most, POST requests for REST services, including update requests; this allows me to test the requests with a browser or a simple wget command. Of course, delete/update operations must require proper authorization as part of the request. (But that's also true for PUT or any other verb.)

Sahay Collection said...

Thanks for this great article..
It's clear the basic idea of rest very nicely....

Unknown said...

Thanks for the great post on your blog, it really gives me an insight on this topic.

JEG said...

I dont quite understand how I would ie. get the first name only
phonebook/UserDetails/FirstName/1231
and to get all details it would be
phonebook/UserDetails/1231

If we use rewrite how does the rewrite know what are methods and what are arguments?

Dr. M. Elkstein said...

Hi JEG,

To use URL rewrites, the URL should be consistent; I think my examples were consistent, but I could be wrong. For example, one URL could be "phonebook/FirstName/1231", while the other is "phonebook/UserDetails/FirstName/1231". There is no confusion in this case. Alternatively, you could use "phonebook/UserDetails/FirstName/1231" vs "phonebook/UserDetails/AllDetails/1231", etc.

Mehul Chauhan said...

Nice explain in technical terms and by using normal human activity of letter sending and receiving.

Thanks

Unknown said...

Very Simple yet very effective way of explaining . Thanks!

Tech-Route said...

Can we say that a simple get/post http call is a rest call. Is it mandatory to use any frameworks like restful, soap to build rest based apps. Even restfull is a wrapper over Http. I think if I create a simple get resource using javax.servlet.http.HttpServlet (in java) then its a rest endpoint. Please correct me if I am wrong.

Dr. M. Elkstein said...

Hello "tech route",

Not "every HTTP call is a REST call" -- REST is an architecture design. But if your system uses this kind of design, then yes, REST calls are simply HTTP GET/PUT calls, and all those wrappers and libraries are hardly required (although they can sometimes be useful, depending on your specific requirements).

Anonymous said...

Hello Sir,
Thanks for the article. I have one question.
Please can you correct me if i am wrong.
Both the forms, REST and SOAP based web-services are secure, but SOAP based services provides message level security and transport level security when we use HTTPS. Where's as REST can be incorporated with HTTPS for transport layer encryption.

On above scenario ,if any application tries to sends some critical information like CREDIT CARD details, ACCOUNT details etc. How REST service can help us to make it more secure Or just providing a Transport level (HTTPS) security is sufficient to safeguard these critical details.

Dr. M. Elkstein said...

Hello pranavkuthe,

Transport-level security should be enough if all the information is sent in the URL; for HTTPS requests, the URL itself isn't visible (except for the domain name part).

If the request contains a payload (a POST request), that too is encoded when HTTPS is used. And of course, the payload itself can be further encrypted if you so wish, independently of HTTPS.

KCL said...

I've been using the REST approach for the last 7 years. It grew out of disdain for constant ODBC changes, and complexities of using SOAP, server-side scripts, and the like for simple transactions using PCs and Arduino-type devices to collect data and run equipment.