Skip to content

API

Jump to bottom
jimsafley edited this page Apr 26, 2013 · 78 revisions

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

Configuration

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

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

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(
        // 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, controller falls back to the default controller (api). Resources using the default controller MUST include a record_type. Records must extend Omeka_Record_AbstractRecord and implement the Omeka_Api_RecordInterface interface. Remove actions that are not wanted or not implemented. For index actions, all GET parameters must be registered with the index_params whitelist.

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

URL

yourdomain.com/api[/:version]

Authentication

Resources must be accessible to the consumer, public or via API key authentication.

Requests

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

Resources

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

GET /resources

Response

{
  "resources": {
    "controller": "resources",
    "record": null,
    "actions": ["index", "get"]
  },
  "collections": {
    "controller": "api",
    "record": "Collection",
    "actions": ["index", "get", "post", "put", "delete"]
  },
  "items": {
    "controller": "api",
    "record": "Item",
    "actions": ["index", "get", "post", "put", "delete"]
  }
}

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"}
  }
]

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