Extending eZ Publish’s REST API - Developer Preview #2

Step 4 : Extending REST

As of now it is possible to extend the eZ Publish REST interface with custom functionality. One REST extension can support many different data providers as well as different versions. The following steps presents how to create a new eZ Publish REST extension.

1. Create an empty folder called “ezxrestapidemo” under the “ <eZ Publish>/extension” location.

2. Inside “ezxrestapidemo” create a setting with the “rest.ini.append.php” file with following content:

<?php /*

[ApiProvider]
ProviderClass[ezx]=ezxRestApiProvider

*/ ?>

ProviderClass is an array where the index is a provider token used in the resource URI. For example for URI: “/api/ezx/v1/foo” the registered provider with token “ezx” will be called. You can have many providers registered within one extension.

3. Next create a folder called “classes” under the “<eZ Publish>/extension/ezxrestapidemo/” location with the “rest_provider.php file”. Edit the newly created PHP file and add the following code:

<?php
class ezxRestApiProvider implements ezpRestProviderInterface
{
    /**
     * Returns registered versioned routes for provider
     *
     * @return array
     */
    public function getRoutes()
    {
        return array( new ezpRestVersionedRoute( new ezcMvcRailsRoute( '/foo',
                                                          'ezxRestController', 'foo' ), 1 ),                                                         
                      new ezpRestVersionedRoute( new ezcMvcRailsRoute( '/foo',                        
                                                           'ezxRestController', 'fooBar' ), 2 ) );
    }

    /**
     * Returns associated with provider view controller
     *
     * @return ezpRestViewController
     */
    public function getViewController()
    {
        return new ezxRestApiViewController();
    }
}
?>

Every REST API provider has to implement the “ezpRestProviderInterface” where “getRoutes()” methods returns registered versioned routes for provider and “getViewController()” returns view controller object which has to implement the “ezpRestViewControllerInterface”.

4. In the next step create the file “view_controller.php” under the “<eZ Publish>/extension/ezxrestapidemo/classes” folder with following code:

<?php
class ezxRestApiViewController implements ezpRestViewControllerInterface
{
    /**
     * Creates a view required by controller's result
     *
     * @param ezcMvcRoutingInformation $routeInfo

    * @param ezcMvcRequest $request
    * @param ezcMvcResult $result
    * @return ezcMvcView
    */
    public function loadView( ezcMvcRoutingInformation $routeInfo, ezcMvcRequest $request,
ezcMvcResult $result )
    {
        return new ezpRestJsonView( $request, $result );
    }
}
?>

Every view controller has to implement the “ezpRestViewControllerInterface” where the “loadView()” method returns an instance of the “ezcMvcView” object. In this example we re-use the “ezpRestJsonView” which is a part of the built-in API, if your provider need a custom view, you can return it here.

5. Registered for REST provider URIs are associated with controllers. This example calls the methods foo() and fooBar() on “ezxRestController”. Create a file called “rest_controller.php” under “<eZ Publish>/extension/ezxrestapidemo/classes” folder and put the following code inside:

<?php

class ezxRestController extends ezcMvcController
{
    public function doFoo()
    {
        $res = new ezcMvcResult();
        $res->variables['message'] = "This is FOO!";
        return $res;
    }

    public function doFooBar()
    {
        $res = new ezcMvcResult();
        $res->variables['message'] = "This is FOOBAR!";
        return $res;
    }
}

?>

Notice the controller methods naming convention. All methods have to be prefixed with “do” word. This is a “ezcMvcController” requirement.

6. Enable “ezxrestapidemo” by adding the following to “ActiveExtensions” list in the “settings/override/site.ini.append.php”

[ExtensionSettings]
[…]
ActiveExtensions[]=oauth
ActiveExtensions[]=rest
ActiveExtensions[]=ezprestapiprovider
ActiveExtensions[]=ezxrestapidemo

7. Update the autoload array with a following command from the eZ Publish root folder :

php bin/php/ezpgenerateautoloads.php -e -p

8. If you have followed all steps carefully then you should be ready to test your new REST API provider by calling www.example.com/api/ezx/v1/foo A simple JSON response should look like :

{"message":"This is FOO!"}

For the second URI www.example.com/api/ezx/v2/foo output should be following:

{"message":"This is FOOBAR!"}