...

A

...

simple API for

...

Version

...

Date

...

Description

...

0.1

...

13 October 2015

...

Initial Draft

...

0.2

...

16 December 2015

...

API as implemented

...

0.3

(Avalon 7.0)

...

3 January 2020

...

Authorization scheme enhanced
status_code, percent_complete, percent_succeeded, and percent_failed fields removed from Media Object parameters

...

0.4

(Avalon 7.1)

...

26 March 2020

...

MediaObject - add masterfile ids, derivative ids are actual ids instead of track ids now, structure can be inlined with query param
Collection items are proper JSON instead of JSON strings

...

Anchor
access control
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 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. (NOTE: In pre-7.0 versions of Avalon, API token logins were granted admin user rights.)

Code Block

language	bash

$ 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
mediaobjects
mediaobjects
Media Objects

...

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)

...

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 id of owning admin collection (optional),

fields: mods converted to JSON hash. Required fields: title, date_issued

...

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):

...

If true, mediaobject will automatically enter a published state with avalon_publisher='REST API'

Example Requests

...

GET /media_objects/:id.json

Code Block

language	bash

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

Example Response

code

Code Block

title

language	js		Example Response
collapse	true

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

language

bash

title

GET /media_objects.json

Code Block

language	bash

curl -H "Avalon-Api-Key:abcdef123456" "https://mallorn.dlib.indiana.edu/media_objects.json?per_page=1&page=3"

Example Response

title

Code Block

true

language	js
title	Example Response
collapse		js

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

Code Block

language

bash

POST /media_objects.json

language

Code Block

language	bash

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

Code Block

js

title

Example Request Data (data.json)

Code Block

collapselanguage	truejs

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

language

Code Block

title

language	js		Example Response
collapse	true

{"id":"f4752h024"}

Code Block

bash

title

PUT /media_objects/:id.json

Code Block

language	bash

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

Code Block

language

js

title

Example Request Data (data.json)

Code Block

collapselanguage	truejs

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

language	js

{"id":"f4752h024"}

DELETE /media_objects/:id.json

{"id":"f4752h024"}

Code Block

language	js
title	Example Response
collapse	true

language	bash

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

Example Response

Code Block

language	xml

<html><body>You are being <a href="http://mallorn.dlib.indiana.edu/">redirected</a>.</body></html>

Anchor
collections
collections
Admin Collection

...

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

language	bash

curl -H "Avalon-Api-Key:abcdef123456" "https://mallorn.dlib.indiana.edu/admin/collections.json?per_page=2&page=3"

Example Response

bash

Code Block

language	js	title	Example Response
collapse	true

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

Code Block

language

title

GET /admin/collections/:id.json

Code Block

language	bash

curl -H "Avalon-Api-Key:abcdef123456" https://mallorn.dlib.indiana.edu/admin/collections/d791sg31t.json

Example Response

Code Block

collapse

language	js
title	Example Response
	true

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

Code Block

language

bash

title

GET /admin/collections/:id/items.json

Code Block

language	bash

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

language	js
title	Example Response
collapse	true

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

Code Block

language

bash

title

POST /admin/collections.

...

json

title

Code Block

language	bash

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

Code Block

language

js

Example Request Data (data.json)

collapse

Code Block

language	truejs

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

language	js
title	Example Response
collapse	true

{"id":"ht24wj605"}

Code Block

language

bash

title

PUT /admin/collections/:id.json

language

Code Block

language	bash

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

Code Block

js

title

Example Request Data (data.json)

collapse

Code Block

language	truejs

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

language	js
title	Example Response
collapse	true

{"id":"ht24wj605"}

Anchor
units
units
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

GET /vocabulary.json

Code Block

language	bash	title	GET /vocabulary.json

curl -H "Avalon-Api-Key:abcdef123456" https://mallorn.dlib.indiana.edu/vocabulary.json

Example Response

bash

Code Block

language	js	title	Example Response
collapse	true

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

Code Block

language

title

GET /vocabulary/:vocab.json

Code Block

language	bash

curl -H "Avalon-Api-Key:abcdef123456" https://mallorn.dlib.indiana.edu/vocabulary/units.json

Example Response

Code Block

collapse

language	js
title	Example Response
	true

[
    "Indiana University Libraries",
    "Default Unit"
]

Code Block

language

bash

title

POST /vocabulary/:vocab.json

title

Code Block

language	bash

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

Code Block

language

js

Example Request Data (data.json)

Code Block

collapselanguage	truejs

{
  "entry": "IU Art Museum"
}

Example Response

Code Block

language	js
title	Example Response
collapse	true

// Empty response

Anchor
codes
codes
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 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 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 (Avalon 7.0)	03 January 2020	Authorization scheme enhanced status_code, percent_complete, percent_succeeded, and percent_failed fields removed from Media Object parameters
0.4 (Avalon 7.1)	26 March 2020	MediaObject - add masterfile ids, derivative ids are actual ids instead of track ids now, structure can be inlined with query param Collection items are proper JSON instead of JSON strings

Page Comparison

Versions Compared

Old Version 55

New Version Current

Key

Version

Date

Description

0.1

13 October 2015

Initial Draft

0.2

16 December 2015

API as implemented

0.3

3 January 2020

Authorization scheme enhancedstatus_code, percent_complete, percent_succeeded, and percent_failed fields removed from Media Object parameters

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 Collection items are proper JSON instead of JSON strings

Table of Contents

Anchoraccess controlaccess controlAccess Control

AnchormediaobjectsmediaobjectsMedia Objects

Parameters for POST and PUTS:

Example Requests

...

GET /media_objects/:id.json

Example Response

GET /media_objects.json

Example Response

POST /media_objects.json

Example Request Data (data.json)

Example Response

PUT /media_objects/:id.json

Example Request Data (data.json)

Example Response

DELETE /media_objects/:id.json

Example Response

AnchorcollectionscollectionsAdmin Collection

Parameters for POST and PUT:

GET /admin/collections.json

Example Response

GET /admin/collections/:id.json

Example Response

GET /admin/collections/:id/items.json

Example Response

POST /admin/collections.

json

Example Request Data (data.json)

Example Response

PUT /admin/collections/:id.json

Example Request Data (data.json)

Example Response

AnchorunitsunitsUnits

GET /vocabulary.json

Example Response

GET /vocabulary/:vocab.json

Example Response

POST /vocabulary/:vocab.json

Example Request Data (data.json)

Example Response

AnchorcodescodesResponse Codes

Version History

Authorization scheme enhanced
status_code, percent_complete, percent_succeeded, and percent_failed fields removed from Media Object parameters

MediaObject - add masterfile ids, derivative ids are actual ids instead of track ids now, structure can be inlined with query param
Collection items are proper JSON instead of JSON strings

Anchor
access control
access control
Access Control

Anchor
mediaobjects
mediaobjects
Media Objects

Anchor
collections
collections
Admin Collection

Anchor
units
units
Units

Anchor
codes
codes
Response Codes