Difference between revisions of "rest/urls"

From Microformats Wiki
Jump to navigation Jump to search
(added header)
Line 1: Line 1:
 
= URL Conventions =
 
= URL Conventions =
  
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. Following these conventions will allow your application to be consumed by ActiveResource, Jester, and other RESTful clients.
+
The recommended conventions for RESTful URLs are those used by [http://topfunky.com/clients/peepcode/REST-cheatsheet.pdf Ruby on Rails]. Following these conventions for both HTTP method names and URL construction will allow your application to be consumed by ActiveResource, Jester, and other RESTful clients.
  
 
== Routing ==  
 
== Routing ==  
 +
The principal unit of operation is the "collection", which typically corresponds to a database table or (in Rails) an ActiveRecord class.
 
For a collection named "people", the primary routes would be:
 
For a collection named "people", the primary routes would be:
  
Line 28: Line 29:
 
;POST /people/1/promote: run the "promote" action against the first record
 
;POST /people/1/promote: run the "promote" action against the first record
 
These should be used sparingly, as they are unlikely to be supported by most clients.
 
These should be used sparingly, as they are unlikely to be supported by most clients.
 +
 +
== File Formats ==
 +
 +
Data types are extremely important in REST.  While it is ideal to specify the appropriate mime-type, developers are encouraged to follow Rails in supporting extension-based typing, e.g.:
 +
 +
;GET /people/1: return the first record in HTML format
 +
;GET /people/1.html: return the first record in HTML format
 +
;GET /people/1.xml: return the first record in XML format
 +
;GET /people/1.json: return the first record in HTML format

Revision as of 22:37, 27 September 2007

URL Conventions

The recommended conventions for RESTful URLs are those used by Ruby on Rails. Following these conventions for both HTTP method names and URL construction will allow your application to be consumed by ActiveResource, Jester, and other RESTful clients.

Routing

The principal unit of operation is the "collection", which typically corresponds to a database table or (in Rails) an ActiveRecord class. For a collection named "people", the primary routes would be:

Operate on the Collection

GET /people
return a list of all records
GET /people/new
return a form for creating a new record
POST /people
submit fields for creating a new record

Operate on a 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
PUT /people/1
submit fields for updating the first record

Follow a Relationship

GET /people/1/friends
return the collection of friends associated with the first person
GET /people/1/friends/1
return the first friend of that person

Invoke Custom Actions

It isn't always possible to map everything into Create-Retrieve-Update-Delete (CRUD). Thus, there is also a syntax for specifying custom actions:

POST /people/1/promote
run the "promote" action against the first record

These should be used sparingly, as they are unlikely to be supported by most clients.

File Formats

Data types are extremely important in REST. While it is ideal to specify the appropriate mime-type, developers are encouraged to follow Rails in supporting extension-based typing, e.g.:

GET /people/1
return the first record in HTML format
GET /people/1.html
return the first record in HTML format
GET /people/1.xml
return the first record in XML format
GET /people/1.json
return the first record in HTML format