I run into business developers who don’t know what REST is. REST stands for Representational State Transfer. That’s a complicated phrase for a very simple concept - using HTTP GET/POST/etc. as an API. Even that can be confusing because most people will say, how is that any different from a normal web application? In many respects, it’s not any different. The main “extension” to a normal web app is that REST uses parts of HTTP that most people don’t even know exist, like PUT and DELETE.

Most developers know that HTTP has a GET and POST but many have never heard of PUT and DELETE. Don’t feel like the lone ranger if you didn’t know they existed. Web server and application server makers ignored them as well - and thus they can’t be used on many platforms. For that reason you’ll see many REST server implementations “fake” PUTs and DELETEs by putting the operations in the URLs.

That’s all well and good, but, so what? What, if anything, does this buy us that a normal web application wouldn’t? How is this any better then SOAP? Or XML-RPC? Very good questions. SOAP stands for Simple Object Access Protocol. It was originally intended to be a simple mechanism to exchange structured information between computers. Despite the “Simple” part it has become very complex. Over time it was noticed that most uses of SOAP were for remote procedure calls (RPC) over HTTP. And it was additionally noticed that the overhead of SOAP was pointless for most users.

A quick aside, SOAP is complicated because it covers many areas that REST doesn’t, like common data formats and security. REST implementations have to re-roll this support if they need it.

Implementers looked around for a simpler approach and decided that they liked the HTTP part but didn’t care for the SOAP overhead. Additionally, most decided that they didn’t want the XML verbosity either. They wanted very simple interfaces. So, it’s become common for REST interfaces to use JavaScript Object Notation (JSON) as the data format. JSON is, literally, JavaScript. It’s a tiny subset that defines data. JSON can’t contain code, just definitions. If you evaluate it in a browser, you get a variable with data. Here’s a quick snippet:

"volumes" : [
  {
    "name" : "public_data",
    "uri" : "http://xrgy.cloud.sun.com/volumes/001",
    "snapshot" : "http://xrgy.cloud.sun.com/snapshot?volume=001"
  }
]

Now that we’ve described the background of all the pieces in REST, we come to the fun part, actually seeing a REST interface in action. Sun’s evolving specification for a cloud definition and control API is REST, and it’s what I’ll use as the examples (see http://kenai.com/projects/suncloudapis/pages/HelloCloud).

Send:

GET /

Get back:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.sun.cloud.compute.Vdc+json
Content-Length: nnn

{
  "name" : "XRGY Virtual Data Center",
  "uri" : "http://xrgy.cloud.sun.com",
  "tags" : [ ],
  "volumes" : [ ],
  "vm-templates" : "http://cloud.sun.com/resources/template-cat.json",
  ... other fields omitted for readability ...
  "clusters" :  [
    {
      "name": "cluster1",
      "uri": "/clusters/cluster1",
      "deploy-status" : "UNDEPLOYED",
      "tags" : [ ],
      "create-vm" : "/clusters/cluster1/ops/create-vm",
      "controllers" : [
        "deploy" : "/clusters/cluster1/ops/deploy",
        "start" : "/clusters/cluster1/ops/start",
        "stop" : "/clusters/cluster1/ops/stop",
        "undeploy" : "/clusters/cluster1/ops/undeploy",
      ]
    }
  ]
  ... other fields omitted for readability ...
}

This returns back JSON that describes the virtual data center environment. Take a look at the Sun web page for the full example, this one is cut down severely for brevity. To create a new VM in the virtual data center:

Send:

POST /clusters/cluster1/ops/create-vm

 {
   "name" : "Database"
   "from-template" : "http://cloud.sun.com/resources/vmtemplates/003",
   "description" : "MySQL host",
   "tags" : [ "sql" ]
 }

Get back:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.sun.cloud.compute.VM+json
Content-Length: nnn
Location: http://xrgy.cloud.sun.com/vms/001

{
  "name" : "Database"
  "uri": "/clusters/cluster1/vms/001",
  "model-status": "UNDEPLOYED",
  ... other fields omitted for readability ...
  }
}

And that’s it. To delete something, you send a DELETE with the name/id of the thing to delete (a VM, a cluster, etc.). To update something, you send a PUT with the name/id. Like SOAP, REST is stateless. And because it uses straight HTTP it is extremely scalable.