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 |
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.
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. 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).
[{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_ingested: "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
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.