Umstieg auf die API-Adresse

Ältere Integrationen rufen die API unter der Hauptadresse von Sursa auf, also unter der Adresse, die Menschen im Browser öffnen, zum Beispiel https://app.sursa.com/v1/…. Die API hat jetzt zusätzlich eine eigene Adresse: https://api.sursa.com in der Cloud oder https://api.<your domain> in Ihrer Installation. Diese Adresse ist für Integrationen gebaut: Sie lässt sich hinter einem Load Balancer skalieren und liefert ausschließlich die API aus.

Sie müssen nicht umsteigen. Die Hauptadresse liefert /v1 für bestehende Integrationen weiterhin aus, ohne Enddatum und ohne Weiterleitung. Steigen Sie um, wenn es Ihnen passt, um die Vorteile der API-Adresse zu nutzen, und verwenden Sie sie für jede neue Integration.

Was gleich bleibt

Pfade, Parameter, Felder, Fehlercodes und Ereignisse: GET /v1/cards ist unter beiden Adressen dieselbe Anfrage.
API-Schlüssel. Dieselben Schlüssel kb_ und kbsrc_ funktionieren unter beiden Adressen, mit derselben Rolle, denselben Scopes und demselben Datenprofil.
Idempotenzschlüssel, Ratenlimits und Kontingente. Anfragen an beide Adressen zählen für dieselben Kontingente der Organisation.
Webhooks. Zustellungen, Signaturen und Secrets hängen nicht von der Adresse ab, die Sie aufrufen.
Links in Antworten. doc_url eines Fehlers zeigt auf dieses Portal und der Header Link einer Listenseite auf die API-Adresse – unabhängig davon, welche Adresse Sie aufrufen.

Was unter der API-Adresse anders ist

Unter der Hauptadresse	Unter der API-Adresse
Jeder Endpunkt der Webanwendung, auch interne	Nur die Endpunkte der öffentlichen API-Referenz. Jeder andere Pfad antwortet mit `404` und dem Code `api.not_found`.
Ein Schlüssel in `X-API-Key` oder `Authorization` oder ein Sitzungscookie des Browsers	Ein Schlüssel oder ein OAuth-Zugriffstoken, bevorzugt in `Authorization: Bearer`. Cookies werden ignoriert.
`GET /auth/me`	`GET /v1/me`. Pfade unter `/auth/` werden nicht ausgeliefert.
Der Modus „Ansicht als“ per Cookie	Der Header `X-View-As` für Schlüssel mit der Rolle `admin`.
Ein Server oder eine feste Gruppe von Servern	Mehrere Server hinter einem Load Balancer.

Die letzte Zeile ist nur in einem Fall wichtig: bei einer gestreamten Antwort von POST /v1/chat. Ein abgebrochener Stream setzt ab Last-Event-ID nur auf dem Server fort, der die Antwort schreibt. Wenn Ihre Integration Streams fortsetzt, geben Sie jeder Frage eine request_id, damit eine Wiederholung auf einem anderen Server die gespeicherte Antwort erhält statt einer zweiten. Siehe Abgebrochenen Stream fortsetzen.

Vor dem Umstieg

Prüfen Sie, ob jeder Aufruf öffentlich ist. Listen Sie die Pfade auf, die Ihre Integration aufruft, und schlagen Sie jeden in der API-Referenz nach, oder vergleichen Sie sie mit der Spezifikation der neuen Adresse:

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

Ein Pfad, der in der öffentlichen Referenz fehlt, gehört zur Webanwendung. Er funktioniert unter der Hauptadresse weiter, wird unter der API-Adresse aber nicht ausgeliefert, und seine Form ist keine öffentliche Zusage. Ersetzen Sie ihn durch einen öffentlichen Endpunkt, oder belassen Sie diesen Teil der Integration auf der Hauptadresse und sagen Sie Ihrem Ansprechpartner bei Sursa, was Sie brauchen.

Prüfen Sie, wie Sie sich authentifizieren. Meldet sich die Integration mit dem Passwort eines Benutzers und einem Sitzungscookie an, stellen Sie sie zuerst auf einen API-Schlüssel um. Sendet sie X-API-Key, ist der Wechsel zu Authorization: Bearer empfohlen, aber nicht erforderlich.

Prüfen Sie Ihr Netzwerk. Erlauben Sie in Ihrer Firewall und Ihren Proxys ausgehendes HTTPS zum neuen Hostnamen.

Schritt für Schritt umsteigen

Machen Sie die Basis-URL zu einer Einstellung Ihrer Integration, falls sie es noch nicht ist.

Probieren Sie die neue Adresse mit einer lesenden Anfrage aus:

curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"

Führen Sie die Testsuite Ihrer Integration gegen die neue Adresse aus, mit einem Testschlüssel und einer Testsammlung.
Stellen Sie einen Teil des Datenverkehrs um, zum Beispiel einen Worker oder eine Umgebung, und achten Sie in Ihren Protokollen auf 404 api.not_found, 401 und 5xx. Jede Antwort trägt X-Request-Id; bewahren Sie die ID mit Ihren Protokollen auf.
Stellen Sie den Rest um. Behalten Sie die alte Basis-URL eine Zeit lang in Ihrer Konfiguration, damit Sie in Sekunden zurückwechseln können.

Was Sie nach dem Umstieg prüfen sollten

GET /v1/health gibt unter der neuen Adresse dieselbe version zurück wie unter der alten.
Die Header RateLimit sind in den Antworten vorhanden. Wenn Ihre Integration sich anhand von X-RateLimit-* selbst bremst, kann sie das weiterhin tun: Beide Sätze werden gesendet. Siehe Ratenlimits und Kontingente.
Läuft Ihre Integration im Browser, braucht sie keinen eigenen Proxy für CORS mehr: Die API-Adresse erlaubt Anfragen von jedem Ursprung, ohne Cookies.