Your Tuesday Cheat Sheet to REST

01 Jul 2014

news-articles-rest_cheat_sheet.jpg

Everything and anything you could ever want to know about REST, but not as you know it!

What is REST?

REST (Representational State Transfer) is an architecture style for designing networked applications. The idea is to use simple HTTP to make calls between machines, rather than using complex mechanisms such as CORBA, RPC, or SOAP. The World Wide Web itself can be viewed as a REST-based architecture, which uses HTTP for all CRUD (Create/Read/Update/Delete) operations. REST is a lightweight alternative to other mechanisms like RPC and Web Services, yet it is fully-featured; there's basically nothing you can do in Web Services that can't be done with a REST-based architecture.

How simple is REST?

Compared to Web Services and SOAP, REST is a much simpler architecture. A nice analogy for REST vs. SOAP is mailing a letter: with SOAP, you're using an envelope; with REST, it's just a postcard. Let's take a simple web service as an example: querying an 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:

REST one

(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.

Using REST, The query will probably look like this:

REST two

And 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.

One thing to note is how the URL's "method" part is not called "GetUserDetails", but simply "UserDetails". Using nouns rather than verbs to denote simple resources is a common convention in REST.

However, and unlike the letters-vs-postcards analogy, 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 suitable mechanism. Without encryption, REST and SOAP are both insecure; with proper encryption in place, both are equally secure.

Which request should I use (GET or POST)?

In general, GET requests should be used for read-only queries; they should not change the state of the server and its data. For creation, updating, and deleting data, POST requests are used. POST can also be used for read-only queries, when complex parameters are required.

What about server responses?

A server response in REST is often an XML file; 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).

Is there anyone out there who is actually using REST?

Some real examples of service providers that use the REST API are: The Google Glass API, known as "Mirror API" (a pure REST API); Facebook uses The Graph API (also based on REST); Twitter has a REST API (in fact, this was their original API); other website such as Amazon.com, Flickr, and many more offer REST services as well.

I don’t get it. What are the advantages and disadvantages of using REST?

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. Other 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 implementation, agility of the design, and the lightweight approach to things.

In a way, SOA and SOAP is for people in business suits; that's what you'll find used in the banking and finance industries. Conversely, somebody that needs something up-and-running quickly, with good performance and low overhead, is often better off using REST and ROA.