Skip to content

API

Jump to bottom
Patrick Murray-John edited this page May 12, 2013 · 78 revisions

This documentation is a work in progress and subject to change.

Configuration

Global

Super users can configure the API using the Settings > API form.

  • Enable/disable the API (default: enabled)
  • Adjust the amount of results per page (default: 50)

API Keys

All users with log in credentials can create and rescind API keys using their Edit User form. API keys are tied to and have all the permissions of an individual user. Super users can create keys for other users. Treat keys as you would your password. Omeka provides the client's IP address and the time it was last accessed.

Extending the API

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.

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

Requests

URL

yourdomain.com/api/

Global Parameters

Parameters

  • key: string, API key authentication
  • callback: string, JSONP function name
  • pretty_print: on/off, Pretty print the JSON output

Generic Requests

Return data about resources (most often records):

GET /:resources

Parameters

  • page: integer

Return data about the specified resource (most often a specific record):

GET /:resources/:id

Version

Return the API version.

GET /version

Response

{
  "version": "1.0"
}

Resources

Return available API resources (must be registered) and information about them:

GET /resources

Response

{
  "resources": {
    "controller": "resources",
    "actions": ["index", "get"]
  },
  "items": {
    "record_type": "Item",
    "actions": ["index", "get", "post", "put", "delete"],
    "index_params": ["collection", "item_type", "featured", 
      "public", "added_since", "modified_since", "owner"]
  }
}

Collections

Return data about collections:

GET /collections

Parameters

  • public: boolean
  • featured: boolean
  • added_since: string (ISO 8601)
  • modified_since: string (ISO 8601)
  • owner (user): integer

Return data about the specified collection:

GET /collections/:id

Response

[
  {
    "id": 1,
    "url": "/collections/1",
    "owner": {"id": 1, "url": "/users/1"},
    "public": true,
    "featured": false,
    "added": "2013-03-27T08:17:37+00:00",
    "modified": "2013-04-21T15:05:07+00:00", 
    "items": {"count": 100, "url": "/items?collection=1"},
    "element_texts": {"count": 100, "url": "/element_texts?record_type=collection&record_id=1"}
  }
]

Items

Return data about items:

GET /items

Parameters

  • collection: integer
  • item_type: integer
  • featured: boolean
  • public: boolean
  • added_since: string (ISO 8601)
  • modified_since: string (ISO 8601)
  • owner (user): integer

Return data about the specified item:

GET /items/:id

Response

[
  {
    "id": 1,
    "url": "/items/1",
    "item_type": {"id": 1, "url": "/item_types/1", "name": "Text"},
    "collection": {"id": 1, "url": "/collections/1"},
    "owner": {"id": 1, "url": "/users/1"},
    "public": true,
    "featured": false,
    "added": "2013-03-27T08:17:37+00:00",
    "modified": "2013-04-21T15:05:07+00:00", 
    "files": {"count": 100, "url": "/files?item=1"},
    "element_texts": {"count": 100, "url": "/element_texts?record_type=item&record_id=1"}
  }
]

Files

Return data about files:

GET /files

Parameters

  • item: integer
  • order: integer
  • size_greater_than: integer
  • has_derivative_image: boolean
  • mime_type: string
  • added_since: string (ISO 8601)
  • modified_since: string (ISO 8601)

Return data about the specified item:

GET /files/:id

Response

[
  {
    "id": 1,
    "url": "/files/1",
    "item": {"id": 1, "url": "/items/1"},
    "order": null,
    "size": 1953540,
    "has_derivative_images": true,
    "authentication": "f6089bca39470e8c19410242061b1f78",
    "mime_type": "audio/mpeg",
    "type_os": "MPEG ADTS, v1, 128 kbps, 44.1 kHz, JntStereo",
    "filename": "54a21c1552feef92069d504fbaf145a8.mp3",
    "original_filename": "1ATwUDzA3SCU.128.mp3",
    "added": "2013-03-27T08:17:37+00:00",
    "modified": "2013-04-21T15:05:07+00:00", 
    "stored": true,
    "metadata": {},
    "element_texts": {"count": 100, "url": "/element_texts?record_type=file&record_id=1"}
  }
]

Note on "metadata"

The metadata object contains data extracted by the getId3 library, and so its structure and content will vary widely based on the file type, what data the library is able to extract, and what data is embedded in the file.

Possible properties within metadata (if it is not empty) are:

  • mime_type
  • video
  • audio
  • comments
  • comments_html
  • iptc
  • jpg

mime_type within metadata is a string, and can differ from the mime_type property in the top level of the response. All other properties will be objects.

Item Types

Return data about item types:

GET /item_types

Parameters

  • name: string

Return data about the specified item type:

GET /item_types/:id

Response

[
  {
    "id": 1,
    "url": "/item_types/1",
    "name": "Text",
    "description": "A resource consisting primarily of words for reading.",
    "elements": {"count": 10, "url": "/elements?item_type=1"},
    "items": {"count": 100, "url": "/items?item_type=1"}
  }
]

Element Sets

Return data about element sets:

GET /element_sets

Parameters

  • name: string
  • record_type: string

Return data about the specified element set:

GET /element_sets/:id

Response

[
  {
    "id": 1,
    "url": "/element_sets/1",
    "record_type": null,
    "name": "Dublin Core",
    "description": "The Dublin Core metadata element set is common to all Omeka records.",
    "elements": {"count": 100, "url": "/elements?element_set=1"}
  }
]

Elements

Return data about elements:

GET /elements

Parameters

  • element_set: integer
  • order: integer
  • name: string

Return data about the specified element:

GET /elements/:id

Response

[
  {
    "id": 1,
    "url": "/elements/1",
    "element_set": {"id": 1, "url": "/element_sets/1"},
    "order": 1,
    "name": "Text",
    "description": "Any textual data included in the document",
    "comment": null,
    "element_texts": {"count": 100, "url": "/element_texts?element=1"}
  }
]

Element Texts

Return data about element texts:

GET /element_texts

Parameters

  • record_type: string
  • record_id: integer
  • element: integer

Response

[
  {
    "record": {"id": 1, "type": "item", "url": "/items/1"},
    "element_set": {"id": 1, "name": "Dublin Core", "url": "/element_sets/1"},
    "element": {"id": 1, "name": "Title", "url": "/elements/1"},
    "html": false,
    "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
  },
  {
    "record": {"id": 2, "type": "item", "url": "/items/2"},
    "element_set": {"id": 1, "name": "Dublin Core", "url": "/element_sets/1"},
    "element": {"id": 2, "name": "Description", "url": "/elements/2"},
    "html": false,
    "text": "Nunc ante ante, mollis at euismod nec, hendrerit vitae turpis."
  }
]

Users

GET /users

GET /users/:id

Tags

GET /tags

Plugins

GET /plugins

GET /plugins/:name
Clone this wiki locally