Migration zur asynchronen API-Referenz, Import und Resynchronisation

Wenn Sie API über die Customer API oder die d360 CLI importieren oder neu synchronisieren, müssen Sie Ihre Integration auf die neuen asynchronen Endpunkte und Befehle verschieben, bevor die alten entfernt werden. Nach der Migration importieren große Spezifikationsdateien ohne Timeouts oder Speicherfehler, und Ihre Pipeline erhält bei jedem Import ein klares Bestehen oder Fehlschlagen.

Dieser Leitfaden führt Sie durch die Migration von Customer API V3, Customer API v2 und der d360 CLI.

Finde heraus, was du zum Migrieren brauchst

Beginne mit der Integration, die du heute nutzt. Jede Zeile führt zu dem Abschnitt, den du brauchst.

Deine aktuellen Endpunkte und Befehle funktionieren weiterhin, sind aber veraltet.

Bevor du anfängst

Bestätigen Sie Folgendes, damit Ihr erster asynchroner Anruf funktioniert:

1. Ihr V3-API-Schlüssel oder Ihre Rolle hat beide Berechtigungen. Das Einreichen erfordert Aktualisierungsartikel. Das Lesen des Ergebnisses erfordert Projekteinstellungen ansehen. Mit nur einer davon können Sie das Ergebnis einreichen, aber nicht lesen, oder umgekehrt. In v2 wird derselbe CI/CD-API-Schlüssel oder API-Token verwendet, um das Ergebnis einzureichen und zu lesen.

2. Du kennst deine regionale Basis-URL.

   Region	Basis-URL
   EU	https://apihub.document360.io
   USA	https://apihub.us.document360.io
   Kanada	https://apihub.ca.document360.io
   Privates Hosting	https://apihub.<your-hosting-name>.document360.io

3. Ihre Spezifikation liegt innerhalb der Größenbegrenzung. Eine Spezifikation kann bis zu 25 MB groß sein, hochgeladen oder von einer URL abgerufen. Die Upload-Anfrage kann bis zu 26 MB betragen. Ein URL-Abruf, der nicht innerhalb von 100 Sekunden abgeschlossen wird, schlägt fehl.

4. Sie haben entschieden, wie Sie mit den Ergebnissen umgehen. Siehe den nächsten Abschnitt.

Entscheide, wie mit den Ergebnissen umgegangen werden soll

Wenn der Zwangsimport deaktiviert ist, wird dein Import oder Neusynchronisieren abgelehnt, wenn die Spezifikation:

• Gibt es irgendeinen Fehler oder eine Warnung.
• Hat keinen servers Eingang.

Der Zwangsimport ist in allen drei Integrationen standardmäßig deaktiviert:

Wenn eine Spezifikation abgelehnt wird, haben Sie zwei Möglichkeiten:

• Korrigiere die Spezifikation. Dies ist die empfohlene Option. Ergebnisse können die generierte Dokumentation beeinflussen. Zum Beispiel wird eine Eigenschaft, die statt von boolean typisiert bool ist, ohne Typ importiert.
• Erzwingen Sie den Import. Senden "force_import": true Sie (V3), forceImport=true (v2), --force-import (apiref submit), oder --force (apidocs:submit). Betrachten Sie dies als bewusste Überschreibung, nicht als Standard.

Wenn deine V3-Skripte auf den alten Standard angewiesen sind, werden sie jetzt abgelehnt, egal ob du migriert hast oder nicht. Korrigiere die Spezifikation oder füge .force_import: true

Die gleiche Bestätigung gilt für eine Neusynchronisation, die Endpunkte entfernen würde. Ohne sie schlägt die Operation mit einer Warnung wie "Dieses Update löscht 19 Endpunkte dauerhaft aus. Übergebe force_import=wahr zum Bestätigen" und listet die Endpunkte in result.deleted_endpointsauf. Nichts wird gelöscht, bis du bestätigt hast.

Wie sich Ihre Integration verändert

Heute wartet Ihr Anruf, bis die gesamte Spezifikation verarbeitet ist und das Ergebnis zurückgegeben wird. Nach der Migration funktioniert Ihre Integration in drei Schritten:

1. Senden Sie den Import ein oder synchronisieren Sie neu. Sie erhalten 202 Accepted sofort eine Operations-ID.
2. Abfrage des Status-Endpunkts mit dieser ID, bis die Operation einen endgültigen Status erreicht.
3. Lesen Sie das Ergebnis, Fehler, Warnungen und die neue API-Referenz-ID aus der finalen Antwort.

Was importiert wird, ändert sich nicht. Die gleiche Spezifikation erzeugt dieselbe API-Referenz. Nur wenn du das Ergebnis bekommst und wo du liest, ändern sich Fehler und Warnungen.

Ein typischer Import ist in wenigen Sekunden bis unter einer Minute fertig. Behandle die Antwort 202 niemals als Erfolg.

Die JSON-Beispiele in diesem Leitfaden sind auf die relevanten Felder gekürzt.

