...

A lightweight API for indexing metadata and links to existing derivatives into Avalon.

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 enhanced

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.

...

Code Block

language	bash

rake avalon:token:list
rake avalon:token:generate username=archivist email=archivist1@example.com
rake avalon:token:revoke username=archivist

...

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:list
rake avalon:token:generate username=archivist email=archivist1@example.com
rake avalon:token:revoke username=archivist

Anchor
mediaobjects
mediaobjects
Media Objects

...

GET /media_objects/:id.json

Retrieves a subset of the mods for the specified media object

GET /media_objects.json

Retrieves a paged list of media_objects (parameters :page and :per_page specify page number and number per page for pagination)

POST /media_objects.json

Creates an media object

...

PUT /media_objects/:

...

id.json

Updates an media object

...

Parameters for POST and PUTS:

...

collection_id: id of owning admin collection,

fields: mods converted to JSON hash.

...

Required fields: title, date_issued

...

title (* required),

...

date_issued (* required),

...

creator (multiple),

...

alternative_title (multiple),

...

translated_title (multiple),

...

uniform_title (multiple),

...

statement_of_responsibility,

...

date_created,

...

copyright_date,

...

abstract,

...

note (multiple

...

): requires note_type from controlled vocabulary to be present also

...

,

...

format,

...

resource_type (multiple),

...

contributor (multiple),

...

publisher (multiple),

...

genre (multiple),

...

subject (multiple),

...

related_item_url (multiple

...

): requires

...

related_item_label to be present also

...

,

...

geographic_subject (multiple),

...

temporal_subject (multiple),

...

topical_subject (multiple),

...

bibliographic_id,

...

language (multiple),

...

terms_of_use,

...

table_of_contents (multiple),

...

physical_description,

...

other_identifier (multiple

...

): requires

...

other_identifier_type from controlled vocabulary to be present also

...

,

...

comment (multiple)

:collection_id

...

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

...

language	ruby
title	:files example

...

.

label (optional),
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,
percent_complete: must be "100.0",
percent_succeeded: must be "100.0",
percent_failed: must be "0",
status_code: must be "COMPLETED",
files: an array of derivative hashes

label,
id,
url,
duration,
mime_type,
audio_bitrate,
audio_codec,
video_bitrate,
video_codec,
width,
height

import_bib_record (boolean):

If true, fields must include value for :bibliographic_id and may include value from controlled vocabulary for :bibliographic_id_label)
Bib import failure will result in a JSON response: {errors: ['Bib import failed', e.message]}, status: 422

replace_masterfiles (boolean):

Relevant only if the media object already exists and it has masterfiles. If true, existing masterfiles will be replaced by those sent. If false, sent masterfiles will be appended to existing list.

publish (boolean):

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

Example Requests

Code Block

language	bash
title	GET /media_objects/:id.json

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

Code Block

language	js
title	Example Response
collapse	true

