A lightweight API for indexing metadata and links to existing derivatives into Avalon.  
13 October 2015
Initial Draft

Table of Contents 

access control

All API methods are protected by token authentication. A specified token is passed through http header 'Avalon-Api-Key'. A matching token must be configured in in avalon's authentication.yml.


GET media_objects/:pid.json Retrieves a subset of the mods for the specified media object


GET media_objects.json Retrieves a paged list of media_objects (parameters :page and :per_page specify page number and number per page for pagination)

POST media_objects.json Creates an media object

PUTS media_objects/:pid.json Updates an media object

parameters for POST and PUTS:

:fields – mods converted to JSON hash. required fields: title, creator, date_issued

      :title (required),
      :creator (required, multiple),
      :date_issued (required),
      :alternative_title (multiple),
      :translated_title (multiple),
      :uniform_title (multiple),
      :note (multiple, requires :note_type from controlled vocabulary to be present also)
      :resource_type (multiple),
      :contributor (multiple),
      :publisher (multiple),
      :genre (multiple),
      :subject (multiple),
      :related_item_url (multiple, requires :related_item_label to be present also),
      :geographic_subject (multiple),
      :temporal_subject (multiple),
      :topical_subject (multiple),
      :language (multiple),
      :table_of_contents (multiple),
      :other_identifier (multiple, requires :other_identifier_type from controlled vocabulary to be present also)


:files – an array masterfile hashes, example below. label and structure are optional. The last five fields must have the specified values (for now).

      [ { file_location: absolute_location,
      label: "Part 1",
      file_checksum: "7ae24368ccb7a6c6422a14ff73f33c9a",
      file_size: "199160",
      duration: "6315",
      display_aspect_ratio: "1.7777777777777777",
      original_frame_size: "200x110",
      file_format: "Moving image",
      poster_offset: "0:02",
      thumbnail_offset: "0:02",
      structure: a string containing xml
      workflow_name: "avalon",
      percent_complete: "100.0",
      percent_succeeded: "100.0",
      percent_failed: "0",
      status_code: "COMPLETED", } , ...]

:import_bib_record – boolean. if true, fields must include value for :bibliographic_id and may include value from controlled vocabulary for :bibliographic_id_label)

Bib import failure will result in a JSON response: {errors: ['Bib import failed', e.message]}, status: 422



GET admin/collections.json Retrieves a paginated list of all collections

GET admin/collections/:pid.json Retrieves information on the collection

GET admin/collections/:pid/items.json Retrieves a paginated list of all items in collection :pid

POST admin/collections.json Creates a collection

parameters for POST and PUT:


      name: collection name, 
      description: collection description (optional), 
      unit: collection unit from controlled vocabulary, 
      managers: array of Avalon user ids or emails

PUTS admin/collections/:pid.json Updates a collection


response codes:


Okay. For GET, the relevant JSON will be contained in response body. For PUTS and POST response body will contain pid of created/updated item.


<Not used> Created


<Not used> Accepted, Queued


<Not used> Bad request


<Not used> Auth Failure


Forbidden. If valid token is not included in request header 'Avalon-Api-Key'


Resource Not Found. If object is not found for requested pid.


<Not used> Method Prohibited


<Not used> Conflict/Other Error. Conflict ex: pid in use

422Processing failed. Response body will contain JSON has with :errors key pointing to a list of error message strings.

Additional information for response included in JSON in the body as {status: Okay or ErrorCode, message: ""}

Open Issues: