rest/urls: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
m (en-US)
(new routes)
Line 1: Line 1:
= URL Conventions =
= URL Conventions =


The Simply Restful plugin for Rails, which will soon become part of Rails Core, has gone with the following scheme:
The recommended conventions for RESTful URLs are those used by [http://topfunky.com/clients/peepcode/REST-cheatsheet.pdf Ruby on Rails]. Note that it is essential to use the proper HTTP verb for the desired action.  Note that the principal unit of operation is the "collection", which typically corresponds to a database table or (in Rails) an ActiveRecord class.


/people
For a collection name "people", the primary routes would be:
/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.
;GET /people/: return a list of all records
;GET /people/new: return a form for creating a new record
;POST /people/: submit a form for creating a new record


;GET /people/1: return the first record
;DELETE /people/1: destroy the first record


= ARCHIVE =
;GET /people/1/edit: return a form to edit the first record
 
;POST /people/1: submit a form for editing the first record
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]].

Revision as of 22:23, 27 September 2007

URL Conventions

The recommended conventions for RESTful URLs are those used by Ruby on Rails. Note that it is essential to use the proper HTTP verb for the desired action. Note that the principal unit of operation is the "collection", which typically corresponds to a database table or (in Rails) an ActiveRecord class.

For a collection name "people", the primary routes would be:

GET /people/
return a list of all records
GET /people/new
return a form for creating a new record
POST /people/
submit a form for creating a new record
GET /people/1
return the first record
DELETE /people/1
destroy the first record
GET /people/1/edit
return a form to edit the first record
POST /people/1
submit a form for editing the first record
Retrieved from "http://microformats.org/wiki/index.php?title=rest/urls&oldid=21874"