{
  "id": "1g05fb83r",
  "title": "Lease 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": [
    {
      "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": "12532-medium",
          "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",
         files: [{label: 'quality-high' "track_id": "12532-medium",
                  id: 'track-1',"hls_track_id": null,
          "managed": false,
          url"derivativeFile": "httpsfile:///srv//streaming.server/path/to/high.m3u8",avalon/rtmp_streams/ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-medium.mp4"
                  duration: "6315",},
        {
          mime_type:  "video/mp4","label": "quality-high",
          "id": "12532-high",
           audio_bitrate: "127716.0"url": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-high",
                  audio_codec: "AAC"hls_url": "https://mallorn.dlib.indiana.edu:8980/avalon/ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-high.mp4/index.m3u8",
                  video_bitrate: "1000000.0""duration": 5336,
                  video_codec: "AVC",
                  width: "640","mime_type": null,
          "audio_bitrate": 192000,
          height"audio_codec": "480" },mp4a-40-2",
          "video_bitrate": 3000000,
      {label: 'quality-medium',   "video_codec": "avc1",
          "width": "1280.0",
  id: 'track-2',       "height": "720.0",
          url"location": "httpsrtmp://streaming.server/path/to/medium.m3u8",
     mallorn.dlib.indiana.edu:1935/avalon/mp4:ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-high",
            duration"track_id": "631512532-high",
                  mime_type: "video/mp4""hls_track_id": null,
                  audio_bitrate: "127716.0",
       "managed": false,
          audio_codec"derivativeFile": "AAC",file:///srv/avalon/rtmp_streams/ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-high.mp4"
        },
        {
   video_bitrate: "1000000.0",      "label": "quality-low",
           video_codec"id": "AVC12532-low",
                  width: "640",
    "url": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-low",
             height: "480" }"hls_url": "https://mallorn.dlib.indiana.edu:8980/avalon/ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-low.mp4/index.m3u8",
                ]"duration": 5336,
        file_location:  "/srv/avalon/master_files/file.mp4",mime_type": null,
          file"audio_checksumbitrate": "7ae24368ccb7a6c6422a14ff73f33c9a"128078,
          file"audio_sizecodec": "199160mp4a-40-2",
         duration: "6315",video_bitrate": 500000,
          display_aspect_ratio"video_codec": "1.7777777777777777avc1",
          original_frame_size"width": "640x480852.0",
          file_format"height": "Moving image480.0",
          poster_offset: "0:02","location": "rtmp://mallorn.dlib.indiana.edu:1935/avalon/mp4:ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-low",
         thumbnail_offset: "0:02",
        date_digitizedtrack_id": "201512532-12-31low",
  
     structure: structure xml,         captions: captions text from vtt or srt file,"hls_track_id": null,
            "managed": false,
 captions_type: 'text/vtt' (or 'text/srt') 	    other_identifier: ["40000000045312derivativeFile"],
        comment: ["test comment"],: "file:///srv/avalon/rtmp_streams/ececa279-0217-45b4-92fb-daf49d552f33/outputs/SampleVideo-low.mp4"
        structure: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!-- Music for Piano; http://server1.variations2.indiana.edu/variations/cgi-bin/access.pl?id=BFJ6801 -->\n<Item label=\"CD 1\">\n    <Div label=\"Copland, Three Piano Excerpts from Our Town\">\n        <Span label=\"Track 1. Story of Our Town\" begin=\"0\" end=\"0:09.99\"/>\n        <Span label=\"Track 2. Conversation at the Soda Fountain\" begin=\"0:10\" end=\"0:19.99\"/>\n        <Span label=\"Track 3. The Resting Place on the Hill\" begin=\"0:20\" end=\"0:29.99\"/>\n    </Div>\n    <Div label=\"Copland, Four Episodes from Rodeo\">\n        <Span label=\"Track 4. Buckaroo Holiday\" begin=\"0:30\" end=\"0:39.99\"/>\n        <Span label=\"Track 5. Corral Nocturne\" begin=\"0:40\" end=\"0:49.99\"/>\n        <Span label=\"Track 6. Saturday Night Waltz\" begin=\"0:50\" end=\"0:59.99\"/>\n        <Span label=\"Track 7. Hoe-Down\" begin=\"1:00\" end=\"1:09.99\"/>\n    </Div>\n    <Span label=\"Track 8. Copland, Piano Variations \" begin=\"1:10\" end=\"1:19.99\"/>\n    <Div label=\"Copland, Four Piano Blues\">\n        <Span label=\"Track 9. For Leo Smit: Freely poetic\" begin=\"1:20\" end=\"1:29.99\"/>\n        <Span label=\"Track 10. For Andor Foldes: Soft and languid\" begin=\"1:30\" end=\"1:39.99\"/>\n        <Span label=\"Track 11. For Willian Kapell: Muted and sensuous\" begin=\"1:40\" end=\"1:49.99\"/>\n        <Span label=\"Track 12. For John Kirkpatrick: WIth bounce\" begin=\"1:50\" end=\"1:59.99\"/>\n    </Div>\n    <Span label=\"Track 13. Copland, Danzon Cubano\" begin=\"2:00\" end=\"2:30\"/>\n</Item>\n",
        workflow_name: "avalon",
        percent_complete: "100.0",
        percent_succeeded: "100.0",
        percent_failed: "0",
        status_code: "COMPLETED"
}]

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

Bib import failure will result in a JSON response: {errors: ['Bib import failed', e.message]}, status: 422

:replace_masterfiles - boolean. Relevant only if the media object already exists and it has masterfiles. If true, existing masterfiles will be replaced by those sent. If false, sent masterfiles will be appended to existing list.

:publish – boolean. If true, mediaobject will automatically enter a published state with avalon_publisher='REST API'

...

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

Code Block

language	bash
title	GET /media_objects.json

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

Code Block

language	js
title	Example Response
collapse	true

Code Block

language	bash
title	POST /media_objects.json

curl -H "Avalon-Api-Key:abcdef123456" -X POST -d @data.json https://mallorn.dlib.indiana.edu/media_objects.json

Code Block

language	js
title	Example Request Data (data.json)
collapse	true

Code Block

language	js
title	Example Response
collapse	true

Code Block

language	bash
title	PUT /media_objects/:id.json

curl -H "Avalon-Api-Key:abcdef123456" -X POST -d @data.json https://mallorn.dlib.indiana.edu/media_objects/abcd1234.json

Code Block

language	js
title	Example Request Data (data.json)
collapse	true

Code Block

language	js
title	Example Response
collapse	true

Anchor
collections
collections
Admin Collection

...

GET /admin/collections.json

Retrieves a paginated list of all collections

GET /admin/collections/:

...

id.json

Retrieves information on the collection

GET /admin/collections/:

...

id/items.json

Retrieves a paginated list of all items in collection :pid

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

...

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

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 pid of created/updated item.
201	<Not used> Created
202	<Not used> Accepted, Queued
400	<Not used> 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 pid.
405	<Not used> Method Prohibited
409	<Not used> Conflict/Other Error. Conflict ex: pid in use
422	Processing failed. Response body will contain JSON hash with :errors key pointing to a list of error message strings.

Versions Compared

Old Version 44

New Version 45

Key

A lightweight API for indexing metadata and links to existing derivatives into Avalon.

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 enhanced

Table of Contents

Anchor
access control
access control

Access Control

Anchor
mediaobjects
mediaobjects
Media Objects

Parameters for POST and PUTS:

Example Requests

Anchor
collections
collections
Admin Collection

Parameters for POST and PUT:

Anchor
units
units

Units

Anchor
codes
codes

Response Codes

Page Comparison

Versions Compared

Old Version 44

New Version 45

Key

<span class="diff-html-changed" data-a11y-before="Start of changed content" data-a11y-after="End of changed content" id="changed-diff-0">[data-colorid=</span>

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 enhanced

Table of Contents

Anchoraccess controlaccess control

Access Control

AnchormediaobjectsmediaobjectsMedia Objects

Parameters for POST and PUTS:

Example Requests

AnchorcollectionscollectionsAdmin Collection

Parameters for POST and PUT:

Anchorunitsunits

Units

Anchorcodescodes

Response Codes

Anchor
access control
access control

Anchor
mediaobjects
mediaobjects
Media Objects

Anchor
collections
collections
Admin Collection

Anchor
units
units

Anchor
codes
codes