Créer et modifier des données avec l’API
Les écritures API modifient le référentiel dès leur réussite. Votre clé nécessite un type effectif Éditeur ou supérieur, les droits métier correspondants et la capacité disponible dans l’offre.
Préparer et vérifier une écriture
- Vérifiez l’organisation de la clé, ses droits effectifs et le contexte souhaité : réel ou scénario.
- Lisez le métamodèle pour identifier clés de propriétés, formats de valeurs et sens de relations autorisés.
- Relisez l’objet cible et préparez uniquement les champs à changer.
- Envoyez la requête avec l’authentification Bearer et
Content-Type: application/json. - Contrôlez le statut HTTP et le résultat, puis relisez l’actif et les relations concernées.
Les chemins ci-dessous suivent /api/v1. Les clés d’exemple application, reference, depends_on et weight doivent exister dans votre métamodèle. Les propriétés calculées sont en lecture seule. Les propriétaires transmis doivent être des membres actifs.
Créer ou mettre à jour un actif
Envoyez cet exemple à POST /assets :
{
"asset_type_key": "application",
"name": "Application démo",
"properties": { "reference": "APP-DEMO-001" },
"on_conflict": "update"
}
Une propriété de clé unique permet de retrouver un actif existant ; son nom seul ne suffit pas. on_conflict règle le comportement quand cette clé existe déjà :
| Valeur | Effet |
|---|---|
error (par défaut) | Refuser le conflit. |
update | Fusionner les champs transmis ; restaurer d’abord une correspondance archivée. |
ignore | Conserver le contenu de l’actif existant ; attest: true l’atteste quand même. |
Contrôlez data.id et data.action : created, updated, restored ou unchanged. Une création renvoie 201 ; les autres réussites renvoient 200. Des propriétés uniques désignant plusieurs actifs différents provoquent conflicting_unique_keys.
Utilisez PATCH /assets/{id} pour une modification ciblée. Les champs omis restent inchangés et properties est partiel. Par exemple :
{
"properties": { "description": null },
"owned_by_ids": []
}
Cela efface la description et retire tous les propriétaires. Omettre owned_by_ids les conserve. access_domain_keys remplace également la liste transmise. Une propriété null est acceptée pour effacer en PATCH, mais pas dans le schéma de création. Les validations du métamodèle restent applicables.
Ajouter ou synchroniser des relations
Pour ajouter une relation indépendamment, utilisez POST /relationships :
{
"source_asset_id": "application:reference:APP-DEMO-001",
"target_asset_id": "application:reference:APP-DEMO-002",
"relationship_type_key": "depends_on",
"properties": { "weight": 25 }
}
Le type doit autoriser les propriétés de relation et vos droits doivent permettre l’opération. GET /metamodel/relationship-types/{key} donne les clés de propriétés dans properties, vide si le type n’a pas de propriétés. Cette route refuse une relation vers soi-même. Pour modifier seulement les propriétés, utilisez PATCH /relationships/{id} ; ses extrémités restent inchangées.
allow_duplicate: true permet une relation parallèle uniquement si son type l’autorise. Au moins une propriété non calculée doit différer, valeurs par défaut comprises ; sinon identical_relationship_already_exists renvoie 409. Dans une requête groupée, ses indexes désignent les éléments concernés. Ne combinez pas allow_duplicate: true avec on_conflict: "update" ou "ignore". Contrôlez l’identifiant de chaque instance plutôt que de considérer la paire d’extrémités comme unique.
Un PATCH d’actif peut aussi synchroniser un groupe entier de relations :
{
"relationships": [{
"direction": "outgoing",
"relationship_type_key": "depends_on",
"related_assets": [{
"related_asset_id": "application:reference:APP-DEMO-002"
}]
}]
}
Le groupe direction/type transmis est synchronisé avec les cibles listées. Les cibles existantes omises peuvent être archivées, selon vos droits. related_assets: [] demande un groupe vide. Les groupes omis restent inchangés ; relationships: [] ne vide pas toutes les relations. Utilisez la création indépendante pour simplement ajouter un lien.
Archiver, restaurer et attester
| Action | Requête |
|---|---|
| Archiver un actif | DELETE /assets/{id} |
| Restaurer un actif | POST /assets/{id}/restore |
| Attester un actif | POST /assets/{id}/attest |
| Archiver une relation | DELETE /relationships/{id} |
| Restaurer une relation | POST /relationships/{id}/restore |
DELETE archive l’objet ; ce n’est pas une suppression définitive. Archiver un actif désactive ses relations attachées. La restauration renvoie restored_relationship_ids ; seules les relations admissibles sont restaurées. Si un lien manque, vérifiez son autre extrémité et son état d’archive.
Restaurer un actif déjà actif par POST /assets/{id}/restore renvoie HTTP 409 avec asset_already_active. Dans un lot, il figure dans data.skipped avec le motif already_active.
L’attestation exige le suivi qualité actif et un titulaire de clé propriétaire de l’actif. Elle fonctionne uniquement dans les données réelles. attest: true à la création unitaire ou en lot demande une attestation après écriture. Les prérequis sont contrôlés, mais contenu et attestation ne constituent pas une opération indivisible garantie. Relisez les deux après un échec.
Traiter un lot
Créez ou modifiez par POST ou PATCH sur /bulk/assets et /bulk/relationships, jusqu’à 10 000 entrées par requête. Consultez la référence pour le schéma de chaque méthode. La création d’actifs utilise un tableau assets et éventuellement on_conflict à la racine. client_ref rapproche une réponse de sa ligne d’entrée ; ce n’est pas une clé unique métier.
Contrairement à la création unitaire, POST /bulk/assets n’accepte pas relationships dans ses entrées d’actifs. Créez ces liens séparément ou utilisez ensuite un PATCH compatible.
La création de relations en lot utilise source, target et direction, contrairement à la route unitaire :
{
"relationships": [{
"source": "application:reference:APP-DEMO-001",
"target": "application:reference:APP-DEMO-002",
"direction": "outgoing",
"relationship_type_key": "depends_on",
"properties": { "weight": 25 }
}]
}
Les lots de cycle de vie ont des limites inférieures. POST /bulk/assets/archive, /bulk/assets/restore et /bulk/assets/attest acceptent un tableau ids de 500 éléments maximum. POST /bulk/relationships/archive et /bulk/relationships/restore en acceptent 200 maximum.
Ces requêtes renvoient data.applied et data.skipped, avec un motif pour chaque identifiant ignoré. Selon l’action : not_found, forbidden, already_archived, already_active ou not_owner. HTTP 200 ne signifie pas que toutes les entrées sont appliquées. Une erreur globale ou un identifiant ambigu peut toujours faire échouer la requête. Ce format de résultat partiel ne s’étend pas automatiquement à toutes les opérations en lot.
Travailler dans un scénario
Lisez GET /scenarios et choisissez un scénario accessible, actif et prêt. Ajoutez ?scenario=<ID> à chaque requête compatible ; son omission cible le réel. Contrôlez le contexte obtenu avant d’écrire. L’en-tête x-boldo-scenario est refusé.
Dans la référence interactive, renseignez le paramètre de requête scenario d’une opération compatible avant de l’exécuter. Le scénario courant dans Boldo ne remplit pas automatiquement ce paramètre. Le laisser vide écrit dans les données réelles.
Les actifs, relations et leurs lectures ou écritures compatibles acceptent le contexte de scénario. L’attestation, y compris attest: true, ne l’accepte pas. L’administration d’organisation et OpenAPI typé ne sont pas des opérations de scénario. L’API publique v1 ne propose pas de créer, appliquer ou abandonner un scénario ; utilisez l’interface des scénarios.
Après un échec ou un délai dépassé, conservez la réponse et x-request-id, puis inspectez l’état avant de répéter l’opération. Suivez les conseils sur les erreurs et le débit.