Is That REST API Really RPC? Roy Fielding Seems to Think So

Question

A large amount of what I thought I knew about REST is apparently wrong - and I\'m not alone. This question has a long lead-in, but it seems to be necessary because the infor

Answer 1

I think your explanation mostly covers it. URIs are opaque identifiers that should, for the most part, not be communicated beyond the bookmark URI that is used by the user agent to access the app.

As for documenting, this question has been done quite a few times. You document your media type, together with the hyperlink controls that it contains (links and forms), and the interaction model if you so wish (see AtomPub).

If you document the URIs or how to build them, you're doing it wrong.

Answer 2

The thing that most people get wrong is that (at least i think) in the REST world you don't document your "Rest interface", what you document is a media type, independently of your server or service.

Answer 3

Your interpretation seems correct to me. I do believe that Fielding's constraints can be practically applied.

I really would like to see someone publish some good examples of how to document a REST interface. There are so many poor examples, have some valid ones to point users to would be very valuable.

Answer 4

Absolutely correct. I'd note in addition that that URI templates are perfectly fine within a RESTful application so long as the patterns are from documents received from the server (OpenSearch being a suitable example). For URI templates, you document where they're being used and what the expected placeholders in the template are, but not the templates themselves. Slightly contrary to what Wahnfrieden said, this isn't an exception.

For example, at my work we have a internal domain management system, and the service document specifies two URI templates: one for producing a best guess URI for a domain resource, and another for constructing a URI for querying domain availability. It's still possible to page through the domains collection to figure out what the URI of a given domain is, but given the immense number of domains it manages, this wouldn't be feasible for the client, so giving them a way to guess what the URI of a domain resource might be is a huge win in terms of ease of implementation from the client's perspective, and bandwidth from the server's.

On to your question: Our normative documentation is exposed resources, the effect of various methods on those resources, and the representation media types used and their schemas, and what kind of resources the URIs in those representions point to.

We also include non-normative (informative) documentation that has attached to it a disclaimer not to read too much into the URIs mentioned in the document, which gives examples of typical client-server interactions. This puts the rather abstract normative documentation in concrete terms.

Answer 5

For those interested, I found a detailed example of HATEOAS in practice in the Sun Cloud API.

Answer 6

The one exception to giving instruction on how to build URIs is that it is permissible to send a URI template in the hypertext response, with fields to be substituted automatically by the client, using other fields in the hypertext. This doesn't usually end up saving much bandwidth though since gzip compression will handle the repeated parts of URIs well enough to not bother with this.

Some good discussions on REST and the related HATEOAS:

Advantages Of (Also) Using HATEOAS In RESTFul APIs

How to GET a cup of coffee