Step 3: Extending the REST API

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 present how to create a new eZ Publish REST extension.

• Create an empty folder called “ezxrestapidemo” under the “ <eZ Publish>/extension” location.
• 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.

• 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
 &nbsp;
 class ezxRestApiProvider implements ezpRestProviderInterface
 {
    /**
     * Returns registered versioned routes for provider
     *
     * @return array Associative array. Key is the route name (beware of name collision!). Value is the versioned route.
     */
     public function getRoutes()
     {
            return array( 'foo'&    => new ezpRestVersionedRoute( new  ezcMvcRailsRoute( '/foo', 'ezxRestController', 'foo' ), 1 ),
                                 'foobar' => 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”.

• 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.

• 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.

• 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

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

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

• 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!"}