...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
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 |
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 |
Table of Contents
| Anchor | ||||
|---|---|---|---|---|
|
...
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 | ||
|---|---|---|
| ||
$ rake avalon:token:generate username=archivist email=archivist1@example.com 37ebd7d86d406e925ba2da4315903440b2439f671dc58c2a36dc827e454d263fdcfd0bf8ad5cea7f5dce5516f2ffe63ee02debf6881b7b466a8600d321b0a01c $ rake avalon:token:list 37ebd7d86d406e925ba2da4315903440b2439f671dc58c2a36dc827e454d263fdcfd0bf8ad5cea7f5dce5516f2ffe63ee02debf6881b7b466a8600d321b0a01c|archivist $ rake avalon:token:revoke username=archivist Token `37ebd7d86d406e925ba2da4315903440b2439f671dc58c2a36dc827e454d263fdcfd0bf8ad5cea7f5dce5516f2ffe63ee02debf6881b7b466a8600d321b0a01c` (archivist) revoked. |
| Anchor | ||||
|---|---|---|---|---|
|
...
GET /media_objects/:id.json
...
DELETE /media_objects/:id.json
Deletes a media object
Parameters for POST and PUTS:
collection_id: id of owning admin collection,
...
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
| Code Block | ||||
|---|---|---|---|---|
| ||||
curl -H 'Avalon-Api-Key:abcdef123456' https://mallorn.dlib.indiana.edu/media_objects/1g05fb83r.json |
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<html><body>You are being <a href="http://mallorn.dlib.indiana.edu/">redirected</a>.</body></html> |
| Anchor | ||||
|---|---|---|---|---|
|
...
GET /admin/collections.json
...
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
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{"id":"ht24wj605"} |
| Anchor | ||||
|---|---|---|---|---|
|
...
In Avalon, units are part of a controlled vocabulary. To add a new unit, a call to the vocabulary is required.
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
// Empty response |
| Anchor | ||||
|---|---|---|---|---|
|
...
| Code | Description |
|---|---|
| 200 | Okay. For GET, the relevant JSON will be contained in response body. For PUTS and POST response body will contain id of created/updated item. |
| 201 | <Not used> Created |
| 202 | <Not used> Accepted, Queued |
| 400 | Bad request |
| 401 | Auth Failure. No token present in request header 'Avalon-Api-Key' |
| 403 | Forbidden. Invalid token in request header 'Avalon-Api-Key' |
| 404 | Resource Not Found. If object is not found for requested 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. |
...