Is “REST API” an Oxymoron?

Posted in SOA by AST on Saturday, December 16th, 2006

Amoxil Generic Buy Clarinex Online Neurontin Without Prescription Topamax No Prescription Soma For Sale Glucotrol Generic Buy Aricept Online Stromectol Without Prescription Lotrisone No Prescription Celexa For Sale

Even though I had to temporarily drop out of the ongoing discussion on the service-orientated-architecture Yahoo group/mailing list, which prompted my last post, to focus on a few high-priority interrupts for a while, my brain hasn’t fully disengaged from the discussion.

One of the light bulbs that went off in my head during the aforementioned discussion was it finally clicked as to what the uniform interface constraint “hypermedia as the engine of application state” (Fielding 2000, §5.1.5) actually means (to me, anyway). Now that I think I understand it, I also understand why it is so hard for people to really get what it means: most of the people trying to figure this out are experienced, traditional programmers. What do traditional programmers do? If they’re any good and they’re dealing with large-scale distributed systems, they spend an awful lot of time on the design of the “perfect” API for their remote components. Perfect in this context means that it is the optimal trade-off between all of the architectural constraints and system requirements to deliver an efficient distributed system.

API Brain Damage

I’m going to go out on a limb here, but I think this “API brain damage” is part of why we haven’t been able to significantly advance the state of the art of software system design over the last 30 years. We all have it, because from the moment you learn what a compiler is and get started with programming they’re all around you. As you develop your own skills and experience, you’re exposed to both good and bad API design, and this all gets mixed in together in our little brains so that each of us develops their own perspective on what is a “good” vs. a “bad” API. Most of us can, by this stage, pass such a judgment in 30 minutes or less.

However, I think the effects of this brain damage are to create some pretty fundamental assumptions about how computer systems work. If you need programmatic access (here it is again, reinforced by the terms we use to describe our requirements) to a set of functionality (for kicks, lets call it a service), then the first thing we as programmers want to know is “where’s the API?”. It’s ingrained in our very being because of years and years of positive reinforcement. We all have it…and I think it’s a tragic mistake.

Even people who have a pretty good understanding of what REST is get pulled back into the primordial slime just as they’re about to sprout legs and walk upright. Joe Gregorio’s really good article on building a RESTful system, Constructing or Traversing URIs?, is a prime example of this type of thinking. I’m not criticizing Joe here, I’m criticizing the way we, as software architects and developers, have been trained to think.

The point of Joe’s article is that hypermedia is about link traversal, but that because the possible URI space is nearly infinite, it’s reasonable to publish recipes for link construction under the argument that this is what HTML Forms using the GET method do anyway (emphasis added). This “optimization” undermines what to me is the whole point of “hypermedia as the engine of application state”: link traversal, and this is recognized by the rest of the article Joe wrote. As soon as you start down this slippery slope, you’ve lost all of the advantages I see in even bothering with hypermedia at all. It no longer becomes part of the application, it’s just data that’s shipped around via some transfer mechanism, in this case HTTP.

Hypermedia Applications

Many things have contributed to my opinion about this topic, including this statement by Eric Newcomer recently on the mailing list:

I should just note that comparing the Web to WS-* is an apples-to-oranges comparison (one being an application and the other being a collection of specifications).

With apologies to Eric, I initially sorta dismissed this statement because I was focused on my conversation with Steve Jones—but I shouldn’t have. Eric is exactly right here. The World Wide Web is a hypermedia application, not just a collection of specifications. Again, our software development training doesn’t help us here very much. Good ol’ functional decomposition makes us (well, me at least) want to see the Web as HTTP (RFC 2616), URIs (RFC 3986), MIME types (Wikipedia entry to set of related RFCs), HTML/XHTML (W3C markup specifications) and HTML forms (W3C recommendation and RFC 2388).

