Migration vers l’importation et la resynchronisation de référence API asynchrone

Si vous importez ou resynchronisez les API via l’API Client ou la d360 CLI, vous devez déplacer votre intégration vers les nouveaux points de terminaison et commandes asynchrones avant que les anciens ne soient supprimés. Après la migration, de gros fichiers de spécification sont importés sans délai ni erreur mémoire, et votre pipeline obtient un résultat clair de réussite ou d’échec pour chaque importation.

Ce guide vous guide dans la migration vers l’API client v3, l’API client v2 et la d360 ligne de cli.

Découvrez ce dont vous avez besoin pour migrer

Commencez par l’intégration que vous utilisez aujourd’hui. Chaque ligne renvoie à la section dont vous avez besoin.

Vos terminaux et commandes actuels fonctionnent toujours, mais ils sont obsolètes.

Avant que tu commences

Confirmez ce qui suit afin que votre premier appel asynchrone fonctionne :

1. Votre clé ou rôle API V3 possède les deux permissions. Soumettre nécessite Mettre à jour les articles. Lire le résultat nécessite Voir les paramètres du projet. Avec un seul d’entre eux, vous pouvez soumettre mais pas lire le résultat, ou inversement. Sur la v2, la même clé API CI/CD ou le même jeton API est utilisé pour soumettre et lire le résultat.

2. Vous connaissez votre URL de base régionale.

   Région	Base URL
   UE	https://apihub.document360.io
   États-Unis	https://apihub.us.document360.io
   Canada	https://apihub.ca.document360.io
   Hébergement privé	https://apihub.<your-hosting-name>.document360.io

3. Votre spécification est dans les limites de taille. Une spécification peut atteindre jusqu’à 25 Mo, téléchargée ou récupérée à partir d’une URL. La requête de téléversement peut atteindre jusqu’à 26 Mo. Une récupération d’URL qui ne se termine pas en 100 secondes échoue.

4. Vous avez décidé comment gérer les résultats. Voir la section suivante.

Décidez comment gérer les découvertes

Lorsque l’importation forcée est désactivée, votre importation ou resynchronisation est refusée si la spécification suivante suit :

• Y a une erreur ou un avertissement.
• Aucune servers entrée.

Force import est désactivé par défaut dans les trois intégrations :

Lorsqu’une spécification est refusée, vous avez deux options :

• Corrigez la spécification. C’est l’option recommandée. Les résultats peuvent affecter la documentation générée. Par exemple, une propriété typée bool au lieu de boolean est importée sans type.
• Force l’importation. Envoyer "force_import": true (V3), forceImport=true (v2), --force-import (apiref submit), ou --force (apidocs:submit). Considérez cela comme un dérogation délibérée, pas comme un défaut.

Si vos scripts V3 dépendaient de l’ancien défaut, ils sont refusés maintenant, que vous ayez migré ou non. Corrigez la spécification ou ajoutez force_import: truela spécification .

La même confirmation s’applique à une resynchronisation qui supprimerait les points de terminaison. Sans cela, l’opération échoue avec un avertissement tel que « Cette mise à jour supprimera définitivement 19 points de terminaison. Pass force_import=true pour confirmer », et liste les points de terminaison dans result.deleted_endpoints. Rien n’est supprimé tant que vous n’avez pas confirmé.

Comment votre intégration évolue

Aujourd’hui, votre appel attend que toute la spécification soit traitée et renvoie le résultat. Après la migration, votre intégration fonctionne en trois étapes :

1. Soumettez l’importation ou la resynchronisation. Vous obtenez 202 Accepted immédiatement un ID d’opération.
2. Interrogez le point de terminaison d’état avec cet ID jusqu’à ce que l’opération atteigne un statut final.
3. Lisez le résultat, les erreurs, les avertissements et le nouvel identifiant de référence API de la réponse finale.

Ce qui est importé ne change pas. La même spécification produit la même référence API. Seulement lorsque vous obtenez le résultat et que l’endroit où vous lisez les erreurs et avertissements changent.

Un import typique se termine en quelques secondes à moins d’une minute. Ne considérez jamais la 202 réponse comme un succès.

