No your API isn't REST, but don't worry, it really shouldn't be!

Published on 2015-11-01. Modified on 2023-10-25.

In 2008 Roy T. Fielding expressed his frustration with people calling their HTTP-based interfaces for REST API's when in fact they aren't. Today in 2023 nothing has changed, people are still calling their HTTP-based interfaces a REST API, even though they are not. But that's not the worst part of all of this, the worst part is that no HTTP driven API should try to be REST in the first place!

Representational State Transfer (REST) is the software architectural style of the World Wide Web. REST was initially proposed by Roy T. Fielding in his 2000 PhD dissertation Architectural Styles and the Design of Network-based Software Architectures. Fielding developed the REST architectural style in parallel with HTTP 1.1 of 1996-1999, based on the existing design of HTTP 1.0 of 1996.

REST provides a set of architectural properties or constraints that define how specific applications should function. When an application fulfills those properties and constraints, it is considered REST. If an application violates any of the requirements, it is not a REST application, no matter how much someone wants it to be.

The ST part of REST formulates how clients and servers should communicate on a RESTful system. The client-server communication must be stateless, meaning that no client context is stored on the server between requests. Each request from any client contains all the information necessary to service the request, and session state is held in the client.

Furthermore, and this is a very important point, a REST service should be entered with no prior knowledge beyond the initial URI and a set of standardized media types that are appropriate for the service, which again is expected to be understood by any client that might use the service.

Roy T. Fielding writes:

From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user's manipulation of those representations. The transitions may be determined (or limited by) the client's knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand).

What does this mean exactly? The best way to understand it is to think of a simple website.

  1. A user enters (the initial root URI) with absolutely no prior knowledge about the website except for the URI itself.
  2. The user is presented with a set of media types, such as links, that the user can click on. These links represents different resources on the website, such as "products", "contact", "search", etc.
  3. The user clicks on a link or writes something in the search field.
  4. The user is then physically redirected to a product or a search result.

If no representation exist beyond the initial root URI, and no further links (media types) are provided by the responses of the server, there is no way to determine how the application state transition can proceed! This is REST!

If your application needs documentation, also referred to by some as a "profile", in order for the client to use your resources beyond the initial root URI, then that is NOT REST!

Prior to REST, a program was hard-coded to a set of known resources on a server. You had to re-code the program to access new resources. After REST, programs let you connect to servers that provide you with a list of resources you could go to without any prior knowledge what so ever. The service provider controls your experience. He can remove links, create new links, remove media content, add new media content, it doesn't matter, the client (a browser in this case) doesn't need to know anything about that prior to entering the service. This paradigm shift cannot be understated. This is what gives REST its power!

X (formerly known as Twitter), Facebook, Google, and thousands of other projects, are all calling their HTTP-based interfaces REST API's when in fact they are not. None of these API's can be used by a client application without prior knowledge beyond the initial root URI. The client has to be hard-coded to access a resource, and if a resource changes, the client needs to be re-coded. In order to use any of these API's you need to study their documentation and you need to hard-code your client. This is not REST!

REST applications are for people, not machines!

REST is fantastic because the client doesn't need to know anything about a server beyond the initial root URI and a set of media types and how to handle those. The server can change all resources from day to day, it doesn't matter, the client doesn't need to know.

The reason why this works, is because a human being is interacting with the client application. As soon as you remove the human part, REST works horribly. You always need the human part to interpret changes and use the client.

Computer applications cannot think and they cannot act intelligently upon change. An Application Programming Interface (API) is an application build upon a set of functions or methods and protocols that defines functionality which other applications can "interface" with and use. In other words, an API is not "a program for people" it is "a program for machines", which means that it is meant to be used by other programs, i.e. not people.

Let's say I would like to build a website that presents users with daily updated exchange rates. Every morning I would have to go to some exchange service to note down all exchange rates and then insert those unto my website. Later, if the rates change, I would have to do it again. That's not very efficient. Now, if the exchange service provides an API I can program my website to interface with that API and fetch exchange rates in real time. And let's say I did that. And let's say my website is great and lots of people are visiting my website to get exchange rates, but suddenly the exchange service changes their API functionality. Suddenly my website isn't working, no exchange rates are fetched any longer because my program no longer knows how to fetch data from the new API they have made. This situation can never happen with a true RESTful system!

This demonstrates why an API shouldn't try to be REST. It can never be REST. It is wrong to call an API RESTful.

Yes, I can subscribe to some mailing list or SMS service and receive information about changes, and yes I can study documentation and even program my client to understand a specific set of profiles, but that's besides the point and has nothing to do with REST. If the system is really REST then I wouldn't need to change my client at all, it would still work. In a REST system the client must not care about change. All the client must care about is protocols and media types.

Why is it then that everyone think they should develop API's using REST? Who came up with that strange idea in the first place?

Square being jammed into a round hole

Let's face it! REST and API just don't match!

REST does provide application specifications that can be adopted and implemented by API's to some degree, as long as those API's don't try to be completely RESTful, and as long as those API's don't get promoted as RESTful systems.

Roy T. Fielding's own words really sums up the problem with so-called REST API's of today. Please note that he wrote this back in 2008 and it still applies today in 2023.

What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?

An API is never driven by hypertext, it cannot be because hypertext is for people, not for machines.

In their book RESTful Web API's Leonard Richardson, Mike Amundsen and Sam Ruby tries to address some of the problems web developers face when trying to make their API's RESTful. The book is great, it has some interesting ideas, but they completely miss the point. They are still trying to jam web API's into the REST architectural style of the World Wide Web.

We need to face the fact that web API's by nature are inherently contrary to REST. Then we need to come up with a new architectural style specifically developed for web API's. We can borrow some of the REST specifications, but we cannot, and should not, try to make web API's RESTful.

Instead we need to develop a set of standards for web API's just like we have the HTML standards. Such a standard could contain specifications and constraints on resource implementations, naming conventions, document presentation and so on. However, the purpose of such a standard is not to make web API's RESTful. The purpose would be to create web API specifications that would make client implementation more uniform across systems.

The benefit should be apparent. Even though each web API is unique in some way, and even though you still need to hard-code your client, common denominators between API's now exist which makes it easier to develop clients for different web API's. But that has still nothing to do with being RESTful what so ever.

I will end this article by another quote from Roy T. Fielding:

The reason to make a real REST API is to get evolvability ... a "v1" is a middle finger to your API customers, indicating RPC/HTTP (not REST)!