In actual fact, it’s all of those working together to provide, as Eric said, the Web as a distributed hypermedia application (which, if I remember correctly is a point also made by Roy Fielding himself in the dissertation). The Web works because both user agents (browsers) and the server applications use all of these specifications together to expose a set of functionality to the interactive user. There is no a priori agreement between the browser and the Web server as to how the information service built on these specifications used, but because of agreement on how these specifications are used together, as an application, it doesn’t matter if today, is built using Microsoft ASP, and tomorrow it’s built on PHP. Apart from the application of the “Cool URIs Don’t Change” principle, if a user starts from, they will always be able to utilize the CNN news service via their browser’s implementation of those specifications and the implicit agreement of CNN to publish its service in accordance with them too.

The moment that CNN or any other service provider publishes a recipe, guideline or specification of how to access specific parts of that service, e.g. the latest headlines may be found at or or whatever, as Joe points out in the article, they’ve made an implicit commitment to support that API (because that’s what it essentially is) for a period of time. When someone comes along an implements a specialized headline grabber that follows that API, and CNN decides to change it due to idle whim or genuine business need, that headline grabber client is now broken. If it’s just a single user, maybe this isn’t a big deal, but if it is every 3rd-party trading partner of your organization, the impact is a bit more significant.

A hypermedia application such as Atom or RSS and content negotiation via MIME types, HTTP accept headers and embedded <link/> tags mean that this sort of evolution could happen without breaking the client—provided there is agreement on the application semantics of how those things should be both used and interpreted between clients and servers. Anything else means you’re back to brittle, API based systems that can no longer evolve independently of each other.

Closing Thoughts

I don’t have all of the answers here, but I think that the notion of a “REST API” is an oxymoron because REST is about dynamic evolvability of clients and servers based on codified understandings of previously agreed application semantics. This means that HTML browsers and Web servers agree to provide the Web application in a way that both can understand and use, but it also means that RSS/Atom feed readers and server feeds agree on the way they interact to both access and provide the syndication application.

What I’m saying is that the nature and specification of the hypermedia application is as key to REST as how you use the HTTP verbs. However, since the HTTP verbs are essentially an API that programmers can get their heads around, that’s where everyone’s focus is at the moment. I think this is a diversion from where people should be thinking about REST. As long as you agree the semantics of the hypermedia application (HTML+Forms+MIME+HTTP or Atom+XHTML+MIME+HTTP), the way that application is implemented on the server should be an implementation detail and not something exposed to clients in terms of an API.

If the hypermedia constructs being used to describe the interaction between the clients and servers are not rich enough to abstract these things so the client needs to know that it’s supposed to POST data to URI x rather than being able to simply traverse hypermedia provided by the server (meaning the operation, data and location are provided to the client in a way it can understand rather than having any of this hard-coded as client implementation logic), then the hypermedia application being used (and not the information service) has not been sufficiently defined. Using the existing and emerging specifications for describing content and interaction, it should be possible to specify the application. If it isn’t, then we need to be spending our efforts on a way to do that rather than arguing about the RESTfulness of so-and-so’s latest HTTP-based API.

To me, this is the real problem to be solved in implementing RESTful systems. I think there are people who are starting to realize this need implicitly, but I think it’s time we made that need an explicit requirement of systems implemented in the REST style. If you can’t describe the interaction via hypermedia and link traversal semantics only, then I don’t think the system truly meets the requirements of REST as I understand them today. The uniform interface is hypermedia, not HTTP. Focusing on HTTP is not seeing the forest for the trees.

