Version: 5.8

API

API v1

docuteam feeder bietet REST-APIs für die Erstellung von Ablieferungen und Ereignissen und den Zugriff auf digitale Objekte. Diese APIs geben in der Regel eine JSON-Antwort (und binäre Daten) zurück.

Mit Hilfe des Deposition-API können externe Anwendungen Ablieferungen (Pakete mit Daten und Metadaten) an docuteam feeder übermitteln. Die Ablieferungen werden dann von docuteam feeder-Workflows abgeholt, verarbeitet und in einem Fedora-Repository gespeichert.

Nach erfolgreichem Ingest liefert die Deposition-API persistente Identifikatoren (PIDs) für jedes Objekt (Datei, Ordner) in der Ablieferung zurück. Anhand dieser PIDs können die Clients wieder auf die hinterlegten Objekte zugreifen.

In der Terminologie des Open Archival Information System (OAIS):

docuteam feeder empfängt "Submission Information Packages" (SIP) über seine Deposition-API.
Die SIPs werden von docuteam feeder verarbeitet (Qualitätssicherung, optionale erste Erhaltungsmassnahmen) und in einem Repository als "Archival Information Packages" (AIP) abgelegt.
Client-Anwendungen rufen "Dissemination Information Packages (DIP)" ihrer ursprünglich eingereichten Objekte über die Access-API von docuteam feeder ab.

Die technische API-Dokumentation ist als OpenAPI-Spezifikation in der Anwendung selbst unter ./docs/v1 verfügbar.

Die Version 1 dieser API bietet die folgenden Operationen:

Deposition API

Diese API kann zur Erstellung von Ablieferungen verwendet werden. Bei der Erstellung einer Ablieferung gibt die HTTP-Antwort die Ablieferungs-ID zurück. Anhand dieser ID können der Status der Ablieferung und (nach erfolgreicher Archivierung) die PIDs der archivierten Objekte über die API abgefragt werden.

Die folgenden API-Routen sind verfügbar:

POST /api/v1/depositions Erstellen einer neuen Ablieferung
GET /api/v1/depositions Alle Ablieferungen mit Details auflisten
GET /api/v1/depositions/:id Ablieferung anzeigen
PUT /api/v1/depositions/:id Ablieferung aktualisieren (Parameter feeder_response)

Bei der Erstellung einer Ablieferung muss das Paketformat mit dem Parameter package_format angegeben werden. Ist er leer, wird das Paketformat standardmässig auf MatterhornMETSv1.0 gesetzt.

Bei der Auflistung von Ablieferungen können die folgenden optionalen Parameter verwendet werden, um die Liste der Ablieferungen zu filtern:

Status
von
bis
Organisation

Bei der Aktualisierung von Ablieferungen ist es möglich, die feeder_response der Ablieferung zu aktualisieren (durch Senden eines wohlgeformten und url-kodierten json-Strings im Parameter feeder_response), vorausgesetzt, der Status der Hinterlegung ist nicht gleich error. Bitte beachten Sie, dass es nicht möglich ist, den Status der Ablieferung über die API zu ändern (nur interne Feeder-Prozesse können den Status ändern).

Antworten

Die Antworten werden in JSON oder (bei der Show-Methode) in binärer Form gegeben. Jede JSON-Antwort ist eine Liste von Ablieferungen mit ihren Details. Die generische Struktur sieht wie folgt aus:

{ "api" :
   { "name": "docuteam feeder API",
     "version": "1.4.0" },
 "response" :
   [
     { "id": 1234,
       "uploaded_at": "2018-11-03T11:13:39.278026Z",
       "queued_at": "2018-11-03T14:16:12.678056Z",
       "processed_by_feeder_at": "2018-11-03T14:16:12.678016Z",
       "archived_at": "2018-11-03T14:16:12.678016Z",
       "deleted_at": null,
       "status": "archived",
       "feeder_response": { json-blackbox },
       "organization": "museumplus",
       "repository_key": "museumplus",
       "package_format" : "DocuteamDublinCorev1.0",
       "package_attached" : true,
       "package_byte_size": 2716786
     }
   ]
 "request" :
   { "organization": "museumplus",
     "role": "reader",
     "requested_at": "2018-11-03T11:13:39.278026Z"}
}

Die wichtigsten Elemente sind:

id ist die Kennung der Ablieferung, d. h. die API-interne Referenz für Ablieferungen. Sie wird verwendet, um auf eine bestimmte Ablieferung zuzugreifen.
status ist der Status der Ablieferung, wie oben beschrieben.
feeder_response enthält Rückmeldungen über die Verarbeitung der Ablieferung in docuteam feeder. Der Inhalt dieses Feldes ist ebenfalls in JSON formatiert. Aus der Sicht der API ist es eine Blackbox.

Bei erfolgreicher Archivierung gibt feeder eine Struktur in folgender Form zurück:

{ "pids":
    [
      { "clientId":"c1", "pid":"CH-1234565-7:1"},
      { "clientId":"c2", "pid":"CH-1234565-7:2"},
         ...
    ],
  "feeder_version": "5.4.0"
}

Es muss beachtet werden, dass:

die clientId den obligatorischen IDs entspricht, die von der Client-Anwendung für jedes Objekt innerhalb des SIP übermittelt werden (zum Beispiel im Fall von docuteam DublinCore SIP befindet sie sich in den dc.xml-Dateien und verwendet die folgende Syntax <dc:identifier>clientId:d4FTw3v6T</dc:identifier>).
Die pid ist der dauerhafte Identifikator, der vom Repository vergeben wird. Er hat die Form {namespace}:{id}, wobei "namespace" im Allgemeinen der institutionelle oder ISIL-Code ist (zum Beispiel: "CH-1234565-7:2") und "id" die eindeutige Nummer für diesen namespace im Repository.

Event API

Diese API kann verwendet werden, um Ereignisse in docuteam feeder zu erstellen und entweder eine Liste von Ereignissen oder die Details eines einzelnen Ereignisses abzurufen.

Die folgenden API-Routen sind verfügbar:

POST /api/v1/events: Neues Ereignis erstellen
GET /api/v1/ereignisse: Alle Ereignisse auflisten. Die Parameter page (Standardwert 1) und per_page (Standardwert 50) können zum Filtern der Ergebnisse verwendet werden.
GET /api/v1/events/🆔 Bestimmte Ereignisse anzeigen

Bei der Erstellung eines Ereignisses sollte der Ereignis-Body wie folgt aussehen

{
  "event": {
    "payload": {
      "event_type": "File Placed",
      "source": "Doc Observer"
    }
  },
}

In payload können Sie alles eingeben, was für das Ereignis relevant ist. Die folgenden zwei Felder sind erforderlich:

Ereignis-Typ: Der Typ Ihres Ereignisses
source: Die Quelle des Ereignisses

Die Parameter werden nur auf ihre Existenz, nicht aber auf ihren Inhalt geprüft. Unsere Empfehlung ist, die Anwendung, die das Ereignis sendet, als source und einen beschreibenden Namen für den event_type anzugeben.

Es steht Ihnen frei, weitere Parameter zum Payload hinzuzufügen. Werfen Sie einen Blick auf die entprechende Dokumentation, um zu sehen, welche Art von Ereignissen erstellt werden können.

Wenn alles in Ordnung ist, antwortet die Ereignis-API mit einer JSON-Darstellung des gerade erstellten Ereignisses:

{
  "id": 9,
  "payload": {
    "event_type": "File Placed",
    "source": "Doc Observer"
  },
  "created_at": "2021-12-06T16:31:29.000+01:00"
}

Wenn etwas mit den bereitgestellten Daten nicht stimmt, antwortet die Event-API mit dem HTTP-Code 400 und einer detaillierten Fehlermeldung. Das Weglassen der Nutzdaten ergibt z. B. die folgende json-Antwort:

[
  "Event payload can't be blank",
  "Event payload Source attribute is missing or empty in payload",
  "Event payload Event type attribute is missing or empty in payload"
]

Access API

Das Access-API von docuteam feeder kann verwendet werden, um auf DIP- und Repository-Objekte in einem Fedora 3-basierten Repository zuzugreifen. Sie fungiert als Proxy für docuteam rservices. Wenn Sie einen Fedora 6-basierten Repository-Stack verwenden, ist die Access API von feeder nicht funktionsfähig. Stattdessen sollte die Access API of docuteam-box verwendet werden und die Access API von feeder sollte mit dem fedora3 feature flag deaktiviert werden.

Die Access-API ist in der Lage, DIPs ausgehend von einer beliebigen Stufe eines Archivierungspakets zu erzeugen und rekursiv zusammenzustellen. Weiter können on-the-fly Vorschaubildern/Thumbnails generiert und andere Formatmigrationen duchgeführt werden. Diese Zugriffsmethode ruft Daten aus dem Repository ab und erwartet daher PIDs (und nicht API-interne IDs, wie es bei der Deposition-API der Fall ist). Die Access-API ist auf synchrone Anfragen beschränkt, was bedeutet, dass das benötigte Objekt sofort vorbereitet und zurückgegeben wird. Asynchrone/Callback-Anfragen sind noch nicht möglich.

