API : Extending the API

• API Index

Register Your Resource

You can extend the API to include custom resources. In your plugin, register your resource using the api_resources filter, following this format:

<?php
public function filterApiResources($apiResources)
{
    // For the path: /api/your_resources/:id
    $apiResources['your_resources'] = array(
        // Module associated with your resource.
        'module' => 'your-plugin-name', 
        // Controller associated with your resource.
        'controller' => 'your-resource-controller',
        // Type of record associated with your resource.
        'record_type' => 'YourResourceRecord',
        // List of actions available for your resource.
        'actions' => array(
            'index',  // GET request without ID
            'get',    // GET request with ID
            'post',   // POST request
            'put',    // PUT request (ID is required)
            'delete', // DELETE request (ID is required)
        ), 
        // List of GET parameters available for your index action.
        'index_params' => array('foo', 'bar'), 
    );
    return $apiResources;
}

If not given, module and controller fall back to their defaults, "default" and "api". Resources using the default controller MUST include a record_type. Remove actions that are not wanted or not implemented. For index actions, all GET parameters must be registered with the index_params whitelist.

Resource Record Type

Your record must have a corresponding API adapter called Api_{YourRecordType} that must extend Omeka_Record_Api_AbstractRecordAdapter and be saved to your plugin's models directory in a subdirectory named Api, e.g. YourPlugin/models/Api/YourRecordType.php. This adapter is responsible for building representations of your record and setting properties to your record.

Extend Existing Resources

You can extend the representations of existing resources by using the api_extend_* filter, where * is the resource you want to extend.

<?php
public function filterApiExtendItems($extend, $args)
{
    $item = $args['record'];
    
    // For one resource:
    $resourceId = $this->_db->getTable('YourResource')->findByItemId($item->id);
    $extend['your_resources'] = array(
        'id' => 1,
        'url' => 'your_resources/' . $resourceId->id,
    );
    
    // Or, for multiple resources:
    $extend['your_resources'] = array(
        'count' => 10,
        'url' => 'your_resources?item=' . $item->id,
    );
    
    return $extend;
}