REST

Many newer application programmers are realizing the need to open their corefunctionality to a greater audience. Providing easy, unfettered access to yourcore API can help get your platform accepted, and allows for mashups and easyintegration with other systems.

While other solutions exist, REST is a great way to provide easy access to thelogic you’ve created in your application. It’s simple, usually XML-based (we’retalking simple XML, nothing like a SOAP envelope), and depends on HTTP headersfor direction. Exposing an API via REST in CakePHP is simple.

The Simple Setup

The fastest way to get up and running with REST is to add a few lines to setupresource routes in your config/routes.php file.

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

// src/Controller/RecipesController.php
class RecipesController extends AppController
{
    public function initialize(): void
    {
        parent::initialize();
        $this->loadComponent('RequestHandler');
    }
 
    public function index()
    {
        $recipes = $this->Recipes->find('all');
        $this->set('recipes', $recipes);
        $this->viewBuilder()->setOption('serialize', ['recipes']);
    }
 
    public function view($id)
    {
        $recipe = $this->Recipes->get($id);
        $this->set('recipe', $recipe);
        $this->viewBuilder()->setOption('serialize', ['recipe']);
    }
 
    public function add()
    {
        $this->request->allowMethod(['post', 'put']);
        $recipe = $this->Recipes->newEntity($this->request->getData());
        if ($this->Recipes->save($recipe)) {
            $message = 'Saved';
        } else {
            $message = 'Error';
        }
        $this->set([
            'message' => $message,
            'recipe' => $recipe,
        ]);
        $this->viewBuilder()->setOption('serialize', ['recipe', 'message']);
    }
 
    public function edit($id)
    {
        $this->request->allowMethod(['patch', 'post', 'put']);
        $recipe = $this->Recipes->get($id);
        $recipe = $this->Recipes->patchEntity($recipe, $this->request->getData());
        if ($this->Recipes->save($recipe)) {
            $message = 'Saved';
        } else {
            $message = 'Error';
        }
        $this->set([
            'message' => $message,
            'recipe' => $recipe,
        ]);
        $this->viewBuilder()->setOption('serialize', ['recipe', 'message']);
    }
 
    public function delete($id)
    {
        $this->request->allowMethod(['delete']);
        $recipe = $this->Recipes->get($id);
        $message = 'Deleted';
        if (!$this->Recipes->delete($recipe)) {
            $message = 'Error';
        }
        $this->set('message', $message);
        $this->viewBuilder()->setOption('serialize', ['message']);
    }
}

RESTful controllers often use parsed extensions to serve up different viewsbased on different kinds of requests. Since we’re dealing with REST requests,we’ll be making XML views. You can make JSON views using CakePHP’s built-inJSON and XML views. By using the built in XmlView wecan define a serialize option. This option is used to define which viewvariables XmlView should serialize into XML.

If we wanted to modify the data before it is converted into XML we should notdefine the serialize option, and instead use template files. We placethe REST views for our RecipesController inside templates/Recipes/xml. We can also usethe Xml for quick-and-easy XML output in those views. Here’s whatour index view might look like:

// templates/Recipes/xml/index.php
// Do some formatting and manipulation on
// the $recipes array.
$xml = Xml::fromArray(['response' => $recipes]);
echo $xml->asXML();

When serving up a specific content type using Cake\Routing\Router::extensions(),CakePHP automatically looks for a view helper that matches the type.Since we’re using XML as the content type, there is no built-in helper,however if you were to create one it would automatically be loadedfor our use in those views.

The rendered XML will end up looking something like this:

<recipes>
    <recipe>
        <id>234</id>
        <created>2008-06-13</created>
        <modified>2008-06-14</modified>
        <author>
            <id>23423</id>
            <first_name>Billy</first_name>
            <last_name>Bob</last_name>
        </author>
        <comment>
            <id>245</id>
            <body>Yummy yummmy</body>
        </comment>
    </recipe>
    ...
</recipes>

Creating the logic for the edit action is a bit trickier, but not by much. Sinceyou’re providing an API that outputs XML, it’s a natural choice to receive XMLas input. Not to worry, theCake\Controller\Component\RequestHandler andCake\Routing\Router classes make things much easier. If a POST orPUT request has an XML content-type, then the input is run through CakePHP’sXml class, and the array representation of the data is assigned to$this->request->getData(). Because of this feature, handling XML and POST data inparallel is seamless: no changes are required to the controller or model code.Everything you need should end up in $this->request->getData().

Accepting Input in Other Formats

Typically REST applications not only output content in alternate data formats,but also accept data in different formats. In CakePHP, theRequestHandlerComponent helps facilitate this. By default,it will decode any incoming JSON/XML input data for POST/PUT requestsand supply the array version of that data in $this->request->getData().You can also wire in additional deserializers for alternate formats if youneed them, using RequestHandler::addInputType().

RESTful Routing

CakePHP’s Router makes connecting RESTful resource routes easy. See the sectionon RESTful Routing for more information.