Les exemples JSON de ce guide sont résumés aux domaines qui comptent.

Migrer une intégration API client V3

Authentifiez avec l’en-tête X-API-Key: d360_sk_… , ou un jeton porteur avec la customerApi lunette.

Étape 1 : Remplacer les points d’extrémité

Étape 2 : Soumettre l’importation ou la resynchronisation

Pour importer depuis une URL :

curl -i -X POST "https://apihub.document360.io/v3/projects/$PROJECT_ID/api-references/imports" \
  -H "X-API-Key: $D360_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://api.example.com/openapi.json",
        "workspace_id": "<workspace-id>"
      }'

Pour importer depuis un fichier, envoyez multipart/form-data:

curl -i -X POST "https://apihub.document360.io/v3/projects/$PROJECT_ID/api-references/imports" \
  -H "X-API-Key: $D360_API_KEY" \
  -F "file=@openapi.json;type=application/json" \
  -F "workspace_id=<workspace-id>"

Pour resynchroniser une référence d’API existante :

curl -i -X POST "https://apihub.document360.io/v3/projects/$PROJECT_ID/api-references/$API_REFERENCE_ID/resyncs" \
  -H "X-API-Key: $D360_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://api.example.com/openapi.json" }'

Une resynchronisation ne prend workspace_idpas . Elle utilise l’espace de travail de la référence API existante.

Utilisez ces champs de requête :

Fournissez exactement un de url, file, ou content.

La réponse est 202 Accepted. Sauvegardez le operation_id champ ou l’en-tête Operation-Location . Les deux identifient l’opération que vous interrogez ensuite.

Operation-Location: https://apihub.document360.io/v3/projects/{projectId}/operations/{operationId}

{
  "data": {
    "id": null,
    "status": null,
    "operation_id": "4da2313e-b2da-440f-b4be-a1632901f2eb",
    "operation_status": "queued"
  },
  "success": true
}

Étape 3 : Interroger jusqu’à la fin de l’opération

curl -sS "https://apihub.document360.io/v3/projects/$PROJECT_ID/operations/$OPERATION_ID" \
  -H "X-API-Key: $D360_API_KEY"

Tant que l’opération est queued ou running, la réponse inclut un Retry-After: 5 en-tête. Attendez autant de secondes entre les sondages. Arrêtez le sondage lorsque le statut est final :

Limitez votre sondage par un temps mort. Vingt minutes sont généreuses pour la plupart des spécifications. Si une opération cesse de progresser, un agent de surveillance de fond la failedmarque, afin que votre sondage atteigne toujours un statut final.

Étape 4 : Lisez le résultat

Lorsque l’opération réussit, enregistrez result.api_definition_id. C’est l’identifiant de référence API que vous utilisez lors des appels de resynchronisation, publication et suppression ultérieurs.

{
  "data": {
    "id": "4da2313e-b2da-440f-b4be-a1632901f2eb",
    "operation_type": "import-api-reference",
    "status": "succeeded",
    "message": null,
    "result": {
      "api_definition_id": "f9af5181-ee76-489d-b6c9-306e9eb6d60a",
      "is_success": true,
      "articles_created": 19,
      "categories_created": 3,
      "errors": null,
      "warnings": null,
      "is_server_available": true,
      "show_spec_file_warning": false,
      "deleted_endpoints": null
    },
    "errors": null,
    "created_at": "2026-10-05T10:02:25.33Z",
    "updated_at": "2026-10-05T10:02:30.866Z",
    "completed_at": "2026-10-05T10:02:30.866Z"
  },
  "success": true
}

Si votre spécification contient des résultats et force_import est false, l’opération se termine comme failed et liste les résultats dans result.errors et result.warnings. Chacun pointer est un pointeur JSON vers votre spécification, vous pouvez donc aller directement à la ligne pour corriger. Le chemin dans cet exemple est illustratif.

