REST API

REST API

The Avalon REST API offers a way to get and modify objects and metadata. Use it to interact with collections, media objects, and supplemental files.

Authentication

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.  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.

$ 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.



Media Objects

Operations

GET

/media_objects/:id.json

GET

/media_objects.json

POST

/media_objects.json

PUT

/media_objects/:id.json

DELETE

/media_objects/:id.json

Get media object

Returns a media object. This includes information about the media object, such as descriptive metadata, file and structure information, and more. The information returned depends on the authentication.

Request

Path parameters

id string REQUIRED

The ID of the media object.

Query parameters

include_structure boolean

Specifies if structure should be included in response.

Responses

200 OK

Returned if the requested media object is returned.

 

GET /media_objects/{id}.json

curl --request GET \ --url 'https://avalon-site.url/media_objects/{id}.json' \ --header 'Avalon-Api-Key:abcdef123456' \ --header 'Accept: application/json'

200 Example Response

{ "id": "1g05fb83r", "title": "Test", "collection": "Historical Videos", "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", "percent_complete": "100.0", "status_code": "COMPLETED", "structure": null, "label": "", "thumbnail_offset": 2000, "poster_offset": 2000, "physical_description": null, "file_location": "/srv/avalon/Archiver_spool/avalon/1c18df984-SampleVideo.mp4", "file_size": "1055736", "duration": "5312", "date_digitized": "2019-12-10T18:33:41Z", "file_checksum": null, "file_format": "Moving image", "other_identifier": [], "captions": null, "captions_type": null, "comment": [], "display_aspect_ratio": "1.7777777777777777", "original_frame_size": "1280x720", "width": 1280, "height": 720, "files": [ { "label": "quality-medium", "id": "26d00ae1-44b9-4306-a310-158b3e39a7c5", "url": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-medium", "hls_url": "https://mallorn.dlib.indiana.edu:8980/avalon/ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-medium.mp4/index.m3u8", "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

Returns all media objects in a paged response. .Parameters :page and :per_page specify page number and number per page for pagination.

Request

Query parameters

per_page integer

The number of objects to return per page.

Default: 25

page integer

The ID of the media object.

Default: 1

Responses

200 OK

Returned if the requested set of media objects is returned.

GET /media_objects.json

curl --request GET \ --url 'https://avalon-site.url/media_objects.json?per_page=1&page=3' \ --header 'Avalon-Api-Key:abcdef123456' \ --header 'Accept: application/json'

200 Example Response

[ { "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 } } ]

 

Create new media object

Creates a new media object.

Request

Request body application/json

collection_id string

ID of target parent collection.

fields hash REQUIRED

Hash containing descriptive metadata values:

  • title string REQUIRED

  • date_issued string

  • creator array<string>

  • alternative_title array<string>

  • translated_title array<string>

  • uniform_title array<string>

  • statement_of_responsibility string

  • date_created string

  • copyright_date string

  • abstract string

  • note  array<string>

  • note_type array <string> (must be present if values exist for note)

  • format string

  • resource_type array<string>

  • contributor array<string>

  • publisher array<string>

  • genre array<string>

  • subject array<string>

  • related_item_url array<string>

  • geographic_subject array<string>

  • temporal_subject array<string>

  • topical_subject array<string>

  • bibliographic_id string

  • language array<string>

  • terms_of_use string

  • table_of_contents array<string>

  • physical_description <string>

  • other_identifier array<string>

  • other_identifier_type array<string> (must be present if other_identifier is used)

  • comment array<string>

files array<file objects> REQUIRED

An array of masterfile (file) objects.

  • label string

  • id string

  • title string

  • file_location string

  • file_checksum string

  • file_size integer

  • duration integer

  • display_aspect_ratio float

  • original_frame_size string

  • file_format string

  • poster_offset integer

  • thumbnail_offset integer

  • date_digitized string

  • structure string<Avalon xml structure data>

  • captions string<vtt or srt document>

  • captions_type string (required if captions are present)

  • other_identifier array<string>

  • comment array<string>

  • workflow_name string

  • date_digitized string

  • files: array<derivative objects> An array of objects for streaming derivatives.

    • label string

    • id string

    • url string

    • hls_url string

    • duration integer

    • mime_type string

    • audio_bitrate integer

    • audio_codec integer

    • video_bitrate integer

    • video_codec string

    • width integer

    • height integer

import_bib_record boolean

If true, fields must include value for :bibliographic_id and may include value from controlled vocabulary for :bibliographic_id_label)

Default: false

replace_masterfiles boolean

If true, existing masterfiles will be destroyed and replaced by the set submitted in the request body. If false, sent masterfiles will be appended to existing list.

Default: false

publish boolean

If true, mediaobject will automatically enter a published state with avalon_publisher taking the value “REST API”.

Default: false

Responses

200 OK

Returned if the media object was successfully created.

POST /media_objects.json

curl --request POST \ --url 'https://avalon-site.url/media_objects.json' \ --header 'Avalon-Api-Key:abcdef123456' \ --header 'Accept: application/json' --header 'Content-type:application/json' --data @data.json or: 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

200 Example Response

{ "id": "f4752h024" }

Example data.json

{ "fields" : { "avalon_uploader" : "student@my.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" } ] }

 

 

 

Update existing media object

Updates an existing media object.

Request

Request body application/json

collection_id string

ID of target parent collection.

fields hash REQUIRED

Hash containing descriptive metadata values:

  • title string REQUIRED

  • date_issued string

  • creator array<string>

  • alternative_title array<string>

  • translated_title array<string>

  • uniform_title array<string>

  • statement_of_responsibility string

  • date_created string

  • copyright_date string

  • abstract string

  • note  array<string>

  • note_type array <string> (must be present if values exist for note)

  • format string

  • resource_type array<string>

  • contributor array<string>

  • publisher array<string>

  • genre array<string>

  • subject array<string>

  • related_item_url array<string>

  • geographic_subject array<string>

  • temporal_subject array<string>

  • topical_subject array<string>

  • bibliographic_id string

  • language array<string>

  • terms_of_use string

  • table_of_contents array<string>

  • physical_description <string>

  • other_identifier array<string>

  • other_identifier_type array<string> (must be present if other_identifier is used)

  • comment array<string>

files array<file objects> REQUIRED

An array of masterfile (file) objects.

  • label string

  • id string

  • title string

  • file_location string

  • file_checksum string

  • file_size integer

  • duration integer

  • display_aspect_ratio float

  • original_frame_size string

  • file_format string

  • poster_offset integer

  • thumbnail_offset integer

  • date_digitized string

  • structure string<Avalon xml structure data>

  • captions string<vtt or srt document>

  • captions_type string (required if captions are present)

  • other_identifier array<string>

  • comment array<string>

  • workflow_name string

  • date_digitized string

  • files: array<derivative objects> An array of objects for streaming derivatives.

    • label string

    • id string

    • url string

    • hls_url string

    • duration integer

    • mime_type string

    • audio_bitrate integer

    • audio_codec integer

    • video_bitrate integer

    • video_codec string

    • width integer

    • height integer

import_bib_record boolean

If true, fields must include value for :bibliographic_id and may include value from controlled vocabulary for :bibliographic_id_label)

Default: false

replace_masterfiles boolean

If true, existing masterfiles will be destroyed and replaced by the set submitted in the request body. If false, sent masterfiles will be appended to existing list.

Default: false

publish boolean

If true, mediaobject will automatically enter a published state with avalon_publisher taking the value “REST API”.

Default: false

Responses

200 OK

Returned if the media object was successfully created.

PUT /media_objects.json

curl --request POST \ --url 'https://avalon-site.url/media_objects/{id}.json' \ --header 'Avalon-Api-Key:abcdef123456' \ --header 'Accept: application/json' --header 'Content-type:application/json' --data @data.json

200 Example Response

{ "id": "{id}" }

Example data.json

{ "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 }

 

Delete existing media object

Deletes an existing media object

DELETE /media_objects/:id.json

Deletes a media object

curl -H 'Avalon-Api-Key:abcdef123456' -X DELETE https://mallorn.dlib.indiana.edu/media_objects/1g05fb83r.json

 


Collections

Operations

GET

/admin/collections/:id.json