REST : Myths & Facts

REST is probably one of the biggest success stories in the technology world. The seamless integration with HTTP and the JSON revolution did wonders and REST is regarded as the most popular, most adopted API pattern. But is every Api that you tend to write a REST Api? Let us talk about some myths and facts.

REST API ! = Remote Procedure Invocation over HTTP

As developers, whenever there is a requirement for an API, one of the common phrases we hear is “Oh, we can develop a REST API for that”. Fine, nothing wrong with that. But what if the requirement is something actionable? Send an update to the server about a client action, say a button click. Or get some data which involves computation - say get the top ten stories that have performed the best? Can this be called a REST API?

GET /toptenstories

POST /sendaclientupdate

No would be the answer!! These are remote procedure invocations! Whether this is true RPC or not is a different discussion for another day as the key feature of RPC is location transparency. The client makes a local function call but in reality, it jumps the network and executes on the server. But for simplicity's sake I am going to call it Remote Procedure Invocation. The HTTP semantics are not broken here as such, I am using GET to read something and POST to perform something that might change the server state. But what if I mix the two up? This is not good. 

GET /sendaclientupdate

REST is all about resources - modelling the resources. And with HTTP being ubiquitous, we make use of the HTTP toolkit to implement REST-ful systems. In the above examples, we are using HTTP as the transport to invoke remote procedures. And with that comes tight coupling!

One of the key features of REST is HATEOAS and it is regarded as the feature that makes a system completely REST-ful. HATEOAS stands for Hypermedia as the Engine of Application State. This defines the “what next” for every resource.

With a REST API we start with an endpoint like https://myrestapi.mydomain.com. A client can then “browse” the API just like a website can be browsed. Every GET request to a resource gets information about the resource, what actions can be performed on the resource and information about related resources as hypermedia(links). This ensures low coupling between the client and server. The server could change the resource url and given the client uses the hypermedia to “browse” the api, the change in resource url does not affect the client.

REST != JSON over HTTP

This is another knowledge trap developers can fall into with REST. Been there done that! REST as a concept does not specify a transport or a format.

REST is guided by six constraints. REST is an architectural style for distributed systems like the web that runs on HTTP. REST was suggested to standardise the web that runs on HTTP. So there are similarities and crossovers between REST and HTTP. But REST, as a concept, doesn’t say about requiring HTTP as a transport. The gist of REST is the transfer of states (Application State and Resource State) using resource representations. A resource can be represented in a variety of formats - JSON, XML, text, media. REST doesn’t lay out JSON as the format. What makes a RESTful system is the true adherence to the six constraints.

REST != HTTP

REST is an architectural style for distributed systems like the web that runs on HTTP. HTTP is a communication protocol. As explained about there are similarities between the two. But it ends there!

While I knew the last point the first two points were total eyeopeners for me! There is also one more thing I usually say in my talks about API paradigms. REST was not designed for APIs. It was designed for the web and API is not quite the web. While we can perfectly imagine how a human would interact with hypermedia it is not that easy with a client simulating this for APIs. This actually increases the barrier to true REST-ful APIs(HATEOAS being that barrier). The quickest win in such instances is to remove HATEOAS. This could be the reason why most of the APIs in the world fall into the Level 2 of the Richardson Maturity Model. But this introduces a certain level coupling between client and server.