{
  "data": {
    "status": "failed",
    "message": "The operation failed.",
    "result": {
      "is_success": false,
      "errors": [
        {
          "message": "Invalid schema type identifier: bool",
          "pointer": "#/paths/~1orders/get/responses/200/content/application~1json/schema/properties/active/type"
        }
      ],
      "warnings": []
    }
  }
}

Si la tâche ne pouvait pas s’exécuter, par exemple parce que l’URL ne pouvait pas être récupérée, message et errors[0].message donner la raison :

{
  "data": {
    "status": "failed",
    "message": "This operation can't be completed. Please ensure that you have given a valid specification URL.",
    "result": null,
    "errors": [
      { "code": "OPERATION_FAILED", "message": "This operation can't be completed. Please ensure that you have given a valid specification URL." }
    ]
  }
}

Exemple : Faire un gate d’une étape pipeline sur le résultat d’importation

Ce script soumet une importation, attend un statut final, puis sort avec un code non nul en cas d’échec :

#!/usr/bin/env bash
set -euo pipefail

BASE="https://apihub.document360.io"
H=(-H "X-API-Key: $D360_API_KEY")

# 1. Submit and capture the status URL from the Operation-Location header
OP_URL=$(curl -sS -D - -o /dev/null -X POST \
  "$BASE/v3/projects/$PROJECT_ID/api-references/imports" "${H[@]}" \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"$SPEC_URL\",\"workspace_id\":\"$WORKSPACE_ID\"}" \
  | awk 'tolower($1)=="operation-location:" {print $2}' | tr -d '\r')

[ -n "$OP_URL" ] || { echo "Submission was not accepted" >&2; exit 1; }

# 2. Poll until a final status (capped at 20 minutes)
for _ in $(seq 1 240); do
  BODY=$(curl -sS "$OP_URL" "${H[@]}")
  STATUS=$(echo "$BODY" | jq -r '.data.status')
  case "$STATUS" in
    queued|running) sleep 5 ;;
    succeeded)      echo "$BODY" | jq '.data.result'; exit 0 ;;
    *)              echo "$BODY" | jq '.data.message, .data.result.errors, .data.result.warnings' >&2; exit 1 ;;
  esac
done
echo "Timed out waiting for the operation" >&2
exit 1

Migrer une intégration API client v2

Authentifier avec l’en-têteapi_token. Les extrémités asynchrones v2 prennent les mêmes multipart/form-data champs que les synchrones, y compris le .forceImport

Étape 1 : Remplacer les points d’extrémité

Si vous appelez directement les routes CI/CD avec une clé API CI/CD, remplacez-les à la place. Les d360 apidocs commandes utilisent les mêmes routes.

Étape 2 : Soumettre l’importation ou la resynchronisation

Pour importer :

curl -i -X POST "https://apihub.document360.io/v2/APIReferences/jobs" \
  -H "api_token: $D360_API_TOKEN" \
  -F "url=https://api.example.com/openapi.json" \
  -F "projectVersionId=<workspace-id>" \
  -F "userId=<user-id>" \
  -F "forceImport=false"

Pour resynchroniser :

curl -i -X PUT "https://apihub.document360.io/v2/APIReferences/jobs" \
  -H "api_token: $D360_API_TOKEN" \
  -F "url=https://api.example.com/openapi.json" \
  -F "apiReferenceId=<api-reference-id>" \
  -F "projectVersionId=<workspace-id>" \
  -F "userId=<user-id>" \
  -F "forceImport=false"

La réponse est 202 Accepted. Sauf background_task_id pour les sondages.

{
  "data": {
    "background_task_id": "c02535d8-f051-41d3-92a9-57a224022f7d",
    "is_processing": true,
    "alerts": [{ "message": "Accepted for processing. Poll /v2/apireferences/jobs/c02535d8-… for the result." }]
  },
  "success": true
}

Étape 3 : Interroger jusqu’à la fin du travail

curl -sS "https://apihub.document360.io/v2/APIReferences/jobs/$BACKGROUND_TASK_ID" \
  -H "api_token: $D360_API_TOKEN"

Continuez à sonder jusqu’à ce que data.is_processing soit false.

Étape 4 : Lisez le résultat

La réponse finale porte le résultat. Sauf api_reference_id pour les appels ultérieurs.

