Versions Compared

Old Version 19

changes.mady.by.user carrickr

Saved on

compared with

New Version Current

changes.mady.by.user Chris Colvard

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
A lightweight API for indexing metadata and links to existing derivatives into Avalon.  
Version
Date
Description
0.1
13 October 2015
Initial Draft

Table of Contents 

...

GET items/:pid Retrieves information on the media object

POST items/ Creates an media object

PUTS items/:pid Updates an media object

JSON:

{mods: {mods converted to JSON}, collection: collection_id, derivatives: [location_of_derivatives], private: <Boolean, default=false> }

GET returns the mods (or otherwise specified subset of metadata), POST requires everything to be able to create a new media object, PUTS updates just the supplied JSON.  POST and PUT fail if there is not: mods, a unique pid for the object, valid collection_id, mods, and derivatives.  If private is not specified, it is assumed to be public.  

...

GET admin/collections/ Retrieves a list of all collections

GET admin/collections/:pid Retrieves information on the collection

GET admin/collections/:pid/items Retrieves a list of all items in collection :pid

POST admin/collections/ Creates a collection

PUTS admin/collections/:pid Updates a collection

...

Okay

...

Created

...

A simple API for interacting with Avalon objects.

Table of Contents
indent10px

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
languagebash
$ 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)

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)

files: an array of masterfile hashes. Optional: label, structure, and captions.

      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
languagebash
curl -H 'Avalon-Api-Key:abcdef123456' https://mallorn.dlib.indiana.edu/media_objects/1g05fb83r.json


Example Response
Code Block
languagejs
{
  "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
  }
}


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


Example Response
Code Block
languagejs
[
  {
    "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
languagebash
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
languagejs
{
   "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
languagejs
{"id":"f4752h024"}


PUT /media_objects/:id.json
Code Block
languagebash
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
languagejs
{
   "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
languagejs
{"id":"f4752h024"}


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


Example Response
Code Block
languagexml
<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
languagebash
curl -H "Avalon-Api-Key:abcdef123456" "https://mallorn.dlib.indiana.edu/admin/collections.json?per_page=2&page=3"


Example Response
Code Block
languagejs
[
  {
    "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
languagebash
curl -H "Avalon-Api-Key:abcdef123456" https://mallorn.dlib.indiana.edu/admin/collections/d791sg31t.json


Example Response
Code Block
languagejs
{
  "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
languagebash
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
languagejs
{
  "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
languagebash
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
languagejs
{
   "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
languagejs
{"id":"ht24wj605"}


PUT /admin/collections/:id.json
Code Block
languagebash
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
languagejs
{
   "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
languagejs
{"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
languagebash
curl -H "Avalon-Api-Key:abcdef123456" https://mallorn.dlib.indiana.edu/vocabulary.json


Example Response
Code Block
languagejs
{
  "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
languagebash
curl -H "Avalon-Api-Key:abcdef123456" https://mallorn.dlib.indiana.edu/vocabulary/units.json


Example Response
Code Block
languagejs
[
    "Indiana University Libraries",
    "Default Unit"
]


POST /vocabulary/:vocab.json
Code Block
languagebash
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
languagejs
{
  "entry": "IU Art Museum"
}


Example Response
Code Block
languagejs
// 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:

pid

id in use

Additional information for response included in JSON in the body as {status: Okay or ErrorCode, message: ""}

Open Issues:

  • Should we be strict with CRUD?  E.g. If an item exists and a post command, versus put, is issued should it update or return a code existing the item already exists?  Also if a PUT is attempted on an item that doesn't exist should we fail or just create the item?  Specifically when a user puts and there is no item to update, do they care?
  • Regarding the 202 Code, this may not be needed, but I put in place in the event we have to accept API requests and wait to go test streaming (make sure the derivatives are there).  This is a worst case if our file storage is too slow (which would be really bad of course).  
  • Should we let GET items/ return a list of all items?  List would be massive.
  • Additionally allow GET to be called without an API key/IP restrictions (public).  Would be useful for third parties who want data feeds from us.

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