Comments, flames and discussion are more than welcome.


  1. protocol7 » Blog Archive » links for 2006-12-17 said,

    December 17, 2006 at 12:19 pm

    […] Is “REST API” an Oxymoron? (tags: rest API HTTP by:andrew_townley) […]

  2. toydi said,

    December 21, 2006 at 2:26 am

    Interesting insight. Eventually we will start appreciate and understand the use of hypermedia in business applications.

    Sometimes, I feel it’s like a full circle with three checkpoints. It’s the simple things like GET/PUT/POST/DELETE that first attract many of us. Then, it’s the URI as a resource identifier that draws a bridge between the Web world and OO world. And now, as you pointed out we may have reached the point to learn how to utilize linking/traversing in hypermedia.

  3. Insights » Catching A Breath said,

    February 2, 2007 at 3:05 pm

    […] Secondly, I’m very happy to say that OASIS has accepted my proposal for a presentation at the OASIS Symposium in April. I’ll be expanding on some of the ideas that I discussed in my “Is ‘REST API’ an Oxymoron?” post and putting them more solidly in a business context. The presentation, “Interactive SOA: Towards Content-Centric Services”, will be part of the session on the challenges ahead for e-Business and e-Government. The presentation represents some on-going research into the challenges around enabling information services within an SOA using hypermedia. Hopefully, sometime in 2007 I’ll be able to publish some more technical information relating to the research, but doing so without understanding how it will deliver measurable value to organizations isn’t in line with what we’re about. […]

  4. Duncan Cragg said,

    February 9, 2007 at 11:06 pm

    API Brain Damage - nice concept! The Atom Publishing Protocol is called the Atom Publishing Protocol, not the Atom Publishing API.

    However, they stopped short in this Mental Health Initiative by using the word ’service’ and having a discovery resource.

    I also think that PUT and DELETE detract from the essential message: that state transfer is nothing to do with methods. It’s actually misleading to go on about a ‘limited set of methods’, when the REST philosophy is really just ‘push or pull on URIs, standard schemas, containing more URIs’ - no methods at all.

    Roy didn’t mention specific methods in his thesis - he threw PUT in once and that was it. Which /may/ be interpreted as a drive (at the time) towards this pull-GET, push-PUT approach. Only Roy can tell us what was in his mind at the time, of course.

    And the acceptance of the non-opaque URI optimisation bugs me too: putting a chunk of your schema into the headers (well, the first header) is just a hack to save a round trip (i.e., POST query-schema resource, redirect on response to results-scheam resource). Plus transparent URIs open us up to the dreaded function-call URIs - to API damaged brains.

    Taking PUT, DELETE and transparent URI schemas and dumping them into the body where they belong would go a long way to help get us free of the function-call mindset.

    A resource is not an object!! Nor a service! Data is open in REST architectures - get over it! There are no methods!

    OK - rant over - thanks for giving me this opportunity!! =0)

    Duncan Cragg

  5. hughw said,

    February 12, 2007 at 11:12 pm

    Right on.

    Next, take a look at what “documented oriented” RESTful applications have done: They’ve reintroduced all the fragility of APIs. Technically speaking they’re RESTful, but they require programmers to bake in knowledge, at design time, about the messages they construct. An APP client isn’t dynamic or weblike at all. To be really weblike, an Atom server would deliver a form; your client would understand the meanings of the form fields, and POST a new entry by serializing a message according to the instructions in the form. Each server could be different and evolve differently.

  6. New JSR to define a high-level REST API for Java « Noelios Consulting said,

    April 3, 2007 at 1:21 pm

    […] Is “REST API” An Oxymoron? […]

  7. A Concrete no QCon SP 2011 - parte 1 | Blog da Concrete said,

    September 19, 2011 at 9:27 pm

    […] É isso aí. Na segunda parte mostraremos que é possível fazer transações distribuídas respeitando o estilo de arquitetura REST (e que isto não é um oximoro). […]

  8. A Concrete no QCon SP 2011 - parte 3 | Blog da Concrete said,

    September 24, 2011 at 2:08 pm

    […] D Andrew S. Townley 2006 – Is “REST API” an Oxymoron? […]

  9. emerge2004 said,

    April 10, 2015 at 6:33 am

    Hello My Friend! I Want To Say That This Post Is Amazing, Nice Written And Include Almost All Vital Infos. I?d Like To See More Posts Like This.

  10. New JSR to define a high-level REST API for Java | Restlet - We Know About APIs said,

    May 17, 2016 at 9:09 pm

    […] Is “REST API” An Oxymoron? […]

Leave a Comment