Why Some Web APIs Are Not RESTful and What Can Be Done About It

| Posted by Abel Avram Follow 12 Followers on Oct 26, 2014. Estimated reading time: 7 minutes |

Many Web API designers claim their are RESTful, but their APIs have little in common with REST. What can be done to make a web service API truly RESTful?

According to Roy Fielding’ doctoral thesis, Architectural Styles and the Design of Network-based Software Architectures, REST is the architectural style that the WWW is built upon, based on a number of principles and constraints that are meant to enforce those principles.

Without attempting to be exhaustive, we will enumerate some of the principles that are significant for our discussion, followed by short descriptions:

  • Resource Identification. Every resource on the web is uniquely identified by an ID, which is a URI.
  • Linking. A client navigates from resource to resource via hypermedia.
  • Multiple resource representations. A client does not deal with the resource itself, but with a representation of it. There can be multiple representations of a resource.

Other principles are Server-client Stateless Communication, Using Standardized Methods, Self-descriptive Messages, etc.

Since Fielding’s paper, web APIs have been proliferating all over the Internet, and many API creators qualify their offspring as RESTful, i.e. adhering to REST principles.

While these do their job well, and many are successfully replacing the older WS-* solutions, the question is: Are they truly RESTful or is the term misused, transforming it into a buzz word?

Any “RESTful” API manual suggests defining resources (entities), giving them names (nouns), using plural, creating URIs that suggest the relationships between entities, avoiding deep linking, etc.. A typical request/response on such an API looks like this:


GET /books/10


200 OK
      "title": "some_title",
      "author": "some_author"

While such APIs have borrowed some of the REST principles, such as identifying each resource by an ID, accessing resources via hyperlinks, providing multiple representations for resources (JSON, XML) – they do not abide to all REST principles, applying the so called “pragmatic REST”, resulting in multiple interpretations of REST. Fielding expressed his frustration with “RESTful” API implementations years ago, informing API designers that several rules need to be followed for an API to be called RESTful, which we quote in brief:

  • A REST API should not be dependent on any single communication protocol
  • A REST API should not contain any changes to the communication protocols
  • A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state …
  • A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server).
  • A REST API should never have “typed” resources that are significant to the client.
  • A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) …

Regarding the last rule, many web APIs today do not have an initial bookmark that a client accesses followed by a way to provide in each response additional links or templates for creating these links to access the various resources that the respective web service has to offer, but usually there is external documentation for developers to follow when constructing such links.  If, according to Fielding, this is not a RESTful way of dealing with hyperlinks, then what is it and how could it be done?

Stefan Tilkov, self proclaimed lead RESTafarian of innoQ, suggested during his GOTO session “REST: I don't Think it Means What You Think it Does”, the use of a service document (video at 35m26s), which would be the homepage of a web service. The client would ask for this homepage, which is the service bookmark, and would receive a response containing the available resources, the operations that can be executed against them, and the relative links to be used to access them, as shown in the following example of an Order Management service:

