Search using this query type:

Search only these record types:


Advanced Search (Items only)

API method documentation


Put simply, an API is a formal line of communication between two programs. A REST API is one that utilizes inherent features of the Web to enable communication between a client and a server. It’s important to note that APIs aren’t designed to be exposed to you, the end user, except through intermediary programs. Remember this when you’re experimenting directly with the API; otherwise you may get frustrated.

Promoter Digital Gallery REST API provides an endpoint against which you can query, create, update, and delete resources:

You can see which resources are available by appending /resources?pretty_print to your endpoint, like this:

Here you are getting the /resources resource as a JSON object containing all the available resources and other information about them. (?pretty_print is helpful to get back nicely formatted JSON, but is not necessary.)

In the above response you’ll notice that all resources have at least one action. These actions, while not important to a beginner, correspond to HTTP request methods. These methods are central to REST, and you should know what they do:

  • GET gets one or more representations of a resource;
  • POST creates a new resource and returns the representation of the newly created resource;
  • PUT modifies an existing resource and returns the representation of the newly modified resource;
  • DELETE deletes an existing resource.

Until you start building your own API client, you won’t need to make POST, PUT, or DELETE requests, but GET is well suited for beginners because you can run them directly from your Web browser, as you probably did above with /resources.

A representation, in this case, is a JSON object that represents a resource. In other words, you are not getting a resource itself, but rather a representation of it. This is very much like viewing an item on the website: the item show page is not the item itself, but a representation of the item.

Promoter Digital Gallery comes with the following resources:

  • /collections
  • /items
  • /files
  • /item_types
  • /elements
  • /element_sets
  • /tags


Using the Promoter Digital Gallery API

Let’s take a look at the /items resource by making a GET request to the following URL using your Web browser:

You’ll see a JSON array of item representations, each with an “id” (the item ID), a “url” (the direct URL to that item), and other metadata about the item. Copy that URL to your Web browser and make another GET request (you’ll first need to remove backslashes from the URL, which were a necessary part of JSON formatting):

Where :id is the item ID. You’ll see the same JSON representation of the item, but by itself. This URL is the item’s canonical URL, that is, it is an unambiguous and permanent link that represents the item itself.

So far you’ve only been using the GET method to get representations of resources. To experiment with POST, PUT, and DELETE you’ll need to use a program that is capable of sending those requests.

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 Promoter Digital Gallery.

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


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