Skip to content

API

Jump to bottom
jimsafley edited this page May 13, 2013 · 78 revisions

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

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

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