rest/urls: Difference between revisions
Jump to navigation
Jump to search
(→Invoke Custom Actions: link) |
(added header) |
||
| Line 3: | Line 3: | ||
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]. 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. | ||
For a collection | == Routing == | ||
For a collection named "people", the primary routes would be: | |||
== Operate on the Collection == | === Operate on the Collection === | ||
;GET /people: return a list of all records | ;GET /people: return a list of all records | ||
;GET /people/new: return a form for creating a new record | ;GET /people/new: return a form for creating a new record | ||
;POST /people: submit fields for creating a new record | ;POST /people: submit fields for creating a new record | ||
== Operate on a Record == | === Operate on a Record === | ||
;GET /people/1: return the first record | ;GET /people/1: return the first record | ||
| Line 18: | Line 19: | ||
;PUT /people/1: submit fields for updating the first record | ;PUT /people/1: submit fields for updating the first record | ||
== Follow a Relationship == | === Follow a Relationship === | ||
;GET /people/1/friends: return the collection of friends associated with the first person | ;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 | ;GET /people/1/friends/1: return the first friend of that person | ||
=== 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 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: | ||
;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. | ||
Revision as of 22:35, 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. Following these conventions will allow your application to be consumed by ActiveResource, Jester, and other RESTful clients.
Routing
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.