API-Vitam Version Alpha - Logbook API documentation version v1
https://api.vitam.gouv.fr/external/v1
API Logbook
L'API de Journalisation propose les points d'entrées et les méthodes pour requêter et récupérer les informations des Journaux.
Notes: actuellement la base URI est external/{version}, cependant, il pourra être envisagé de séparer les ressources par service. On pourrait envisager par exemple un point d'entrée logbooks/{version} tout comme un access/{version}, ce qui permetrait de filtrer sur les uris via des outils largement répendus.
Operations
operations est le point d'entrée pour tous les journaux des opérations réalisées dans Vitam (Journal du Service d'Archivage Electronique).
UnitLifeCycles
unitlifecycles est le point d'entrée pour tous les journaux de cycle de vie des units dans Vitam.
ObjectLifeCycles
objectlifecycles est le point d'entrée pour tous les journaux de cycle de vie des objets dans Vitam.
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).
Operations Logbooks
API d'accès aux Journaux d'opérations (Logbooks Operations). Ce point d'entrée permet de chercher une opération (entrée, audit, élimination, préservation, ...).
La recherche sur cette API retourne pour chaque opération, la première entrée (la création à la date de démarrage de l'opération) et la dernière entrée (dans l'état connu par le journal à la date de la dernière étape de cette opération).
Response model for the listing of Logbook operations
Response model for the listing of Logbook operations
Accès à une opération.
Response model for one Logbook operation item
Response model for one Logbook operation item
API d'accès aux Journaux de cycle de vie des Units. Ce point d'entrée permet de chercher un cycle de vie ayant été impacté par cette opération (pour une entrée les archives ayant été intégrées, pour une élimination les archives ayant été éliminées, ...).
La recherche sur cette API retourne uniquement la première ligne et la dernière connue pour chaque journal du cycle de vie en rapport avec l'opération concernée.
Response model for the listing of Logbook unit life cycles
Response model for the listing of Logbook unit life cycles
Accès à un cycle de vie lié à l'opération en référence (Unit).
Le cycle de vie concerné est retourné complet ou tronqué aux seuls événements liés à l'opération en référence selon l'argument X-Full.
Response model for one Logbook unit life cycle item
Response model for one Logbook unit life cycle item
API d'accès aux Journaux de cycle de vie des Objects. Ce point d'entrée permet de chercher un cycle de vie ayant été impacté par cette opération (pour une entrée les archives ayant été intégrées, pour une élimination les archives ayant été éliminées, ...).
La recherche sur cette API retourne uniquement la première ligne et la dernière connue pour chaque journal du cycle de vie en rapport avec l'opération concernée.
Response model for the listing of Logbook object life cycles
Response model for the listing of Logbook object life cycles
Accès à un cycle de vie lié à l'opération en référence (Object).
Le cycle de vie concerné est retourné complet ou tronqué aux seuls événements liés à l'opération en référence selon l'argument X-Full.
Response model for one Logbook object life cycle item
Response model for one Logbook object life cycle item
Unit Life Cycle Logbook
API d'accès aux Journaux de cycle de vie des Units.
La recherche sur cette API retourne uniquement la première ligne et la dernière connue pour chaque journal du cycle de vie.
Response model for the listing of Logbook unit life cycles
Response model for the listing of Logbook unit life cycles
Accès à un cycle de vie (Unit). Le cycle de vie concerné est retourné complet.
Response model for one Logbook unit life cycle item
Response model for one Logbook unit life cycle item
Object Life Cycle Logbook
API d'accès aux Journaux du Cycle de Vie des archives (Object).
La recherche sur cette API retourne uniquement la première ligne et la dernière connue pour chaque journal du cycle de vie.
Response model for the listing of Logbook object life cycles
Response model for the listing of Logbook object life cycles
Accès à un cycle de vie (Object). Le cycle de vie concerné est retourné complet.
Response model for one Logbook object life cycle item
Response model for one Logbook object life cycle item