Explorer la référence API et OpenAPI

La référence interactive présente les opérations API, leurs paramètres et les formats de réponse. Vous pouvez la lire sans clé ; exécuter une opération authentifiée utilise la clé fournie.

Trouver et exécuter une opération

1. Ouvrez Gestion de l’organisation > API > Documentation interactive, ou /api-doc sur votre environnement Boldo.
2. Recherchez une opération et affinez la liste par catégorie, méthode HTTP ou type utilisateur.
3. Cliquez sur S’authentifier, saisissez la clé API de l’organisation cible, puis cliquez à nouveau sur S’authentifier.
4. Ouvrez d’abord une opération de lecture, comme la liste des types d’actifs.
5. Contrôlez le chemin, les paramètres, la réponse attendue et l’exemple généré. Remplacez les valeurs illustratives par de vrais identifiants ou clés.
6. Cliquez sur Execute et examinez la réponse affichée.
7. Pour une écriture, relisez l’objet modifié avant d’enchaîner d’autres opérations.

Utilisez Changer de clé API pour remplacer le secret d’exécution. Être connecté à l’interface Boldo ne remplace pas cette authentification.

Execute envoie une vraie requête

Pour une opération compatible, renseignez le paramètre de requête scenario afin de viser ce scénario. Le laisser vide cible les données réelles. La référence n’est pas une simulation. Les écritures créent, modifient ou archivent les données avec la clé fournie. Vérifiez organisation, scénario et requête complète avant de cliquer sur Execute.

L’assistant IA de requête utilise les droits IA et l’organisation de votre session web. L’exécution API utilise la clé fournie. Vérifiez la correspondance des contextes avant d’exécuter une requête générée. Un exemple généré ne prouve pas l’existence de son type d’actif dans l’organisation de la clé.

Choisir un schéma OpenAPI

Boldo fournit des schémas OpenAPI 3.1 en JSON et YAML. Utilisez l’origine de votre environnement avec ces chemins :

Schéma	Chemins	Accès
Générique	/api/v1/openapi/base.json et /api/v1/openapi/base.yaml	Public ; décrit le contrat général de l’API.
Typé	/api/v1/openapi/typed.json et /api/v1/openapi/typed.yaml	Clé API avec accès Lecteur minimum et offre comprenant l’API.

La référence interactive exige une authentification pour Execute, même sur une opération de schéma public. Les URL du schéma générique restent directement accessibles sans clé.

Le schéma typé décrit le métamodèle de l’organisation, pour les types d’actifs comme pour les types de relations : types de propriétés, valeurs d’énumération, contraintes et propriétés calculées en lecture seule. Les propriétés masquées sont exclues. Régénérez-le après évolution du métamodèle avant de réutiliser d’anciens clients générés ou validations.

Respecter le schéma ne donne pas accès à chaque actif ou domaine. Règles métier et droits effectifs sont vérifiés à l’exécution. Utilisez la gestion des clés pour diagnostiquer ces droits.

Lors de l’import du schéma dans un autre outil, vérifiez l’adresse du serveur. Un exemple localhost dans le schéma ne correspond pas nécessairement au port de votre environnement local. Utilisez l’origine de l’instance Boldo effectivement visée.

Explorer les opérations d’analyse

POST /analytics/assets/aggregate calcule des mesures regroupées. POST /analytics/assets/impact parcourt les chemins de relations configurés. Ces opérations lisent les données, exigent un accès Lecteur minimum et appliquent les droits métier. Leur contexte de scénario compatible utilise le paramètre scenario.

Les deux opérations valident les filtres sur les propriétés et attributs système des actifs. Les clés de types d’actifs ou de propriétés inconnues et les valeurs incompatibles avec leur opérateur renvoient HTTP 400. Consultez la validation des filtres.

Par exemple, cette requête d’impact suit un type de relation sortante sur trois sauts maximum :

{
  "sources": ["application:reference:APP-DEMO-001"],
  "stages": [{
    "relationships": [{
      "relationship_type_key": "depends_on",
      "direction": "outgoing"
    }],
    "max_depth": 3
  }],
  "include": ["paths"],
  "page": { "number": 1, "size": 50 }
}

Remplacez l’identifiant composite de source et la clé de relation par les valeurs de votre organisation. Les parcours se placent dans stages, sans propriété relationships à la racine.

L’API d’impact accepte au maximum 100 sources explicites, cinq étapes et 200 définitions de parcours toutes étapes confondues. Le serveur limite le parcours à 30 sauts ; une page contient au maximum 100 éléments. Les sources dynamiques utilisent source_asset_type_key et source_filter.

target_filter coupe les branches non correspondantes. stop_conditions inclut le nœud atteint mais arrête la propagation. display_filter masque seulement les résultats sans empêcher le parcours ; les intermédiaires masqués peuvent apparaître dans hidden_path_assets.

La pagination concerne les actifs impactés. Sources, relations et résumé décrivent l’analyse complète. Lisez les indicateurs de troncature et de profondeur avant de présenter les chemins comme exhaustifs. Consultez l’analyse d’impact pour comprendre les étapes et filtres dans l’interface.

Maintenir la compatibilité

Utilisez la référence fournie par l’environnement appelé. Actualisez les définitions typées après changement du métamodèle et examinez les réponses lors d’une mise à jour d’intégration. Conservez les noms de paramètres, clés d’énumération et formats propres à chaque opération, sans les traduire en libellés d’interface.

Lors d’une mise à jour d’intégration, vérifiez la structure de la réponse du métamodèle. GET /metamodel retourne deux collections distinctes : asset_types et relationship_types. Les types d’actifs ne contiennent plus de collection relationships imbriquée et la réponse ne fournit plus de bloc roles. Lisez les propriétés d’un type de relation dans sa propre définition. Ces changements de réponse ne retirent pas les contrôles de droits des opérations API.

Les choix de liste de la réponse du métamodèle comprennent une description, éventuellement null, contenant leur texte d’aide. Les styles d’extrémités source_marker et target_marker des relations comprennent aussi open_diamond, open_triangle et open_arrow. Ils décrivent l’apparence et n’imposent aucune cardinalité. Actualisez les intégrations qui valident ces champs avec une liste fixe de valeurs.

Pour construire les requêtes, paginer et reprendre après une erreur, poursuivez avec lecture et synchronisation ou écriture des données.