API-Vitam - Access API documentation version v1
https://api.vitam.gouv.fr/access-external/{version}
- version: required (v1)
Avertissements
Cette version d'API présente des fonctionnalités sous différents statuts :
- Supportées : rien n'est spécifié, la fonctionnalité ou la donnée est supportée
- Non supportées : le mot clef UNSUPPORTED est indiqué et précise que cette fonctionnalité ou donnée n'est pas supportée par l'implémentaton courante.
Pour le détail du modèle de chaque collection, se référer à la documentation du modèle de données.
Licence
Ce document est distribué sous les termes de la Licence Ouverte V2.0
API Access
L'API d'Accès propose les points d'entrées et les méthodes pour atteindre, requêter et récupérer les informations depuis les Units et les Objects.
Cette API est globalement reproduite dans tous les autres points d'accès lorsque l'accès à des Units et Objects est nécessaire. Les fonctionnalités offertes peuvent par contre varier (droit en modification, effacement, ...) selon le contexte.
API Access externe
Dans le projet Vitam, Les API externes supportent le POST-X-HTTP-OVERRIDE=GET. Les API internes ne supportent que le GET.
Units
Units est le point d'entrée pour toutes les descriptions d'archives. Celles-ci contiennent les métadonnées de description et les métadonnées archivistiques (métadonnées de gestion).
Une Unit peut être de 3 types :
- "ingest" (unité archivistique classique),
- "holding" (unité archivistique d'arbre de positionnement)
"filing" (unité archivistique de plan de classement). Les métadonnées de ces unités peuvent tout aussi bien décrire un dossier qu'un groupe d'objet lié. Les Units peuvent être organisées en arborescence et peuvent posséder :
- Plusieurs racines dans l'arborescence (Unit de plus haut niveau)
- Plusieurs parents directs (un dossier peut être rattaché à plusieurs dossiers)
Il s'agit d'une représentation dite de "graphe dirigé sans cycle" (DAG en Anglais pour "Directed Acyclic Graph").
Pour le model SEDA, il est équivalent à l'ArchiveUnit, notamment pour les parties Content et Management. Pour l'Isad(G) / EAD, il est équivalent à Description Unit.
Au plus, un seul groupe d'objets d'archives (Objects) est attaché à une Unit. Cela signifie que si une Unit doit avoir plus d'un groupe d'objets d'archive attaché, vous devez spécifier des sous-Units à l'Unit principale, chaque sous-Unit n'ayant qu'un groupe d'objets d'archives attaché. Un même groupe d'objets d'archives peut par contre être attaché à de multiples Units.
Aucun effacement n'est autorisé, ni aucune mise à jour complète (seules les mises à jours partielles sont autorisées via la commande PUT). Les mises à jour ne sont authorisées que par Unit, il n'y a pas de mise à jour en masse.
Structuration des métadonnées
La structuration d'un Unit est la suivante :
{
"#id": "UnitId",
"#tenant": "tenantId",
"#version": 1,
"#unitType" : "HOLDING_UNIT (arbre), FILING_UNIT (Plan) ou INGEST (ArchiveUnit standard)"
//Métadonnées du content
"DescriptionLevel": "Fonds",
"Title": "titre",
"Description": "description du Unit",
"#Management": {
"StorageRule": {},
"AppraisalRule": {},
"AccessRule": {},
"DisseminationRule": {},
"ReuseRule": {},
"ClassificationRule": {},
"NeedAuthorization": false // Accès nécessitant une autorisation explicite
},
"#unitups": [ "unitParentId", "unitParentId"], // liste des parents immédiats
"#min": 1,
"#max": 1,
"#object": "objectId",
"#nbunits": 1, // Nombre de Unit fils
"#operations" : [ "id", "id" ], // liste des opérations auxquelles cette AU a participées
"#allunitsups": [ "unitParentId", "unitParentId"], // liste de tous les parents jusqu'au sommet
"#storage": { "#nbc": 2 } // information de stockage,
"#originating_agency": "originationAgencyId",
"#originating_agencies": [ "originationAgencyId" ],
"#operations" : [ "operationId" ] // liste des opérations auxquelles cette AU a participées
Objects
/units/{idu}/objects est le point d'entrée pour :
- tous les groupes objets, qui contiennent les métadonnées techniques (nom des objets, format, type MIME...)
- tous les objets binaires (des fichiers) non binaires (des références à des objets d'archives physiques ou externes au système).
Un Groupe d'Objects peut posséder de 1 à N objets. Chaque objet a un usage et une version dans son groupe d'objet. Ces distinctions permettent de différencier des usages comme version de conservation, version de diffusion...
Il peut exister plusieurs versions de l'objet pour un même usage (pour l'original numérique notamment), au fur et à mesure du cycle de vie du Groupe d'Objects. Par exemple l'objet d'usage+version "BinaryMaster_1" est la version 1 de l'usage BinaryMaster, le "BinaryMaster_2" est la version 2 de l'usage BinaryMaster. Dans le modèle de données de la solution logicielle Vitam, cet usage correspond au champ "qualifier".
Pour le model SEDA, il est équivalent à un DataObjectGroup. Pour l'EAD, il est équivalent à un Digital Archive Object Group or Set.
Chaque Groupe d'Objets doit être attaché à au moins un parent Unit.
Seul l'accès est autorisé (GET/POST en override de GET).
Chaque Objet n'est lié qu'à un seul Groupe d'objets. Chaque Objet a un qualifier (spécifiable via #qualifiers dans le DSL pour l'accès métadonnées et X-Qualifier en Header pour l'accès aux objets binaires) :
- PhysicalMaster : il s'agit de l'original papier ou physique s'il existe
- BinaryMaster : il s'agit de l'original numérique s'il existe
- Dissemination : il s'agit d'une version adaptée à la diffusion via le réseau et l'usage dans des navigateurs
- Thumbnail : il s'agit d'une version adaptée à la diffusion dans une taille et une qualité correspondant à une vignette (utile lors de l'affichage d'une liste)
- TextContent : il s'agit d'une version ne contenant que le texte du document, sans la mise en forme (son usage est en prévision du futur, par exemple pour des opérations d'analyses sémantiques)
Ces qualifiers peuvent être utilisés dans une requête GET en conjonction avec le Header Accept: application/octet-stream pour accéder en lecture à un usage particulier.
Structuration des métadonnées
A noter: la structuration va changer dans la prochaine release
La structuration d'un Object est la suivante :
{
"#id": "ObjectId",
"#tenant": "tenantId",
//Métadonnées de l'Object
"FileInfo": {
"Filename": "filename",
"LastModified": "date",
"GPS": {}
},
"#qualifiers": [{
"qualifier": "PhysicalMaster",
"#nbc": 1,
"versions": [
{
"#id": "abcdef",
"DataObjectGroupId": "abcdef",
"DataObjectVersion": "PhysicalMaster_1",
"PhysicalDimensions": {},
"PhysicalId": {},
"xxx": "" // autres informations
}
]},
{
"qualifier": "BinaryMaster", // Version numérique
"#nbc": 1, // nombre de versions
"versions": [
{
"#id": "abcdef",
"#storage" : {// informations sur le stockage de l'objet}
"DataObjectGroupId": "abcdef",
"DataObjectVersion": "BinaryMaster_1",
"MessageDigest": "algorithme digest", // empreinte et algorithme d'empreinte de l'objet
"Algorithm": "SHA-512",
"FileInfo": {// informations du fichier},
"Size": 10, // taille de l'objet
"Uri": "Content/uri", // uri de l'objet
"FormatIdentification": {
"FormatLitteral": "format Literral",
"MimeType": "mimetype",
"FormatId": "pronomId"
},
"OtherMetadata": {
// autres métadonnées non classées
}
}
]
},
{
"qualifier": "Dissemination", // Version de diffusion
"#nbc": 1, // nombre de versions
"versions": [
{//idem à BinaryMaster}
]
},
{
"qualifier": "TextContent", // Contenu brut
"#nbc": 1, // nombre de versions
"versions": [
{//idem à BinaryMaster}
]
},
{
"qualifier": "Thumbnail", // Vignette
"#nbc": 1, // nombre de versions
"versions": [
{//idem à BinaryMaster}
]
}
],
"#unitups": [ "unitParentId", "unitParentId"],
"#nbobjects": 1, // Nombre de versions d'objets contenus pour tous les usages
"#storage": { "#nbc": 2 }, // information de stockage,
"#originating_agency": "originationAgencyId",
"#originating_agencies": [ "originationAgencyId" ],
"#operations" : [ "operationId" ] // liste des opérations auxquelles ce groupe d'objets a participées
}
Note : A l'avenir, à l'intérieur d'une version d'usage, et pour chaque version (pour les BinaryMaster notamment), un contexte sera ajouté à la structure de l'Object afin de pouvoir y introduire des données de contexte (version du référentiel Pronom par exemple...).
DIPEXPORT
/dipexport est le point d'entrée permettant l'export sous forme de DIP (paquet d'information diffusé ou Dissemination Information Package en anglais) d'une sélection d'unités archivistiques.
Important : Deux actions sont disponibles. La première permet de lancer un processus de génération d'un DIP. La deuxième permet de télécharger le fichier généré par le processus précédent, une fois terminé.
Champs d'application sur les Units
Les principes sont les suivants :
- Pas de POST (sauf X-Http-Method-Override: GET) car ceci relève de l'entrée
- Le PUT est utilisé pour réaliser un update partiel
- Pas de DELETE car ceci relève de l'élimination
- GET correspond à la recherche ou l'accès selon la présence d'un body ou non
- Un seul Object par Unit max
- Une requête depuis un Unit signifie recherche relative depuis celui-ci (roots = this)
- Accept: application/json signifie les métadonnées au format Json
- (UNSUPPORTED) Accept: application/zip signifie les métadonnées au format Json et le contenu binaire de l'Objet
- Accept: application/octet-stream signifie le retour du contenu binaire de l'Object
Champs d'application sur les Objects
Les principes sont les suivants :
- Object signifie ObjectGroup en masquant la complexité ObjectGroup/Object
- Pas de POST (sauf X-Http-Method-Override: GET) car ceci relève de l'entrée
- Pas de DELETE car ceci relève de l'élimination
- GET correspond à la recherche ou l'accès selon la présence d'un body ou non
- Une requête depuis un object signifie recherche relative depuis celui-ci (roots = this)
- Accept: application/json signifie les métadonnées au format Json
- (UNSUPPORTED) Accept: application/zip signifie les métadonnées au format Json et le contenu binaire de l'Objet
- Accept: application/octet-stream signifie le retour du contenu binaire de l'Object
ArchiveUnits
API qui définit les requêtes pour accéder aux Unités d'archives. La requête utilise le langage de requête DSL de Vitam en entrée et retourne une liste d'Unités d'archives selon le DSL Vitam en cas de succès.
Requête qui retourne des résultats contenant des Unités d'archives. La requête utilise le langage de requête DSL de type recherche multiple (SELECT MULTIPLE) de Vitam en entrée et retourne une liste d'Unités d'archives selon le DSL Vitam en cas de succès.
Requête qui retourne des résultats contenant des Unités d'archives. La requête utilise POST avec X-Http-Method-Override: GET La requête utilise le langage de requête DSL de type recherche multiple (SELECT MULTIPLE) de Vitam en entrée et retourne une liste d'Unités d'archives selon le DSL Vitam en cas de succès.
API qui définit les requêtes pour accéder à une Unité d'archive. La requête utilise le langage de requête DSL de Vitam en entrée et retourne une liste d'Unités d'archives selon le DSL Vitam en cas de succès.
Requête qui retourne une Unité d'archive. La requête utilise le langage de requête DSL de type recherche unitaire (GET BY ID) de Vitam en entrée et retourne une liste d'Unités d'archives contenant 1 seul résultat selon le DSL Vitam en cas de succès.
Requête qui retourne une Unité d'archives. La requête utilise POST avec X-Http-Method-Override: GET La requête utilise le langage de requête DSL de type recherche unitaire (GET BY ID) de Vitam en entrée et retourne une liste d'Unités d'archives contenant 1 seul résultat selon le DSL Vitam en cas de succès.
Requête qui modifie une Unité d'archive. La requête utilise le langage de requête DSL de type modification unitaire (UPDATE BY ID) de Vitam en entrée et retourne le statut de la mise à jour en résultat selon le DSL Vitam en cas de succès.
API qui définit les requêtes pour accéder à l'Objet d'archives associé à l'Unité d'archives s'il existe. La requête utilise le langage de requête (DSL) de Vitam en entrée et retourne l'objet d'archives selon le DSL Vitam en cas de succès.
Requête qui retourne le résultat contenant un Object d'archives : ses métadonnées ou un de ses objets binaires. Dans le cas des métadonnées, la requête utilise le langage de requête DSL de type recherche unitaire (GET BY ID) de Vitam en entrée. 'Accept' header est 'application/octet-stream' (objet binaire) ou 'application/json' (métadonnées)
Requête qui retourne le résultat contenant un Object d'archives : ses métadonnées ou un de ses objets binaires. Dans le cas des métadonnées, la requête utilise le langage de requête DSL de type recherche unitaire (GET BY ID) de Vitam en entrée. 'Accept' header est 'application/octet-stream' (objet binaire) ou 'application/json' (métadonnées) La requête utilise POST avec X-Http-Method-Override: GET.
DIP Export
API qui définit les requêtes pour générer un DIP (Dissemination Information Package : ZIP contenant les métadonnées et les objets) pour une sélection d'Unités d'archives. La requête utilise le langage de requête (DSL) de Vitam en entrée et va lancer un processus générant le DIP selon le DSL passé. Une autre requête pourra être exécutée par la suite pour télécharger le fichier Zip généré.
response : JSON asynchronous state / HTTP CODE 202 or 500 for KO La requête utilise le langage de requête DSL de type recherche multiple (SELECT MULTIPLE) de Vitam en entrée.
Télécharger le DIP généré par l'opération passée en paramètre
Requête qui retourne les résultate composés des métadonnées et des objets binaires dans un fichier zip 'Accept' header est 'application/octet-stream'
LFC traceability audit
API qui définit les requêtes pour générer un audit de la traçabilité des journaux de cycles de vie.
Opération d'audit de la traçabilité des journaux de cycles de vie d'une unité archivistique.
Lancer une opération d'audit de la traçabilité des journaux de cycles de vie d'une unité archivistique.
Opération d'audit de la traçabilité des journaux de cycles de vie d'un groupe d'objets.
Lancer une opération d'audit de la traçabilité des journaux de cycles de vie d'un groupe d'objets.
Endpoints
API qui liste les endpoints de la ressource /access-external/{version}.