Migration einer Customer API V3-Integration

Authentifiziere dich mit dem X-API-Key: d360_sk_… Header oder einem Inhabertoken mit dem customerApi Scope.

Schritt 1: Ersetzen Sie die Endpunkte

Schritt 2: Den Import einreichen oder neu synchronisieren

Um von einer URL zu importieren:

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>"
      }'

Um aus einer Datei zu importieren, senden multipart/form-dataSie :

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>"

Um eine bestehende API-Referenz neu zu synchronisieren:

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" }'

Eine Neusynchronisation nimmt workspace_idnicht . Sie verwendet den Arbeitsbereich der bestehenden API-Referenz.

Verwenden Sie diese Anfragefelder:

Liefere genau eine von url, file, oder content.

Die Antwort ist 202 Accepted. Speichere das operation_id Feld oder den Header Operation-Location . Beide identifizieren die Operation, die du als Nächstes abrufst.

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
}

Schritt 3: Umfragen, bis die Operation abgeschlossen ist

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

Während die Operation oder runningistqueued, enthält die Antwort einen HeaderRetry-After: 5. Warte so viele Sekunden zwischen den Umfragen. Stoppe das Abfragen, wenn der Status endgültig ist:

Begrenzt deine Umfrage mit einer Auszeit. Zwanzig Minuten sind großzügig für die meisten Spezifikationen. Wenn eine Operation keinen Fortschritt macht, markiert ein Hintergrund-Watchdog sie failed, sodass deine Umfrage immer einen Endstatus erreicht.

Schritt 4: Lesen Sie das Ergebnis

Wenn die Operation erfolgreich ist, speichern result.api_definition_idSie . Dies ist die API-Referenz-ID, die Sie bei späteren Resync-, Publish- und Delete-Aufrufen verwenden.

{
  "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
}

Wenn Ihre Spezifikation Ergebnisse und force_import istfalse, endet die Operation mit failed und listet die Ergebnisse in und result.warningsresult.errors auf. Jede pointer Spezifikation ist ein JSON-Zeiger in Ihre Spezifikation, sodass Sie direkt zur Zeile zur Korrektur gehen können. Der Pfad in diesem Beispiel ist anschaulich.

{
  "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": []
    }
  }
}

Wenn der Job nicht ausgeführt werden konnte, zum Beispiel weil die URL nicht abgerufen werden konnte, message und errors[0].message gib den Grund an:

{
  "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." }
    ]
  }
}

Beispiel: Gatet einen Pipeline-Schritt auf das Importergebnis

Dieses Skript sendet einen Import, wartet auf einen Endstatus und verlässt bei einem Fehler einen von null verschiedenen Code:

#!/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

Migration einer Customer API v2-Integration

Authentifizieren Sie sich mit dem api_token Header. Die asynchronen Endpunkte v2 verwenden dieselben multipart/form-data Felder wie die synchronen, einschließlich der erforderlichen forceImport.

Schritt 1: Ersetzen Sie die Endpunkte

Wenn Sie die CI/CD-Routen direkt mit einem CI/CD-API-Schlüssel aufrufen, ersetzen Sie diese stattdessen. Die Befehle d360 apidocs verwenden dieselben Routen.

Schritt 2: Den Import einreichen oder neu synchronisieren

Zum Import:

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"

Zum Resynchronisieren:

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"

Die Antwort lautet 202 Accepted. Sparen background_task_id Sie die Umfragen.

{
  "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
}

Schritt 3: Umfragen, bis die Arbeit abgeschlossen ist

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

Weiter abfragen, bis data.is_processing .false

Schritt 4: Lesen Sie das Ergebnis

Die endgültige Antwort trägt das Ergebnis. Sparen Sie api_reference_id auf spätere Anrufe.

{
  "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
}

Lesen Sie die Ergebnisse von data.errors, und Warnungen von data.alerts. Für eine Neusynchronisation listet data.deleted_endpoints man die entfernten Endpunkte auf, mit dem method, path, article_id, und title von jedem.

Migrieren Sie die d360 CLI- und CI/CD-Pipelines

Die CLI hat zwei Befehlsfamilien: V3 (apiref) und v2 (apidocs). Bleib innerhalb deiner aktuellen Familie beim Migrieren. Ersetze V3-Befehle durch V3-Befehle und v2-Befehle durch v2-Befehle.

Schritt 1: Upgrade der CLI

Die neuen Befehle erfordern Version 3.0.7 oder neuer.

npm install -g d360@latest
d360 --version

Die alten Befehle (apiref import, apiref resync, apidocs, ) apidocs:resyncsind in --helpmarkiert[DEPRECATED]. Sie hören auf zu funktionieren, wenn die von ihnen aufgerufenen Endpunkte entfernt werden.d360 apidocs:validate wird nicht veraltet.

Schritt 2: Überprüfen Sie, ob Sie die richtige Qualifikation verwenden

