http://oreilly.com/catalog/9780596529260 chapter 9.2.3

http://oreilly.com/catalog/9780596805838 chapter 2

http://oreilly.com/catalog/0636920028468 chapter 5

This article does not describe a RESTful architecture. Several things that do not pass the Litmus test <http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... or otherwise stick out like a sore thumb:

1. Explicit versioning, stuffed into each resource's URI

This is really bad, it shows the designer has only experience with RPC, but not resource-oriented. Bumping the server version breaks all clients for no good reason. Imagine if the Web sites worked that way: you have to upgrade your browser before you can visit an updated site. The correct way to do it is to version gradually, and express a changed semantic for a resource type by coining a new link relation for it. Do not put semantics in a resource URI as the article advises!

2. Utter lack of hypermedia controls

The article mentions CSV as possible media type for that entity. As we all know, CSV does not have or support hyperlinks, forms or any other hypermedia control. This is a serious oversight because it's not possible to have a RESTful architecture without those controls. Remedy: the designer must implement controls in the message body where natively supported by an entity type (e.g. XLink or XForms for XML) or else fall back to the message header (e.g. Link header/URI templates for CSV).

3. Fixed URI structuring

This is related to point 2 above. Example: How does the client know how to construct this URI? The article mentions no hyperlinks or other controls. It does say "define the right endpoint names" which I surmise go into some sort of specification document, which is wrong. Doing so makes the server lose control over its URI space and creates unnecessary tight coupling, which is brittle. Express typed resources with link relations, not with the resource URI structure! There must be only exactly one entry point (bookmark) for the client to know, all other URIs are derived by traversing the resources through controls!

4. Lack of clue about security

The article talks about authentication with OAuth or HTTP basic authentication. OAuth is chiefly for 3rd party authorization, no wonder the article's author is confused. Implementing this is workable, but overkill if all you need is authentication, making it much more difficult for a programmer to implement client software correctly, but brings no benefit. HTTP basic authentication is either clear text or susceptible to replay attacks. <http://www.xml.com/pub/a/2003/12/17/dive.html> Remedy: it's 2014, just use TLS. Let the transport layer take care of authenticating a user, the application code on the server is free of authentication.

5. Reinvents the wheel for error handling

Established draft standards exist. Use them. <http://www.mnot.net/blog/2013/05/15/http_problem> <https://github.com/blongden/vnd.error>

tl;dr Article is pretty much amateur hour, I advise the interested reader to get one of the classic books on REST instead to learn it properly. <http://oreilly.com/catalog/9780596529260> <http://oreilly.com/catalog/9780596805838> <http://oreilly.com/catalog/9781449358068>

Update: angle brackets are reserved characters for delimiting a URI, not part of a URI. Hackernews, you are out of compliance with RFC 3986, please fix your shit.

My $0.02. In general, I've found many people describe something as "RESTful" but not actually know what RESTful truly means. Instead, they use it as an acronym to say "A web-based API", which is not necessarily the same thing as RESTful.

The best follow-up question to ask someone is: "What level on the Richardson Maturity Model is your RESTful API?" If they can't answer that, they're probably using the term RESTful to describe something else.

Richardson Maturity Model:

    Level Zero Service  - URI API. Usually just POST. SOAP, XML-RPC, POX.     Level One Service   - URI Tunneling via URI Templates. GET/POST.     Level Two Service   - CRUD (POST, GET, PUT, DELETE). Amazon S3.     Level Three Service - "Hypermedia as the Engine of Application State" (HATEOAS). 

The higher up the level, the more "RESTful" your API (you can argue about the order of level's 0 and 1), but the more complex it will be. Not everything fits perfectly in those levels either; you're free to borrow concepts and mash-up your own custom API.

HATEOAS is the most complicated. Imagine you're browsing the internet. You go to a webpage, and it loads with lots of text, links, images, and videos. You can interact with it, click on links, watch videos, submit a form, and go elsewhere. You have no idea what appeared on the webpage until after you visited it, and the next time you visit it might change entirely. The link might become broken and you get 404'ed, or you need a username/password otherwise you get 401'ed. HATEOAS is similar to that, but instead of a "person" browsing a "website", it's "client software" browsing "XML/URIs/Resources" received from a server API.

REST is not easy to understand or explain, as it entails learning about many different concepts, ideas, and custom-building something based on them. This is probably why there's no single-sentence which easily describes REST. Saying that something is RESTful is like saying something is Drivable. You can drive a car, truck, motorcycle, bicycle, or boat, but they're all very different from one another. There are similar concepts between them, like accelerating, steering, breaking, but how they do each of those things is very different.

A good book I recommend is "REST in Practice" by Jim Webber, Savas Parastatidis, and Ian Robinson (http://www.amazon.com/REST-Practice-Hypermedia-Systems-Archi... or http://shop.oreilly.com/product/9780596805838.do). That helped me grasp what REST means.