Migreren naar asynchrone API-referentie import en hersynchronisatie

Als je API importeert of opnieuw synchroniseert via de Customer API of de d360 CLI, moet je je integratie verplaatsen naar de nieuwe asynchrone endpoints en commando's voordat de oude worden verwijderd. Na de migratie importeren grote specificatiebestanden zonder time-outs of geheugenfouten, en je pipeline krijgt een clear pass or fail resultaat voor elke import.

Deze gids leidt je door de migratie voor Customer API V3, Customer API v2 en de d360 CLI.

Ontdek wat je nodig hebt om te migreren

Begin met de integratie die je vandaag gebruikt. Elke rij linkt naar de sectie die je nodig hebt.

Je huidige endpoints en commando's werken nog steeds, maar ze zijn verouderd.

Voordat je begint

Bevestig het volgende zodat je eerste asynchrone oproep werkt:

1. Je V3 API-sleutel of rol heeft beide rechten. Indienen vereist Bijwerken artikelen. Het lezen van het resultaat vereist projectinstellingen. Met slechts één daarvan kun je het resultaat indienen maar niet lezen, of omgekeerd. Op v2 wordt dezelfde CI/CD API-sleutel of API-token gebruikt om het resultaat in te dienen en te lezen.

2. Je kent je regionale basis-URL.

   Regio	Basis-URL
   EU	https://apihub.document360.io
   VS	https://apihub.us.document360.io
   Canada	https://apihub.ca.document360.io
   Privéhosting	https://apihub.<your-hosting-name>.document360.io

3. Je specificatie valt binnen de groottelimieten. Een specificatie kan tot 25 MB zijn, geüpload of opgehaald van een URL. Het uploadverzoek kan tot 26 MB zijn. Een URL-ophalen die niet binnen 100 seconden voltooid is, faalt.

4. Je hebt besloten hoe je met de bevindingen omgaat. Zie de volgende sectie.

Bepaal hoe je met bevindingen omgaat

Wanneer geforceerde import uit staat, wordt je import of resync geweigerd als de specificatie:

• Er is een fout of waarschuwing.
• Heeft geen servers ingang.

Force import staat standaard uit in alle drie de integraties:

Wanneer een specificatie wordt geweigerd, heb je twee opties:

• Herstel de specificatie. Dit is de aanbevolen optie. Bevindingen kunnen de gegenereerde documentatie beïnvloeden. Bijvoorbeeld, een eigenschap die in plaats van boolean is getypeerdbool, wordt geïmporteerd zonder een type.
• Forceer de import. Stuur "force_import": true (V3), forceImport=true (v2), --force-import (apiref submit), of --force (apidocs:submit). Behandel dit als een bewuste override, niet als een standaard.

Als je V3-scripts op de oude standaard vertrouwden, worden ze nu geweigerd, ongeacht of je bent gemigreerd of niet. Herstel de specificatie of voeg force_import: true.

Dezelfde bevestiging geldt voor een hersynchronisatie die eindpunten verwijdert. Zonder deze bevestiging mislukt de operatie met een waarschuwing zoals "Deze update verwijdert permanent 19 eindpunten. Geef force_import=waar om te bevestigen" en vermeldt de eindpunten in result.deleted_endpoints. Niets wordt verwijderd totdat je bevestigt.

Hoe je integratie verandert

Vandaag wacht je oproep tot de volledige specificatie is verwerkt en geeft het resultaat terug. Nadat je hebt gemigreerd, werkt je integratie in drie stappen:

1. Dien de import in of resync. Je krijgt 202 Accepted direct een operatie-ID.
2. Poll het status-eindpunt met die ID totdat de bewerking een definitieve status bereikt.
3. Lees het resultaat, fouten, waarschuwingen en de nieuwe API-referentie-ID uit de uiteindelijke reactie.

Wat geïmporteerd wordt, verandert niet. Dezelfde specificatie produceert dezelfde API-referentie. Alleen wanneer je het resultaat krijgt en waar je leest , veranderen fouten en waarschuwingen.

Een typische import is binnen enkele seconden tot minder dan een minuut klaar. Beschouw de 202 reactie nooit als succes.

