REST Design Philosophies
March 18, 2012 4 Comments
In my previous post I said that REST is a protocol design technique. Chances are you do not agree or at least not completely. REST can be deceptively simple and frustratingly controversial at the same time. We often find ourselves in the middle of heated debates and are quickly labeled dogmatic RESTafarians or clueless, reckless hackers when expressing an opinion. If you don’t know what I’m talking about, read this well-researched article by Ivan Zuzak or better yet, join a REST discussion group.
Why is REST controversial? Building distributed applications is hard. REST simplifies it by leveraging existing web design patterns and protocols, but many important design tradeoffs remain. Designers resolve tradeoffs based on what they consider important. What is important is not simply a matter of personal opinion, but depends on the kind of application you are building. So instead of best practices everybody agrees on REST has a number of distinct schools of thought or design philosophies; neither inherently good nor bad, neither obviously right nor wrong; each with its champions and detractors.
I’ll attempt to describe four of these design philosophies without claiming any authority in the matter. Others would likely name and describe them differently. I decided to draw quick sketches instead of painting full portraits, capturing the distinctive features and worrying less about getting every detail right.
Hypermedia APIs
This design philosophy admires and tries to replicate the properties of the World Wide Web as a distributed application development platform. Its proponents believe that the phenomenal success of the Web is due to a number of high-level design choices which together define what they call its architectural style. Roy Fielding was the first to describe this architectural style naming it REpresentational State Transfer or REST. For this reason many consider it the only “true” definition of REST.
The single most distinctive feature of this design philosophy is the use of hypermedia or HTTP messages with embedded hyperlinks, hence the name. The links guide clients to discover available resources and operations dynamically. While specific URIs patterns are used, clients are not expected to understand them and are actively discouraged from parsing or building URIs. You can get a better understanding of how Hypermedia APIs are designed and how they work watching Jon Moore build one in this video.
Much of the Hypermedia API discussion focuses on the difficult task of writing complex, large-scale distributed applications and on evolving them over decades. Design attributes like scalability and loose coupling are considered much more important than simplicity and ease of use. This discourages some who claim that while they understand Hypermedia APIs in theory, they find them difficult to use in practice.
Data APIs
If Hypermedia APIs are an architectural style, Data APIs are first and foremost an application integration pattern. Its proponents consider standardization as the most important design goal, believing that exposing the application’s underlying data in a standard format permits easier and more innovative integrations than exposing the application’s complex, cumbersome, and often restrictive business logic. Data APIs are published by organizations wishing to share useful data without giving access to the application which collects it or are added to existing enterprise software to facilitate third-party integrations.
Data APIs use the HTTP methods POST/GET/PUT/DELETE strictly as the CRUD operations Create/Read/Update/Delete. If they expose any application logic at all, they expose it implicitly. For example, if you use a Data API to manipulate purchase orders you obviously expect that products will be shipped and people billed as a result, but this has no direct effect on how the API looks or works. The behavior is simply implied by our shared understanding of what a purchase order is.
The URI structure is standardized and client applications are encouraged to use URI templates for building queries similar to SQL select statements. The format in which the data is returned is also standardized, often based on the ATOM format. For an example of a standardized Data API take a closer look at Microsoft’s Open Data Protocol.
Web APIs
The designers of Web APIs consider achieving large-scale developer adoption as the most important API design challenge. They try to drive adoption by aiming for the widest possible platform support and maintaining a very low barrier of entry.
It is only a slight exaggeration to say that if a feature is not guaranteed to work in Adobe Flash, on an underpowered mobile phone, on a remote Pacific island, through a web proxy, and from behind an ancient firewall from the 90’s, Web API designers won’t use it. If an interface cannot be accessed directly from HTML forms or called by writing less than five lines of JavaScript, Web API designers worry about adoption.
The result is that Web APIs manage to get by using a surprisingly small subset of features. They stick to GET and POST, largely eschew HTTP headers, strongly favor JSON over XML, and rarely use hyperlinks. Information is often passed in URLs, because “URLs are easy to type into the address bar of a browser”. I call them Web APIs because I see this pattern in services offered to developers at large over the Internet (often free of charge) and are primarily used in Web Mashups or equivalent mobile apps. Many of the smaller, simpler APIs listed in the Programmable Web API Directory are Web APIs. Perhaps the best known and most frequently imitated is the Twitter API.
Pragmatic REST APIs
Pragmatists believe that design trade-offs should be resolved based on concrete, project-specific requirements and constraints. They view the indiscriminate application of the same design patterns to widely different problems as a sign of dogmatic thinking, not as disciplined design. Absent specific requirements and constraints, pragmatists prefer to use the simplest possible design. What “simplest” means is again very context dependent. It may mean a design which fits the technologies, frameworks, or tools used the best.
You might argue that Pragmatic REST is not a separate design philosophy since its practitioners freely borrow and mix design approaches from all the other schools. The “pragmatic” label best describes APIs which do not fit neatly into any of the other categories. There are quite a few of these. If you look at the collection of the Google APIs you will discover characteristics of Hypermedia APIs, Data APIs, and Web APIs, but not in their purest forms.
In Lieu of Conclusion
If memory serves me well, the Big REST Debate reached its peak sometime around 2008. The rhetoric cooled since, largely because the protagonists agreed to disagree, do REST their own way, and mostly ignore each other. But the issue is far from being settled and I doubt it will ever be. When I decided to illustrate the principles and methods of protocol design using REST, I knew that I can’t pretend not to notice the elephant in the room. That’s why I wrote this post. In my next post I’ll return to talk about REST and protocol design.
This work is licensed under a Creative Commons Attribution-ShareAlike 2.5 Canada License.
About Ferenc Mihaly
The Amiable API 
Thanks for a well-organized article. I appreciate your main point – that there are several distinct camps of REST APIs, and that many (perhaps most) practitioners see only one. This makes obvious one of the ways that those arguing about “true REST” are talking past each other, so cannot resolve their disagreements.
As someone currently working on OData (data API) who has previously implemented both Web API and Pragmatic (towards Hypermedia, but my first API so not as pure as I could create now), this post helped categorize my own thinking. The terms you gave helped me see more patterns in the emergent behavior resulting from the API designs in which I’ve been involved.
This post gives me a set of clear and well-defined categories where before I had a messy single category. As always, this leaves me wondering whether there are actually more categories (does your Pragmatic break down further? Did you miss something?). So your article both makes me think, and makes it easier for me to do so.
Thank you.
The problem is the label “REST”.
Today, the label is meaningless. The fact that you list “Hypermedia”, “Data”, “Web”, and “Pragmatic” “REST” APIs means we have nothing at all. At this point REST == HTTP. Yet, most of the “practitioners”, in fact, practice neither.
For those interested in REST REST, Fielding’s REST, the REST architecture that’s actually named after his paper, it’s very frustrating as folks start talking past each other. Someone asks a question about “REST” when they’re babbling about POSTing a file using WCF. If you use the word “REST” in a discussion, it can mean anything across the vast spectrum of distributed computing over HTTP. When REST is used as Fielding’s REST, it is rare indeed. Even I have to qualify it here to clarify what I’m talking about. “Oh, you mean THAT REST.”
About the only thing folks might agree upon is that REST != SOAP, even though I guarantee there are folks out essentially practicing the same thing as SOAP by POSTing their own contrived payloads and calling it REST “because its easier, everyone knows REST is easier, and we’re agile, yo!”.
So, essentially this post mostly documents how far REST has fallen as it’s been adopted by the mainstream.
The term REST is indeed problematic for the reasons you mentioned. I myself mulled a long time over what would be the best umbrella term to use in this post. I only decided on REST after realizing that the staunches defenders of “REST as an architectural style” school of thought essentially gave up “REST” in favor of “Hypermedia”. This is important because one can make a strong argument that this school includes Roy Fielding himself. By adopting the term “hypermedia” they acknowledged that “REST” evolved into an ambiguous and poorly defined concept.
That REST is now a somewhat vague concept Is not entirely a bad thing. Most of our natural language is ambiguous and poorly defined. You can see this in legal documents and technical specifications which sometimes struggle to define the precise meaning of such common words as “must”. We can still have reasonable conversations as long as we don’t insists that our words have precise meanings that they don’t actually have.
I’ll continue using REST as a generic umbrella term in casual conversations, mostly because I cannot not think of any other alternatives that serve this role better. After all, the phrase “HTTP-based protocols that are not SOAP and show at least certain aspects of what used to be known as REST” doesn’t seem to be catching on.
Pingback: This Week in #REST – Volume 43 (Mar 7 2012 – Apr 3 2012) « This week in REST