Die folgenden API-Routen sind verfügbar:

GET /api/v1/access/sync_ead/:pid EAD Metadaten herunterladen
GET /api/v1/access/sync_premis/:pid PREMIS Metadaten herunterladen
GET /api/v1/access/sync_dip/:pid DIP herunterladen
GET /api/v1/access/sync_original/:pid Binärdatei herunterladen
GET /api/v1/access/sync_preview/:pid Zugangskopie / Preview einer Binärdatei herunterladen

Beim Herunterladen von DIPs ist es möglich, rekursiv ein DIP zu erstellen, das sowohl den durch den Parameter pid ausgewählten Knoten als auch dessen Kinder enthält.

Workflow executions API

Die API für Workflow-Ausführungen kann verwendet werden, um Workflow-Ausführungen aufzulisten, Details zu einer Ausführung anzuzeigen und eine Workflow-Ausführung zu starten. Die API gibt XML-Daten von einer oder mehreren Workflow-Ausführungen zurück.

Die folgenden API-Routen sind verfügbar:

GET /api/v1/workflow_executions Auflistung aller Workflow-Ausführungen (je nach Token werden alle Ausführungen oder nur Ausführungen einer feeder-Organisation angezeigt)
GET /api/v1/workflow_executions/:id Zeigt Daten einer einzelnen Workflow-Ausführung an (basierend auf einer Workflow-Ausführungskennung)
POST /api/v1/workflow_executions Erstellen einer neuen Workflow-Ausführung

Wenn Sie die API verwenden, um eine neue Ausführung zu erstellen, muss ein json-Body mit den Details geliefert werden:

{
  "workflow_execution": {
    "workflow_id": 248042309,
    "sip": "sip",
    "queue_name": "queue_name"
  }
}

Authentifizierungen

Der Zugriff auf APIs wird über Token beschränkt, die bei jeder Anfrage mit dem Parameter token übermittelt werden müssen. Dies ist für alle HTTP-Methoden erforderlich, d.h. GET, POST, PUT, DELETE. docuteam feeder API verlässt sich ausschließlich auf Token für die Authentifizierung und Autorisierung. Token sind an Organisationen und Rollen gebunden und schränken die API ein. Ein Authentifizierungs-Token muss mindestens 15 Zeichen lang sein. Token werden mit einem "token"-HTTP-Anfrageparameter übergeben, z.B. https://server:port/api/method?token=123456789012345

Über den Menüpunkt "Authentifizierungen" im Reiter "Admin" können Authentifizierungen (Token) für die feeder APIs erstellt und verwaltet werden.

Authentifizierungen

Bei der Erstellung einer Authentifizierung stehen die folgenden Felder zur Verfügung:

Name: Pflichtfeld, kann beliebig definiert werden
Organization: Pflichtfeld, Dropdown-Menü zur Auswahl einer Organisation, auf die der Token zugreifen kann
Role: Rolle des Tokens
Repository: Dropdown-Menü zur Auswahl eines Repositories, auf das mit dem Token zugegriffen werden kann (nur notwendig für die Access API).
Username: Benutzername für den Zugriff auf docuteam rservices
Password: Passwort für den Zugriff auf docuteam rservices

Der eigentliche Wert des Tokens wird beim Erstellen des Eintrags automatisch generiert.

Die folgenden vier Rollen sind verfügbar:

read (beschränkt auf eine einzelne Organisation)
deliver (beschränkt auf eine einzelne Organisation)
manage (beschränkt auf eine einzelne Organisation)
feeder (globaler Geltungsbereich)

Die folgende Tabelle gibt einen Überblick über die verschiedenen Rollen und ihre Berechtigungen. Die drei Rollen read, deliver und manage sind auf eine einzige Organisation beschränkt:

API Endpunkt	Methode	read Token	deliver Token	manage Token	feeder Token
access	alle	ya	Ja	Ja	Ja
depositions	create		Ja	Ja	Ja
depositions	index / show		Ja (eigene Ablieferungen)	Ja (Ablieferungen der Organisation)	Ja
depositions	update				Ja
events	create		Ja	Ja	Ja
events	index / show		Ja (eigene Ereignisse)	Ja (Ereignisse der Organisation)	Ja
workflow_executions	create		Ja	Ja	Ja
workflow_executions	index / show			Ja (Ausführungen der Organisation)	Ja

API v1​

Deposition API​

Antworten​

Event API​

Access API​

Workflow executions API​

Authentifizierungen​

API v1

Deposition API

Antworten

Event API

Access API

Workflow executions API

Authentifizierungen