Version: 8.0

API

API v1

docuteam feeder propose des API REST pour créer des dépositions et des événements et accéder à des objets numériques. Ces API renvoient généralement une réponse JSON (et des données binaires).

Grâce à l'API de déposition, les applications externes peuvent soumettre des dépositions (paquets avec données et métadonnées) à docuteam feeder. Les dépositions sont ensuite récupérées par les flux de travail de docuteam feeder, qui les traitent et les stockent dans un repository Fedora.

Après une ingestion réussie, l'API des dépositions renvoie des identifiants persistants (PID) pour chaque objet (fichier, dossier) contenu dans la déposition. En utilisant ces PID, les clients peuvent à nouveau accéder aux objets déposés.

Dans la terminologie de l'Open Archival Information System (OAIS) :

docuteam feeder reçoit des "Submission Information Packages" (SIP) sur son API de déposition.
Les SIP sont traités par docuteam feeder (assurance qualité, actions de préservation initiales optionnelles) et stockés dans un repository en tant que "Archival Information Packages" (AIP).
Les applications clientes récupèrent les "Dissemination Information Packages (DIP)" des objets qu'elles ont soumis à l'origine en utilisant l'API d'accès de docuteam feeder.

La documentation technique de l'API est disponible en tant que spécification OpenAPI à partir de l'application elle-même sous ./docs/v1.

La version 1 de cette API propose les opérations suivantes :

Deposition API

Cette API peut être utilisée pour créer des dépositions. Lors de la création d'une déposition, la réponse HTTP renvoie l'ID de la déposition. Sur la base de cet ID, le statut de la déposition et (après un archivage réussi) les PID des objets archivés peuvent être interrogés à l'aide de l'API.

Les routes API suivantes sont disponibles :

POST /api/v1/depositions : Créer une nouvelle déposition
GET /api/v1/depositions : Liste de toutes les dépositions avec leurs détails
GET /api/v1/depositions/:id : Afficher la déposition
PUT /api/v1/depositions/:id : Mise à jour de la réponse des dépositions (paramètre feeder_response)

Lors de la création d'une déposition, le format du paquet doit être spécifié dans le paramètre package_format. S'il est vide, le format du paquet est fixé à MatterhornMETSv1.0 par défaut.

Lors de l'établissement de la liste des dépositions, les paramètres facultatifs suivants peuvent être utilisés pour filtrer la liste des dépositions :

statut
de
jusqu'à
organisation

Lors de la mise à jour des dépositions, il est possible de mettre à jour la feeder_response de la déposition (en envoyant une chaîne json bien formée et encodée en url dans le paramètre feeder_response), en supposant que le statut de la déposition n'est pas égal à error. Veuillez noter qu'il n'est pas possible de changer le statut de la déposition en utilisant l'API (seuls les processus internes du feeder peuvent changer le statut).

Réponses

Les réponses sont données en JSON ou (pour la méthode show) en binaire. Chaque réponse JSON est une liste de dépositions avec leurs détails. La structure générique est la suivante :

{ "api" :
   { "name": "docuteam bridge 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"}
}

Les éléments clés sont les suivants :

id est l'identifiant de la déposition, c'est-à-dire la référence interne de l'API pour les dépositions. Il est utilisé pour accéder à une déposition spécifique
status est le statut de la déposition, comme décrit ci-dessus.
feeder_response contient un retour d'information sur le traitement de la déposition dans le feeder. Le contenu de ce champ est également formaté en JSON. C'est une boîte noire du point de vue de l'API.

En cas de succès de la déposition, feeder renvoie une structure de la forme:

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

Il convient de noter que :

le clientId correspond aux identifiants obligatoires soumis par l'application cliente pour chaque objet du SIP (par exemple, dans le cas de docuteam DublinCore SIP, il est situé dans les fichiers dc.xml et utilise la syntaxe suivante <dc:identifier>clientId:d4FTw3v6T</dc:identifier>).
le pid est l'identifiant persistant attribué par le repository. Il est de la forme namespace:id, où "namespace" est généralement le code institutionnel ou ISIL (par exemple : CH-1234565-7:2), et "id" le numéro unique pour cet espace de noms dans le repository.

Event API

Cette API peut être utilisée pour créer des événements dans docuteam feeder et récupérer une liste d'événements ou les détails d'un seul événement.

Les routes API suivantes sont disponibles :

POST /api/v1/events : Créer un nouvel événement
GET /api/v1/events : Liste de tous les événements. Les paramètres page (1 par défaut) et per_page (50 par défaut) peuvent être utilisés pour filtrer les résultats.
GET /api/v1/events/:id : Afficher des événements spécifiques

Lors de la création d'un événement, le corps de la requête doit se présenter comme suit

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

Dans payload, vous pouvez entrer tout ce qui est pertinent pour l'événement que vous envoyez. Les deux champs suivants sont obligatoires :

event_type : Le type de votre événement
source : La source de l'événement

Les paramètres ne sont vérifiés que pour leur existence, mais pas pour leur contenu. Notre recommandation est de déclarer l'application qui envoie l'événement comme source et un nom descriptif pour le event_type.

Vous êtes libre d'ajouter d'autres paramètres à un payload. Jetez un coup d'œil à la page de documentation correspondante pour voir quels types d'événements peuvent être créés.

Si tout va bien, l'API de l'événement répondra avec une représentation JSON de l'événement qui vient d'être créé :

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

