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

Posted on 01.11.2015 by Kim N. Lesmer. Last updated on 07.03.2016.
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 2015 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 defines 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 a person 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 that mean exactly? The best way to understand this is to think of a simple website.

  1. A user enters www.example.com (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 types something in a search field.
  4. The user is 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!

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!

Imagine opening your browser, typing in some URI that you have no prior knowledge of, and entering a website with no links and no other media types on it. How do you proceed? What URIs can be used in order to proceed and locate other resources on that website?

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. However, the reason why this work, is because a human being is interacting with the client application!

As soon as you remove the human part, REST works horribly! You 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 people program" it is "a machine program", meaning: It is meant to be used by other programs!

Lets 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 that day, if the rates where changed, I would have to do it again. That's not very efficient.

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, without me knowing (how can I know?) 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 would never happen with a true RESTful system. But this should also clearly demonstrate to anyone that an API really shouldn't try to be REST. It cannot be REST! NEVER!

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 this was 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 that everyone think they should develop API's using REST? Who came up with that insane idea in the first place?

Square being jammed into a round hole

Lets face it! REST and API's really don't match!

And why in the world would you want your application to become something that it cannot be? In order to make an inherently RESTless application RESTful, you have to change it into something that it isn't! The result will be one out of two possible scenarios:

  • Your application really isn't a REST application even though you call it that. And all that hard work has made the application overly complicated, error prone, inefficient, and really difficult to work with. Or..
  • Your application is 100% RESTful, but now it is broken because it cannot function as an API.

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.

When it comes to REST, 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.

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?

In their book RESTful Web API's Leonard Richardson, Mike Amundsen and Sam Ruby tries to address some of the problems developers face when trying to make their web API's RESTful.

The book is great, it has some interesting ideas, but I still think 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 really need to stop doing that!

What we need is 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 should develop a set of standards for web API's just like we have the HTML standards from the World Wide Web Consortium.

Such a standard could contain specifications and constraints on resource implementations, naming conventions, document presentation and so on.

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.

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.

Some companies (like Twitter and Facebook) and some projects have all tried to do that, but they are still pushing their web API's to the limit in the attempt to make them fit the REST architectural style.

Even if some kind of standard eventually becomes the adopted standard for developing web API's. If such a standard still tries to "force" web API's to be RESTful, the result would be a major step backward.

Lets end this article by another great Roy T. Fielding fact about the problems of trying to make API's RESTful:

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)!

If you have any comments or corrections feel free to email them to me.