Calling your web API "RESTful"? You're doing it wrong.

by Thibault - May 11, 2016

UPDATE 2019: This post resulted from my frustration trying to figure out the right approach while writing Master Ruby Web APIs. I’ve chilled out since then, and published a post on my views of REST & Co. these days: REST in peace.

After digging into REST and various RFCs, I’m really wondering why developers still call their APIs “RESTful”. Who was the first guy who decided to pin “RESTful” on his API? Did he actually read Fielding’s dissertations? I have my doubts…

Disclaimer: I’m not going to tell you to create RESTful APIs. The goal of this article is to make you stop calling your APIs RESTful when they are just HTTP APIs. If you really want to call your API “RESTful”, start by building one.

If you go full berserk with REST (as you should, because there is no middle-ground), you will not find a single web API that respects all the constraints. This means there are not RESTful APIs.

REST constraints define how the World Wide Web works (or should work in an optimal way). Those constraints were put together more than 15 years ago when most of the HTTP requests were sent by browsers with human ready to understand the representations and take decisions. These days, web APIs clients tend not to have the human component anymore. Instead, decisions must be programmed. This usually creates a tight coupling between client and server which can be partially reduced by applying the hypermedia constraint.

Web APIs clients (e.g. programmed iPhone app) are not the same as websites clients (e.g. web browsers) which delegate all decisions to humans.

Most websites and web applications are not actually truly RESTful. Cookies, used by pretty much everyone for sessions, clearly violate the Stateless constraint of REST. At least, nobody calls their website RESTful so people can’t come and say:

REST is a good set of constraints defining the characteristics of the optimal application for a distributed hypermedia system, like the World Wide Web. After all, Fielding put those constraints together so people could improve the World Wide Web 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. But, as I said earlier, there is no middle-ground in Fielding’s dissertation. You either follow all constraints and build a RESTful application or you don’t. Period.

What I’m saying here is nothing new. A lot of people have pointed it out before. Sadly, most people still don’t understand REST. Fielding himself said how annoyed he was that REST became the buzzword it is today.

Once again, what is REST?

REST, or REpresentational State Transfer, is an architectural style made up of a set of constraints for distributed hypermedia systems like the World Wide Web.

REST was defined in Roy Fielding’s dissertation. It’s not a standard. It’s a smart guy’s dissertation about how things should be designed in a distributed hypermedia system.

There are 6 constraints in the REST architectural style:

Client-Server
Stateless
Cache
Uniform Interface

Identification of resources
Manipulation of resources through these representations
Self-descriptive messages
HATEOAS

Layered System
Code-On-Demand (optional)

I won’t go into the details of those constraints in this article but there will be one coming soon that explains each constraint with easy-to-understand examples.

Quick note about REST vs RESTful. REST is the name of the architectural style while RESTful is a wrongly and overused adjective for web APIs.

The REST vs SOAP nonsense

People often put REST in opposition to SOAP. Indeed, you can see many articles and Stack Overflow questions with ‘REST vs SOAP’ in the title. The good news is that most of these results are quite old so things seem to be getting better. \o/

Putting protocol (HTTP) versus protocol (SOAP) is alright. Architectural style (REST) vs protocol (SOAP) doesn’t make any sense.

What they really want to say is that they are building an API that relies on HTTP instead of a specialized protocol used for web services like SOAP. Basically, they are building an HTTP API.

SOAP actually relies on HTTP (or SMTP) for data transmission, therefore, a SOAP API can be called an HTTP API. Luckily, they are called web services and are slowly disappearing from the surface of the Earth.

By the way, REST is protocol-agnostic so it does not have any close relation with HTTP. You could use any transfer protocol (SNMP, SMTP, etc) and still call your API RESTful (if you are respecting all the constraints of course).

What people think RESTful applications are

I did a bit of research to see what people consider a RESTful application these days and my conclusion is that a lot of people don’t understand REST. I’m not saying that’s your case and I really hope you know what REST really is.

First, developers always associate REST with HTTP. When they say they are building a RESTful API, you can be sure it’s just a basic HTTP API. We’ve seen above that it’s simply not true. Any transfer protocol can be used to create a RESTful API.
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.
Next, people think that defining nice URIs for resources, like /users or /users/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. It could be /MySuperUsers, /fkofekdl or [2001:db8::7]/c=GB?objectClass?one and it would be alright. Obviously, you and I, we wouldn’t like it. We want to understand what is the resource represented by the URI and to do that, we give them good and simple names. That’s a best practice for HTTP APIs and we can make super clean URIs thanks to the use of HTTP methods (GET, POST, etc). No need to call anything /get_users for example since GET /get_users would be quite redundant.

Did I forget anything about how most people see RESTful applications? Please let me know in the comments! From my short research and my personal experience, those are the 3 that came up the most.

In The End, It doesn’t even matter.

You don’t want to apply all the REST constraints? Fine, just don’t call your API “RESTful”. I don’t really care about what you are actually building. On the other hand, I kind of care about overused buzzwords. For some reason, it tends to really annoy me.

Buzzword Fun: BIG DATA. CLOUD. GROWTH HACKING. SERVERLESS ARCHITECTURE.

No, your API is not RESTful, end of the story. There is no pragmatic RESTful, dogmatic RESTful and no RESTafarian. Those terms are just meaningless to be honest. They were just made up by people who don’t understand REST or HTTP. :/

You’re either building an HTTP API following best practices or you’re building a RESTful API.

The good news is that no one is going to scream at you for building a non-RESTful API: everyone is doing it!

Let’s take an example. We talked earlier about cookies and how they violate REST Stateless constraint. Likewise, a RESTful API should not have any session mechanism where the client state is kept on the server. So if you have /login and /logout in your API, you are breaking the Stateless constraint. If creating a real Stateless authentication system is too much of a pain for you, then don’t. You know what I’m going to say now: just don’t call your API RESTful ;)

You can keep calling your APIs RESTful but at least now you know that you’re wrong: just call it what it is, an HTTP API. Nobody will judge you and you will help stop the buzzword propagation.

Do you really want to build RESTful APIs?

Building RESTful web APIs is not easy. The good news is that you don’t need to be REST-compliant to build awesome APIs. Just look at all the web APIs available today. While they are not RESTful, the businesses behind are still thriving, providing services and making money.

Obviously, they had to compensate the areas where they are lacking and not following REST constraints. Let’s take scalability for example. The Stateless constraint allows an application to grow more easily since the server is not keeping any state of the client. In reality, keeping the client state can often be a requirement. That means that developers need to handle more complex clusters of servers with interconnected stores for client states… It’s more complicated indeed but if it means making more money for a business, I’m guessing they will be fine with the AWS bill.

Your API does not have to be RESTful to be awesome.