Enable API on new frontend app¶

• from shell

  cd /path/to/bedita
  ./cake.sh frontend init
  

• in app/config/frontend.ini.php define $config['api']['baseUrl'] with your API base url, for example

  $config['api'] = array('baseUrl' => '/api/v1');
  

That’s all! You are ready to consume the API!

Point the browser to your API base url and you should see the list of endpoints available, for example

{
    "auth": "http://example.com/api/v1/auth",
    "me": "http://example.com/api/v1/me",
    "objects": "http://example.com/api/v1/objects",
    "poster": "http://example.com/api/v1/poster"
}

Enable API on old frontend app¶

• create a new ApiController in your frontend

  require(BEDITA_CORE_PATH . DS . 'controllers' . DS . 'api_base_controller.php');
  
  class ApiController extends ApiBaseController {
     //...
  }
  

• in app/config/frontend.ini.php define $config['api']['baseUrl'] with your API base url.

• edit app/config/routes.php putting

  $apiBaseUrl = Configure::read('api.baseUrl');
  if (!empty($apiBaseUrl) && is_string($apiBaseUrl)) {
     Router::connect($apiBaseUrl . '/*', array('controller' => 'api', 'action' => 'route'));
  }
  

  above

  Router::connect('/*', array('controller' => 'pages', 'action' => 'route'));
  

That’s all!

After #570 we have implemented a new (and better) way to handle Exceptions. Remember to update your frontend index.php file:

if (isset($_GET['url']) && $_GET['url'] === 'favicon.ico') {
    return;
} else {
    $Dispatcher = new Dispatcher();
    $Dispatcher->dispatch();
}

Also make sure you have defined views/errors/error.tpl in your frontend for generic error handling.

Response¶

Usually the response of API query has the structure

{
    "api": "objects",
    "data": {},
    "method": "get",
    "params": [],
    "url": "https://example.com/api/v1/objects/1"
}

where:

• api is the endpoint called
• data is an object containing all data requested
• method is the HTTP verb used in the request
• params contains all query url params used in the request
• url is the complete url requested (full base url + basepath + endpoint + other)

To set data for response is available the method ApiBaseController::setData() that accepts an array as first argument. A second argument permits to replace (default) or merge present data with that passed.

Other meta data can be placed inside response object, for example paging useful to paginate results:

{
    "api": "objects",
    "data": {},
    "method": "get",
    "paging": {
        "page": 1,
        "page_size": 10,
        "page_count": 10,
        "total": 995,
        "total_pages": 100
    },
    "params": [],
    "url": "https://example.com/api/v1/objects/1/children"
}

where:

• page is the current page
• page_size is the page dimension
• page_count is the number of items inside current page
• total if the count of all items
• total_pages is the total pages available

Errors¶

Every time the API thrown an error the response will be similar to

{
    "error": {
        "status": 405,
        "code": null,
        "message": "Method Not Allowed",
        "details": "Method Not Allowed",
        "more_info": null,
        "url": "https://example.com/api/v1/foobar"
    }
}

where:

• status is the HTTP status code
• code is the API error code (not implemented)
• message is the error message
• details is the error detail
• more_info is the url to error documentation (not implemented)
• url is the url that has responded with the error

Customize authentication¶

If you need to customize or change the authentication you can define your own auth component. To maintain the component method signature used in ApiBaseController your component should implements the interface ApiAuthInterface.

Remember that REST API are thought to implement token based authentication with the use of both access_token and refresh_token so the interface define methods to handle these tokens. If you need something different probably you would also override authenication methods of ApiBaseController.

In case you only need some little change it should be better to directly extend ApiAuth component that already implements the interface, and override the methods you need.

For example supposing you want to add additional check to user credentials, you can simply override ApiAuth::authenticate() method which deals with it:

App::import('Component', 'ApiAuth');

class CustomAuthComponent extends ApiAuthComponent {

    public function authenticate($username, $password, array $authGroupName = array()) {
        // authentication logic here
    }

}

and finally to activate the component all you have to do is define in configuration file config/frontend.ini.php the auth component you want to use.

$config['api'] = array(
    'baseUrl' => '/api',
    'auth' => array(
        'component' => 'CustomAuth'
    )
);

In ApiController you will have access to CustomAuth instance by $this->ApiAuth attribute.

Define your API pagination default options¶

The default values used paginating items are defined in ApiBaseController::paginationOptions property.

protected $paginationOptions = array(
    'page' => 1,
    'pageSize' => 20,
    'maxPageSize' => 100
);

where pageSize is the default items per page and maxPageSize is the max page dimension that client can request. Requests with page_size greater of maxPageSize returns a 400 HTTP error.

If you want modify those defaults you can simply override that property in ApiController.

Paginate objects in custom endpoints¶

When a request has page or page_size as GET parameters those are validated and $paginationOptions is updated to contain the requested page options. A dim key equal to pageSize is added to be ready to use in some methods as FrontendController::loadSectionObjects().