{
  "data": {
    "api_reference_id": "b8e74ec5-7de3-4d4b-8cbc-b2945f7aeb56",
    "articles_created": 19,
    "categories_created": 3,
    "errors": [],
    "alerts": [],
    "background_task_id": "c02535d8-f051-41d3-92a9-57a224022f7d",
    "is_processing": false
  },
  "success": true
}

Lisez les résultats de data.errors, et les avertissements de data.alerts. Pour une resynchronisation, data.deleted_endpoints liste les points de terminaison qui ont été supprimés, avec les method, path, article_id, et title de chacun.

Migrer les pipelines CLI et CI/CD du d360

Le CLI a deux familles de commandes : V3 (apiref) et v2 (apidocs). Restez dans votre famille actuelle lors de la migration. Remplacez les commandes V3 par des commandes V3, et les commandes v2 par des commandes v2.

Étape 1 : Mettre à jour le CLI

Les nouvelles commandes nécessitent la version 3.0.7 ou ultérieure.

npm install -g d360@latest
d360 --version

Les anciennes commandes (apiref import, apiref resync, apidocs, apidocs:resync) sont marquées [DEPRECATED] dans --help. Elles cessent de fonctionner lorsque les points de terminaison qu’elles appellent sont supprimés. d360 apidocs:validate n’est pas obsolète.

Étape 2 : Vérifiez que vous utilisez la bonne certification

Les deux familles lisent le même D360_API_KEY nom de variable, mais chacune attend une identification différente. Utiliser la mauvaise est l’erreur de configuration la plus courante. La CLI vous indique quand elle détecte la mauvaise identifiante.

La ligne de commande n’a pas de connexion interactive. Elle prend la clé API de la première source qui est définie : un drapeau de commande, une variable d’environnement (D360_API_KEY, D360_PROJECT_ID, D360_BASE_URL), puis la configuration enregistrée (d360 init, ou d360 config set-key et d360 config set-project-id). Dans un pipeline, stockez la clé dans votre mémoire secrète CI et passez-la comme variable d’environnement. Utilisez l’URL de base de votre région.

Étape 3 : Remplacez vos commandes

Si vous utilisez les commandes V3

Remplacez les deux apiref import et apiref resync par apiref submit. L’ID que vous passez décide de l’opération : --workspace-id importe, --api-reference-id resynchronise.

Avant :

d360 apiref import --workspace-id <workspace-id> --url https://api.example.com/openapi.json
d360 apiref resync --api-reference-id <api-reference-id> --url https://api.example.com/openapi.json

Après :

# Import a new API reference and wait for the result
d360 apiref submit --workspace-id <workspace-id> --url https://api.example.com/openapi.json --wait

# Resync an existing API reference from a local file and wait
d360 apiref submit --api-reference-id <api-reference-id> --file ./openapi.json --wait

# Submit now and poll separately, for example from another pipeline stage
id=$(d360 apiref submit --workspace-id <workspace-id> --file ./openapi.json \
       --filter operation_id -o tsv)
d360 operations wait "$id"

Mettez à jour vos drapeaux :

Le --filter drapeau emprunte un chemin vers les données de réponse. Utilisez operation_id, non data.operation_id. L’option -o tsv affiche l’identifiant nu.

--wait et d360 operations wait quittent 0 l’opération lorsque l’opération réussit. Ils quittent 1 quand elle échoue ou si le budget d’attente de 20 minutes est épuisé. Un délai budgétaire cesse d’attendre mais n’annule pas l’opération.

Si vous utilisez des commandes v2 (apidocs)

Ce sont les commandes affichées pour CI/CD dans les panneaux de référence Ajouter une API et Modifier l’API du portail. Remplacez les deux apidocs et apidocs:resync par apidocs:submit, puis lisez le résultat par apidocs:status. Les noms des drapeaux restent les mêmes (camelCase), et vous conservez la clé CI/CD.

Avant :

d360 apidocs --apiKey "$D360_CICD_KEY" --userId <user-id> --versionId <workspace-id> \
  --path ./openapi.json

