Avalon Ingest API

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

Version	Date	Description
0.1	13 October 2015	Initial Draft
0.2	16 December 2015	API as implemented

: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. In the MDPI case use "mdpi barcode")

:collection_id

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

:files example

       [{file_location: absolute_location,
        label: "Part 1",
        files: [{label: 'quality-high',
                  id: 'track-1',
                  url: absolute_location,
                  duration: "6315",
                  mime_type:  "video/mp4",
                  audio_bitrate: "127716.0",
                  audio_codec: "AAC",
                  video_bitrate: "1000000.0",
                  video_codec: "AVC",
                  width: "640",
                  height: "480" },
                {label: 'quality-medium',
                  id: 'track-2',
                  url: absolute_location,
                  duration: "6315",
                  mime_type: "video/mp4",
                  audio_bitrate: "127716.0",
                  audio_codec: "AAC",
                  video_bitrate: "1000000.0",
                  video_codec: "AVC",
                  width: "640",
                  height: "480" }
               ],
        file_location: absolute_location,
        file_checksum: "7ae24368ccb7a6c6422a14ff73f33c9a",
        file_size: "199160",
        duration: "6315",
        display_aspect_ratio: "1.7777777777777777",
        original_frame_size: "640x480",
        file_format: "Moving image",
        poster_offset: "0:02",
        thumbnail_offset: "0:02",
        date_digitized: "2015-12-31",
        workflow_name: "avalon",
        percent_complete: "100.0",
        percent_succeeded: "100.0",
        percent_failed: "0",
        status_code: "COMPLETED",
        structure: structure}]

: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

:replace_masterfiles - boolean. Relevant only if the media object already exists and it has masterfiles. If true, existing masterfiles will be replaced by those sent. If false, sent masterfiles will be appended to existing list.

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

units

In avalon, units are part of a controlled vocabulary. To add a new unit, a call to the vocabulary is required.

GET vocabulary.json Retrieves a hash of avalon controlled vocabularies, { units: [ 'Default Unit' , ...], ... }

GET vocabulary/:vocab.json Retrieves values contained in specified controlled vocabulary

POST vocabulary/:vocab.json Updates specified vocab by adding the value contained in the :entry parameter

response codes:

Code	Description
200	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.
201	<Not used> Created
202	<Not used> Accepted, Queued
400	<Not used> Bad request
401	Auth Failure. No token present in request header 'Avalon-Api-Key'
403	Forbidden. Invalid token in request header 'Avalon-Api-Key'
404	Resource Not Found. If object is not found for requested pid.
405	<Not used> Method Prohibited
409	<Not used> Conflict/Other Error. Conflict ex: pid in use
422	Processing failed. Response body will contain JSON hash with :errors key pointing to a list of error message strings.

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.

Avalon Ingest API

Version

Date

Description

0.1

13 October 2015

Initial Draft

0.2

16 December 2015

API as implemented

Table of Contents