In this way in a ‘custom’ API endpoint you can simply do

protected function custom($id) {
    $result = $this->loadSectionObjects($id, $this->paginationOptions);
    // format and set pagination
    $this->setPaging($this->ApiFormatter->formatPaging($result['toolbar']));

    // do other stuff
}

and you are sure that pagination will work properly without doing anything else.

Custom endpoints¶

Once you have enabled a frontend to consume API you have a set of default available endpoints visible pointing the browser to your API base url.

Sometimes you would want to define other endpoints to serve your custom data to clients. You can do it simply override the $endpoints attribute of ApiBaseController.

Write in your ApiController

protected $endPoints = array('friends');

and define the related custom method that will handle the data to show

protected function friends() {
    $friendsList = array('Tom', 'Jerry');
    $this->setData($friendsList);
}

The setData() method takes care of put $friendsList array inside response data key. Point the browser to your API base url you should see ‘friends’ in the endpoints list and if you request GET /api/base/url/friends you should see

{
    "api": "friends",
    "data": [
        "Tom",
        "Jerry"
    ],
    "method": "get",
    "params": [],
    "url": "https://example.com/api/v1/friends"
}

In this way all request types (GET, POST, PUT, DELETE) have to be handled by friends() method. Another possibility is to create one method for every request type allowed from the endpoint. It can be done creating methods named “request type + endpoint camelized”.

protected function getFriends() {
}

protected function postFriends() {
}

protected function putFriends() {
}

protected function deleteFriends() {
}

Blacklist endpoints¶

In some situations you will not want to expose some or all default endpoints, so in order to disable them it is possible to define a blacklist. After that calling those endpoints the response will be a 405 Method Not Allowed HTTP error status code.

For example to blacklist “auth” and “objects” endpoints, in your ApiController override $blacklistEndPoints writing

protected $blacklistEndPoints = array('auth', 'objects');

Now, pointing to API base url you shouldn’t see “auth” and “objects” endpoints anymore.

Pointing to them directly and you will receive a 405 HTTP error.

Enable special object types endpoints¶

If you need you can also enable some special endpoint disabled by default. Those endpoints refer to BEdita object types mapping them to their pluralize form. So if you want to enable /documents end /galleries endpoints you have to edit ApiController

protected $whitelistObjectTypes = array('document', 'gallery');

These special endpoints automatically filter response objects through the object type related.

Again go to API base url to see ‘documents’ and ‘galleries’ added to endpoints list.

Note

Note that those special endpoints work only for GET requests.

Customize /objects endpoint with your own URL path filter types¶

objects endpoint can be customized with URL path filters building endpoint structured as /objects/:id/url_path_filter. URL path filters on by default are visible in ApiBaseController::$allowedObjectsUrlPath property

protected $allowedObjectsUrlPath = array(
        'get' => array(
            'relations',
            'children',
            'contents',
            'sections',
            'descendants',
            'siblings',
            //'ancestors',
            //'parents'
        ),
        'post' => array(
            'relations',
            'children'
        ),
        'put' => array(
            'relations',
            'children'
        ),
        'delete' => array(
            'relations',
            'children'
        )
    );

URL path filters can be inhibited or new ones can be added overriding that property in ApiController.

In practice URL path filters are divided by request type (GET, POST, ...) so it is possible doing request like GET /objects/1/children, POST /objects/1/relations but not POST /objects/1/siblings because of that filter is active only for GET requests.

Every URL path filter must have a corresponding controller method named “request type + Objects + URL path filter camelized” that will handle the request. First url part :id and every other url parts after URL path filter will be passed to that method as arguments.

For example, supposing to want to remove all ‘delete’ and ‘post’ URL path filters and add a new ‘foo_bar’ filter for GET request, in ApiController we can override

protected $allowedObjectsUrlPath = array(
        'get' => array(
            'relations',
            'children',
            'contents',
            'sections',
            'descendants',
            'siblings',
            'foo_bar'
        ),
    );

and add the method

protected function getObjectsFooBar($objectId) {
    // handle request here
}

In this way the new URL path filter is active and reachable from GET /objects/:id/foo_bar. Every other request type (POST, PUT, DELETE) to that will receive 405 Method Not Allowed.

If our ‘foo_bar’ URL path filter have to support GET /objects/:id/foo_bar/:foo_val requests then ApiController::getObjectsFooBar() will receive :foo_val as second argument. A best practice should be to add to method a validation on the number of arguments supported to avoid to respond to request as GET /objects/:id/foo_bar/:foo_val/bla/bla/bla.

protected function getObjectsFooBar($objectId, $fooVal = null) {
    if (func_num_args() > 2) {
        throw new BeditaBadRequestException();
    }
    // handle request here
}

Introducing the ApiFormatter Component¶

To respond with consistent data the BEdita object types are transformed and formatted using the ApiFormatter Component that deals with cleaning objects from useless data and casting and trasforming some fields in correct format.

