Reference Omeka Classic plugin

Extending the Browser

API Browser finds a plugin's API resources by itself, from Omeka's api_resources filter: their operations and query parameters, and the keys of their JSON from a real record. What it cannot know is what a plugin's own keys and parameters mean. A plugin can say so with one method on its record adapter.

The apiBrowserSchema() method

Add a public apiBrowserSchema() method to the plugin's adapter class (Api_<RecordType>) and return any of three keys:

class Api_BlogPost extends Omeka_Record_Api_AbstractRecordAdapter
{
    public function apiBrowserSchema()
    {
        return [
            'keys' => [
                'status' => ['type' => 'string', 'description' => 'Draft, scheduled or published.'],
                'published' => ['type' => 'string', 'description' => 'When it was published (ISO 8601).'],
            ],
            'queryParams' => [
                ['name' => 'status', 'type' => 'string', 'description' => 'Posts with this status.'],
                ['name' => 'category', 'type' => 'integer', 'description' => 'Posts in this category (its ID).'],
            ],
            'bodyParams' => [
                ['name' => 'notify', 'type' => 'boolean', 'default' => false, 'description' => 'Email subscribers when it is published.'],
            ],
        ];
    }

    // getRepresentation(), setPostData(), setPutData() …
}
Key Shape Used for
keys key name ⇒ type, description The keys of the resource's JSON: added to those read from a record, or describing them. (jsonLdKeys, the Omeka S module's name, works too.)
queryParams list of name, type, description The search's parameters: one with the name of a parameter already listed replaces it, others are added. Declare them in index_params too, or the API refuses them.
bodyParams list of name, type, default, description Fields of the body of Create and Update, shown as a form above the JSON.

Types are string, integer, number, boolean, array or object, and become the OpenAPI types of the export.

Notes

  • The method is called on a new adapter with no arguments.
  • If it throws, or returns something other than an array, the browser goes on without it.
  • It changes the documentation only, never how the API handles requests.

Resources with their own controller

Omeka lets a plugin serve a resource with its own API controller ('module' and 'controller' in api_resources) instead of a record type. The browser documents it, but cannot send its requests in the admin (they answer 501); the code samples and the public browser, which call /api, work.

Log in for Support