<?xml version="1.0" encoding="UTF-8"?>
<serviceDescription xml:base="">
   <link rel="all" href="/orders/" />
   <link rel="received" href="/orders/received/" />
   <link rel="accepted" href="/orders/accepted/" />
   <link rel="rejected" href="/orders/rejected/" />
   <link rel="cancelled" href="/orders/cancelled/" />
   <link rel="fulfilled" href="" />
   <link rel="cancellations" href="/cancellations/" />
   <link rel="reports" href="/reports/" />
   { "serviceDescription" : {
      "base": ",
      "links": [
         { "rel": "all", "href": "/orders/" },
         { "rel": "received", "href": "/orders/received/" },
         { "rel": "accepted", "href": "/orders/accepted/" },
         { "rel": "rejected", "href": "/orders/rejected/" },
         { "rel": "cancelled", "href": "/orders/cancelled/" },
         { "rel": "fulfilled", "href": "/orders/fulfilled/" },
         { "rel": "cancellations", "href": "/cancellations/" },
         { "rel": "reports", "href": "/reports/" }

While this approach may seem to complicate things by introducing a level of indirection in constructing the hyperlinks, the benefit it brings is decoupling between the client and server. The client no longer has to hardcode the links or build them based on some external guideline, but it gets them from the server. The server can change the links anytime it wants, and can introduce or remove resource operations without having to fear that it might break some clients. Actually, according to Tilkov, some enterprises do exactly that: intentionally messing up with the links to see what clients break, to see where REST principles are not respected.

Also, responses from a server should include state transition links. When the client operates on a resource, the response can contain links to further operations that correspond to possible transition states.

For today’s web APIs, the URLs have become the APIs, transforming REST into a number of URI patterns plus HTTP methods, such as GET, PUT, POST, DELETE. During the same session, Tilkov asked the audience if the following URIs are RESTful (video at 17m16s):

The replies varied: depending on the URI, some considered them as RESTful while others as not, highlighting the actual confusion that has been created around REST. Tilkov’s take on this was that it does not matter what’s in a URI because from REST’s perspective a URI is just a string of characters, no matter what is inside it. There are no constraints on URIs to make them RESTful. What actually matters is the context in which the URI is used.

Another issue raised by Tilkov was versioning the APIs within the URI, as many leading web API creators do, as shown by the following samples taken from their respective websites:

Swagger word API example
Apigee Edge API example
SauceLabs example

Tilkov explained that this happens because “the URI expresses the API”, wondering “what happens when one changes the API?” He considers that the URI could include a version number if it refers to a certain version of data or a document, but one should not tie an API to URIs pointing to resources because this introduces a coupling between the client and the server.

He provided a number of other recommendations on making APIs RESTful:

  • Use advanced hypermedia controls, such as forms, even for machine-to-machine communication
  • Use advanced hypermedia controls, such as forms, even for machine-to-machine communication
  • Use different media types for different type of resources
  • Create new resources if the need arises
  • Reserve space for links

It’s obvious that today many web APIs are not RESTful. Nothing stops the respective companies to build such APIs, and they have been quite successful at doing so. What we do not understand is why they insist on calling them RESTful? They could coin another term. Web API could be enough.

It also remains to be seen who will win in the end, if there will be a winner or rather a peaceful coexistence between the two: REST or wannabe RESTful web APIs? In a discussion with InfoQ, Tilkov expressed his confidence that REST “has more than just theoretical advantages, and in the past couple of decades, the web approach always won in the end.” In the meantime, the not-really-RESTful Web APIs have taken over the web. In the ProgrammableWeb index there are currently 12,199 APIs and counting, with over 6,000 being categorized as “RESTful”.

About the Author

Abel Avram has been involved in many InfoQ editorial activities since 2008, enjoying writing news reports on Mobile, HTML, .NET, Cloud Computing, EA and other topics. If you are interested in submitting a news story or educational articles please contact him at abel [at]

Rate this Article

Adoption Stage

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Never quite convinced by Richard Bywater

I've never been quite convinced about the hypermedia part of REST. For instance, take the following sentence from the article:
"The server can change the links anytime it wants, and can introduce or remove resource operations without having to fear that it might break some clients."

Yes its good that the server can change links anytime it wants and have the client get to the right place. But in terms of the second part, that of removing resource operations without having to fear it will break the client, if a client has a "reporting" feature then surely it must have to know about the reporting operation and, therefore, would break if the API suddenly didn't return "reporting".

Re: Never quite convinced by Abel Avram

Yes, that is correct although that regards the system at a higher level. If an operation is no longer available, it means the server no longer complies with a contract, and the users should be informed ahead of time. But a client should not break because of that. It might not be able to fulfill a task, but it should not break.
The whole idea is that we should not have hard coding of URLs at lower levels of the client-server interaction.

Why Some Web APIs Are Not Bloated And What Can Be Done About It by Eric Jain

There are many RESTful practices that make Web APIs easier to use (and manage), including proper use of HTTP methods, status codes and headers. But I haven't come across a Web API where I felt hypermedia "operation" links helped any. Also, supposed protocol independence was one of the things that overcomplicated SOAP...

It's 2015 ... by Jean-Jacques Dubray

>> It’s obvious that today many web APIs are not RESTful.
You bet, if REST was such a "Silver Bullet" do you really think that would be the case?

You are still talking about REST like it is 2007. Can you please use a non trivial example where REST actually works? Nobody builds API that look like the one you are using or the ones that Stefan talked about in his infamous paper.

Hypermedia is the UDDI of WS-*.

Resource Orientation does not work when there is no human in the loop, period. Everybody who pretends otherwise is either financially or emotionally attached to a concept that simply does not work.

Perhaps after all these years you could admit defeat and move on.

Re: It's 2015 ... by Abel Avram

The issue I am drawing attention to is the misuse of the term REST. You cannot say REST for a vast majority of APIs when its author meant something else. And I'm not saying people should not use the rather successful Web APIs the way they are used. But why are they insisting in calling them RESTful?

Re: It's 2015 ... by Jean-Jacques Dubray

I think it's time to move on. Resource Orientation cannot be applied to the architecture of distributed systems. That would be something that would be newsworthy, IMHO. The APIs have won, i.e. the action model.

Re: It's 2015 ... by Abel Avram

Oh, the world has been moving on. There are >12,000 APIs only in the ProgrammableWeb index. And imagine the number of internal private APIs in enterprises.
Just don't call them RESTful. Why does the world need to use a word that means something else?

Re: It's 2015 ... by Jean-Jacques Dubray

perhaps, if some people has not "hyped" that term, nobody would be using it ... REST-for-distributed-systems is dead, RIP :-)

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

8 Discuss