De JSON-voorbeelden in deze gids zijn ingekort tot de velden die ertoe doen.

Migrate a Customer API V3 integratie

Authenticeer met de X-API-Key: d360_sk_… header, of een bearer-token met de customerApi scope.

Stap 1: Vervang de eindpunten

Stap 2: Dien de import in of synchroniseer opnieuw

Om te importeren vanaf een 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>"
      }'

Om uit een bestand te importeren, stuur 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>"

Om een bestaande API-referentie opnieuw te synchroniseren:

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

Een hersynchronisatie neemt workspace_idgeen . Het gebruikt de werkruimte van de bestaande API-referentie.

Gebruik deze verzoekvelden:

Geef precies één van url, file, of content.

Het antwoord is 202 Accepted. Sla het operation_id veld of de Operation-Location header op. Beide identificeren de operatie die je als volgende pollt.

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
}

Stap 3: Peil tot de operatie is afgerond

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

Terwijl de bewerking queued of runningis, bevat de respons een Retry-After: 5 header. Wacht dat aantal seconden tussen polls. Stop pollen wanneer de status definitief is:

Beperk je polling met een timeout. Twintig minuten is gul voor de meeste specificaties. Als een operatie stopt met voortgang, markeert een achtergrondwatchdog het failed, zodat je poll altijd een definitieve status bereikt.

Stap 4: Lees het resultaat

Wanneer de operatie slaagt, sla result.api_definition_iddan op. Dit is de API-referentie-ID die je gebruikt bij latere hersynchronisatie-, publiceer- en verwijderingsaanroepen.

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

Als je specificatie bevindingen heeft en force_import is false, eindigt de bewerking als failed en vermeldt de bevindingen in result.errors en result.warnings. Elke pointer is een JSON-pointer in je specificatie, zodat je direct naar de lijn kunt gaan om te fixen. Het pad in dit voorbeeld is illustratief.

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

Als de taak niet kon draaien, bijvoorbeeld omdat de URL niet kon worden opgehaald, message en errors[0].message geef de reden:

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

Voorbeeld: Gate een pipelinestap op het importresultaat

Dit script voert een import in, wacht op een eindstatus en sluit bij falen af met een niet-nul 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

Migrate a Customer API v2 integratie

Authenticeer met de api_token header. De v2 asynchrone eindpunten nemen dezelfde multipart/form-data velden als de synchrone, inclusief de vereiste forceImport.

Stap 1: Vervang de eindpunten

Als je de CI/CD-routes direct aanroept met een CI/CD API-sleutel, vervang deze dan in plaats daarvan. De d360 apidocs commando's gebruiken dezelfde routes.

Stap 2: Dien de import in of synchroniseer opnieuw

Importeren:

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"

Om opnieuw te synchroniseren:

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"

Het antwoord is 202 Accepted. Behalve background_task_id voor peilingen.

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

Stap 3: Peil tot de klus klaar is

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

Blijf pollen tot data.is_processing is false.

Stap 4: Lees het resultaat

De uiteindelijke reactie draagt het resultaat. Bewaar api_reference_id voor latere oproepen.

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

Lees bevindingen uit data.errors, en waarschuwingen van data.alerts. Voor een hersynchronisatie worden data.deleted_endpoints de verwijderde eindpunten vermeld, met de method, path, article_id, en title van elk.

Migreer de d360 CLI en CI/CD-pijplijnen

De CLI heeft twee commandofamilies: V3 (apiref) en v2 (apidocs). Blijf binnen je huidige familie wanneer je migreert. Vervang V3-commando's door V3-commando's en v2-commando's door v2-commando's.

Stap 1: Upgrade de CLI

De nieuwe commando's vereisen versie 3.0.7 of later.

npm install -g d360@latest
d360 --version

De oude commando's (, , , ) apidocs:resynczijn gemarkeerd [DEPRECATED] in --help. Ze stoppen met werken wanneer de eindpunten die ze aanroepen worden verwijderd.d360 apidocs:validate is niet verouderd. apidocsapiref resyncapiref import

Stap 2: Controleer of je het juiste certificaat gebruikt

