The problem with a lot of REST framework implementations, like Rails, is that it acts as nothing more than a database record serializer/deserializer. A vanilla Rails resource looks something like this:
<post>
<id>1</id>
<title>This is a post</title>
<comments></comments>
<author_id>100</author_id>
</post>
When you consume this resource, you end up having to munging database foreign key IDs into an URL string. For example, if I want more data about the author of the post above, I'd have to grab <author_id/> and plug into another endpoint, like /authors/:author_id. Who knows if /authors is the correct endpoint? Even if it was, if that endpoint changes, it could break the URLs that I munged together.
These "RESTful" implementations should really look like is the following:
<post href="/posts/1">
<id>1</id>
<title>This is a post</title>
<comments href="/posts/1/comments"/>
<author href="/authors/100"/>
</post>
Given such a format, I don't have to guess what the endpoints are for associated resources; I just look at the href and grab the resource if I want it.
A collection could include dataset navigation information, such as:
<posts>
<link rel="prev" href="/posts/?start_id=51&items=50"/>
<link rel="next" href="/posts/?start_id=101&items=50"/>
<post href="/posts/1">
<id>1</id>
<title>This is a post</title>
<comments href="/posts/1/comments"/>
<author href="/authors/100"/>
</post>
<!-- more posts here... -->
</posts>
Now I can implement a less breakable client that doesn't need to munge URL endpoints with database foreign keys. Furthermore, I can navigate through datasets by following the <link rel/> tags.
The only thing I'd do differently here is put the comments and author links as <link rel/> tags as well. No reason not to standardize the representation of links. Optionally you could list inline the entire contents of the sub-resources. Doc types should allow composition in this way and it allows you as a designer to reduce unnecessary traffic and latency.
This article doesn't really clarify things for me. I agree that not many APIs in the wild right now are truly RESTful, but this has been stated for years. We know this. The article then posits that true REST is too hard. This is simply not true when you look at the bigger picture. Yes, it may be easier in the moment to cowboy it up and reinvent the wheel, but when it comes to maintaining your service and integrating it with others, you pay the price for lack of foresight.
The questions that need to be answered are how would true REST be different, and why would I want to spend my precious time learning about it and implementing it?
I appreciate the author's enthusiasm towards REST, but I would prefer to discuss the technical merits rather than engage in justification and categorization of what's out there right now. Yeah, it's not REST, and yeah people are going to call it REST anyway in certain contexts. But in the context of architectural design we have clear definitions about what REST is, and there's no need to muddy the waters.
I was following, until I got this "No out-of-band knowledge should, therefore, be required beyond understanding a media type that the resource can provide. From there, it should be possible to follow relations provided in “hypertext” context of the representation to “transfer state”, follow relations, or perform any necessary actions." -- can someone translate that? I don't understand it.
Out-of-band knowledge is prior knowledge. Typically file formats or protocol specifications (whether they are standardized or not, widely used or not).
The first sentence of your quote say that all prior knowledge should be about media formats (like the html specification, microformats, the PNG image format…).
From there, the medium itself should provide enough clue for the client to go on. For instance, anchor links in html says you can GET a resource at the specified URI. Other media formats could provide other clues.
To sum up, the only things you can specify a-priori are media formats. URIs and protocols should be interchangeable, so you can update and deprecate them. I think the main goal of REST is to concentrate coupling on media formats alone. Hopefully, most media formats are (or will be) standardized, effectively reducing coupling. Basically, REST architectures are for the long term.
Also, a URL for the root of your service should be sufficient to find every resource that the service provides access to, and every method that can be used with those resources. The example is a website; from the home page of a website you can reach every other page of the website by navigating through hyperlinks and form submissions.
Another example drawn from the article: if the blog posting service provides each post under a uri like /posts/{post-id}, the client of the service shouldn't have to know the uri structure. Instead, /posts/ should be a resource, and it should contain hyperlinks to all of the /posts/{post-id} uris that are available. There would probably be some metadata about each one as well, such as a title, to enable clients to figure out which one they want to follow.
Actually, I think the REST community is pretty clear on this now - there's no need need to accept incorrect definitions, omitting the hypertext constraint is not REST.
"While the true definition is interesting for academic purposes and certainly lies behind the technologies upon which we build every day, it simply doesn’t have a whole lot of use to web application developers" - this is missing the point a bit.. If you're developing web apps for humans the reason REST 'doesn't have a use' is because it's already been 'used' to produce HTTP and HTML. "Doing REST" is essentially the process of designing hypermedia types, and defining/extending a uniform interface. Examples of that would be writing the AtomPub spec or reintroducing Link headers.
I think understanding "true REST" is an excellent starting point and guideline for any API designer. But also trying to follow it too rigidly, at the cost of performance and complexity, is unwise. I believe the article came to the same conclusion.
I was under the impression that HTTP was only a one example of RESTful system. The OP suggests that HTTP verbs must be used to interact with a RESTful API.
Uniform methods are an important aspect of a RESTful system, just as important as Uniform Resource Identifiers. The client of the system has to know what the methods are, so if you define your own methods you put a burden on clients to implement those methods in order to use your service. HTTP provides a set of methods that are sufficient for most RESTful services, and the methods in HTTP are widely implemented in existing libraries. Base your service on HTTP's methods and you've enabled a huge number of clients to use your service.
It's not so much that HTTP itself is RESTful. It's more that using HTTP's existing functionality instead of reinventing your own is RESTful. REST is a set of design principles for building software on top of HTTP.
I care about REST because I remember SOAP and I am very happy that REST mostly won that war, at least in the public API space. I suppose there's something to his article about diverging from the idea of resource definitions but I hope that API providers stick to REST as closely as possible and don't do things such as require cookies in their API or have the app manage state some other non-RESTFUL way that isn't simply passing a token as a POST or GET value for example.
I never meant to imply that I don't LIKE REST-like APIs on the web. Holy opposite day, Batman, I think they're fabulous! It's really just an exploration of the ways in which the popular definition of REST diverge from the actual definition, and what we can learn from the original definition to make our REST-like APIs all the better.
Yes people have tended to miss out the hypermedia constraint and claim to be REST - partly because everyone's been too excited about using HTTP properly to think about anything else, but also just because there's been a lack of tooling and guidelines for designing media types properly. Most people in the REST community agree on that point and now there are useful approaches and technology emerging - restfulie is a great example of this.
Requiring cookies is exactly the same as requiring specific request headers (like oauth) or even requiring parameters in a GET/POST. Sending updated cookies with an unrelated request isn't that great of thing to be doing, but cookies aren't inherently terrible.
Oauth tokens don't have be in the header and I never put them in the header. Which service requires them to be in the header? Requiring parameters in a get post is the way to manage state in REST, isn't it? How else would you do it? REST does not allow for protected resources? Cookies are terrible because when you are using a programming environment that doesn't have cookie management for free you have to write values in the cookie format from scratch and work with headers when you don't have to do this with RESTlike applications that use OAUTH.
It frustrates me to no end that SOAP is the face of RPC. SOAP is pretty much the worst thing ever, but there are RPC alternatives that don't have SOAP's problems and are less weird (i.e. don't attempt to adhere to an impossible ideal).
I highly recommend checking out JSON-RPC 2.0 or just rolling your own to see how easy it can be. The one I wrote is 200 lines of code and slightly more robust than you actually need to have a working RPC server (I added automatic casting and support for optional parameters with defaults, just for my convenience.)
These "RESTful" implementations should really look like is the following:
Given such a format, I don't have to guess what the endpoints are for associated resources; I just look at the href and grab the resource if I want it.A collection could include dataset navigation information, such as:
Now I can implement a less breakable client that doesn't need to munge URL endpoints with database foreign keys. Furthermore, I can navigate through datasets by following the <link rel/> tags.