A lightweight API for indexing metadata and links to existing derivatives into Avalon.
Version | Date | Description |
---|---|---|
0.1 | 13 October 2015 | Initial Draft |
Table of Contents
access control Anchor access control 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 Anchor mediaobjects mediaobjects
GET itemsmedia_objects/:pid Retrieves information on the media objectPOST items/ .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 itemsmedia_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 Anchor collections 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/ Creates a collection.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: Anchor codes 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 | <Not used> Auth Failure |
403 | Forbidden. If valid token is not included 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 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: ""}
...
- Should we be strict with CRUD? E.g. If an item exists and a post command, versus put, is issued should it update or return a code existing the item already exists? Also if a PUT is attempted on an item that doesn't exist should we fail or just create the item? Specifically when a user puts and there is no item to update, do they care? 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? List would be massive. 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.
let!(:masterfile) {{ | |
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", | |
workflow_name: "avalon", | |
percent_complete: "100.0", | |
percent_succeeded: "100.0", | |
percent_failed: "0", | |
status_code: "COMPLETED", | |
structure: structure | |
}} | |
let!(:descMetadata_fields) {[ | |
:title, | |
:alternative_title, | |
:translated_title, | |
:uniform_title, | |
:statement_of_responsibility, | |
:creator, | |
:date_created, | |
:date_issued, | |
:copyright_date, | |
:abstract, | |
:note, | |
:format, | |
:resource_type, | |
:contributor, | |
:publisher, | |
:genre, | |
:subject, | |
:related_item_url, | |
:geographic_subject, | |
:temporal_subject, | |
:topical_subject, | |
:bibliographic_id, | |
:language, | |
:terms_of_use, | |
:table_of_contents, | |
:physical_description, | |
:other_identifier | |
]} |