REST Series‎ > ‎

REST vs RPC - What is RESTful?

In all software engineering, there are few terms as buzzwordized or overdefined as REST.  One of the most common misconceptions is that anything that uses HTTP verbs such as GET, PUT, POST rather than using SOAP bindings to expose a service endpoint is called "RESTful".  This blurring of the line between REST and XML-RPC (or JSON-RPC, etc) has some pretty significant consequences in practice.

Mistaking POX web services for "REST", many web API implementations never fully explore RESTful architecture, thereby missing out on capitalizing on the simplicity and zen of truly RESTful APIs.

REST is not a framework like WCF, a protocol like HTTP, a framework like JAX-RS, or a communication format like SOAP.  REST is an architecture, a structured way of representing a software solution - specifically, exposing aspects of a solution to a set of remote client-consumers.  The central tenet of REST is that these aspects of a solution can be modeled as resources which the client can consume or act upon.  

This resource-oriented thinking, and not the implementation details of how one communicates between client and server, is what REST is actually all about.  This is the key difference that separates actual RESTful APIs from RPC based on HTTP verbs.

Why is this important?
The RESTful approach enables us to model our domain objects as consistent, hierarchical URLs with predictable semantics mapping (loosely) to CRUD.  As well, HTTP comes with standard error codes, MIME types and generally does most of the heavy lifting, so we benefit from not needing to maintain a thick user-developed protocol stack that is subject to frequent modification.

Consider the following example of HTTP APIs that model orders being placed in a restaurant.  
  • The RPC API thinks in terms of "verbs", exposing the restaurant functionality as function calls that accept parameters, and invokes these functions via the HTTP verb that seems most appropriate - a 'get' for a query, and so on, but the name of the verb is purely incidental and has no real bearing on the actual functionality, since you're calling a different URL each time.  Return codes are hand-coded, and part of the service contract.
  • The REST API, in contrast, models the various entities within the problem domain as resources, and uses HTTP verbs to represent transactions against these resources - POST to create, PUT to update, and GET to read.  All of these verbs, invoked on the same URL, provide different functionality.  Common HTTP return codes are used to convey status of the requests.

Placing an Order:
  • RPC:  http://MyRestaurant:8080/Orders/PlaceOrder (POST: <Order OrderNumber="asdf"><Appetizer><Appetizer><Entree>Tacos</Entree><! --Rest of the order--></Order>)
  • REST: http://MyRestaurant:8080/Orders/Order?OrderNumber=asdf (POST: <Order><Appetizer><Appetizer><Entree>Tacos</Entree><! --Rest of the order--></Order>)

Retrieving an Order:
  • RPC:  http://MyRestaurant:8080/Orders/GetOrder?OrderNumber=asdf (GET)
  • REST: http://MyRestaurant:8080/Orders/Order?OrderNumber=asdf (GET)

Updating an Order:
  • RPC:  http://MyRestaurant:8080/Orders/UpdateOrder (PUT: <Order OrderNumber="asdf"><Appetizer><Appetizer><Entree>Pineapple Tacos</Entree><! --Rest of the order--></Order>)
  • REST: http://MyRestaurant:8080/Orders/Order?OrderNumber=asdf (PUT: <Order><Appetizer><Appetizer><Entree>Pineapple Tacos</Entree><! --Rest of the order--></Order>)