...
...
...
...
...
...
...
...
...
...
...
Version | Date | Description |
---|---|---|
0.1 | 13 October 2015 | Initial Draft |
0.2 | 16 December 2015 | API as implemented |
Table of Contents
A simple API for interacting with Avalon objects.
Table of Contents | ||
---|---|---|
|
Anchor | ||||
---|---|---|---|---|
|
...
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 database. Creating and viewing tokens can be done via rake tasks.
...
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, date_issued
...
Every token is associated with an Avalon user. User sessions authenticated against an API token will assume the same authorization rights as the associated user. (NOTE: In pre-7.0 versions of Avalon, API token logins were granted admin user rights.)
Code Block | ||
---|---|---|
| ||
$ rake avalon:token:generate username=archivist email=archivist1@example.com
37ebd7d86d406e925ba2da4315903440b2439f671dc58c2a36dc827e454d263fdcfd0bf8ad5cea7f5dce5516f2ffe63ee02debf6881b7b466a8600d321b0a01c
$ rake avalon:token:list
37ebd7d86d406e925ba2da4315903440b2439f671dc58c2a36dc827e454d263fdcfd0bf8ad5cea7f5dce5516f2ffe63ee02debf6881b7b466a8600d321b0a01c|archivist
$ rake avalon:token:revoke username=archivist
Token `37ebd7d86d406e925ba2da4315903440b2439f671dc58c2a36dc827e454d263fdcfd0bf8ad5cea7f5dce5516f2ffe63ee02debf6881b7b466a8600d321b0a01c` (archivist) revoked. |
Anchor | ||||
---|---|---|---|---|
|
...
GET /media_objects/:id.json
Retrieves a subset of the mods for the specified media object (parameter :include_structure specifies if structure should be included in response)
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
PUT /media_objects/:id.json
Updates an media object
DELETE /media_objects/:id.json
Deletes a media object
Parameters for POST and PUTS:
collection_id: id of owning admin collection (optional),
fields: mods converted to JSON hash. Required fields: title, date_issued
title (* required),
date_issued (* required),
creator (multiple),
...
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
...
,
...
comment (multiple)
:collection_id
...
files: an array of masterfile hashes. Optional: label, structure, and captions
...
language | ruby |
---|---|
title | :files example |
...
.
label (optional),
id,
title,
file_location,
file_checksum,
file_size,
duration,
display_aspect_ratio,
original_frame_size,
file_format,
poster_offset,
thumbnail_offset,
date_digitized,
structure (optional): structure xml as a string,
captions(optional): captions text from vtt or srt file as a string,
captions_type (optional): required if captions are present,
other_identifier (multiple),
comment (multiple),
workflow_name,
date_digitized,
files: an array of derivative hashes
label,
id,
url,
hls_url,
duration,
mime_type,
audio_bitrate,
audio_codec,
video_bitrate,
video_codec,
width,
height
import_bib_record (optional 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 (optional 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.
publish (optional boolean):
If true, mediaobject will automatically enter a published state with avalon_publisher='REST API'
Example Requests
GET /media_objects/:id.json
Code Block | ||
---|---|---|
| ||
curl -H 'Avalon-Api-Key:abcdef123456' https://mallorn.dlib.indiana.edu/media_objects/1g05fb83r.json |
Example Response
Code Block | ||
---|---|---|
| ||
{ "id": "1g05fb83r", "title": "Test", "collection": "7.0 testing", "unit": "Default Unit", "main_contributors": [], "publication_date": null, "published_by": null, "published": false, "summary": null, "visibility": "private", "read_groups": [], "files": [ { id: "1c18df984", "workflow_name": "avalon", video_bitrate"percent_complete": "1000000100.0", video_codec"status_code": "AVCCOMPLETED", "structure": null, width"label": "640", "thumbnail_offset": 2000, height: "480poster_offset": }2000, ]"physical_description": null, "file_location": "/srv/avalon/masterArchiver_files/filespool/avalon/1c18df984-SampleVideo.mp4", "file_checksumsize": "7ae24368ccb7a6c6422a14ff73f33c9a1055736", file_size"duration": "1991605312", duration"date_digitized": "63152019-12-10T18:33:41Z", display_aspect_ratio: "1.7777777777777777""file_checksum": null, original_frame_size"file_format": "640x480Moving image", "other_identifier": file_format: "Moving image"[], "captions": null, "captions_type": null, poster_offset: "0:02" "comment": [], thumbnail_offset"display_aspect_ratio": "0:021.7777777777777777", date_digitized"original_frame_size": "2015-12-311280x720", "width": 1280, structure: structure xml, "height": 720, captions: captions text from vtt or srt file,"files": [ { captions_type: 'text/vtt' (or 'text/srt') other_identifier"label": ["40000000045312quality-medium"], comment "id": ["test comment"]"26d00ae1-44b9-4306-a310-158b3e39a7c5", structure: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!-- Music for Piano; http"url": "rtmp://server1mallorn.variations2dlib.indiana.edu:1935/variations/cgi-bin/access.pl?id=BFJ6801 -->\n<Item label=\"CD 1\">\navalon/mp4:ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-medium", <Div label=\"Copland, Three Piano Excerpts from Our Town\">\n "hls_url": "https://mallorn.dlib.indiana.edu:8980/avalon/ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-medium.mp4/index.m3u8", <Span label=\"Track 1. Story of Our Town\" begin=\"0\" end=\"0:09.99\"/>\n <Span label=\"Track 2. Conversation at the Soda Fountain\" begin=\"0:10\" end=\"0:19.99\"/>\n <Span label=\"Track 3. The Resting Place on the Hill\" begin=\"0:20\" end=\"0:29.99\"/>\n </Div>\n <Div label=\"Copland, Four Episodes from Rodeo\">\n <Span label=\"Track 4. Buckaroo Holiday\" begin=\"0:30\" end=\"0:39.99\"/>\n <Span label=\"Track 5. Corral Nocturne\" begin=\"0:40\" end=\"0:49.99\"/>\n <Span label=\"Track 6. Saturday Night Waltz\" begin=\"0:50\" end=\"0:59.99\"/>\n <Span label=\"Track 7. Hoe-Down\" begin=\"1:00\" end=\"1:09.99\"/>\n </Div>\n <Span label=\"Track 8. Copland, Piano Variations \" begin=\"1:10\" end=\"1:19.99\"/>\n <Div label=\"Copland, Four Piano Blues\">\n <Span label=\"Track 9. For Leo Smit: Freely poetic\" begin=\"1:20\" end=\"1:29.99\"/>\n <Span label=\"Track 10. For Andor Foldes: Soft and languid\" begin=\"1:30\" end=\"1:39.99\"/>\n <Span label=\"Track 11. For Willian Kapell: Muted and sensuous\" begin=\"1:40\" end=\"1:49.99\"/>\n <Span label=\"Track 12. For John Kirkpatrick: WIth bounce\" begin=\"1:50\" end=\"1:59.99\"/>\n </Div>\n <Span label=\"Track 13. Copland, Danzon Cubano\" begin=\"2:00\" end=\"2:30\"/>\n</Item>\n", 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
: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.
:publish – boolean. If true, mediaobject will automatically enter a published state with avalon_publisher='REST API'
...
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
...
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
...
"duration": 5336,
"mime_type": null,
"audio_bitrate": 128078,
"audio_codec": "mp4a-40-2",
"video_bitrate": 1500000,
"video_codec": "avc1",
"width": "1280.0",
"height": "720.0",
"location": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-medium",
"track_id": "12532-medium",
"hls_track_id": null,
"managed": false,
"derivativeFile": "file:///srv/avalon/rtmp_streams/ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-medium.mp4"
},
{
"label": "quality-high",
"id": "e87804de-916b-40f9-aa28-69b8ce6dbcb4",
"url": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-high",
"hls_url": "https://mallorn.dlib.indiana.edu:8980/avalon/ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-high.mp4/index.m3u8",
"duration": 5336,
"mime_type": null,
"audio_bitrate": 192000,
"audio_codec": "mp4a-40-2",
"video_bitrate": 3000000,
"video_codec": "avc1",
"width": "1280.0",
"height": "720.0",
"location": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-high",
"track_id": "12532-high",
"hls_track_id": null,
"managed": false,
"derivativeFile": "file:///srv/avalon/rtmp_streams/ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-high.mp4"
},
{
"label": "quality-low",
"id": "6cc0e00a-eaf4-4fb7-9be6-64772a5b258a",
"url": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-low",
"hls_url": "https://mallorn.dlib.indiana.edu:8980/avalon/ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-low.mp4/index.m3u8",
"duration": 5336,
"mime_type": null,
"audio_bitrate": 128078,
"audio_codec": "mp4a-40-2",
"video_bitrate": 500000,
"video_codec": "avc1",
"width": "852.0",
"height": "480.0",
"location": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-low",
"track_id": "12532-low",
"hls_track_id": null,
"managed": false,
"derivativeFile": "file:///srv/avalon/rtmp_streams/ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-low.mp4"
}
]
}
],
"fields": {
"duration": "5312",
"avalon_resource_type": [
"moving image"
],
"avalon_publisher": null,
"avalon_uploader": "archivist1@example.com",
"identifier": [],
"title": "Lease Test",
"alternative_title": [],
"translated_title": [],
"uniform_title": [],
"statement_of_responsibility": null,
"creator": [],
"date_created": null,
"date_issued": "2020",
"copyright_date": null,
"abstract": null,
"format": [
"video/mp4"
],
"resource_type": [],
"contributor": [],
"publisher": [],
"genre": [],
"subject": [],
"geographic_subject": [],
"temporal_subject": [],
"topical_subject": [],
"terms_of_use": null,
"table_of_contents": [],
"physical_description": [],
"record_identifier": [
"http://127.0.0.1:8984/fedora4/rest/1g/05/fb/83/1g05fb83r"
],
"comment": [],
"bibliographic_id": null,
"bibliographic_id_label": null,
"note": null,
"note_type": null,
"language": null,
"related_item_url": null,
"related_item_label": null,
"other_identifier": null,
"other_identifier_type": null,
"rights_statement": null
}
} |
GET /media_objects.json
Code Block | ||
---|---|---|
| ||
curl -H "Avalon-Api-Key:abcdef123456" "https://mallorn.dlib.indiana.edu/media_objects.json?per_page=1&page=3" |
Example Response
Code Block | ||
---|---|---|
| ||
[
{
"id": "vd66w000m",
"title": "100_item_8",
"collection": "Krishna_Ptest",
"unit": "Indiana University Libraries",
"main_contributors": [],
"publication_date": null,
"published_by": null,
"published": false,
"summary": null,
"visibility": "private",
"read_groups": [],
"files": [
{
"workflow_name": "avalon-skip-transcoding",
"percent_complete": null,
"status_code": null,
"structure": null,
"label": "popeye",
"thumbnail_offset": 2000,
"poster_offset": 2000,
"physical_description": null,
"file_location": "/srv/avalon/dropbox/Krishna_Ptest/assets/Popeye_forPresident.mp4",
"file_size": "2352948",
"duration": "30101",
"date_digitized": "2018-10-02T19:18:35Z",
"file_checksum": null,
"file_format": "Moving image",
"other_identifier": [],
"captions": "WEBVTT\r\n\r\n1\r\n00:00:00.200 --> 00:00:02.000\r\nTitle frame 1-2 sec\r\n\r\n2\r\n00:00:04.000 --> 00:00:05.000\r\n4 seconds\r\n\r\n3\r\n00:00:10.000 --> 00:00:11.000\r\n10 seconds\r\n\r\n4\r\n00:00:16.000 --> 00:00:16.500\r\n16 seconds\r\n\r\n5\r\n00:00:27.000 --> 00:00:27.800\r\n27 seconds",
"captions_type": "text/vtt",
"comment": [],
"display_aspect_ratio": "1.3333333333333333",
"original_frame_size": "320x240",
"width": 320,
"height": 240,
"files": [
{
"label": "quality-high",
"id": "track-3",
"url": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:06e89f15-e16a-475b-af5f-8a119891e559/c16082dd-5fc7-4b1b-b582-8fa71923e6f6/Popeye_forPresident",
"hls_url": "https://mallorn.dlib.indiana.edu:8980/avalon/06e89f15-e16a-475b-af5f-8a119891e559/c16082dd-5fc7-4b1b-b582-8fa71923e6f6/Popeye_forPresident.mp4/index.m3u8",
"duration": "30102",
"mime_type": "video/mp4",
"audio_bitrate": "98902.0",
"audio_codec": "AAC",
"video_bitrate": "513984.0",
"video_codec": "AVC",
"width": "320",
"height": "240",
"location": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:06e89f15-e16a-475b-af5f-8a119891e559/c16082dd-5fc7-4b1b-b582-8fa71923e6f6/Popeye_forPresident",
"track_id": "track-3",
"hls_track_id": "track-4",
"managed": false,
"derivativeFile": "file:///var/avalon/rtmp_streams/06e89f15-e16a-475b-af5f-8a119891e559/c16082dd-5fc7-4b1b-b582-8fa71923e6f6/Popeye_forPresident.mp4"
}
]
}
],
"fields": {
"duration": "30101",
"avalon_resource_type": [
"moving image"
],
"avalon_publisher": null,
"avalon_uploader": "archivist1@example.com",
"identifier": [],
"title": "100_item_8",
"alternative_title": [],
"translated_title": [],
"uniform_title": [],
"statement_of_responsibility": null,
"creator": [],
"date_created": null,
"date_issued": "2017",
"copyright_date": null,
"abstract": null,
"format": [
"video/mp4"
],
"resource_type": [],
"contributor": [],
"publisher": [],
"genre": [],
"subject": [],
"geographic_subject": [],
"temporal_subject": [],
"topical_subject": [],
"terms_of_use": null,
"table_of_contents": [],
"physical_description": [],
"record_identifier": [
"http://127.0.0.1:8984/fedora4/rest/vd/66/w0/00/vd66w000m"
],
"comment": [],
"bibliographic_id": null,
"bibliographic_id_label": null,
"note": null,
"note_type": null,
"language": null,
"related_item_url": null,
"related_item_label": null,
"other_identifier": null,
"other_identifier_type": null,
"rights_statement": null
}
}
] |
POST /media_objects.json
Code Block | ||
---|---|---|
| ||
curl -H "Avalon-Api-Key:abcdef123456" -X POST -d @data.json -H "Content-type:application/json" -H "Accept:application/json" https://mallorn.dlib.indiana.edu/media_objects.json |
Example Request Data (data.json)
Code Block | ||
---|---|---|
| ||
{
"fields" : {
"avalon_uploader" : "srsridh@iu.edu",
"subject" : [],
"format" : [
"video/mp4"
],
"title" : "100_item_8",
"translated_title" : [],
"publisher" : [],
"note_type" : null,
"alternative_title" : [],
"duration" : "30101",
"date_created" : null,
"related_item_url" : null,
"related_item_label" : null,
"genre" : [],
"contributor" : [],
"bibliographic_id" : null,
"uniform_title" : [],
"topical_subject" : [],
"note" : null,
"comment" : [],
"statement_of_responsibility" : null,
"temporal_subject" : [],
"rights_statement" : null,
"language" : null,
"date_issued" : "2017",
"creator" : [],
"other_identifier" : null,
"geographic_subject" : [],
"terms_of_use" : null,
"abstract" : null,
"avalon_resource_type" : [
"moving image"
],
"record_identifier" : [
"http://127.0.0.1:8984/fedora4/rest/61/08/vb/48/6108vb48x"
],
"identifier" : [],
"resource_type" : [],
"bibliographic_id_label" : null,
"copyright_date" : null,
"physical_description" : [],
"table_of_contents" : [],
"other_identifier_type" : null,
"avalon_publisher" : "srsridh@iu.edu"
},
"publish" : true,
"collection_id" : "jh343s44s",
"files" : [
{
"file_location" : "/srv/avalon/dropbox/Performance_Testing_100/assets/Popeye_forPresident.mp4",
"duration" : "30101",
"files" : [
{
"derivativeFile" : "file:///var/avalon/rtmp_streams/3c5ee8d6-dc51-4112-8f60-f4cc36abab5c/5136f7be-1637-4ebf-be5e-35c79df16dac/Popeye_forPresident.mp4",
"managed" : false,
"video_bitrate" : "513984.0",
"duration" : "30102",
"audio_codec" : "AAC",
"url" : "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:3c5ee8d6-dc51-4112-8f60-f4cc36abab5c/5136f7be-1637-4ebf-be5e-35c79df16dac/Popeye_forPresident",
"track_id" : "track-3",
"id" : "track-3",
"video_codec" : "AVC",
"hls_url" : "https://mallorn.dlib.indiana.edu:8980/avalon/3c5ee8d6-dc51-4112-8f60-f4cc36abab5c/5136f7be-1637-4ebf-be5e-35c79df16dac/Popeye_forPresident.mp4/index.m3u8",
"width" : "320",
"label" : "quality-high",
"hls_track_id" : "track-4",
"location" : "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:3c5ee8d6-dc51-4112-8f60-f4cc36abab5c/5136f7be-1637-4ebf-be5e-35c79df16dac/Popeye_forPresident",
"height" : "240",
"mime_type" : "video/mp4",
"audio_bitrate" : "98902.0"
}
],
"captions" : "WEBVTT\r\n\r\n1\r\n00:00:00.200 --> 00:00:02.000\r\nTitle frame 1-2 sec\r\n\r\n2\r\n00:00:04.000 --> 00:00:05.000\r\n4 seconds\r\n\r\n3\r\n00:00:10.000 --> 00:00:11.000\r\n10 seconds\r\n\r\n4\r\n00:00:16.000 --> 00:00:16.500\r\n16 seconds\r\n\r\n5\r\n00:00:27.000 --> 00:00:27.800\r\n27 seconds",
"other_identifier" : [],
"file_checksum" : null,
"workflow_name" : "avalon-skip-transcoding",
"structure" : null,
"physical_description" : null,
"file_size" : "2352948",
"poster_offset" : 2000,
"display_aspect_ratio" : "1.3333333333333333",
"height" : 240,
"comment" : [],
"thumbnail_offset" : 2000,
"original_frame_size" : "320x240",
"date_digitized" : "2018-10-15T18:57:39Z",
"width" : 320,
"captions_type" : "text/vtt",
"file_format" : "Moving image",
"label" : "popeye"
}
]
} |
Example Response
Code Block | ||
---|---|---|
| ||
{"id":"f4752h024"} |
PUT /media_objects/:id.json
Code Block | ||
---|---|---|
| ||
curl -H "Avalon-Api-Key:abcdef123456" -X PUT -d @data.json -H "Content-type:application/json" -H "Accept:application/json" https://mallorn.dlib.indiana.edu/media_objects/f4752h024.json |
Example Request Data (data.json)
Code Block | ||
---|---|---|
| ||
{
"publish" : true,
"collection_id" : "jh343s44s",
"fields" : {
"physical_description" : [],
"related_item_label" : null,
"creator" : [],
"avalon_uploader" : "srsridh@iu.edu",
"terms_of_use" : null,
"copyright_date" : null,
"date_issued" : "2017",
"note_type" : null,
"other_identifier" : null,
"alternative_title" : [],
"bibliographic_id" : null,
"date_created" : null,
"comment" : [],
"avalon_publisher" : "srsridh@iu.edu",
"rights_statement" : null,
"uniform_title" : [],
"bibliographic_id_label" : null,
"geographic_subject" : [],
"translated_title" : [],
"abstract" : null,
"note" : null,
"duration" : "30101",
"title" : "Ingest API Test",
"topical_subject" : [],
"genre" : [],
"contributor" : [],
"statement_of_responsibility" : null,
"publisher" : [],
"table_of_contents" : [],
"language" : null,
"avalon_resource_type" : [
"moving image"
],
"temporal_subject" : [],
"record_identifier" : [
"http://127.0.0.1:8984/fedora4/rest/61/08/vb/48/6108vb48x"
],
"related_item_url" : null,
"subject" : [],
"other_identifier_type" : null,
"resource_type" : [],
"identifier" : [],
"format" : [
"video/mp4"
]
},
"files" : [
{
"width" : 320,
"thumbnail_offset" : 2000,
"file_format" : "Moving image",
"file_checksum" : null,
"file_size" : "2352948",
"poster_offset" : 2000,
"date_digitized" : "2018-10-15T18:57:39Z",
"structure" : null,
"workflow_name" : "avalon-skip-transcoding",
"comment" : [],
"other_identifier" : [],
"display_aspect_ratio" : "1.3333333333333333",
"captions" : "WEBVTT\r\n\r\n1\r\n00:00:00.200 --> 00:00:02.000\r\nTitle frame 1-2 sec\r\n\r\n2\r\n00:00:04.000 --> 00:00:05.000\r\n4 seconds\r\n\r\n3\r\n00:00:10.000 --> 00:00:11.000\r\n10 seconds\r\n\r\n4\r\n00:00:16.000 --> 00:00:16.500\r\n16 seconds\r\n\r\n5\r\n00:00:27.000 --> 00:00:27.800\r\n27 seconds",
"file_location" : "/srv/avalon/dropbox/Performance_Testing_100/assets/Popeye_forPresident.mp4",
"original_frame_size" : "320x240",
"duration" : "30101",
"physical_description" : null,
"height" : 240,
"files" : [
{
"mime_type" : "video/mp4",
"hls_track_id" : "track-4",
"duration" : "30102",
"video_bitrate" : "513984.0",
"audio_codec" : "AAC",
"managed" : false,
"height" : "240",
"track_id" : "track-3",
"derivativeFile" : "file:///var/avalon/rtmp_streams/3c5ee8d6-dc51-4112-8f60-f4cc36abab5c/5136f7be-1637-4ebf-be5e-35c79df16dac/Popeye_forPresident.mp4",
"location" : "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:3c5ee8d6-dc51-4112-8f60-f4cc36abab5c/5136f7be-1637-4ebf-be5e-35c79df16dac/Popeye_forPresident",
"label" : "quality-high",
"width" : "320",
"audio_bitrate" : "98902.0",
"hls_url" : "https://mallorn.dlib.indiana.edu:8980/avalon/3c5ee8d6-dc51-4112-8f60-f4cc36abab5c/5136f7be-1637-4ebf-be5e-35c79df16dac/Popeye_forPresident.mp4/index.m3u8",
"video_codec" : "AVC",
"url" : "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:3c5ee8d6-dc51-4112-8f60-f4cc36abab5c/5136f7be-1637-4ebf-be5e-35c79df16dac/Popeye_forPresident",
"id" : "track-3"
}
],
"captions_type" : "text/vtt",
"label" : "popeye"
}
],
"replace_masterfiles" : true
} |
Example Response
Code Block | ||
---|---|---|
| ||
{"id":"f4752h024"} |
DELETE /media_objects/:id.json
Code Block | ||
---|---|---|
| ||
curl -H 'Avalon-Api-Key:abcdef123456' -X DELETE https://mallorn.dlib.indiana.edu/media_objects/1g05fb83r.json |
Example Response
Code Block | ||
---|---|---|
| ||
<html><body>You are being <a href="http://mallorn.dlib.indiana.edu/">redirected</a>.</body></html> |
Anchor | ||||
---|---|---|---|---|
|
...
GET /admin/collections.json
Retrieves a paginated list of all collections (parameters :page and :per_page specify page number and number per page for pagination)
GET /admin/collections/:id.json
Retrieves information on the specified collection
GET /admin/collections/:id/items.json
Retrieves a paginated list of all items in the specified collection (parameters :page and :per_page specify page number and number per page for pagination)
POST /admin/collections.json
Creates a collection
PUT /admin/collections/:id.json
Updates a collection
Parameters for POST and PUT:
admin_collection:
name: collection name,
description (optional): collection description,
unit: collection unit from controlled vocabulary,
managers: array of Avalon user ids or emails
GET /admin/collections.json
Code Block | ||
---|---|---|
| ||
curl -H "Avalon-Api-Key:abcdef123456" "https://mallorn.dlib.indiana.edu/admin/collections.json?per_page=2&page=3" |
Example Response
Code Block | ||
---|---|---|
| ||
[
{
"id": "1r66j1149",
"name": "100 sec test",
"unit": "Indiana University Libraries",
"description": null,
"object_count": {
"total": 0,
"published": 0,
"unpublished": 0
},
"roles": {
"managers": [
"archivist1@example.com",
"saidulla@iu.edu",
"manager-cjc@example.com"
],
"editors": [],
"depositors": [
"cjcolvar"
]
}
},
{
"id": "d791sg31t",
"name": "2882 mallorn",
"unit": "Indiana University Libraries",
"description": null,
"object_count": {
"total": 5,
"published": 0,
"unpublished": 5
},
"roles": {
"managers": [
"saidulla@iu.edu"
],
"editors": [
"editor@example.com"
],
"depositors": null
}
}
] |
GET /admin/collections/:id.json
Code Block | ||
---|---|---|
| ||
curl -H "Avalon-Api-Key:abcdef123456" https://mallorn.dlib.indiana.edu/admin/collections/d791sg31t.json |
Example Response
Code Block | ||
---|---|---|
| ||
{
"id": "d791sg31t",
"name": "2882 mallorn",
"unit": "Indiana University Libraries",
"description": "",
"object_count": {
"total": 5,
"published": 0,
"unpublished": 5
},
"roles": {
"managers": [
"saidulla@iu.edu"
],
"editors": [
"editor@example.com"
],
"depositors": []
}
} |
GET /admin/collections/:id/items.json
Code Block | ||
---|---|---|
| ||
curl -H "Avalon-Api-Key:abcdef123456" "https://mallorn.dlib.indiana.edu/admin/collections/d791sg31t/items.json?per_page=2&page=2" |
Example Response
Code Block | ||
---|---|---|
| ||
{
"mk61rh07c": {
"id": "mk61rh07c",
"title": "elec1 2882 bug",
"collection": "2882 mallorn",
"unit": "Indiana University Libraries",
"main_contributors": [],
"publication_date": null,
"published_by": null,
"published": false,
"summary": null,
"visibility": "private",
"read_groups": [],
"files": [
{
"id": "tq57nr13n",
"workflow_name": "avalon",
"percent_complete": null,
"status_code": null,
"structure": null,
"label": "",
"thumbnail_offset": 2000,
"poster_offset": 2000,
"physical_description": null,
"file_location": "/tmp/electricbeat-1.mp4",
"file_size": "337659",
"duration": "5334",
"date_digitized": "2018-03-29T17:59:15Z",
"file_checksum": "94000912e0c10c6c668f13dfb0a70072",
"file_format": "Moving image",
"other_identifier": [],
"captions": "WEBVTT\r\n\r\n1\r\n00:00:00.200 --> 00:00:02.000\r\nTitle frame 1-2 sec\r\n\r\n2\r\n00:00:04.000 --> 00:00:05.000\r\n4 seconds",
"captions_type": "text/vtt",
"comment": [],
"display_aspect_ratio": "1.3333333333333333",
"original_frame_size": "320x240",
"width": 320,
"height": 240,
"files": [
{
"label": "quality-high",
"id": "0b5272fe-b498-47d5-b75f-6c258894296d",
"url": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:c9eb28f9-4ef3-4040-9478-1633bfa58b74/e3037981-dd6f-4663-b8b0-adb1c2dc54e2/electricbeat_1",
"hls_url": "https://mallorn.dlib.indiana.edu:8980/avalon/c9eb28f9-4ef3-4040-9478-1633bfa58b74/e3037981-dd6f-4663-b8b0-adb1c2dc54e2/electricbeat_1.mp4.m3u8",
"duration": "5334",
"mime_type": "video/mp4",
"audio_bitrate": null,
"audio_codec": null,
"video_bitrate": "2000000.0",
"video_codec": "AVC",
"width": "960",
"height": "720",
"location": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:c9eb28f9-4ef3-4040-9478-1633bfa58b74/e3037981-dd6f-4663-b8b0-adb1c2dc54e2/electricbeat_1",
"track_id": "track-8",
"hls_track_id": "track-11",
"managed": false,
"derivativeFile": "file:///var/avalon/rtmp_streams/c9eb28f9-4ef3-4040-9478-1633bfa58b74/e3037981-dd6f-4663-b8b0-adb1c2dc54e2/electricbeat_1.mp4"
},
{
"label": "quality-medium",
"id": "11a94a20-335d-459a-a3d2-042226bc83d4",
"url": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:c9eb28f9-4ef3-4040-9478-1633bfa58b74/826b8471-6125-4c88-b332-1026fa27b6aa/electricbeat_1",
"hls_url": "https://mallorn.dlib.indiana.edu:8980/avalon/c9eb28f9-4ef3-4040-9478-1633bfa58b74/826b8471-6125-4c88-b332-1026fa27b6aa/electricbeat_1.mp4/index.m3u8",
"duration": "5334",
"mime_type": "video/mp4",
"audio_bitrate": null,
"audio_codec": null,
"video_bitrate": "1064690.0",
"video_codec": "AVC",
"width": "640",
"height": "480",
"location": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:c9eb28f9-4ef3-4040-9478-1633bfa58b74/826b8471-6125-4c88-b332-1026fa27b6aa/electricbeat_1",
"track_id": "track-7",
"hls_track_id": "track-10",
"managed": false,
"derivativeFile": "file:///var/avalon/rtmp_streams/c9eb28f9-4ef3-4040-9478-1633bfa58b74/826b8471-6125-4c88-b332-1026fa27b6aa/electricbeat_1.mp4"
},
{
"label": "quality-low",
"id": "7c71553f-8b0d-45ae-a2de-14768f3baeec",
"url": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:c9eb28f9-4ef3-4040-9478-1633bfa58b74/10cd97b9-6d32-4196-9e9a-83250308b170/electricbeat_1",
"hls_url": "https://mallorn.dlib.indiana.edu:8980/avalon/c9eb28f9-4ef3-4040-9478-1633bfa58b74/10cd97b9-6d32-4196-9e9a-83250308b170/electricbeat_1.mp4/index.m3u8",
"duration": "5334",
"mime_type": "video/mp4",
"audio_bitrate": null,
"audio_codec": null,
"video_bitrate": "530724.0",
"video_codec": "AVC",
"width": "480",
"height": "360",
"location": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:c9eb28f9-4ef3-4040-9478-1633bfa58b74/10cd97b9-6d32-4196-9e9a-83250308b170/electricbeat_1",
"track_id": "track-9",
"hls_track_id": "track-12",
"managed": false,
"derivativeFile": "file:///var/avalon/rtmp_streams/c9eb28f9-4ef3-4040-9478-1633bfa58b74/10cd97b9-6d32-4196-9e9a-83250308b170/electricbeat_1.mp4"
}
]
}
],
"fields": {
"duration": "5334",
"avalon_resource_type": [
"moving image"
],
"avalon_publisher": null,
"avalon_uploader": "saidulla@iu.edu",
"identifier": [],
"title": "elec1 2882 bug",
"alternative_title": [],
"translated_title": [],
"uniform_title": [],
"statement_of_responsibility": null,
"creator": [],
"date_created": null,
"date_issued": "1111",
"copyright_date": null,
"abstract": null,
"format": [
"video/mp4"
],
"resource_type": [],
"contributor": [],
"publisher": [],
"genre": [],
"subject": [],
"geographic_subject": [],
"temporal_subject": [],
"topical_subject": [],
"terms_of_use": null,
"table_of_contents": [],
"physical_description": [],
"record_identifier": [
"http://127.0.0.1:8984/fedora4/rest/mk/61/rh/07/mk61rh07c"
],
"comment": [],
"bibliographic_id": null,
"bibliographic_id_label": null,
"note": null,
"note_type": null,
"language": null,
"related_item_url": null,
"related_item_label": null,
"other_identifier": null,
"other_identifier_type": null,
"rights_statement": null
}
},
"sx61dm430": {
"id": "sx61dm430",
"title": "Luna r642",
"collection": "2882 mallorn",
"unit": "Indiana University Libraries",
"main_contributors": [],
"publication_date": null,
"published_by": null,
"published": false,
"summary": null,
"visibility": "private",
"read_groups": [],
"files": [
{
"id": "5138jd99j",
"workflow_name": "fullaudio",
"percent_complete": null,
"status_code": null,
"structure": null,
"label": "",
"thumbnail_offset": 0,
"poster_offset": 0,
"physical_description": null,
"file_location": "/tmp/Caruso-LunaDestate.mp3",
"file_size": "2165531",
"duration": "135209",
"date_digitized": "2018-04-18T15:09:20Z",
"file_checksum": "df20cc5ee6ec04ed63b0d8497e41fbd0",
"file_format": "Sound",
"other_identifier": [],
"captions": null,
"captions_type": null,
"comment": [],
"display_aspect_ratio": null,
"original_frame_size": null,
"width": null,
"height": null,
"files": [
{
"label": "quality-medium",
"id": "adad926d-3cb2-4547-9159-02dd6c85d014",
"url": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:d7ffad5f-9c41-4106-94af-99abf055d5d5/9ff00ea7-2652-4087-a630-dc48638d861f/Caruso_LunaDestate",
"hls_url": "https://mallorn.dlib.indiana.edu:8980/avalon/d7ffad5f-9c41-4106-94af-99abf055d5d5/9ff00ea7-2652-4087-a630-dc48638d861f/Caruso_LunaDestate.mp4.m3u8",
"duration": "135207",
"mime_type": "audio/mp4",
"audio_bitrate": "124204.0",
"audio_codec": "AAC",
"video_bitrate": null,
"video_codec": null,
"width": null,
"height": null,
"location": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:d7ffad5f-9c41-4106-94af-99abf055d5d5/9ff00ea7-2652-4087-a630-dc48638d861f/Caruso_LunaDestate",
"track_id": "track-7",
"hls_track_id": "track-9",
"managed": false,
"derivativeFile": "file:///var/avalon/rtmp_streams/d7ffad5f-9c41-4106-94af-99abf055d5d5/9ff00ea7-2652-4087-a630-dc48638d861f/Caruso_LunaDestate.mp4"
},
{
"label": "quality-high",
"id": "86452f55-b9d5-4045-a9a9-25a6e6438936",
"url": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:d7ffad5f-9c41-4106-94af-99abf055d5d5/cd18d1ca-870d-48fa-a395-c576efbf4bab/Caruso_LunaDestate",
"hls_url": "https://mallorn.dlib.indiana.edu:8980/avalon/d7ffad5f-9c41-4106-94af-99abf055d5d5/cd18d1ca-870d-48fa-a395-c576efbf4bab/Caruso_LunaDestate.mp4/index.m3u8",
"duration": "135207",
"mime_type": "audio/mp4",
"audio_bitrate": "147344.0",
"audio_codec": "AAC",
"video_bitrate": null,
"video_codec": null,
"width": null,
"height": null,
"location": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:d7ffad5f-9c41-4106-94af-99abf055d5d5/cd18d1ca-870d-48fa-a395-c576efbf4bab/Caruso_LunaDestate",
"track_id": "track-6",
"hls_track_id": "track-8",
"managed": false,
"derivativeFile": "file:///var/avalon/rtmp_streams/d7ffad5f-9c41-4106-94af-99abf055d5d5/cd18d1ca-870d-48fa-a395-c576efbf4bab/Caruso_LunaDestate.mp4"
}
]
}
],
"fields": {
"duration": "135209",
"avalon_resource_type": [
"sound recording"
],
"avalon_publisher": null,
"avalon_uploader": "saidulla@iu.edu",
"identifier": [],
"title": "Luna r642",
"alternative_title": [],
"translated_title": [],
"uniform_title": [],
"statement_of_responsibility": null,
"creator": [],
"date_created": null,
"date_issued": "1212",
"copyright_date": null,
"abstract": null,
"format": [
"audio/mpeg"
],
"resource_type": [],
"contributor": [],
"publisher": [],
"genre": [],
"subject": [],
"geographic_subject": [],
"temporal_subject": [],
"topical_subject": [],
"terms_of_use": null,
"table_of_contents": [],
"physical_description": [],
"record_identifier": [
"http://127.0.0.1:8984/fedora4/rest/sx/61/dm/43/sx61dm430"
],
"comment": [],
"bibliographic_id": null,
"bibliographic_id_label": null,
"note": null,
"note_type": null,
"language": null,
"related_item_url": null,
"related_item_label": null,
"other_identifier": null,
"other_identifier_type": null,
"rights_statement": null
}
}
} |
POST /admin/collections.json
Code Block | ||
---|---|---|
| ||
curl -H "Avalon-Api-Key:abcdef123456" -X POST -d @data.json -H "Content-type:application/json" -H "Accept:application/json" https://mallorn.dlib.indiana.edu/admin/collections.json |
Example Request Data (data.json)
Code Block | ||
---|---|---|
| ||
{
"admin_collection" : {
"unit" : "Indiana University Libraries",
"managers" : [
"archivist1@example.com"
],
"description" : "This great new collection has all new content from the IU Libraries.",
"name" : "New Collection"
}
} |
Example Response
Code Block | ||
---|---|---|
| ||
{"id":"ht24wj605"} |
PUT /admin/collections/:id.json
Code Block | ||
---|---|---|
| ||
curl -H "Avalon-Api-Key:abcdef123456" -X PUT -d @data.json -H "Content-type:application/json" -H "Accept:application/json" https://mallorn.dlib.indiana.edu/admin/collections/ht24wj605.json |
Example Request Data (data.json)
Code Block | ||
---|---|---|
| ||
{
"admin_collection" : {
"unit" : "Indiana University Libraries",
"managers" : [
"archivist1@example.com"
],
"description" : "This great collection has all mostly new content from the IU Libraries.",
"name" : "Not Quite So New Collection"
}
} |
Example Response
Code Block | ||
---|---|---|
| ||
{"id":"ht24wj605"} |
Anchor | ||||
---|---|---|---|---|
|
...
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
GET /vocabulary.json
Code Block | ||
---|---|---|
| ||
curl -H "Avalon-Api-Key:abcdef123456" https://mallorn.dlib.indiana.edu/vocabulary.json |
Example Response
Code Block | ||
---|---|---|
| ||
{
"units": [
"Indiana University Libraries",
"Default Unit"
],
"identifier_types": {
"local": "Catalog Key",
"oclc": "OCLC",
"lccn": "LCCN",
"issue number": "Issue Number",
"matrix number": "Matrix Number",
"music publisher": "Music Publisher/Label",
"videorecording identifier": "Videorecording Identifier",
"other": "Other"
},
"note_types": {
"general": "General Note",
"awards": "Awards",
"biographical/historical": "Bibliographical/Historical Note",
"creation/production credits": "Creation/Production Credits",
"language": "Language Note",
"local": "Local Note",
"performers": "Performers",
"statement of responsibility": "Statement of Responsibility",
"venue": "Venue/Event Date"
},
"rights_statements": {
"http://rightsstatements.org/vocab/InC/1.0/": "In Copyright",
"http://rightsstatements.org/vocab/InC-OW-EU/1.0/": "In Copyright - EU Orphan Work",
"http://rightsstatements.org/vocab/InC-EDU/1.0/": "In Copyright - Educational Use Permitted",
"http://rightsstatements.org/vocab/InC-NC/1.0/": "In Copyright - Non-Commercial Use Permitted",
"http://rightsstatements.org/vocab/InC-RUU/1.0/": "In Copyright - Rights-Holders Unlocatable or Unidentifiable",
"http://rightsstatements.org/vocab/NoC-CR/1.0/": "No Copyright - Contractual Restrictions",
"http://rightsstatements.org/vocab/NoC-NC/1.0/": "No Copyright - Non-Commercial Use Only",
"http://rightsstatements.org/vocab/NoC-OKLR/1.0/": "No Copyright - Other Known Legal Restrictions",
"http://rightsstatements.org/vocab/NoC-US/1.0/": "No Copyright - United States",
"http://rightsstatements.org/vocab/CNE/1.0/": "Copyright Not Evaluated",
"http://rightsstatements.org/vocab/UND/1.0/": "Copyright Undetermined",
"http://rightsstatements.org/vocab/NKC/1.0/": "No Known Copyright"
}
} |
GET /vocabulary/:vocab.json
Code Block | ||
---|---|---|
| ||
curl -H "Avalon-Api-Key:abcdef123456" https://mallorn.dlib.indiana.edu/vocabulary/units.json |
Example Response
Code Block | ||
---|---|---|
| ||
[
"Indiana University Libraries",
"Default Unit"
] |
POST /vocabulary/:vocab.json
Code Block | ||
---|---|---|
| ||
curl -H "Avalon-Api-Key:abcdef123456" -X POST -d @data.json -H "Content-type:application/json" -H "Accept:application/json" https://mallorn.dlib.indiana.edu/vocabulary/units.json |
Example Request Data (data.json)
Code Block | ||
---|---|---|
| ||
{
"entry": "IU Art Museum"
} |
Example Response
Code Block | ||
---|---|---|
| ||
// Empty response |
Anchor | ||||
---|---|---|---|---|
|
...
Code | Description |
---|---|
200 | Okay. For GET, the relevant JSON will be contained in response body. For PUTS and POST response body will contain |
id of created/updated item. | |
201 | <Not used> Created |
202 | <Not used> Accepted, Queued |
400 |
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 |
<Not used> Method Prohibited
<Not used> Conflict/Other Error. Conflict ex: pid in use
id. | |
405 | <Not used> Method Prohibited |
409 | <Not used> Conflict/Other Error. Conflict ex: id in use |
422 | Processing failed. Response body will contain JSON hash with :errors key pointing to a list of error message strings. |
Version History
Version | Date | Description |
---|---|---|
0.1 | 13 October 2015 | Initial Draft |
0.2 | 16 December 2015 | API as implemented |
0.3 | 03 January 2020 | Authorization scheme enhanced |
0.4 | 26 March 2020 | MediaObject - add masterfile ids, derivative ids are actual ids instead of track ids now, structure can be inlined with query param |