Are our REST APIs really RESTful

REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution
- Roy T. Fielding

I have had worked on quite a few number of integrations and each time I encountered a documentation or tutorials on REST API, the common inference given was "..okay, its going to be simple compared to SOAP, we will get a JSON/XML, parse it and do the stuff that we want etc...". Is that all about it? I don't think so. If we look at the term REST - REpresentational State Transfer, it tells us some different story. For me I find it a mystery trying to understand how exactly does one transfer the State in a Representational way consuming those APIs. I believe most of us have ignored the definition and more or less our understanding of the actual term have been wrong. Atleast so far, the APIs that I have consumed, I didn't see a State transfer happening inherently when I call the API.

While exploring more and more about the protocol and trying to build and expose a perfect REST based API, I came across articles, posts and publications that all pointed towards Roy T. Fielding's Dissertation - the originator of REST architectural style (way back in 2000). Rest assured, I now knew I never understood what REST was!

Unlike SOAP, REST is an architectural style and not a protocol

HATEOAS (Hypermedia As The Engine Of Application State)

Out of many constraints described in the dissertation and elsewhere for an API to be RESTful, the most important constraint that I felt to be the heart of the REST architectural style is the HATEOAS. I do not claim to have understood it completely because there isn't any concrete precedence that I came across. Having said that, if we try to catch the crux of this constraint using a simple analogy; the way I did, it must make sense that most of the APIs that claim to be REST based are in fact nothing more than plain HTTP APIs because these aren't protocol-agnostic and for different resources we have different APIs, again separated by method (GET, POST, PUT, DELETE etc.)

Roy in response to the question "... what do you think is the reason that so many people who think they are doing REST get it wrong?"

To some extent, people get REST wrong because I failed to include enough detail on media type design within my dissertation. That’s because I ran out of time, not because I thought it was any less important than the other aspects of REST. Likewise, I suspect a lot of people get it wrong because they read only the Wikipedia entry on the subject, which is not based on authoritative sources.

Let us think of it in terms of the Web. Imagine a state where the web browsers need to be aware of the implementation and distinction between different resources a.ka. web applications (e.g. between Facebook and Twitter). Every time a small change is done in the design or implementation of any of these web applications, the web browser has to change the way it interprets the resources (the final HTML pages generated) and renders it to the user, or else it be broken - we refer this as hard coupling.

Fortunately our web is not designed that way. Web application creators and web browsers (I.E is a pain at times though!) all agree to the common specification and standards of the HTML and other constructs of web. As far as the web applications generate the output adhering to those specifications - web browsers need not make any changes - and are totally decoupled with the implementation changes of these web applications. In Roy's words - "...what the browsers need to be aware of is the potential state transitions — the links and forms (Hypermedia) — and what semantics/actions are implied by traversing those links. A browser represents them as distinct UI controls so that a user can see potential transitions and anticipate the effect of chosen actions. Typed relations, specific media types, and action-specific elements provide the guidance needed for automated agents."

What is the takeaway?

REST has come a long way since its inception and the actual definition shaded away. Companies somehow adapted to this ignorance and have improvised their own version/definition. They still chose to keep the term REST associated to the APIs because it was and is a buzz.

The takeaway is, if we really build a true RESTful system then we could get away from the hassle of updating the client applications each time the back-end systems have any implementation changes. That really saves a lot of time and we could focus more on improving and try making our Enterprise applications more robust.

A simple example would be to look at one of the Salesforce API - /vXX.X/sobjects/SObjectName/describe) - they are versioned. Each time a feature is updated or added all the apps that are using those APIs need to be upgraded to ensure the systems aren't broken. Even if the client applications make it configurable, the metadata has to be updated. The point is with true RESTful systems that need should never arise. The information they provide and the purpose they serve indicates they are just HTTP APIs. A describe call doesn't trigger a state transition of any of the resource nor does the response enlist any action for state transition. It is a dedicated API to describe the sObject passed in the URI and that is all it serves.

If and when we build a real RESTful system we no longer need to provide any documentation of the APIs because the client applications/automation agents won't need it anymore. The hypermedia in the response is what guides them regarding the available actions for next state transition - thereafter another response and another set of possible actions for further state transition of the resource(s). To start with, the agent will have only one entry point/URI to trigger the transitions. Just like our web browsers - they don't need any documentation on how they should process the response from [each of] the web applications - they follow the specifications that defines each media type - and, the home page URL is how we make entry to any of the web application. The subsequent transitions are defined by how we interact with the hypermedia on the pages.

And finally a takeaway in Roy's language:

...that doesn’t mean that I think everyone should design their own systems according to the REST architectural style. REST is intended for long-lived network-based applications that span multiple organizations. If you don’t see a need for the constraints, then don’t use them. That’s fine with me as long as you don’t call the result a REST API.

The next time you look at a REST API, do think about it 😊