Skip to content

API

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

This documentation is a work in progress and subject to change. Assume that resources (records) must be accessible to the consumer, public or via authentication.

URL

yourdomain.com/api[/:version]

Requests

Generic Requests

Return data about records:

GET /:record-types

Parameters

  • page: integer
  • per_page: integer

Return data about the specified record:

GET /:record-types/:id

Record Types

Return available records (must be registered) and HTTP methods for each record (GET, POST, PUT, DELETE):

GET /record-types

Response

[
  {
    "name": "collections",
    "methods": ["GET", "POST", "PUT", "DELETE"]
  },
  {
    "name": "items",
    "methods": ["GET", "POST", "PUT", "DELETE"]
  },
  {
    "name": "files",
    "methods": ["GET", "POST", "PUT", "DELETE"]
  },
  {
    "name": "item-types",
    "methods": ["GET", "POST", "PUT", "DELETE"]
  }
]

Collections

Return data about collections:

GET /collections

Parameters

  • public: boolean
  • featured: boolean
  • added_since: string (timestamp)
  • modified_since: string (timestamp)
  • 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-02-13 11:24:34",
    "modified": "2013-02-18 11:09:50", 
    "element_texts": {"count": 100, "url": "/collections/:id/element-texts"},
    "items": [
      {"id": 1, "url": "/items/1"},
      {"id": 2, "url": "/items/2"},
      {"id": 3, "url": "/items/3"}      
    ]
  }
]

Return element texts of the specified collection:

GET /collections/:id/element-texts

Params

  • element_set: integer
  • element_set_name: string
  • element: integer
  • element_name: string (requires element_set or element_set_name)

Items

Return data about items:

GET /items

Parameters

  • collection: integer
  • item_type: integer
  • featured: boolean
  • public: boolean
  • added_since: string (timestamp)
  • modified_since: string (timestamp)
  • 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-02-13 11:24:34",
    "modified": "2013-02-18 11:09:50",
    "files": [
      {"id": 1, "url": "/files/1"},
      {"id": 2, "url": "/files/2"},
      {"id": 3, "url": "/files/3"}
    ]
  }
]

Return element texts of the specified item:

GET /items/:id/element-texts

Params

  • element_set: integer
  • element_set_name: string
  • element: integer
  • element_name: string (requires element_set or element_set_name)

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 (timestamp)
  • modified_since: string (timestamp)

Return data about the specified item:

GET /files/:id

Response

[
  {
    "id": 1,
    "file_url": "/files/1",
    "item_id": 1,
    "item_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-02-13 11:24:34",
    "modified": "2013-02-18 11:09:50", 
    "stored": true,
    "metadata": {}
  }
]

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,
    "item_type_url": "/item-types/1",
    "name": "Text",
    "description": "A resource consisting primarily of words for reading.",
    "elements": [
      {"id": 1, "url": "/elements/1"},
      {"id": 2, "url": "/elements/2"},
      {"id": 3, "url": "/elements/3"}
    ],
    "items": [
      {"id": 1, "url": "/items/1"},
      {"id": 2, "url": "/items/2"},
      {"id": 3, "url": "/items/3"}
    ]
  }
]

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,
    "element_set_url": "/element-sets/1",
    "record_type": null,
    "name": "Dublin Core",
    "description": "The Dublin Core metadata element set is common to all Omeka records.",
    "elements": [
      {"id": 1, "url": "/elements/1"},
      {"id": 2, "url": "/elements/2"},
      {"id": 3, "url": "/elements/3"}
    ]
  }
]

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,
    "element_url": "/elements/1",
    "element_set_id": 1,
    "element_set_url": "/element-sets/1",
    "order": 1,
    "name": "Text",
    "description": "Any textual data included in the document",
    "comment": null,
    "element_texts_count": 100,
    "element_texts_url": "/elements/1/element-texts"
  }
]

Return element texts of the specified element:

GET /elements/:id/element-texts

Response

[
  {
    "record_id": 1,
    "record_type": "Item",
    "record_url": "/items/1",
    "element_set_id": 1,
    "element_set_name": "Dublin Core",
    "element_set_url": "/element-sets/1",
    "element_id": 1,
    "element_name": "Title",
    "element_url": "/elements/1",
    "html": false,
    "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
  },
  {
    "record_id": 2,
    "record_type": "Item",
    "record_url": "/items/2",
    "element_set_id": 1,
    "element_set_name": "Dublin Core",
    "element_set_url": "/element-sets/1",
    "element_id": 1,
    "element_name": "Title",
    "element_url": "/elements/1",
    "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