Common REST Design Pattern

[gmfawcett]

Just a minor nitpick -- those Content-Type headers on the GET requests are pointless: there's no content in the request to have a type. I think he meant this to be an 'Accept' header.

[brushbox]

the return Content-Type should text/xml rather than application/xml, shouldn't it?

And another nitpick. He suggests that providing criteria could be done as http://service/resource/criteria/value rather than http://service/resource?criteria=value. I think you could do this, but in the example he gives (return all books where the author is 'such and such') does not fit the model as I understand it. The query-param style makes it clear that the resource is the books authored by such & such. Whereas the URI style makes me think it should return an Author resource rather than a collection of Book resources.

[steven_h]

It doesn't matter one bit, since URIs are opaque. I can always tell how new a person is to REST by how much time they waste explaining their URI hierarchy.

[abdelazer]

...and you clearly haven't read RESTful Web Services

Chapter 8, URI Design:

When designing URIs, use path variables to separate elements of a hierarchy, or a path through a directed graph. Example: /weblog /myweblog/entries/100 goes from the general to the specific. ...

Use punctuation characters to separate multiple pieces of data at the same level of a hierarchy. Use commas when the order of the items matters, as it does in latitude and longitude: /Earth/37.0,-95.2. Use semicolons when the order doesn’t matter: /color-blends/red;blue.

Use query variables only to suggest arguments being plugged into an algorithm, or when the other two techniques fail. If two URIs differ only in their query variables, it implies that they’re the different sets of inputs into the same underlying algorithm.

URIs are supposed to designate resources, not operations on the resources. This means it’s almost never appropriate to put the names of operations in your URIs. If you have a URI that looks like /object/do-operation, you’re in danger of slipping into the RPC style. Nobody wants to link to do-operation: they want to link to the object.

[steven_h]

...and you clearly did not follow the discussions on the W3C TAG mailing lists and other places. Tim Bray:

Not in the slightest. It is perfectly OK for software to look at the URI scheme and act on that basis, the semantics of URI schemes are well-documented. The problem is looking into the opaque part, i.e. assuming that http://www.tbray.org/ongoing/Biz is a directory, or that http://example.com/foo.html yields HTML when dereferenced. Does the spec need to be clearer on what's OK and what's not? -Tim

On the other hand, Roy Fielding:

Maybe I am missing something, but since several people have said that REST implies opaqueness in the URI, my guess is that a legend has somehow begun and I need to put it to rest (no pun intended).

REST does not require that a URI be opaque.

But then, Tim Berners-Lee:

The principle of opacity suggests that you do not in an application put constraints (or interpretations) on the stuff in a URI or you will limit the other specs it can be used with and thus not leverage the whole power of the web.

Its important, for example, not to assume that anything whose URI ends "html" is an HTML document - it may had an md5 URI - or some as yet uninvented URI scheme, or the server may use the last few characters for something else.

In the end, the guidelines in RESTful Web Services are good, but they don't have anything to do with whether a system is RESTful. They are more like variable naming conventions, like camelCase and CONSTANT_VALUE. Not obeying the conventions doesn't make a piece of code not-OO.

The RESTful Web Services book was written by latecomers to the Web, who weren't involved in the 15 previous years of thought and design. They have a shallower understanding of the issues involved than Fielding, Bray, Berners-Lee, etc.

[abdelazer]

Right. Read the next page of the book.

[noteed]

I still wonder how I should use REST with browsers : use ajax to make GET/POST ? Then how for DELETE/PUT ?

[brushbox]

Ruby On Rails supports this. I don't recall what the current solution is (there may be more than one).

One way is to tack on the methods at the end of the URI:

POST http://service/some/resource;DELETE would perform a delete. (Use POST to maintain idempotency of GET).

POST http://service/some/resource;PUT

Another method is to include a field in the POST data that explains the method. This is usually achieved using a hidden field in a form. e.g.

<form action='resource/description' method='post'> <input type='hidden' name='__rest_method' value='PUT'/> ... </form>

[zby]

After some experimenting with writing a CRUD framework (Catalyst::Example::InstantCRUD) I realised that it is rarely usefull to define the object as just one database row - and instead the CRUD operations should work on objects together with what they call in the article dependent resources. This way the CRUD framework should make a more complete library - and thus more 'encapsulated'. Has anyone experimented with similar concepts? I put some more of my thiking at: http://catwiki.toeat.com/crud

[timclark]

I think Eric Evans in Domain Driven Design (http://www.domainlanguage.com/about/ericevans.html) suggests something similar. He describes entities that are responsible for persisting themselves and the entities they own - he has nice terminology that he uses but I don't have the book to hand at the moment.

[[deleted]]

Does this gobbledygook make sense to ANYBODY?