What Makes Good REST?

| by Mark Little on Oct 24, 2008. Estimated reading time: 5 minutes |

The SocialSite REST API has come under fire recently about it's RESTfullness from Roy Fielding. Roy uses it as an example of systems that claim to be REST but are often very far from it.

[OpenSocial REST API] is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.

It's not too hard to find evidence in the OpenSocial pages to agree with Roy. For example:

  • Support for OpenSocial style REST and JSON-RPC on the server-side
  • Support for JSON-RPC batching of requests on client-side
  • Comply with OpenSocial requirements for extensions

And we all know how REST is closely related to RPC. (Or not.) Given the number of sites that Roy has come across that claim to be RESTful and yet aren't, he goes on to give guidance on the best approaches to take to be a good Web (and REST API) citizen, some of which we summarize below:

  • A REST API should not be dependent on any single communication protocol. Any protocol element that uses a URI for identification must allow any URI scheme to be used for the sake of that identification. [Failure here implies that identification is not separated from interaction.]
  • 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, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
  • A REST API must not define fixed resource names or hierarchies. Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling].
  • A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). 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). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]

Roy's post has generated a lot of feedback in terms of comments and associated posts, including questions are the use of hypertext/hypermedia in the rules, to which Roy responds:

When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions. Hypermedia is just an expansion on what text means to include temporal anchors within a media stream; most researchers have dropped the distinction. Hypertext does not need to be HTML on a browser. Machines can follow links when they understand the data format and relationship types.

When asked why he thinks many people get it wrong, Roy says:

To some extent, people get REST wrong because I failed to include enough detail on media type design within my dissertation. That’s because I ran out of time, not because I thought it was any less important than the other aspects of REST. Likewise, I suspect a lot of people get it wrong because they read only the Wikipedia entry on the subject, which is not based on authoritative sources. However, I think most people just make the mistake that it should be simple to design simple things. In reality, the effort required to design something is inversely proportional to the simplicity of the result. As architectural styles go, REST is very simple. REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution. Many of the constraints are directly opposed to short-term efficiency. Unfortunately, people are fairly good at short-term design, and usually awful at long-term design. Most don’t think they need to design past the current release. There are more than a few software methodologies that portray any long-term thinking as wrong-headed, ivory tower design (which it can be if it isn’t motivated by real requirements).

In fact the entire comment section on the article is definitely worth a read if you are interested in REST. Dare Obasanjo attempts to summarize and clarify in a separate article:

The key thing to remember is that REST is about building software that scales to usage on the World Wide Web by being a good participant of the Web ecosystem. Ideally a RESTful API should be designed to be implementable by thousands of websites and consumed by hundreds of applications running on dozens of platforms with zero coupling between the client applications and the Web services. A great example of this is RSS/Atom feeds which happen to be one of the world's most successful RESTful API stories.

He looks specifically at one of the items that Roy mentioned: requiring a specific URL structure for services that implement the API.

The problem with this approach is that it assumes that every implementer will have complete control of their URI space and that clients should have URL structures baked into them. The reason this practice is a bad idea is well documented in Joe Gregorio's post No Fishing - or - Why 'robots.txt and 'favicon.ico' are bad ideas and shouldn't be emulated where he lists several reasons why hard coded URLs are a bad idea. The reasons against include lack of extensibility and poor support for people in hosted environments who may not fully control their URI space.

There's a plethora of other REST resources on the Web (pun intended). Most written by authorative people with a track record of implementation. But it is clear that not everything that uses the Web is RESTful and not everything that says it is RESTful is RESTful.

Rate this Article


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

Rush and Buzz word by William Martinez

I guess the real problem comes when someone reads the dissertation and rushes to create a tool to support it. The tool is obviously intended to sales, and no tool will be created if the word is not a buzz word.

Same they did with Web Services. They rushed to use SOAP and later on everybody was saying they got document style web services when they were actually using RPC. SOA is another example, where everybody claimed it was a SOA tool just because it supported web services.

I have seen articles saying Roy's dissertation distinguishes between the two web service approaches! The problem here is many people hear the REST word, go to the airline example and then buys whatever has the REST logo. Furthermore, we engineers (developers) are the most stubborn, golden hammer maniacs you can find in terms of discussing what we think we understood against what was said, even when discussing whit the guy that said it!

I was going to blog about the dissertation due to the article mentioned above, and this post just makes rush into it! :-D

William Martinez Pomares.
Architect's Thoughts

Example please by Eric Roch

How about some examples of REST applications that do something besides display web content? This set of constraints seems to make it very difficult to write a complex peer to peer application. The REST examples I have seen publicized have a well defined set of URI for operations - the servers do not " have the freedom to control their own namespace."

Related post - mine by Eric Roch

If you think about these two constraints the argument that REST is simple architectural style should be debunked - at least for APIs. Most of the so called REST examples I have seen have used fixed resource names with a documented set of URIs for operations.

Re: Related post - mine by William Martinez

Hello Erich.

I understand REST is an architecture style for networking application, not only for displaying web content. This style contains a set of constrains taken from other styles used in networking applications too. Let's see:

1. When I go to a site, I don't need to know all the URIs in that site's namespace, right? I usually go to ONE URI, that is the entry page.

2. The entry page sends back a representation of a Media Type, which I'm suppose to know how to handle. It is ok if the media is not known and you need "out-of-band" info on how to handle it, that is expected.

3. You handle the media representation. You know how to read it, execute it, apply it, anything. The media should be a HyperMedia (which means it contains links to other parts of the media or to other resources). So, the client (you) should know how to follow those links, and how to choose which link to follow. Important: You do not know the links previously! Those links may change by the will of the server and the client must accept that, and support it easily.

4. The server has all the freedom then to modify the URI (its namespace). Of course, nobody is talking about a server choosing its domain name. We may even think of a server (not the machine, but the server process running into it, even a servlet!) that may not be able to change its URI up to its context part, but from there on, the serve is king.

An example? Well, you will think I'm crazy for saying this: SOAP Web Services.
Let's see:
1. We have a unique URI that points to a resource of media type XML, sub type WSDL. I know how to handle that, since WSDL is an standard!

2. So, I request that resource. I start processing it. That XML contains a definition of an XML document inside, and also another URI I need to send that document to (the endpoint).

3. Next step, I build an XML document following the first resource instructions. I sent that document to the provided URI. And at the end I get another response.

That is an uncommon Web Service, I know. All people create RPC with web services. The one I describe is document oriented. The difference with usual POX services out there is that you need to know the POX structure out-of-band, in here that is given by WSDL. Sure, you need to know WSDL structure, the difference is that WSDL is standard, and thus is permitted by REST.

Maybe I'm wrong, but that example gives an incredible complexity to the API. (REST is not to simplify the API).

All this I mentioned long ago at my blog. It is interesting how things seem to go from black to white. (I may be wrong, though).


William Martinez Pomares.
Architect's Thoughts

Re: Related post - mine by Eric Roch

Good explaination - I understanda and agree with all of that. But, I was looking for an example of an API set that is large and REST based. Most of the REST examples are a very small set of APIs that often do not adhere to the REST constraints.

The problems I work with all the time are integrating with large COTS systems - SAP or Oracle EBS for example. I cannot image a very large API set evoving independantly with mutiple peer systems connecting to the interfaces. I just don't think that is a problem that REST should solve.

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

5 Discuss