Rest Handler

The class Vectorface\SnappyRouter\Handler\RestHandler provides a simple "by convention" api routing handler that builds on top of the controller handler by mapping specific route patterns to controllers and actions.

Rest Routing

The following route patterns are supported:

/(optional/base/path/)v{$apiVersion}/${controller}/${objectId}/${action}
/(optional/base/path/)v{$apiVersion}/${controller}/${action}/${objectId}
/(optional/base/path/)v{$apiVersion}/${controller}/${action}
/(optional/base/path/)v{$apiVersion}/${controller}/${objectId}
/(optional/base/path/)v{$apiVersion}/${controller}

Examples:

/api/v1.2/users/1234/details
/api/v1.2/users/details/1234
/api/v1.2/users/search
/api/v1.2/users/1234
/api/v1.2/users

JSON Serialization

Unlike the Twig view handler used in standard controller handler, the rest handler is configured by default to encode all responses in JSON text. To use a different encoder it is recommended to subclass the RestHandler class and override a couple of methods.

Example:

<?php

namespace Vendor\MyNamespace\Handler;

use \Exception;
use Vectorface\SnappyRouter\Handler\RestHandler;

class MyRestHandler extends RestHandler
{
    public function getEncoder()
    {
        // return a custom encoder
    }

    public function handleException(Exception $e)
    {
        // custom exception handling if needed
    }
}

Writing a Restful Controller

Similar to the controller handler, the controller class should subclass Vectorface\SnappyRouter\Controller\AbstractController. A key difference between the REST handler and the controller handler is that the route parameters will always have the API version as the first element. If present in the route, the ${objectId} will be second element of the route parameters.

Note that the return value of the action will be encoded as a JSON string automatically.

Example controller:

<?php

namespace Vendor\MyNamespace\Controller;

use \Exception;
use Vectorface\SnappyRouter\Controller\AbstractController;

class RestUsersController extends AbstractController
{
    public function detailsAction($routeParams)
    {
        $apiVersion = array_pop($routeParams);
        if (empty($routeParams)) {
            throw new Exception('Missing user ID');
        }
        $user = ModelLayer::getUser(array_pop($routeParams));
        return $user->getDetails();
    }
}