d360 apidocs:resync --apiKey "$D360_CICD_KEY" --userId <user-id> \
  --apiReferenceId <api-reference-id> --path ./openapi.json

Après :

# Import (prints the task ID on its own line)
d360 apidocs:submit --apiKey "$D360_CICD_KEY" --userId <user-id> --versionId <workspace-id> \
  --path ./openapi.json

# Resync (passing --apiReferenceId makes it a resync)
d360 apidocs:submit --apiKey "$D360_CICD_KEY" --userId <user-id> \
  --apiReferenceId <api-reference-id> --path ./openapi.json

# Wait for the job to finish
d360 apidocs:status <task-id> --apiKey "$D360_CICD_KEY" --wait

apidocs:submit accepte les mêmes indicateurs que l’ancienne apidocs commande : --apiKey, --userId, --versionId, --apiReferenceId, --path, --force, , --publish, , et --apihubUrl. Elle affiche un identifiant de tâche et quitte la commande.

apidocs:status ne prend que --apiKey, plus --apihubUrl pour les régions hors UE. Verrouillez toujours votre pipeline sur --wait. Sans cela, la commande rapporte une fois et sort 0 même si le travail est toujours en cours. Avec --wait, elle interroge jusqu’à la fin du travail, imprime les résultats (erreurs, alertes et tous les points de terminaison supprimés par une resynchronisation), et sort 1 si le travail n’a pas réussi.

Si une resynchronisation supprime les points de terminaison, il s’arrête et les liste. Relance avec --force pour confirmer.

Étape 4 : Mettez à jour votre pipeline

Utilisez l’une de ces étapes GitHub Actions comme point de départ. Dans les deux, l’étape échoue lorsque la tâche échoue, et les résultats sont imprimés dans le journal.

V3 :

- name: Publish API reference (V3)
  env:
    D360_API_KEY: ${{ secrets.D360_API_KEY }}          # a d360_sk_ key
    D360_PROJECT_ID: ${{ vars.D360_PROJECT_ID }}
  run: |
    npm install -g d360@latest
    d360 apiref submit --api-reference-id "${{ vars.D360_API_REFERENCE_ID }}" \
      --file ./openapi.json --wait

v2 (apidocs) :

- name: Publish API reference (v2)
  env:
    D360_CICD_KEY: ${{ secrets.D360_CICD_KEY }}         # the project's CI/CD key
  run: |
    npm install -g d360@latest
    task=$(d360 apidocs:submit --apiKey "$D360_CICD_KEY" --userId "${{ vars.D360_USER_ID }}" \
             --apiReferenceId "${{ vars.D360_API_REFERENCE_ID }}" --path ./openapi.json)
    d360 apidocs:status "$task" --apiKey "$D360_CICD_KEY" --wait

Corrigez les problèmes courants après la migration

Le CLI suit la même règle de réessayage. Il ne réessaie pas une soumission après une 5xx ou une connexion coupée. Il ne fait qu’essayer un 429, qui est rejeté avant que tout travail ne commence.

Vérifiez votre migration

Votre migration est terminée lorsque :

• Chaque appel d’importation et de resynchronisation utilise un point d’extrémité ou une commande asynchrone.
• Votre intégration lit le résultat du point de terminaison d’état, pas de la 202 réponse.
• Sur la version 3, votre intégration utilise operation_id la réponse de soumission au lieu de data.id et data.status de de.
• Votre intégration se 409 Conflict fait en attendant la tâche en cours et en réessayant.
• Vous avez choisi comment gérer les résultats : corriger la spécification, ou fixer force_import: true délibérément.
• Votre clé API ou votre rôle peut à la fois soumettre et lire des opérations.
• Votre CLI est sur la version 3.0.7 ou ultérieure, et chaque famille utilise son propre identifiant : une d360_sk_ clé pour apiref, et la clé CI/CD pour apidocs.
• Votre pipeline échoue à l’étape lorsqu’une importation ou une resynchronisation échoue.
• Vous avez terminé la migration avant que les anciens terminaux et commandes ne soient supprimés fin mars 2027.