API-Vitam Version Alpha - Access API documentation version v1
https://api.vitam.gouv.fr/external/v1
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).
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 soit un simple dossier (comme dans un plan de classement), soit une description d'un item. Les Units portent l'arborescence d'un plan de classement. Ce plan de classement peut être multiple :
- Plusieurs racines (Unit de plus haut niveau)
- Plusieurs parents (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.
A priori, un seul groupe d'objets d'archives (Objects) est attaché à une Unit. Cela signifie que si une Unit devait 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).
La structuration d'un Unit est la suivante :
{
"#id": "UnitId",
"#tenantId": "tenantId",
"#type": "DocumentTypeId",
"#sector": "FilièreId",
//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
},
"#parents": [ "unitParentId", "unitParentId"],
"#object": "objectId",
"#childNb": 1 // Nombre de Unit fils
}
Objects
Objects est le point d'entrée pour toutes les archives binaires mais également les non binaires (comme une référence à des objet d'archives physiques ou externes au système). Elles contiennent les métadonnées techniques. Il est constitué de plusieurs usages et versions d'usages du même contenu. C'est dans ce sens qu'il est aussi appelé un Groupe d'objets.
Un Groupe d'Objects peut être constitué de plusieurs versions (sous-objets) pour différencier des usages comme version de conservation, version de diffusion...
Il peut exister plusieurs enregistrements pour une même version d'usage (pour l'original numérique notamment), au fur et à mesure du cycle de vie du Groupe d'Objects.
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/HEAD).
Pour le model SEDA, chaque usage/version est équivalent à un DataObject (binaire avec BinaryDataObject ou physique avec PhysicalDataObject). Pour l'EAD, il est équivalent à un Digital Archive Object.
Chaque Objet n'est lié qu'à un seul Groupe. Chaque Objet a un qualifier (spécifiable via #qualifiers dans le DSL et X-Qualifier en Header) :
- 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)
- All : il s'agit en consultation d'un accès en cas de ZIP ou TAR à l'ensemble des usages et versions. Il est utilisable également en mode HEAD.
Ces qualifiers peuvent être utilisés dans une requête GET en conjonction avec le Header Accept: application/octet-stream ou application/zip ou application/x-tar pour accéder en lecture ou en check à un usage particulier. Le qualifier All est ajouté pour permettre l'accès à l'ensemble des usages avec le Header Accept: application/zip ou application/x-tar. Pour la commande HEAD, ces Qualifiers peuvent être spécifiés pour préciser sur quoi porte le test d'existence.
La structuration d'un Object est la suivante :
{
"#id": "ObjectId",
"#tenantId": "tenantId",
"#type": "ObjectTypeId", // Audio, Video, Document, Text, Image, ...
//Métadonnées de l'Object
"FileInfo": {
"Filename": "filename",
"LastModified": "date",
"GPS": {}
},
"#qualifiers": {
"PhysicalMaster": { // Version papier
"PhysicalId": "abcdef",
"PhysicalDimensions": {},
"xxx": "" // autres informations
},
"BinaryMaster": { // Version numérique
"nb": 1, // nombre de versions
"versions": [
{
"MessageDigest": "algorithme digest", // empreinte et algorithme d'empreinte de l'objet
"IngestDate": "yyyy-MM-dd'T'HH:mm:ssZ", // date de l'ingest de cette version
"Rank": 1, // quantième de la version
"Size": 10, // taille de l'objet
"FormatIdentification": {
"FormatLitteral": "format Literral",
"MimeType": "mimetype",
"FormatId": "pronomId"
},
"Metadata": { // un parmi tous
"Text": {}, "Document": {}, "Image": {}, "Audio": {}, "Video": {}
},
"OtherMetadata": {
// autres métadonnées non classées
}
}
]
},
"Dissemination": {
// idem à #master
},
"Thumbnail": {
// idem à #master
},
"TextContent": {
// idem à #master
},
}
"#parents": [ "unitParentId", "unitParentId"],
"#childNb": 1 // Nombre de versions d'objets contenus pour tous les usages
}
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...).
De plus, pour le moment, les recherches actuelles retournent uniquement le nombre de versions pour chaque usage (ex : "#qualifiers": { "BinaryMaster": 3, "Dissemination": 1, "Thumbnail": 1, "TextContent": 1 }), mais à l'avenir, il sera possible de retourner le détail de chaque usage (ou de tous les usages), comme indiqué dans l'exemple ci-dessus.
Conventions REST Générales
Ici sont présentées des conventions dans le cadre des API Vitam.
Modèle REST
Les URL sont découpées de la façon suivantes :
- protocole: https
- FQDN : exemple api.vitam.fr avec éventuellement un port spécifique
- Base :
/ - Resource : le nom d'une collection
- L'URL peut contenir d'autres éléments (item, sous-collections)
Exemple: https://api.vitam.fr/access/v1/units/id
Les méthodes utilisées :
- GET: pour l'équivalent de "Select" (possibilité d'utiliser POST avec X-Http-Method-Override: GET dans le Header)
- POST: pour l'équivalent de "Insert"
- PUT: pour l'équivalent de "Update"
- DELETE: pour l'équivalent de "Delete" (possibilité d'utiliser POST avec X-Http-Method-Override: DELETE dans le Header)
- HEAD: pour l'équivalent du "Test d'existence"
- OPTIONS: pour l'équivalent de "Lister les commandes disponibles"
Les codes retours HTTP standards utilisés sont :
- 200: Sur des opérations de GET, PUT, DELETE, HEAD, OPTIONS
- 201: Sur l'opération POST (sans X-Http-Method-Override)
- 202: Pour les réponses asynchrones
- 204: Pour des réponses sans contenu (type HEAD sans options)
- 206: Pour des réponses partielles
Les codes d'erreurs HTTP standards utilisés sont :
- 400: Requête mal formulée
- 401: Requête non autorisée
- 404: Resource non trouvée
- 409: Requête en conflit
- 412: Des préconditions ne sont pas respectées
- 413: La requête dépasse les capacités du service
- 415: Le Media Type demandé n'est pas supporté
- 501: Le service n'est pas implémenté
Modèle asynchrone
Dans le cas d'une opération asynchrone, deux options sont possibles :
Mode Pooling
Dans le mode pooling, le client est responsable de requêter de manière répétée l'URI de vérification du statut, et ce de manière raisonnée (pas trop souvent).
Le principe est le suivant :
- Création de l'opération à effectuer
- Exemple: POST /ingests et retourne 202 + #id
- Pooling sur l'opération demandée
- Exemple: GET /ingests/#id et retourne 202 + #id tant que non terminé
- Intervalle recommandé : pas moins que la minute
- Fin de pooling sur l'opération demandée
- Exemple : GET /ingests/#id et retourne 200 + le résultat
Mode Callback
Dans le mode Callback, le client soumet une création d'opération et simultanément propose une URI de Callback sur laquelle Vitam rappellera le client pour lui indiquer que cette opération est terminée.
Le principe est le suivant :
- Création de l'opération à effectuer avec l'URI de Callback
- Exemple: POST /ingests + dans le Header X-Callback: https://uri?id={id}&status={status} et retourne 202 + #id + Header X-Callback confirmé
- A la fin de l'opération, Vitam rappelle le client avec l'URI de Callback
- Exemple: GET /uri?id=idop&status=OK
- Le client rappelle alors Vitam pour obtenir l'information
- Exemple: GET /ingests/#id et retourne 200 + le résultat
Perspectives d'évolution
Dans le cas où l'accès au résulat final ne doit pas se faire sur l'URI /resources/id, il faudra ajouter une réponse 303.
Authentification
L'authentification dans Vitam authentifie l'application Front-Office qui se connecte à ses API. Cette authentification s'effectue en trois temps :
- Un premier composant authentifie la nouvelle connexion
- La première implémentation sera basée sur une authentification du certificat client dans la connexion TLS
- Le premier composant passe au service REST la variable Header "X-Identity" contenant l'identifiant de l'application Front-Office
- Le service REST, sur la base de cette authentification, s'assure que l'application Front-Office ait bien l'habilitation nécessaire pour effectuer la requête exprimée.
Identifiant de corrélation
Vitam étant un service REST, il est "State Less". Il ne dispose donc pas de notion de session en propre. Cependant chaque requête retourne un identifiant de requête "X-Request-Id" qui est traçé dans les logs et journaux du SAE et permet donc de faire une corrélation avec les événements de l'application Front-Office cliente si celle-ci enregistre elle-aussi cet identifiant.
Considérant que cela peut rendre difficile le suivi d'une session utilisateur connecté sur un Front-Office, il est proposé que l'application Front-Office puisse passé en paramètre dans le Header l'argument "X-Application-Id" correspondant à un identifiant de session de l'utilisateur connecté. Cet identifiant DOIT être non signifiant car il sera lui aussi dans les logs et les journaux de Vitam. Il est inclu dans chaque réponse de Vitam si celui-ci est exprimé dans la requête correspondante. Grâce à cet identifiant externe de session, il est alors plus facile de retracer l'activité d'un utilisateur grâce d'une part au regroupement de l'ensemble des actions dans Vitam au travers de cet identifiant, et d'autre part grâce aux logs de l'application Front-Office utilisant ce même identifiant de session.
Pagination
Vitam ne dispose pas de notion de session en raison de son implémentation « State Less ». Néanmoins, pour des raisons d'optimisations sur des requêtes où le nombre de résultats serait important, il est proposé une option tendant à améliorer les performances : X-Cursor et X-Cursor-Id.
De manière standard, il est possible de paginer les résultats en utilisant le DSL avec les arguments suivants dans la requête : (pour GET uniquement)
- $limit : le nombre maximum d'items retournés (limité à 1000 par défaut, maximum à 100000)
- $per_page : le nombre maximum des premiers items retournés (limité à 100 par défaut, maximum à 100)
- $offset : la position de démarrage dans la liste retournée (positionné à 0 par défaut, maximum à 100000)
En raison du principe State-less, les requêtes suivantes (en manipulant notamment $offset) seront à nouveau exécutées, conduisant à des performances réduites.
Afin d'optimiser, il est proposé d'ajouter de manière optionnelle dans le Header lors de la première requête le champs suivant : X-Cursor: true Si la requête nécessite une pagination (plus d'une page de réponses possible), le SAE répondra alors la première page (dans le Body) et dans le Header :
- X-Cursor-Id: id (identifiant du curseur)
- X-Cursor-Timeout: datetime (date limite de validité du curseur)
Le client peut alors demander les pages suivantes en envoyant simplement une requête GET avec un Body vide et dans le Header : X-Cursor-Id: id.
DSL Vitam
Le DSL (Domain Specific Language) Vitam est composé de deux parties :
- Request: Contient la structure du Body contenant la requête au format Json. Le DSL permet d'exprimer un grand nombre de possibilités de requêtes. Dans le cadre des Units et Objects, cette requête peut être arborescente et multiples.
- Response: Contient la structure du Body contenant le résultat au format Json. Il contient différentes informations utiles ou demandées.
Request
Une requête est composée de plusieurs parties, et en particulier le Body qui contient un Json exprimant la requête.
Elle peut être complétée par quelques valeurs dans le Header :
- X-Application-Id : pour conserver la session (valeur non signifiante) dans les journaux et logs du SAE associés à l'opération demandée
- X-Valid: true : pour une requête HEAD sur un Object pour vérifier la validité (check d'empreinte)
- X-Qualifier et X-Version : pour une requête GET sur un Object pour récupérer un usage et une version particulière
- X-Callback : pour les opérations de longue durée et donc asynchrones pour indiquer l'URL de Callback
- X-Cursor: true et X-Cursor-Id : pour la gestion d'une requête en mode "curseur"
- X-Http-Method-Override : pour permettre aux clients HTTP ne supportant pas tous les modes de la RFC 7231 (GET/PUT/DELETE avec Body)
Units et Objects uniquement
- $roots:
- Il s'agit des racines (Units) à partir desquelles la requête est exprimée (toutes les recherches sur les Units et Objects sont en mode arborescente). Il correspond d'une certaine façon à "FROM x" dans le langage SQL étendu au cas des arborescences.
- Autres collections: ce champ n'existe pas car il n'y a pas d'arborescence.
- $query:
- Il s'agit de la liste des Query successives à exécuter côté Vitam.
- Une Query correspond à la formulation "WHERE xxx" dans le langage SQL, c'est à dire les critères de sélection.
- La succession est exécutée avec la signification suivante :
- Depuis $roots, chercher les Units/Objects tel que Query[1] => liste d'identifiants[1]
- Depuis cette liste d'identifiant, chercher les Units/Objects tel que Query[2] => liste d'identifiants[2]
- Et ainsi de suite, la liste d'identifiants[n] de la dernière Query[n] est la liste de résultat définitive
$filter:
- Il permet de spécifier des filtres additionnels :
- Pour GET :
- $limit: le nombre maximum d'items retournés (limité à 1000 par défaut, maximum à 100000)
- $per_page: le nombre maximum des premiers items retournés (limité à 100 par défaut, maximum à 100)
- $offset: la position de démarrage dans la liste retournée (positionné à 0 par défaut, maximum à 100000)
- $orderby: { fieldname: 1, fieldname: -1 } : permet de définir un tri
- $hint: "nocache" permet de spécifier si l'on ne veut pas bénéficier du cache (cache actif par défaut)
- Pour POST, PUT et DELETE
- $mult: booléen où true signifie que l'opération peut concerner de multiples items (par défaut, positionné à false)
- POST: les pères sélectionnés peuvent être multiples
- PUT: la mise à jour peut concerner de multiples items simultanément
- DELETE: l'effacement peut concerner plusieurs items
- $mult: booléen où true signifie que l'opération peut concerner de multiples items (par défaut, positionné à false)
- Pour GET :
- Il permet de spécifier des filtres additionnels :
$projection: { fieldname: 0, fieldname: 1 } uniquement pour GET
- Il permet de définir la forme du résultat que l'on souhaite. Il correspond au "SELECT *" dans le langage SQL.
- Une valeur à 1 réclame le champ.
- Une valeur à 0 exclut le champ.
- Si rien n'est spécifié, cela correspond à tous les champs (équivalent à "SELECT *")
- $data: uniquement pour POST
- Permet de définir le contenu à insérer dans la collection.
- $action: uniquement pour PUT
- Permet de définir le contenu à modifier dans la collection.
- facetQuery: uniquement pour GET et optionnel
- Permet de définir des sous-requêtes (sous la forme d'agrégats) correspondant généralement à des facettes dans l'application Front-Office
Autres collections
- $query:
- Il s'agit d'une Query unique.
- Une Query correspond à la formulation "WHERE xxx" dans le langage SQL, c'est à dire les critères de sélection.
$filter:
- Il permet de spécifier des filtres additionnels :
- Pour GET :
- $limit: le nombre maximum d'items retournés (limité à 1000 par défaut, maximum à 100000)
- $per_page: le nombre maximum des premiers items retournés (limité à 100 par défaut, maximum à 100)
- $offset: la position de démarrage dans la liste retournée (positionné à 0 par défaut, maximum à 100000)
- $orderby: { fieldname: 1, fieldname: -1 } : permet de définir un tri
- $hint: "nocache" permet de spécifier si l'on ne veut pas bénéficier du cache (cache actif par défaut)
- Pour POST, PUT et DELETE
- $mult: booléen où true signifie que l'opération peut concerner de multiples items (par défaut, positionné à false)
- POST: les pères sélectionnés peuvent être multiples
- PUT: la mise à jour peut concerner de multiples items simultanément
- DELETE: l'effacement peut concerner plusieurs items
- $mult: booléen où true signifie que l'opération peut concerner de multiples items (par défaut, positionné à false)
- Pour GET :
- Il permet de spécifier des filtres additionnels :
$projection: { fieldname: 0, fieldname: 1 } uniquement pour GET
- Il permet de définir la forme du résultat que l'on souhaite. Il correspond au "SELECT *" dans le langage SQL.
- Une valeur à 1 réclame le champ.
- Une valeur à 0 exclut le champ.
- Si rien n'est spécifié, cela correspond à tous les champs (équivalent à "SELECT *")
- $data: uniquement pour POST
- Permet de définir le contenu à insérer dans la collection.
- $action: uniquement pour PUT
- Permet de définir le contenu à modifier dans la collection.
- facetQuery: uniquement pour GET et optionnel
- Permet de définir des sous-requêtes (sous la forme d'agrégats) correspondant généralement à des facettes dans l'application Front-Office
Query
Les commandes de la Query peuvent être :
| Catégorie | Opérateur | Arguments | Commentaire |
|---|---|---|---|
| Accès direct | $path | identifiants | Accès direct à un noeud |
| Booléens | $and, $or, $not | opérateurs | Combinaison logique d'opérateurs |
| Comparaison | $eq, $ne, $lt, $lte, $gt, $gte | Champ et valeur | Comparaison de la valeur d'un champ et la valeur passée en argument |
| $range | Champ, $lt, $lte, $gt, $gte et valeurs | Comparaison de la valeur d'un champ avec l'intervalle passé en argument | |
| Existence | $exists, $missing, $isNull | Champ | Existence d'un champ |
| Tableau | $in, $nin | Champ et valeurs | Présence de valeurs dans un tableau |
| $size | Champ et taille | Taille d'un tableau | |
| [n] | Position (n >= 0) | Élément d'un tableau | |
| Textuel | $term, $wildcard | Champ, mot clef | Comparaison de champs mots-clefs |
| $match, $matchPhrase, $matchPhrasePrefix | Champ, phrase, $max_expansions (optionnel) | Recherche de phrase | |
| $regex | Champ, Expression régulière | Recherche via une expression régulière | |
| $search | Champ, valeur | Recherche du type moteur de recherche | |
| $flt, $mlt | Champ, valeur | Recherche « More Like This » | |
| Géomatique | $geometry, $box, $polygon, $center | Positions | Définition d'une position géographique |
| $geoWithin, $geoIntersects, $near | Une forme | Recherche par rapport à une forme géométrique |
Chaque Query dispose éventuellement d'arguments additionnels pour gérer l'arborescence :
| Catégorie | Opérateur | Arguments | Commentaire |
|---|---|---|---|
| Profondeur | $depth, $exactdepth | + ou - n | Permet de spécifier si la query effectue une recherche vers les racines (-) ou vers les feuilles (+) et de quelle profondeur (n), avec une profondeur relative ($depth) ou exacte ($exactdepth) |
| Collection | $source | units / objects | Permet dans une succession de Query de changer de collection. Attention, la dernière Query doit respecter la collection associée à la requête |
Actions
Dans la commande PUT (Update) :
| Opérateur | Arguments | Commentaire |
|---|---|---|
| $set | nom de champ, valeur | change la valeur du champ |
| $unset | liste de noms de champ | enlève le champ |
| $min, $max | nom de champ, valeur | change la valeur du champ à la valeur minimale/maximale si elle est supérieure/inférieure |
| $inc | nom de champ, valeur | incrémente/décremente la valeur du champ |
| $rename | nom de champ, nouveau nom | change le nom du champ |
| $push, $pull | nom de champ, liste de valeurs | ajoute/retire les éléments de la liste du champ (qui est un tableau) |
| $add, $pop | nom de champ, liste de valeurs | ajoute/retire les éléments de la liste du champ (qui est un "set" avec unicité des valeurs) |
FacetQuery
Lors d'une commande GET (Select), les possibilités envisagées sont :
| Opérateur | Arguments | Commentaire |
|---|---|---|
| $cardinality | nom de champ | indique le nombre de valeurs différentes pour ce champ |
| $avg, $max, $min, $stats | nom de champ numérique | indique la valeur moyenne, maximale, minimale ou l'ensemble des statistiques du champ |
| $percentile | nom de champ numérique, valeurs optionnelles | indique les percentiles de répartition des valeurs du champ, éventuellement selon la répartition des valeurs indiquées |
| $date_histogram | nom de champ, intervalle | indique la répartition selon les dates selon un intervalle définie sous la forme "nX" où n est un nombre et X une lettre parmi y (year), M (month), d(day), h(hour), m(minute), s(seconde) ou encore de la forme "year", "quarter", "month", "week", "day", "hour", "minute" ou "second" |
| $date_range | nom de champ, format, ranges | indique la répartition selon les dates selon un intervalle défini "ranges" : [ { "to": "now-10M/M" }, { "from": "now-10M/M" } ] et "format" : "MM-yyyy" |
| $range | nom de champ, intervalles | indique la répartition selon des valeurs numériques par la forme "ranges" : [ { "to": 50 }, { "from": 50, "to": 100 }, { "from": 100 } ] |
| $terms | nom de champ | indique la répartition selon des valeurs textuelles du champ |
| $significant_terms | nom de champ principal, nom de champ secondaire | indique la répartition selon des valeurs textuelles du champ principal et affiche pour chaque les termes significatifs pour le second champ |
Exemples
GET
- La query sélectionne les Units qui vont être retournées.
- Le contenu est :
- Pour Units/Objects :
- $roots
- $query
- $filter
- $projection: { fieldname: 0, fieldname: 1 }
- facetQuery optionnel
- Pour les autres collections :
- $query
- $filter
- $projection: { fieldname: 0, fieldname: 1 }
- facetQuery optionnel
- Pour Units/Objects :
{
"$roots": [ "id0" ],
"$query": [
{ "$match": { "title": "titre" }, "$depth": 4 }
],
"$filter": { "$limit": 100 },
"$projection": { "$fields": { "#id": 1, "title": 1, "#type": 1, "#sector": 1, "#parents": 1, "#object": 1 } },
"$facetQuery": { "$terms": "#object.#type" }
}
POST
- La query sélectionne le ou les Units parents de celle qui va être créée.
- Le contenu est :
- Pour Units/Objects :
- $roots
- $query
- $filter
- $data
- Pour les autres collections :
- $query
- $filter
- $data
- Pour Units/Objects :
{
"$roots": [ "id0" ],
"$query": [
{ "$match": { "title": "titre" }, "$depth": 4 }
],
"$filter": { },
"$data": { "title": "mytitle", "description": "my description", "value": 1 }
}
PUT
- La query sélectionne les Units sur lesquelles l'update va être réalisé.
- Le contenu est :
- Pour Units/Objects :
- $roots
- $query
- $filter
- $action
- Pour les autres collections :
- $query
- $filter
- $action
- Pour Units/Objects :
{
"$roots": [ "id0" ],
"$query": [
{ "$eq": { "title": "mytitle" }, "$depth": 5 }
],
"$filter": { },
"$action": [{ "$inc": { "value": 10 } }]
}
DELETE
- La query sélectionne les Units sur lesquelles le delete va être réalisé.
- Le contenu est :
- Pour Units/Objects :
- $roots
- $query
- $filter
- Pour les autres collections :
- $query
- $filter
- Pour Units/Objects :
{
"$roots": [ "id0" ],
"$query": [
{ "$match": { "title": "titre" }, "$depth": 4 }
]
}
Response
Une réponse est composée de plusieurs parties :
- $hits:
- limit: le nombre maximum d'items retournés (limité à 1000 par défaut)
- offrset: la position de démarrage dans la liste retournée (positionné à 0 par défaut)
- total: le nombre total potentiel (estimation) des résultats possibles
- size: le nombre réel d'items retournés
- time_out: Vrai si la requête a durée trop longtemps et donc avec un résultat potentiellement partiel
- $context: rapelle la requête exprimée
- $results: contient le résultat de la requête sous forme d'une liste d'items
- $facets: contient le résultat de la partie $facetQuery.
Des champs sont protégés dans les requêtes :
- Il est interdit d'exprimer un champ qui démarre par un '_'
- #id est l'identifiant de l'item
- #all permet de spécifier l'équivalent de "SELECT *"
- #type permet de spécifier le type d'item (Document Type)
- #sector permet de spécifier la filière de l'item
- #parents permet de spécifier la liste des Units parents
- #object permet de spécifier l'objet associé à un Unit (s'il existe)
- Les "qualifiers" disponibles pour les objets :
- PhysicalMaster pour original physique
- BinaryMaster pour conservation
- Dissemination pour la version de diffusion compatible avec un accès rapide et via navigateur
- Thumbnail pour les vignettes pour les affichages en qualité très réduite et très rapide en "prévue"
- TextContent pour la partie native texte (ASCII UTF8)
La réponse dispose également de champs dans le Header :
- FullApiVersion : retourne le numéro précis de la version de l'API en cours d'exécution
- X-Request-Id : pour chaque requête, un unique identifiant est fourni en réponse
- X-Application-Id : pour conserver la session (valeur non signifiante) dans les journaux et logs associés à l'opération demandée
- X-Qualifier et X-Version : pour une requête GET sur un Object pour indiquer un usage et une version particulière
- X-Callback : pour les opérations de longue durée et donc asynchrones pour indiquer l'URL de Callback
- Si X-Cursor: true a été spécifié et si la réponse nécessite l'usage d'un curseur (nombre de réponses > $per_page), le SAE retourne X-Cursor-Id et X-Cursor-Timeout (date de fin de validité du curseur) : pour la gestion d'une requête en mode "curseur" par le client
Exemple Units
{
"$hits": {
"total": 3,
"size": 3,
"offset": 0,
"limit": 100,
"time_out": false
},
"$context": {
"$roots": [ "id0" ],
"$query": [
{ "$match": { "title": "titre" }, "$depth": 4 }
],
"$filter": { "$limit": 100 },
"$projection": { "$fields": { "#id": 1, "title": 1, "#type": 1, "#sector": 1, "#parents": 1, "#object": 1 } },
"$facetQuery": { "$terms": "#object.#type" }
},
"$results": [
{
"#id": "id1", "title": "titre 1", "#type": "DemandeCongés", "#sector": "RessourcesHumaines",
"#parents": [ { "#id": "id4", "#type": "DossierCongés", "#sector": "RessourcesHumaines" } ],
"#object": { "#id": "id101", "#type": "Document",
"#qualifiers": { "BinaryMaster": 5, "Dissemination": 1, "Thumbnail": 1, "TextContent": 1 } }
},
{
"#id": "id2", "title": "titre 2", "#type": "DemandeCongés", "#sector": "RessourcesHumaines",
"#parents": [ { "#id": "id4", "#type": "DossierCongés", "#sector": "RessourcesHumaines" } ],
"#object": { "#id": "id102", "#type": "Document",
"#qualifiers": { "BinaryMaster": 5, "Dissemination": 1, "Thumbnail": 1, "TextContent": 1 } }
},
{
"#id": "id3", "title": "titre 3", "#type": "DemandeCongés", "#sector": "RessourcesHumaines",
"#parents": [ { "#id": "id4", "#type": "DossierCongés", "#sector": "RessourcesHumaines" } ],
"#object": { "#id": "id103", "#type": "Image",
"#qualifiers": { "BinaryMaster": 3, "Dissemination": 1, "Thumbnail": 1, "TextContent": 1 } }
}
],
"$facet": {
"#object.#type": { "Document": 2, "Image": 1 }
}
}
Exemple Objects
{
"$hits": {
"total": 3,
"size": 3,
"offset": 0,
"limit": 100,
"time_out": false
},
"$context": {
"$roots": [ "id0" ],
"$query": [
{ "$match": { "title": "titre" }, "$depth": 4, "$source": "units" },
{ "$eq": { "#type": "Document" }, "$source": "objects" }
],
"$filter": { "$limit": 100 },
"$projection": { "$fields": { "#id": 1, "#qualifiers": 1, "#type": 1, "#parents": 1 } }
},
"$results": [
{
"#id": "id101", "#type": "Document",
"#qualifiers": { "BinaryMaster": 5, "Dissemination": 1, "Thumbnail": 1, "TextContent": 1 },
"#parents": [ { "#id": "id1", "#type": "DemandeCongés", "#sector": "RessourcesHumaines" } ]
},
{
"#id": "id102", "#type": "Document",
"#qualifiers": { "BinaryMaster": 5, "Dissemination": 1, "Thumbnail": 1, "TextContent": 1 },
"#parents": [ { "#id": "id2", "#type": "DemandeCongés", "#sector": "RessourcesHumaines" } ]
},
{
"#id": "id103", "#type": "Document",
"#qualifiers": { "BinaryMaster": 3, "Dissemination": 1, "Thumbnail": 1, "TextContent": 1 },
"#parents": [ { "#id": "id3", "#type": "DemandeCongés", "#sector": "RessourcesHumaines" } ]
}
]
}
Réponse en cas d'erreurs
En cas d'erreur, Vitam retourne un message d'erreur dont le format est :
- httpCode : code erreur Http
- code : code erreur Vitam
- context : contexte de l'erreur
- state : statut en format de message court sous forme de code
- message : statut en format de message court
- description : statut détaillé
- errors : le cas échéant des sous-erreurs associées avec le même format
Exemple de retour en erreur
{
"httpCode": 404,
"code" : 123456,
"context": "ingest",
"state": "Item_Not_Found",
"message": "Item is not found",
"description": "Operation on item xxx cannot be done since item is not found in <<resourcePathName>>",
"errors": [
{ "httpCode": 415,
"code" : 123457,
"context": "ingest",
"state": "Unsupported_Media_Type",
"message": "Unsupported media type detected",
"description": "File xxx has an unsupported media type yyy" },
{ "httpCode": 412,
"code": 123458,
"context": "ingest",
"state": "Precondition_Failed",
"message": "Precondition in error",
"description": "Operation on file xxx cannot continue since precondition is in error" }
]
}
Cas particuliers
HEAD pour test d'existence et validation
La commande HEAD permet de savoir pour un item donné s'il existe (retour 204) ou pas (retour 404).
Si dans le Header est ajoutée la commande X-Valid: true, la commande HEAD vérifie si l'item (Unit ou Object) existe et s'il est conforme (audit de l'item sur la base de son empreinte). S'il n'est pas conforme mais qu'il existe, le retour est 417 (Expectation Failed).
Champs de l'étude Units
Le principe est le suivant:
- Pas de POST (sauf X-Http-Method-Override: GET) ou PUT 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
- 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
- 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 de l'étude Objects
Le principe proposé serait le suivant:
- 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
- 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.
Request that will return results composed of Units
Request that will return results composed of Units. The request is using POST with X-Http-Method-Override: GET
Request that will update a set of Units according to the query and the filter parts. The actions to be applied on the set of Units are specified in the action part of the request.
API qui définit les requêtes pour accéder aux Unités d'archives à partir d'une Unité donnée (racine). 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.
Request that will return results composed of Units
Request that will return results composed of Units. The request is using POST with X-Http-Method-Override: GET
Test the existence of this Unit
Request that will update a set of Units according to the query and the filter parts. The actions to be applied on the set of Units are specified in the action part of the request. In this case this update is to be applied for only one Unit (the one specified in the URI).
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.
Request that will return results composed of Objects (generally 1)
Request that will return results composed of Objects (generally 1). The request is using POST with X-Http-Method-Override: GET
Test the existence of this Object
Objects
API qui définit les requêtes pour accéder aux Objets d'archives. La requête utilise le langage de requête (DSL) de Vitam en entrée et retourne une liste d'Objets d'archives selon le DSL Vitam en cas de succès.
Request that will return results composed of Objects
Request that will return results composed of Objects. The request is using POST with X-Http-Method-Override: GET
API qui définit les requêtes pour accéder aux Objets d'archives à partir d'un Objet d'archives donné (racine). La requête utilise le langage de requête (DSL) de Vitam en entrée et retourne une liste d'Objets d'archives selon le DSL Vitam en cas de succès.
Request that will return results composed of Objects (generally 1)
Request that will return results composed of Objects (generally 1). The request is using POST with X-Http-Method-Override: GET
Test the existence of this Object