[uf-rest] Instance/Collection URL conventions

[Dr. Ernie Prabhakar]

Hi all,

Donald posted a lovely, concise recommendation (on rest-discuss)  
about how to structure REST URLs which looks *remarkably* like what  
Rails does (or will do, or maybe ought to do :-) by default.  He gave  
me permission to share it here, and I've added it to the wiki:

http://microformats.org/wiki/rest/urls

-- Ernie P.

From: Donald_Strong

You can get a bit more mileage from having separate lists and  
instances of
your widgets.

You could organise your URIs like this:

# The second widget
http://example.org/widget/2

# A form describing how to create a widget
http://example.org/widget

# The list of the first N (say N=25) widgets
http://example.org/widgets

# The list of the next N widgets starting at 26
http://example.org/widgets/26

Then consider a sequence of hypertext style actions:

# Retrieve a list of widgets
GET http://example.org/widgets

# Retrieve details of the second one
GET http://example.org/widget/2

# Replace some of the details
POST http://example.org/widget/2

# Retrieve a form (resource parameter decription)
# or whatever you want to call it, for creating widgets
GET http://example.org/widget

# Create a new widget
POST http://example.org/widget
<= LOCATION:  //example.org/widget/123

# Get the new widget
GET http://example.org/widget/123

# Delete the Widget
DELETE http://example.org/widget/123

This organisation is similar to that of the rest-discuss
html interface. But you cannot use PUT, POST and DELETE in
that interface.

There is nothing that says you must organise resources hierarchically,
although many people prefer to do so. There are advantages to separating
your containment hierarchies from your components. It makes it trivial
to add new containers and the containers can accept search parameters.
Using the http://example.org/widget URI for creating new widgets is
similar to the Prototype design pattern while still adhering to the
expected behaviour of a POST, ie. create a subordinate resource.

Donald.


------------
Ernest N. Prabhakar, Ph.D. <drernie at opendarwin.org>
Ex-Physicist, Marketing Weenie, and Dilettante Hacker
Probe-Hacker blog: http://www.opendarwin.org/~drernie/