Lire et synchroniser les données avec l’API

Utilisez l’API pour consulter les données de Boldo depuis un script ou un autre système. Une synchronisation doit traiter pagination, relations, archives et droits ; une simple liste d’actifs n’exporte pas tout le référentiel.

Effectuer une première lecture

1. Créez une clé pour l’organisation cible, avec les droits de lecture nécessaires.
2. Utilisez https://app.boldo.io/api/v1 en production, ou l’origine de votre environnement Boldo suivie de /api/v1.
3. Envoyez Authorization: Bearer <API_KEY> à chaque requête. La clé sélectionne l’organisation ; n’ajoutez pas son slug à cette URL de base.
4. Lisez GET /metamodel/asset-types et GET /metamodel/relationship-types pour obtenir les vraies clés de types et de propriétés. Chaque type de relation nomme sa source et sa cible, et liste ses propres propriétés dans properties, sous la même forme que celles d’un type d’actif. filter[asset_type_key]={key} ne garde que les types de relations d’un type d’actif ; filter[source_asset_type_key] et filter[target_asset_type_key] filtrent sur un côté.
5. Demandez une petite page d’actifs et contrôlez ses identifiants et champs visibles.

Ajoutez Content-Type: application/json lorsque vous envoyez du JSON. Ne placez pas le secret dans les URL ou les journaux. Les clés comme application sont illustratives : remplacez-les par celles de votre métamodèle.

GET /api/v1/assets?page[number]=1&page[size]=50&filter[asset_type_key]=application&include=total&sort=name
Authorization: Bearer <API_KEY>

Laissez votre bibliothèque HTTP encoder les paramètres. Avec curl, utilisez --globoff ou --get --data-urlencode, car les crochets appartiennent aux noms de paramètres Boldo.

Paginer, filtrer et choisir les formats

Les réponses de liste contiennent data et meta, dont page_number, page_size et has_more. Commencez à la page 1, puis augmentez page[number] jusqu’à obtenir has_more: false. La taille par défaut est 50, le maximum 100. include=total demande le total optionnel pour les actifs et relations.

Les numéros et tailles de page doivent être des entiers positifs dans les limites de la route. Les listes et recherches d’actifs refusent avec HTTP 400 les clés de type d’actif inconnues et les propriétés inconnues des filtres ou du tri. Consultez le métamodèle plutôt que de les deviner.

Les filtres de propriétés et d’attributs système des actifs renvoient HTTP 400 si la valeur est incompatible avec l’opérateur. Par exemple, greater_than exige un nombre ou une date valide. Une liste est refusée lorsque l’opérateur attend une valeur unique.

Les filtres d’égalité GET utilisent filter[champ]=valeur. Une propriété s’écrit properties.<clé>. Séparez les champs de tri par des virgules ; préfixez un champ par - pour un ordre décroissant.

Pour les groupes ET/OU et les comparaisons, utilisez POST /search/assets ou POST /search/relationships. Ces opérations POST lisent les données. Leurs objets de groupe de filtres refusent les champs JSON supplémentaires : respectez la structure documentée. Utilisez les opérateurs de la référence API, comme greater_than_or_equals, sans inventer d’abréviations.

Les horodatages système utilisent ISO 8601 UTC. Les propriétés de date utilisent YYYY-MM-DD. Le texte riche revient en Markdown par défaut ; demandez rich_text_format=plain pour du texte simple. Interprétez les propriétés absentes selon le métamodèle et les droits : leur absence ne prouve pas une valeur stockée vide.

Lire les relations et les archives

Ajoutez include=relationships pour inclure les relations d’un actif. Ajoutez relationships.related_asset pour développer les voisins, ou relationships.related_asset.properties pour leurs propriétés. Cette expansion possède sa propre pagination avec relationships_page[number] et relationships_page[size]. Affinez-la avec relationships_filter[direction], relationships_filter[relationship_type_key] et relationships_sort.

Chaque relation parallèle possède son identifiant. Lisez /relationships ou /relationships/{id} pour ses propriétés et son updated_at. Filtrez cette liste avec source_asset_id, target_asset_id ou asset_id. include=source_asset,target_asset développe les extrémités ; ajoutez .properties à l’extrémité voulue pour ses propriétés.