Beide families lezen dezelfde D360_API_KEY variabelenaam, maar verwachten elk een ander inlog. Het gebruik van de verkeerde is de meest voorkomende installatiefout. De CLI geeft je aan wanneer het het verkeerde inloggegevens detecteert.

De CLI heeft geen interactieve login. Het neemt de API-sleutel van de eerste bron die wordt ingesteld: een commando-vlag, een omgevingsvariabele (D360_API_KEY, , ), D360_BASE_URLdan de opgeslagen configuratie (d360 init, of d360 config set-key en d360 config set-project-id). In een pipeline sla je de sleutel op in je CI-geheime opslag en geef je deze door als een omgevingsvariabele. Gebruik de basis-URL D360_PROJECT_IDvoor je regio.

Stap 3: Vervang je commando's

Als je V3-commando's gebruikt

Vervang beide apiref import en apiref resync met apiref submit. De ID die je doorgeeft bepaalt de operatie: --workspace-id importeert, --api-reference-id resynct.

Voor:

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

Na:

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

Werk je vlaggen bij:

De --filter vlag volgt een pad naar de responsgegevens. Gebruik operation_id, niet data.operation_id. De -o tsv optie print de kale ID af.

--wait en d360 operations wait vertrekken 0 wanneer de operatie slaagt. Ze vertrekken 1 als deze mislukt of het wachtbudget van 20 minuten is af. Een budgettimeout stopt het wachten, maar annuleert de operatie niet.

Als je v2 (apidocs) commando's gebruikt,

Dit zijn de commando's die worden weergegeven voor CI/CD in de referentiepanelen Add API en Edit API van het portaal. Vervang beide apidocs en apidocs:resync door apidocs:submit, lees het resultaat vervolgens met apidocs:status. De vlagnamen blijven hetzelfde (camelCase), en je behoudt de CI/CD-sleutel.

Voor:

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

Na:

# 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:submitaccepteert dezelfde vlaggen als het oude apidocs commando: --apiKey, --userId, , --versionId, --apiReferenceId, --path--force, --publish, , en --apihubUrl. Het print een taak-ID en sluit af.

apidocs:status neemt alleen --apiKey, plus --apihubUrl voor niet-EU-regio's. Gate je pipeline altijd op --wait. Zonder deze commando rapporteert het commando één keer en sluit 0 het af, zelfs als de taak nog draait. Met --wait, pollt het totdat de taak klaar is, print de bevindingen (fouten, meldingen en eventuele eindpunten die door een hersynchronisatie zijn verwijderd), en sluit 1 af als de taak niet succesvol is.

Als een hersynchronisatie eindpunten zou verwijderen, stopt het en vermeldt het ze. Voer opnieuw uit met --force om het te bevestigen.

Stap 4: Update je pijplijn

Gebruik een van deze GitHub Actions-stappen als uitgangspunt. In beide faalt de stap wanneer de taak faalt, en worden de bevindingen in het logboek afgedrukt.

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

Los veelvoorkomende problemen op nadat je bent gemigrerd

De CLI volgt dezelfde retry-regel. Het probeert geen verzending opnieuw na een 5xx of een verbroken verbinding. Het probeert alleen een 429, die wordt afgewezen voordat er werk begint.

Controleer je migratie

Uw migratie is voltooid wanneer:

• Elke import- en resync-aanroep gebruikt een asynchroon eindpunt of commando.
• Je integratie leest de uitkomst uit het status-eindpunt, niet uit de 202 respons.
• Op V3 gebruikt operation_id je integratie in plaats van data.id en data.status uit het submit response.
• Je integratie regelt 409 Conflict het door te wachten tot de taak draait en het opnieuw te proberen.
• Je hebt gekozen hoe je met bevindingen omgaat: de specificatie corrigeren, of bewust instellen force_import: true .
• Je API-sleutel of rol kan zowel operaties verzenden als lezen.
• Je CLI staat op versie 3.0.7 of later, en elke familie gebruikt zijn eigen credential: een d360_sk_ sleutel voor apiref, en de CI/CD-sleutel voor apidocs.
• Je pijplijn faalt in de stap wanneer een import of hersynchronisatie mislukt.
• Je hebt de migratie voltooid voordat de oude eindpunten en commando's eind maart 2027 worden verwijderd.