Avalon Ingest API

A lightweight API for indexing metadata and links to existing derivatives into Avalon.  

Table of Contents 

• Avalon Ingest API
• Avalon Ingest API
• Avalon Ingest API
• response codes
  

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.

mediaobjects

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),
      :statement_of_responsibility,
      :date_created,
      :copyright_date,
      :abstract,
      :note (multiple, requires :note_type from controlled vocabulary to be present also)
      :format,
      :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),
      :bibliographic_id,
      :language (multiple),
      :terms_of_use,
      :table_of_contents (multiple),
      :physical_description,
      :other_identifier (multiple, requires :other_identifier_type from controlled vocabulary to be present also)

:collection_id

:files – an array masterfile hashes, example below. label and structure are optional. The last five fields must have the specific 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

admin/collections

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:

admin_collection: 

      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:

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.