REST — Stop calling your HTTP APIs as RESTful APIs (Part 1)

In my recent conversations with many developers on REST, many of them claimed they are building RESTful APIs. We certainly know what REST is. But the only catch was what the developers thought they were building was not truly REST!

And that’s why I decided to pen down my thoughts on this topic to succinctly express in two separate blogs about something that is difficult to implement.

In my opinion, building/designing a RESTful application is very herculean task as it requires description of complications in the most simple manner, using simpler terms. I mean, describing all the functionalities using only CRUD functions is tricky. But if you manage to accomplish that, your life would be a lot simpler and you will figure out ways to shorter methods.

So, lets begin with why developers are confused with HTTP APIs?

1. Most developers always associate REST with HTTP and that’s where the confusion arises. Just to steer clear of the head scratching moments, any transfer protocol can be used to create a RESTful API. REST is not necessarily tied to HTTP. RESTful web services are just web services that follow a RESTful architecture.
2. HTTP is a contract, a communication protocol and REST is a concept. It is an architectural style which may use HTTP, FTP or other communication protocols but is widely used with HTTP. REST implies a series of constraints about how Server and Client should interact. HTTP is a communication protocol with a given mechanism for server-client data transfer. It’s most commonly used in REST API just because REST was inspired by WWW (world wide web) which largely used HTTP before REST was defined, so it’s easier to implement REST API style with HTTP.
3. Another misconception is the use of HTTP methods to retrieve, create, update and delete entities on the server. This has nothing to do with REST itself and is simply part of the HTTP RFC.
4. Next, people think that defining nice URIs for resources, like /customer or /cusrtomer/1, falls under REST constraints. REST, just like HTTP or the URI RFC, could not care less how you name your resource identifiers (URI stands for Unique Resource Identifier). All they care about is that they are unique.

OK, So what is REST then?

Let me give you some history behind REST before deep-diving into the topic.

Given the new, rapidly growing demand and use case for the Web, many working groups got formed to develop the web further. One of these groups was the HTTP Working Group, which worked on the new requirements to support the future of the growing World Wide Web. One member of the HTTP Working Group was Roy Thomas Fielding, who simultaneously worked on a broader architectural concept called Representational State Transfer — REST.

So REST architecture and HTTP 1.1 protocol are independent of each other, but the HTTP 1.1 protocol was built to be the ideal protocol to follow the principles and constraints of REST.

REST stands for REpresentational State Transfer.

It means when a RESTful API is called, the server will transfer to the client a representation of the state of the requested resource.

For example, when a developer calls Instagram API to fetch a specific user (the resource), the API will return the state of that user, including their name, the number of posts that user posted on Instagram so far, how many followers they have, and more.

The representation of the state can be in a JSON format, and probably for most APIs, this is indeed the case. It can also be in XML or HTML format.

REST doesn’t add any specific functionality to HTTP. But is an architectural style that was developed alongside HTTP and most commonly uses HTTP for its application layer protocol.

REST is a set of ‘rules’ (or ‘constraints’) defining the characteristics of the optimal application for a distributed hypermedia system, like the World Wide Web. After all, Roy Thomas Fielding put those constraints together so people could improve the WWW and create applications that are scalable, performant, fault-tolerant and extendable. The more constraints you follow, the stronger your web API becomes and the harder it becomes to create.

I hope this simplifies REST for you. Stay tuned for the next blog to learn about the architectural constraints of REST.

Leave your thoughts in the comment section below.