If you have a look at /objects/:id response you’ll see that fields as ‘id’ are integer other like ‘latitude’ and ‘longitude’ of geo tag are float and dates are formatted in ISO-8601. ApiFormatter Component with a little help from Models takes care of it.

When you load an object or list of objects you should always use the ApiFromatter Component to have data always formatted in the same way.

// load an object
$object = $this->loadObj($id);
$result = $this->ApiFormatter->formatObject($object);
// in $result['object'] you have the formatted object

// list of objects
$objects = $this->loadSectionObjects($id, array('itemsTogether' => true));
$result = $this->ApiFormatter->formatObjects($objects['children']);
// in $result['objects'] you have the formatted objects

ApiFormatter::formatObject() and ApiFormatter::formatObjects() accept as second argument an array of options with which it is possible add to the formatted object the count of relations and children.

$result = $this->ApiFormatter->formatObject($object, array(
    'countRelations' => true,
    'countChildren' => true
));

By default no count is done.

Help ApiFormatter to cast object fields in the right way¶

When formatting BEdita object ApiFormatter asks help to related object type Model to know which fields have to be cast in the right type. Basically every object type returns an array of fields that are defined in database as ‘integer’, ‘float’, ‘date’, ‘datetime’, ‘boolean’. This array is returned from BEAppObjectModel::apiTransformer() method and it is something similar to

array(
    'id' => 'integer',
    'start_date' => 'datetime',
    'end_date' => 'datetime',
    'duration' => 'integer',
    'object_type_id' => 'integer',
    'created' => 'datetime',
    'modified' => 'datetime',
    'valid' => 'boolean',
    'user_created' => 'integer',
    'user_modified' => 'integer',
    'fixed' => 'boolean',
    'GeoTag' => array(
        'id' => 'integer',
        'object_id' => 'integer',
        'latitude' => 'float',
        'longitude' => 'float',
        'gmaps_lookat' => array(
            'latitude' => 'float',
            'longitude' => 'float',
            'zoom' => 'integer',
        )

    )
    'Tag' => array(
        'id' => 'integer',
        'area_id' => 'integer',
        'object_type_id' => 'integer',
        'priority' => 'integer',
        'parent_id' => 'integer',
    ),
    'Category' => array(
        'id' => 'integer',
        'area_id' => 'integer',
        'object_type_id' => 'integer',
        'priority' => 'integer',
        'parent_id' => 'integer',
    )
)

By default only tables that form the object chain plus ‘categories’, ‘tags’ and ‘geo_tags’ are automatically returned, but that method can be overridden to customize the result. For example the Event model add to basic transformer the DateItem transformer:

public function apiTransformer(array $options = array()) {
    $transformer = parent::apiTransformer($options);
    $transformer['DateItem'] = $this->DateItem->apiTransformer($options);
    return $transformer;
}

The ApiFormatter uses these transformers merged to common object transformer ApiFormatterComponent::$transformers['object'] to present consistent data to client. It is possible to use some special transformer types that are:

• underscoreField that underscorize a camelcase field maintaining value unchanged
• integerArray that cast to integer all array values

Remove unwanted fields¶

Another useful task of ApiFormatter is to clean unwanted fields from data exposed to client. To do that it uses ApiFormatter::$objectFieldsToRemove array that can be customized through configuration or on the fly in controller.

$config['api'] = array(
    'baseUrl' => '/api/v1',
    ...
    'formatting' => array(
        'fields' => array(
            // fields that should be added
            // to ApiFormattingComponent::objectFieldsToRemove
            // i.e. removed from formatted object
            'remove' => array(
                'description',
                'title',
                'Category' => array('name'),
                'GeoTag' => array('title'),
                'Tag'
            )
        )
    )
);

// get the current value
$currentFieldsToRemove = $this->ApiFormatter->objectFieldsToRemove();

// to ovveride all. It completely replaces current fields to remove with new one
$this->ApiFormatter->objectFieldsToRemove(
    array(
        'title',
        'description'
    ),
    true
);

// to add new fields to remove
$this->ApiFormatter->objectFieldsToRemove(array(
    'remove' => array('title', 'description')
));

Keep fields that are removed by default¶

Sometime you could want to present to client some fields that normally are cleaned up. Likewise to what seen with fields to remove, it is possible do it from configuration or on the fly.

$config['api'] = array(
    'baseUrl' => '/api/v1',
    ...
    'formatting' => array(
        'fields' => array(
            // fields that should be removed
            // to ApiFormattingComponent::objectFieldsToRemove
            // i.e. kept in formatted object
            'keep' => array(
                'fixed',
                'ip_created',
                'Category' => array('object_type_id', 'priority')
            )
        )
    )
);

// to keep fields
$this->ApiFormatter->objectFieldsToRemove(array(
    'keep' => array('ip_created', 'fixed')
));