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

Supply data for your record type to the API by creating an additional model called Api_{YourRecordType} which extends Omeka_Record_Api_AbstractRecordAdapter. It should reside in your plugin's models/ directory in a subdirectory called Api/. The name of the file within that Api/ subdirectory should be the same as the name of the file for the basic record type:

/MyPlugin
    /models
        MyModel.php
        /Api
            MyModel.php (contains `class Api_MyModel extends Omeka_Record_Api_AbstractRecordAdapter`)

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;
}