Üleminek API-aadressile

Varasemad integratsioonid kutsuvad API-t Sursa põhiaadressil, mille inimesed brauseris avavad, näiteks https://app.sursa.com/v1/…. Nüüd on API-l ka oma aadress: pilves https://api.sursa.com, teie paigalduses https://api.<your domain>. See on loodud integratsioonide jaoks: see skaleerub koormusjaoturi taga horisontaalselt ega teeninda midagi muud peale API.

Te ei pea üle minema. Põhiaadress teenindab olemasolevate integratsioonide jaoks teed /v1 edasi, ilma lõppkuupäeva ja ümbersuunamiseta. Minge üle siis, kui see teile sobib, et saada API-aadressi eelised, ja kasutage seda iga uue integratsiooni jaoks.

Mis jääb samaks

Teed, parameetrid, väljad, veakoodid ja sündmused: GET /v1/cards on mõlemal aadressil sama päring.
API-võtmed. Samad võtmed kb_ ja kbsrc_ töötavad mõlemal aadressil sama rolli, ulatuste ja andmeprofiiliga.
Idempotentsusvõtmed, sageduspiirangud ja kvoodid. Mõlema aadressi päringud lähevad arvesse organisatsiooni samades kvootides.
Veebihaagid. Edastused, allkirjad ja saladused ei sõltu aadressist, mida kutsute.
Vastuste lingid. Vea doc_url viitab sellele portaalile ja loendilehe päis Link viitab API-aadressile, olenemata sellest, millist aadressi kutsute.

Mis on API-aadressil teisiti

Põhiaadressil	API-aadressil
Kõik veebirakenduse lõpp-punktid, ka sisemised	Ainult avaliku API teatmiku lõpp-punktid. Iga muu tee vastab `404` koodiga `api.not_found`.
Võti päises `X-API-Key` või `Authorization` või brauseri seansiküpsis	Võti või OAuth-juurdepääsuluba, eelistatavalt kujul `Authorization: Bearer`. Küpsiseid eiratakse.
`GET /auth/me`	`GET /v1/me`. Tee `/auth/` all olevaid teid ei teenindata.
Režiim „View as“ (vaade teise kasutaja silmade läbi) küpsise kaudu	Päis `X-View-As` võtmetele, millel on roll `admin`.
Üks server või kindel serverite komplekt	Mitu serverit koormusjaoturi taga.

Viimane rida on oluline ainult ühel juhul: päringu POST /v1/chat voogedastatud vastuse puhul. Katkenud voog jätkub päise Last-Event-ID põhjal ainult serveris, mis vastust kirjutab. Kui teie integratsioon jätkab vooge, andke igale küsimusele request_id, et korduskatse teises serveris saaks salvestatud vastuse, mitte teist vastust. Vt Katkenud voo jätkamine.

Enne üleminekut

Kontrollige, et iga kutse oleks avalik. Loetlege teed, mida teie integratsioon kutsub, ja otsige igaüks üles API teatmikust või võrrelge neid uue aadressi spetsifikatsiooniga:

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

Tee, mis avalikust teatmikust puudub, kuulub veebirakendusele. See töötab põhiaadressil endiselt, kuid API-aadressil seda ei teenindata ja selle kuju ei ole avalik kohustus. Asendage see avaliku lõpp-punktiga või jätke see integratsiooni osa põhiaadressile ja öelge oma kontaktisikule Sursas, mida vajate.

Kontrollige, kuidas autendite. Kui integratsioon logib sisse kasutaja parooli ja seansiküpsisega, viige see esmalt üle API-võtmele. Kui see saadab päist X-API-Key, on üleminek kujule Authorization: Bearer soovitatav, kuid mitte kohustuslik.

Kontrollige oma võrku. Lubage tulemüüris ja puhverserverites väljuv HTTPS-ühendus uuele hostinimele.

Samm-sammult üleminek

Muutke baas-URL oma integratsiooni seadeks, kui see seda veel ei ole.

Proovige uut aadressi lugemispäringuga:

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

Käivitage oma integratsiooni testikomplekt uue aadressi vastu, kasutades testvõtit ja testkogu.
Lülitage ümber osa liiklusest, näiteks üks töötlusprotsess või üks keskkond, ja jälgige logides vastuseid 404 api.not_found, 401 ja 5xx. Igal vastusel on päis X-Request-Id; hoidke seda koos oma logidega.
Lülitage ümber ülejäänu. Hoidke vana baas-URL mõnda aega oma konfiguratsioonis, et saaksite sekunditega tagasi lülituda.

Mida pärast üleminekut kontrollida

GET /v1/health tagastab uuel aadressil sama version mis vanal.
Vastustes on päised RateLimit. Kui teie integratsioon aeglustab end päiste X-RateLimit-* järgi, võib see seda jätkata: saadetakse mõlemad komplektid. Vt Sageduspiirangud ja kvoodid.
Kui teie integratsioon töötab brauseris, ei vaja see CORS-i jaoks enam teie oma puhverserverit: API-aadress lubab päringuid mis tahes päritolust ilma küpsisteta.