rest/urls
URL Conventions
The recommended conventions for RESTful URLs are those used by Ruby on Rails, as seen in 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.
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