Si quelque chose ne va pas avec les données fournies, l'API de l'événement répondra avec le code HTTP 400 et un message d'erreur détaillé. Par exemple, si l'on ne tient pas compte du payload, on obtient le json de réponse suivant :

[
  " Le payload de l'événement ne peut pas être vide ",
  "L'attribut Source du payload de l'événement est manquant ou vide dans le payload",
  "L'attribut Event payload Event type est manquant ou vide dans le payload".
]

Access API

L'API d'accès de docuteam feeder peut être utilisée pour accéder aux objets du DIP et du repository à partir d'un respository basé sur Fedora 3. Il agit comme un proxy pour docuteam rservices. Si vous utilisez un stack de repository basé sur Fedora 6, l'API d'accès de feeder n'est pas fonctionnelle. A la place, l'Access API of docuteam box doit être utilisé et l'Access API du feeder doit être désactivé en utilisant le fedora3 feature flag.

L'API d'accès est capable de générer des DIP à partir de n'importe quel niveau d'un paquet d'archives et de l'assembler de manière récursive. Une autre caractéristique notable est la génération à la volée d'aperçus et de vignettes et, plus généralement, de migrations de format. Cette méthode d'accès récupère les données du repository, et attend donc des PID (et non des ID internes à l'API, comme c'est le cas pour l'API des dépositions). L'API d'accès est limitée aux demandes synchrones, ce qui signifie que l'objet requis est préparé et renvoyé en une seule fois. Les requêtes asynchrones/de rappel ne sont pas encore possibles.

Les routes API suivantes sont disponibles :

GET /api/v1/access/sync_ead/:pid : Télécharger les métadonnées EAD
GET /api/v1/access/sync_premis/:pid : Télécharger les métadonnées PREMIS
GET /api/v1/access/sync_dip/:pid : Télécharger le DIP
GET /api/v1/access/sync_original/:pid : Télécharger le fichier binaire
GET /api/v1/access/sync_preview/:pid : Télécharger la version de prévisualisation du fichier binaire

Lors du téléchargement de DIP, il est possible de créer récursivement un DIP contenant à la fois le nœud sélectionné par le paramètre pid et ses enfants.

Workflow executions API

L'API des exécutions de flux de travail peut être utilisée pour dresser la liste des exécutions de flux de travail, afficher les détails d'une exécution et lancer une exécution de flux de travail. L'API renvoie les données XML d'une ou de plusieurs exécutions de flux de travail.

Les routes API suivantes sont disponibles :

GET /api/v1/workflow_executions : Liste toutes les exécutions de flux de travail (en fonction du token, toutes les exécutions ou seulement les exécutions d'une feeder organisation sont affichées).
GET /api/v1/workflow_executions/:id : Affiche les données d'une seule exécution de flux de travail (sur la base d'un identifiant d'exécution de flux de travail)
POST /api/v1/workflow_executions : Créer une nouvelle exécution de workflow

Lorsque vous utilisez l'API pour créer une nouvelle exécution, un corps json contenant les détails doit être fourni :

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

Authentications

L'accès est limité par des tokens qui doivent être transmis à chaque demande à l'aide du paramètre token. Ce paramètre est requis pour toutes les méthodes HTTP, c'est-à-dire GET, POST, PUT, DELETE. L'API du docuteam feeder s'appuie uniquement sur des tokens pour l'authentification et l'autorisation. Les tokens sont liés à des organisations et à des rôles et restreignent l'accès à l'API. Un token d'authentification doit comporter au moins 15 caractères. Les tokens sont transmis à l'aide d'un paramètre de requête HTTP "token", par exemple https://server:port/api/method?token=123456789012345

L'entrée de menu "Authentifications" dans l'onglet "Admin" permet de créer et de gérer des authentifications (tokens) pour le feeder API.

Authentifications

Lors de la création d'une authentification, les champs suivants sont disponibles :

Name : Champ obligatoire, peut être défini à volonté
Organization : Champ obligatoire, menu déroulant pour la sélection d'une organisation à laquelle le token peut accéder.
Role : Rôle du token
Repository : Menu déroulant permettant de sélectionner un repository auquel le token peut accéder (nécessaire uniquement pour l'Access API)
Username : Nom d'utilisateur pour accéder aux docuteam rservices
Password : Mot de passe pour accéder aux docuteam rservices

La valeur réelle du token est générée automatiquement lors de la création de l'entrée.

Les quatre rôles suivants sont disponibles:

read (limité à une seule organisation)
deliver (limité à une seule organisation)
manage (limité à une seule organisation)
feeder (portée globale)

Le tableau suivant donne un aperçu des différents rôles et de leurs autorisations. Les trois rôles read, deliver et manage sont limités à une seule organisation:

API endpoint	méthode	read token	deliver token	manage token	feeder token
access	all methods	oui	oui	oui	oui
depositions	create		oui	oui	oui
depositions	index / show		oui (propres dépositions)	oui (dépositions de l'organisation)	oui
depositions	update				oui
events	create		oui	oui	oui
events	index / show		oui (propres événements)	oui (événements de l'organisation)	oui
workflow_executions	create		oui	oui	oui
workflow_executions	index / show			oui (exécutions de l'organisation)	oui

API v1​

Deposition API​

Réponses​

Event API​

Access API​

Workflow executions API​

Authentications​

API v1

Deposition API

Réponses

Event API

Access API

Workflow executions API

Authentications