Requests

Endpoint URL

yourdomain.com/api/

Pagination

For index requests using the default controller, pagination is set in the response’s Link header:

Link: <http://yourdomain.com/api/items?page=1&per_page=50>; rel="first",
      <http://localhost/omeka/api/items?page=10&per_page=50>; rel="last",
      <http://localhost/omeka/api/items?page=1&per_page=50>; rel="previous",
      <http://localhost/omeka/api/items?page=3&per_page=50>; rel="next"``

Global GET Parameters

  • key: string, API key authentication

  • callback: string, JSONP function name

  • pretty_print: on/off, Pretty print the JSON output

Generic Requests

POST and PUT requests are designed to take a JSON payload that is essentially identical to a GET response of the same resource. This makes it possible to, for example, GET an item, modify the representation directly and POST or PUT it back to Omeka.

Some servers do not accept PUT or DELETE requests. For compatibility we’ve added support for the X-HTTP-Method-Override header, which you can use to declare an unsupported HTTP method.

X-HTTP-Method-Override: DELETE

GET a resource

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

GET /:resources/:id HTTP/1.1

GET one or more resources

Return data about resources (most often records):

GET /:resources HTTP/1.1

  • page: integer

  • sort_field: string

  • sort_dir: string ('a' or 'd')

A response of a resource using the default controller will include a non-standard Omeka-Total-Results header set to the total count of request results.

POST a resource

Create a new resource:

POST /:resources HTTP/1.1

PUT a resource

Update an existing resource:

PUT /:resource/:id HTTP/1.1

DELETE a resource

Delete a resource

DELETE /:resource/:id HTTP/1.1

Errors

Router Errors

All requests may return the following errors:

  • 400 Bad Request

    • Invalid GET request parameter: “[parameter]”

  • 403 Forbidden

    • Invalid key.

    • API is disabled

  • 404 Not Found

    • The “[resource]” resource is unavailable.

  • 405 Method Not Allowed

    • This resource does not implement the “[action]” action.

    • POST requests must not include an ID.

    • PUT and DELETE requests must include an ID.

  • 500 Internal Server Error

    • Resources using the default controller must register a record type.

Default Controller Errors

Requests to the default controller may return the following errors:

  • 400 Bad Request

    • Invalid request. Request body must be a JSON object.

    • Error when saving record.

  • 403 Forbidden

    • Permission denied.

  • 404 Not Found

    • Invalid record. Record not found.

    • Invalid record. Record type “[record_type]” not found.

    • Invalid record adapter. Record adapter “[record_adapter_class]” not found.

  • 500 Internal Server Error

    • Invalid record adapter. Record adapter “[record_adapter_class]” is invalid

    • Invalid record. Record “[record_type]” must define an ACL resource.

Record Errors

Requests that invoke the abstract record adapter may return the following errors:

  • 500 Internal Server Error

    • The “[record_type]” API record adapter does not implement setPostData

    • The “[record_type]” API record adapter does not implement setPutData