Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 21 Next »

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:

  • Should we be strict with CRUD? Yes, for now. Exception is PUTS and POST return effected item's pid.
  • Regarding the 202 Code, this may not be needed, but I put in place in the event we have to accept API requests and wait to go test streaming (make sure the derivatives are there).  This is a worst case if our file storage is too slow (which would be really bad of course).  
  • Should we let GET items/ return a list of all items? Pagination is in place: :page and :per_page can be specified in request parameters. 
  • Additionally allow GET to be called without an API key/IP restrictions (public).  Would be useful for third parties who want data feeds from us. For now GETs are protected by tokens.


  • No labels