Difference between revisions of "rest/urls"

From Microformats Wiki
Jump to navigation Jump to search
m (en-US)
Line 51: Line 51:
 
* Create a new widget
 
* Create a new widget
 
  POST  http://example.org/widget
 
  POST  http://example.org/widget
  <= LOCATION:  //example.org/widget/123
+
  <= LOCATION: //example.org/widget/123
  
 
* Get the new widget
 
* Get the new widget
Line 67: Line 67:
 
Using the  http://example.org/widget URI for creating new widgets is
 
Using the  http://example.org/widget URI for creating new widgets is
 
similar to the Prototype design pattern while still adhering to the
 
similar to the Prototype design pattern while still adhering to the
expected behaviour of a POST, ie. create a subordinate resource.
+
expected behavior of a POST, ie. create a subordinate resource.
  
 
Whatever you do, be sure to ''tell'' clients what structure they use, so they don't have to guess
 
Whatever you do, be sure to ''tell'' clients what structure they use, so they don't have to guess
 
(which would violated HTTP [[rest/opacity]].
 
(which would violated HTTP [[rest/opacity]].

Revision as of 22:49, 31 August 2007

URL Conventions

The Simply Restful plugin for Rails, which will soon become part of Rails Core, has gone with the following scheme:

/people /people/1

We recommend that other implementations follow the same conventions, since that is the first concrete example of such explicitly RESTful URLs in the wild.


ARCHIVE

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.

Example URLs

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

Example Actions

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

Notes

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

Using the http://example.org/widget URI for creating new widgets is similar to the Prototype design pattern while still adhering to the expected behavior of a POST, ie. create a subordinate resource.

Whatever you do, be sure to tell clients what structure they use, so they don't have to guess (which would violated HTTP rest/opacity.