Manual

RESTful Services

To make it easier to setup RESTful web services with Routes, there's a shortcut Mapper method that will setup a batch of routes for you along with conditions that will restrict them to specific HTTP methods. This is directly styled on the Rails version of $map->resource(), which was based heavily on the Atom Publishing Protocol.

The Horde_Routes_Mapper->resource() command creates a set of Routes for common operations on a collection of resources, individually referred to as 'members'. Consider the common case where you have a system that deals with users. In that case operations dealing with the entire group of users (or perhaps a subset) would be considered collection methods. Operations (or actions) that act on an individual member of that collection are considered member methods. These terms are important to remember as the options to $map->resource() rely on a clear understanding of collection actions vs. member actions.

The default mapping that $map->resource() sets up looks like this: 

$map->resource('message', 'messages')

// Will setup all the routes as if you had typed the following map commands:
$map->connect('messages', 
  array('controller'=>'messages', 'action'=>'create', 
        'conditions'=>array('method'=>array('POST'))));
$map->connect('messages', 'messages', 
  array('controller'=>'messages', 'action'=>'index', 
        'conditions'=>array('method'=>array('GET'))));
$map->connect('formatted_messages', 'messages.:(format)', 
  array('controller'=>'messages', action=>'index',
        'conditions'=>array('method'=>array('GET'))));
$map->connect('new_message', 'messages/new', 
  array('controller'=>'messages', 'action'=>'new',
        'conditions'=>array('method'=>array('GET'))));
$map->connect('formatted_new_message', 'messages/new.:(format)', 
  array('controller'=>'messages', 'action'=>'new',
        'conditions'=>array('method'=>array('GET'))));
$map->connect('messages/:id', 
  array('controller'=>'messages', 'action'=>'update',
    'conditions'=>array('method'=>array('PUT'))));
$map->connect('messages/:id', 
  array('controller'=>'messages', 'action'=>'delete',
    'conditions'=>array('method'=>array('DELETE'))));
$map->connect('edit_message', 'messages/:(id)/edit', 
  array('controller'=>'messages', 'action'=>'edit',
        'conditions'=>array('method'=>array('GET'))));
$map->connect('formatted_edit_message', 'messages/:(id)/edit.:(format)', 
  array('controller'=>'messages', 'action'=>'edit', 
        'conditions'=>array('method'=>array('GET'))));
$map->connect('message', 'messages/:id', 
  array('controller'=>'messages', 'action'=>'show',
        'conditions'=>array('method'=>array('GET'))));
$map->connect('formatted_message', 'messages/:(id).:(format)', 
  array('controller'=>'messages', 'action'=>'show',
    'conditions'=>array('method'=>array('GET'))));

The most important aspects of this is the following mapping that is established: 

GET    /messages         -> messages.index()          -> $utils->urlFor('messages')
POST   /messages         -> messages.create()         -> $utils->urlFor('messages')
GET    /messages/new     -> messages.new()            -> $utils->urlFor('new_message')
PUT    /messages/1       -> messages.update(id)       -> $utils->urlFor('message', array('id'=>1))
DELETE /messages/1       -> messages.delete(id)       -> $utils->urlFor('message', array('id'=>1))
GET    /messages/1       -> messages.show(id)         -> $utils->urlFor('message', array('id'=>1))
GET    /messages/1/edit  -> messages.edit(id)         -> $utils->urlFor('edit_message', array('id'=>1))

Note Several of these methods map to functions intended to display forms. The new message method should be used to return a form allowing someone to create a new message, while it should POST to /messages. The edit message function should work similarly returning a form to edit a message, which then performs a PUT to the /messages/1 resource.

Additional methods that respond to either a new member, or different ways of viewing collections can be added via keyword arguments to $map->resource() as shown in the complete list with examples of the $map->resource() options.