rest/urls: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(→‎Routing: creation)
(methods)
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], as seen in [http://developer.37signals.com/highrise/ Highrise]. 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. Note that Rails 1.x used ";edit" and ";new" in place of the simpler "/edit" and "/new" recommended going forward.
These are the recommended conventions for [http://bitworking.org/news/How_to_create_a_REST_Protocol RESTful URLs], based on work pioneered 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. Note that Rails 1.x used ";edit" and ";new" in place of the simpler "/edit" and "/new" recommended going forward.


== Methods ==
One of the key aspects of REST is using the HTTP Verbs to implement the standard Create-Retrieve-Update-Delete ([http://en.wikipedia.org/wiki/Create%2C_read%2C_update_and_delete CRUD]) database semantics.
;POST:'''C'''reate a resource within a given collection
;GET:'''R'''etrieve a resource
;PUT:'''U'''pdate a resource
;DELETE:'''D'''elete a resource
Note that most browsers do not currently support PUT and DELETE, so those need to be implemented using a POST with an "?_method=" argument.
== Routing ==  
== Routing ==  
The principal unit of operation is the "collection", which typically corresponds to a database table or (in Rails) an ActiveRecord class.  
The principal unit of operation is the "collection", which typically corresponds to a database table or (in Rails) an ActiveRecord class.  
Line 16: Line 26:
;GET /people/1: return the first record
;GET /people/1: return the first record
;DELETE /people/1: destroy the first record
;DELETE /people/1: destroy the first record
;POST /people/1?_method=DELETE: alias for DELETE, to compensate for browser limitations


;GET /people/1/edit: return a form to edit 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
;PUT /people/1: submit fields for updating the first record
;POST /people/1?_method=PUT: alias for PUT, to compensate for browser limitations


=== Follow a Relationship ===
=== Follow a Relationship ===
Line 28: Line 40:


=== Invoke Custom Actions ===
=== Invoke Custom Actions ===
It isn't always possible to map ''everything'' into Create-Retrieve-Update-Delete ([http://en.wikipedia.org/wiki/Create%2C_read%2C_update_and_delete CRUD]).  Thus, there is also a syntax for specifying custom actions:
It isn't always possible to map ''everything'' into CRUD.  Thus, there is also a syntax for specifying custom actions:
;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.
Line 50: Line 62:
See the [http://developer.37signals.com/highrise/reference.shtml Highrise reference] for an example of how this works in practice.
See the [http://developer.37signals.com/highrise/reference.shtml Highrise reference] for an example of how this works in practice.


= Implementations =
== Response Codes ==
Another important aspect of REST is returning the appropriate [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP Response Codes].
 
= Examples in the Wild =


* [http://www.computerworld.com/action/article.do?command=viewArticleBasic&articleId=9020098 Ruby on Rails]
* [http://www.computerworld.com/action/article.do?command=viewArticleBasic&articleId=9020098 Ruby on Rails]
*  [http://developer.37signals.com/highrise/ Highrise]
* [http://weblogs.java.net/blog/bleonard/archive/2007/08/rails_to_java_v.html Java]
* [http://weblogs.java.net/blog/bleonard/archive/2007/08/rails_to_java_v.html Java]
* [http://routes.groovie.org/index.html  Python]
* [http://routes.groovie.org/index.html  Python]
* [http://giantrobots.thoughtbot.com/2007/4/2/jester-javascriptian-rest Jester] (JavaScript)
* [http://giantrobots.thoughtbot.com/2007/4/2/jester-javascriptian-rest Jester] (JavaScript)
* ....
* ....

Revision as of 21:56, 28 September 2007

URL Conventions

These are the recommended conventions for RESTful URLs, based on work pioneered 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. Note that Rails 1.x used ";edit" and ";new" in place of the simpler "/edit" and "/new" recommended going forward.

Methods

One of the key aspects of REST is using the HTTP Verbs to implement the standard Create-Retrieve-Update-Delete (CRUD) database semantics.

POST
Create a resource within a given collection
GET
Retrieve a resource
PUT
Update a resource
DELETE
Delete a resource

Note that most browsers do not currently support PUT and DELETE, so those need to be implemented using a POST with an "?_method=" argument.

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
POST /people/1?_method=DELETE
alias for DELETE, to compensate for browser limitations
GET /people/1/edit
return a form to edit the first record
PUT /people/1
submit fields for updating the first record
POST /people/1?_method=PUT
alias for PUT, to compensate for browser limitations

Follow a Relationship

GET /people/1/phones
return the collection of phone numbers associated with the first person
GET /people/1/phones/23
return the phone number with id #15 associated with the first person
GET /people/1/phones/new
return a form for creating a new phone number for the first person
POST /people/1/phones/
submit fields for creating a new phone number for the first person

Invoke Custom Actions

It isn't always possible to map everything into 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 as an HTTP header, developers are encouraged to follow Rails in allowing extension-based typing, e.g.:

HTML

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

XML

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

JSON

GET /people/1.json
return the first record in JSON format

While the JSON mapping should be trivially obvious, the best practice for XML is to:

  1. use the column name as the element name
  2. include an appropriate "type" field

See the Highrise reference for an example of how this works in practice.

Response Codes

Another important aspect of REST is returning the appropriate HTTP Response Codes.

Examples in the Wild

Retrieved from "http://microformats.org/wiki/index.php?title=rest/urls&oldid=21959"