REST¶

The Simple Setup¶

The fastest way to get up and running with REST is to add a few lines to your routes.php file, found in app/config. The Router object features a method called mapResources(), that is used to set up a number of default routes for REST access to your controllers. If we wanted to allow REST access to a recipe database, we’d do something like this:

//In app/config/routes.php...

Router::mapResources('recipes');
Router::parseExtensions();

The first line sets up a number of default routes for easy REST access. These routes are HTTP Request Method sensitive.

CakePHP’s Router class uses a number of different indicators to detect the HTTP method being used. Here they are in order of preference:

1. The _method POST variable

2. The X_HTTP_METHOD_OVERRIDE

3. The REQUEST_METHOD header

The _method POST variable is helpful in using a browser as a REST client (or anything else that can do POST easily). Just set the value of _method to the name of the HTTP request method you wish to emulate.

Once the router has been set up to map REST requests to certain controller actions, we can move on to creating the logic in our controller actions. A basic controller might look something like this:

// controllers/recipes_controller.php

class RecipesController extends AppController {

    var $components = array('RequestHandler');

    function index() {
        $recipes = $this->Recipe->find('all');
        $this->set(compact('recipes'));
    }

    function view($id) {
        $recipe = $this->Recipe->findById($id);
        $this->set(compact('recipe'));
    }

    function edit($id) {
        $this->Recipe->id = $id;
        if ($this->Recipe->save($this->data)) {
            $message = 'Saved';
        } else {
            $message = 'Error';
        }
        $this->set(compact("message"));
    }

    function delete($id) {
        if($this->Recipe->delete($id)) {
            $message = 'Deleted';
        } else {
            $message = 'Error';
        }
        $this->set(compact("message"));
    }
}

Since we’ve added a call to Router::parseExtensions(), the CakePHP router is already primed to serve up different views based on different kinds of requests. Since we’re dealing with REST requests, the view type is XML. We place the REST views for our RecipesController inside app/views/xml. We can also use the XmlHelper for quick-and-easy XML output in those views. Here’s what our index view might look like:

// app/views/recipes/xml/index.ctp

<recipes>
    <?php echo $xml->serialize($recipes); ?>
</recipes>

Experienced CakePHP users might notice that we haven’t included the XmlHelper in our RecipesController $helpers array. This is on purpose - when serving up a specific content type using parseExtensions(), CakePHP automatically looks for a view helper that matches the type. Since we’re using XML as the content type, the XmlHelper is automatically loaded up for our use in those views.

The rendered XML will end up looking something like this:

<posts>
    <post id="234" created="2008-06-13" modified="2008-06-14">
        <author id="23423" first_name="Billy" last_name="Bob"></author>
        <comment id="245" body="This is a comment for this post."></comment>
    </post>
    <post id="3247" created="2008-06-15" modified="2008-06-15">
        <author id="625" first_name="Nate" last_name="Johnson"></author>
        <comment id="654" body="This is a comment for this post."></comment>
    </post>
</posts>

Creating the logic for the edit action is a bit trickier, but not by much. Since you’re providing an API that outputs XML, it’s a natural choice to receive XML as input. Not to worry, however: the RequestHandler and Router classes make things much easier. If a POST or PUT request has an XML content-type, then the input is taken and passed to an instance of Cake’s Xml object, which is assigned to the $data property of the controller. Because of this feature, handling XML and POST data in parallel is seamless: no changes are required to the controller or model code. Everything you need should end up in $this->data.

Asignación de rutas personalizadas REST¶

Si las rutas por defecto creadas a través de mapResources() se ajustan a un desarrollado determinado, entonces utilizar el método Router::connect() para definir un conjunto personalizado de rutas REST. El método connect() permite definir un número de opciones diferentes para una URL dada. El primer parámetro es la URL misma, y el segundo parámetro permite suministrar aquellas opciones. El tercer parámetro permite especificar los patrones de expresiones regulares para ayudar a CakePHP a identificar determinados marcadores en la URL especificada.

Aquí se provee un simple ejemplo, permite ajustar la ruta para sus propios propósitos en el uso de RESTful. Lo que se muestra a continuación es una posible ruta de edición personalizada, sin utilizar mapResources():

Router::connect(
    "/:controller/:id",
    array("action" => "edit", "[method]" => "PUT"),
    array("id" => "[0-9]+")
)

Técnicas avanzadas de asignación de rutas no son cubiertas aquí, así se le otorga el foco al punto más importante para los propósitos del ejemplo: la clave [method] del arreglo de opciones en el segundo parámetro. Una vez que la clave ha sido establecida, la ruta especificada funcionará solo para aquel método de solicitud HTTP (el cual bien podría ser GET, DELETE, etc.)