Átállás az API-címre

A korábbi integrációk a Sursa fő címén hívják az API-t, azon, amelyet a felhasználók a böngészőben megnyitnak, például https://app.sursa.com/v1/…. Az API-nak most saját címe is van: a felhőben https://api.sursa.com, a saját telepítésedben https://api.<your domain>. Ez a cím integrációkhoz készült: terheléselosztó mögött vízszintesen skálázódik, és kizárólag az API-t szolgálja ki.

Nem kötelező átállnod. A fő cím a meglévő integrációk számára továbbra is kiszolgálja a /v1 útvonalakat, határidő és átirányítás nélkül. Akkor állj át, amikor neked megfelel, hogy kihasználd az API-cím előnyeit, és minden új integrációhoz ezt használd.

Ami ugyanaz marad

Az útvonalak, a paraméterek, a mezők, a hibakódok és az események: a GET /v1/cards mindkét címen ugyanaz a kérés.
Az API-kulcsok. Ugyanazok a kb_ és kbsrc_ kulcsok működnek mindkét címen, ugyanazzal a szerepkörrel, hatókörökkel és adatprofillal.
Az idempotenciakulcsok, a gyakorisági korlátok és a kvóták. A két címre küldött kérések a szervezet ugyanazokba a kvótáiba számítanak bele.
A webhookok. A kézbesítések, az aláírások és a titkos kulcsok nem függnek attól, melyik címet hívod.
A válaszokban szereplő hivatkozások. A hiba doc_url mezője erre a portálra mutat, a listaoldal Link fejléce pedig az API-címre, bármelyik címet hívod is.

Ami más az API-címen

A fő címen	Az API-címen
A webalkalmazás összes végpontja, a belsőket is beleértve	Csak a nyilvános API-referencia végpontjai. Minden más útvonalra a válasz `404` az `api.not_found` kóddal.
Kulcs az `X-API-Key` vagy az `Authorization` fejlécben, vagy böngészős munkamenet sütije	Kulcs vagy OAuth-hozzáférési token, lehetőleg az `Authorization: Bearer` fejlécben. A sütiket figyelmen kívül hagyja.
`GET /auth/me`	`GET /v1/me`. A `/auth/` alatti útvonalakat nem szolgálja ki.
A „View as” mód (megtekintés más felhasználóként) sütivel	Az `X-View-As` fejléc, az `admin` szerepkörű kulcsok számára.
Egy szerver vagy rögzített szervercsoport	Több szerver terheléselosztó mögött.

Az utolsó sor csak egy esetben számít: a POST /v1/chat adatfolyamként érkező válaszánál. A megszakadt adatfolyam csak azon a szerveren folytatódik a Last-Event-ID alapján, amelyik a választ írja. Ha az integrációd folytatja az adatfolyamokat, adj minden kérdésnek request_id azonosítót, hogy egy másik szerveren történő újrapróbálkozás a mentett választ kapja meg, ne egy második választ. Lásd: Megszakadt adatfolyam folytatása.

Az átállás előtt

Ellenőrizd, hogy minden hívás nyilvános-e. Írd össze az integrációd által hívott útvonalakat, és mindegyiket keresd meg az API-referenciában, vagy vesd össze őket az új cím specifikációjával:

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

A nyilvános referenciából hiányzó útvonal a webalkalmazáshoz tartozik. A fő címen továbbra is működik, de az API-címen nem érhető el, és a szerkezete nem nyilvános kötelezettségvállalás. Cseréld le egy nyilvános végpontra, vagy az integráció ezen részét hagyd a fő címen, és mondd el a kapcsolattartódnak a Sursánál, mire van szükséged.

Ellenőrizd, hogyan hitelesítesz. Ha az integráció egy felhasználó jelszavával és munkamenet-sütivel jelentkezik be, előbb állítsd át API-kulcsra. Ha X-API-Key fejlécet küld, az Authorization: Bearer fejlécre való áttérés ajánlott, de nem kötelező.

Ellenőrizd a hálózatodat. A tűzfaladban és a proxyjaidban engedélyezd a kimenő HTTPS-forgalmat az új gépnév felé.

Átállás lépésről lépésre

Tedd beállíthatóvá az alap-URL-t az integrációdban, ha még nem az.

Próbáld ki az új címet egy olvasó kéréssel:

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

Futtasd le az integrációd tesztkészletét az új címen, tesztkulccsal és tesztgyűjteménnyel.
Állítsd át a forgalom egy részét, például egy feldolgozót vagy egy környezetet, és figyeld a naplóidban a 404 api.not_found, a 401 és az 5xx válaszokat. Minden válasz tartalmazza az X-Request-Id fejlécet; őrizd meg a naplóiddal együtt.
Állítsd át a többit. A régi alap-URL-t egy ideig tartsd meg a konfigurációdban, hogy másodpercek alatt visszaválthass.

Ellenőrzendők az átállás után

Az új címen a GET /v1/health ugyanazt a version értéket adja vissza, mint a régin.
A válaszokban megvannak a RateLimit fejlécek. Ha az integrációd az X-RateLimit-* fejlécek alapján lassítja magát, ezt továbbra is megteheti: mindkét fejléckészlet megérkezik. Lásd: Gyakorisági korlátok és kvóták.
Ha az integrációd böngészőben fut, már nincs szüksége saját proxyra a CORS miatt: az API-cím bármely eredetből, sütik nélkül fogad kéréseket.