Beide Familien lesen denselben D360_API_KEY Variablennamen, erwarten aber jeweils eine andere Zugangsberechtigung. Die Verwendung der falschen ist der häufigste Einrichtungsfehler. Die CLI zeigt dir an, wenn sie die falsche Zugangsberechtigung erkennt.

Die CLI hat keinen interaktiven Login. Sie nimmt den API-Schlüssel aus der zuerst gesetzten Quelle: ein Befehlsflag, eine Umgebungsvariable (D360_API_KEY, D360_PROJECT_ID, D360_BASE_URL), dann die gespeicherte Konfiguration (d360 init, oder d360 config set-key und d360 config set-project-id). In einer Pipeline speichern Sie den Schlüssel in Ihrem CI-Geheimspeicher und geben Sie ihn als Umgebungsvariable weiter. Verwenden Sie die Basis-URL für Ihre Region.

Schritt 3: Ersetze deine Befehle

Wenn du V3-Befehle benutzt

Ersetze beide apiref import und apiref resync durch apiref submit. Die von dir übergebene ID entscheidet über die Operation: --workspace-id importiert, --api-reference-id synchronisiert neu.

Vorher:

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

Nach:

# 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"

Aktualisieren Sie Ihre Flaggen:

Die Flagge --filter nimmt einen Pfad in die Antwortdaten. Verwenden operation_idSie , nicht data.operation_id. Die -o tsv Option druckt die nackte ID aus.

--wait und d360 operations wait verlassen, 0 wenn die Operation erfolgreich ist. Sie verlassen, 1 wenn sie scheitert oder das 20-minütige Wartebudget abgelaufen ist. Eine Budget-Auszeit beendet das Warten, aber die Operation wird nicht abgebrochen.

Wenn du v2 (apidocs) Befehle verwendest

Dies sind die Befehle, die für CI/CD in den API-Referenzpanels hinzufügen und API-Bearbeiten des Portals angezeigt werden. Ersetzen Sie beide apidocs durch apidocs:submitapidocs:resync und lesen Sie das Ergebnis mit apidocs:status. Die Flag-Namen bleiben gleich (camelCase), und Sie behalten den CI/CD-Schlüssel.

Vorher:

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

Nach:

# 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:submitakzeptiert die gleichen Flags wie der alte apidocs Befehl: --apiKey, --userId, , --versionId, --apiReferenceId, --publish--path--forceund --apihubUrl. Es druckt eine Task-ID aus und verlässt es.

apidocs:status nimmt nur --apiKey, plus --apihubUrl für Nicht-EU-Regionen. Sperre deine Pipeline immer auf --wait. Ohne sie meldet der Befehl einmal und verlässt 0 den Job, selbst wenn der Job noch läuft. Mit --wait, pollt er ab, bis der Job abgeschlossen ist, druckt die Ergebnisse (Fehler, Warnungen und alle durch eine Neusynchronisierung entfernten Endpunkte aus und verlässt 1 es, wenn der Job nicht erfolgreich war.

Wenn eine Neusynchronisation Endpunkte löschen würde, stoppt es und listet sie auf. Führe mit erneut aus --force , um es zu bestätigen.

Schritt 4: Aktualisieren Sie Ihre Pipeline

Nutzen Sie einen dieser GitHub-Aktionsschritte als Ausgangspunkt. In beiden Fällen scheitert der Schritt, wenn der Job fehlschlägt, und die Ergebnisse werden im Logbuch veröffentlicht.

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

Beheben Sie häufige Probleme nach der Migration

Die CLI folgt derselben Retry-Regel. Sie versucht keine Absendung nach einer 5xx oder einer abgebrochenen Verbindung erneut. Sie versucht nur eine 429, die abgelehnt wird, bevor die Arbeit beginnt.

Überprüfe deine Migration

Ihre Migration ist abgeschlossen, wenn:

• Jeder Import- und Resync-Aufruf verwendet einen asynchronen Endpunkt oder Befehl.
• Deine Integration liest das Ergebnis vom Statusendpunkt, nicht von der Antwort 202 .
• In V3 verwendet operation_id deine Integration statt und data.id data.status aus der Send-Antwort.
• Deine Integration regelt 409 Conflict das, indem du auf die laufende Aufgabe wartest und es erneut versuchst.
• Du hast gewählt, wie du mit den Ergebnissen umgehst: die Spezifikation korrigieren oder gezielt einstellen force_import: true .
• Dein API-Schlüssel oder deine Rolle kann sowohl Operationen senden als auch lesen.
• Ihre CLI ist auf Version 3.0.7 oder neuer, und jede Familie verwendet ihre eigene Zugangsberechtigung: einen d360_sk_ Schlüssel für apiref, und den CI/CD-Schlüssel für apidocs.
• Deine Pipeline scheitert im Schritt, wenn ein Import oder Resync fehlschlägt.
• Sie haben die Migration abgeschlossen, bevor die alten Endpunkte und Befehle Ende März 2027 entfernt werden.