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.