Par défaut, les listes renvoient les données actives. Pour les actifs, archived=true sélectionne les archives et archived=any les deux états. Un actif non archivé a archived_at: null. Pour les relations, archived=true sélectionne celles archivées indépendamment dont les extrémités restent actives. archived=any inclut aussi les relations archivées avec un actif.

Adressez un actif par UUID ou par type:propriété_unique:valeur. La propriété doit être une clé unique, pas simplement un nom sans doublon actuel. Encodez l’identifiant dans l’URL et choisissez l’option d’archive appropriée pour lire des données archivées.

Une clé unique réutilisée après archivage peut désigner un actif et une archive. Une recherche composite incluant les archives renvoie alors un conflit ; utilisez l’UUID de l’actif voulu. Une extrémité archivée développée peut fournir son identité sans ses valeurs de propriétés.

Préparer la synchronisation incrémentale

Par exemple, envoyez ce corps à POST /search/assets pour lire les changements de contenu depuis un horodatage connu :

{
  "archived": "any",
  "filter": {
    "logic": "and",
    "conditions": [{
      "field": "updated_at",
      "operator": "greater_than_or_equals",
      "value": "2026-09-01T00:00:00.000Z"
    }]
  },
  "sort": [{ "field": "updated_at", "order": "asc" }],
  "page": { "number": 1, "size": 100 },
  "include": ["total"]
}

Traitez toutes les pages et dédupliquez par identifiant. Enregistrez votre point de reprise après traitement réussi. Relisez une période chevauchante au prochain passage pour gérer horodatages égaux et modifications concurrentes. La pagination ne constitue ni un instantané figé ni un curseur de synchronisation.

Traitez les archives à partir de archived_at si nécessaire. Effectuez un passage distinct sur les relations avec archived: "any" et updated_at : lire seulement les propriétés d’actif ne décrit pas leurs relations.

L’horodatage du contenu n’est pas un journal complet

Responsabilité et qualité nécessitent une réconciliation distincte. En particulier, l’attestation et la demande de réattestation ne modifient pas l’horodatage du contenu. Examinez selon votre besoin owned_by_ids, last_attested_at, last_attested_by_id, stale_marked_at, stale_marked_by_id, stale_mark_reason et completion_score. Ces champs de sortie ne sont pas tous disponibles comme filtres : ne déduisez pas un filtre du seul nom retourné. Prévoyez des relectures dédiées ou une réconciliation complète périodique. L’API ne fournit pas de flux recensant les suppressions définitives. Un changement de droits peut également faire disparaître une donnée auparavant visible.

Choisir un scénario

Lisez GET /scenarios, choisissez un scénario accessible avec status: "active" et ready: true, puis ajoutez ?scenario=<ID> à chaque requête compatible. Si des paramètres existent déjà, utilisez &. Son omission sélectionne les données réelles. N’envoyez pas l’en-tête interne x-boldo-scenario : l’API publique le refuse. Consultez les écritures et restrictions en scénario.

Gérer les erreurs et le débit

La limite est de 300 requêtes par 60 secondes par organisation, partagées entre ses clés API. À HTTP 429, respectez Retry-After et retryAfterSeconds ; ajouter des clés ne multiplie pas la limite.

Statut HTTP	Action
400	Corrigez le JSON ou les arguments selon error, message et les éventuels details.
401	Vérifiez la présence et la validité de la clé.
403	Contrôlez droits, appartenance active, offre, IP autorisées et admissibilité du scénario.
404	Vérifiez l’identifiant et la visibilité ; cela ne prouve pas l’inexistence de la ressource.
409	Relisez l’état et résolvez le conflit indiqué avant de répéter une écriture.
429	Attendez le délai retourné et réduisez le débit partagé.
500 ou 503	Conservez l’erreur et l’en-tête de réponse x-request-id pour le diagnostic ; réessayez les lectures avec un délai contrôlé.

Après expiration du délai d’une écriture, relisez l’état avant de réessayer. Une réponse perdue ne prouve pas l’échec de l’écriture.