There is a Core Principle of REST API that No One Follows

In the crowded world of web development, REST API has become a "too much popular" term. From startups to tech giants, everyone claims to offer a RESTful interface. It's on job listings and anywhere devs are talking about it. But here's a twist: Most of us are doing it wrong.

The author of REST is Roy Fielding, and his Ph.D dissertation in the year 2000 defines it. Yet, his most profound idea remains ignored. Fast forward to 2008, long after REST had become a famous word. Fielding wrote in his blog: "I am getting frustrated by the number of people calling any HTTP-based interface a REST API". The man who works behind the entire web industry is seeing his core principle forgotten.

That principle is HATEOAS, or Hypermedia as the Engine of Application State. It's not just a feature, it's the very soul of REST. Oddly enough, it's the one part most "RESTful" APIs ignore.

Let's take a look at some API JSON responses that follow HATEOAS principle:

The JSON have "_embedded" and "_links" properties that provide hypermedia control to guide API consumers. For example:

What Are The Benefits?

• The API consumers don't need hardcoded information on API structure. They just adapted based on the links provided.
• Let's say the back-end changes API endpoint from `/api/book/{bookId}` to `/api/v2/book/{bookId}`. The app still works and no need to do one of these processes which were frustrating: Update the endpoint -> Update all API documentation -> Email all API consumers telling them to update API endpoint by deadline -> Some clients miss the memo, their apps break -> We maintain both old and new endpoints during transition.
• Progressive Enhancement: Today: View, Edit, Delete actions. Tomorrow: Add "Borrow" link to book details. The React app instantly supports it without changes.
• Intuitive Data Relationships: The genre link in book details makes it clear that genres are explorable resources.
• Form Handling: In a full HATEOAS API, even form structures could be dynamic. The API might provide a template: { "template": { "title": "", "author": "", "genre": ["list","of","options"] } }.
• Error Handling: If a request fails, the API could return links like {"_links": { "retry": {...}, "support": {...} }}.

And many more fundamentals of HATEOAS require more of your research. Properties _links and _embedded is HAL (Hypertext Language Format), which is one of the most popular media types for implementing HATEOAS in REST APIs.

Some Tech Giants Used It

Between 2012 and 2014, Netflix re-architected their API around HATEOAS principles. Daniel Jacobson, their API chief at the time, wasn't equivocating when he stated in a 2014 presentation: "HATEOAS is the backbone of our API evolution."

Netflix's success with HATEOAS isn't an isolated incident. PayPal, mired in the complexity of SOAP web services in the late 2000s, transitioned to REST architecture with HATEOAS implementation around 2011.

So why does HATEOAS still remain unpopular?

The answer may lie in psychology:

• Instant Gratification: Quick to build 'REST' APIs, HATEOAS feels slow.
• Some Bias: "Everyone uses Swagger, why bother?"
• Dunning-Kruger Effect: Overconfidence in our REST understanding.

In summary, with a HATEOAS-driven API, our client application becomes much more adaptable and resilient. It doesn't just consume data; it learns how to interact with the API in real time. This design leads to a more maintainable, evolvable, and truly RESTful architecture. As the API grows and changes, the front-end gracefully adapts, guided by the hypermedia controls in each response.

Related article:

https://intercoolerjs.org/2016/01/18/rescuing-rest

Roy Fielding 2008's blog: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

#frontenddevelopment #backenddevelopment #softwaredevelopment #HATEOAS #RESTAPI #API #wecommit100xshare