API : Extending the API

• API Index

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

Using the Default Controller

When using the default controller, 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. This adapter is responsible for building representations of, and setting properties to, your record.

For example, an API adapter for YourRecordType saved to YourPlugin/models/Api/YourRecordType.php:

<?php
class Api_YourRecordType extends Omeka_Record_Api_AbstractRecordAdapter
{
    // Get the REST representation of a record.
    public function getRepresentation(Omeka_Record_AbstractRecord $record)
    {
        // Return a PHP array, representing the passed record.
    }
    
    // Set data to a record.
    public function setData(Omeka_Record_AbstractRecord $record, $data)
    {
        // Set properties directly to the record.
    }
}

Records using the default controller must implement Zend_Acl_Resource_Interface by including a getResourceId() method that returns the ACL resource identifier associated with your record type.

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