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 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.