Perėjimas prie API adreso

Ankstesnės integracijos kviečia API pagrindiniu Sursos adresu – tuo, kurį žmonės atidaro naršyklėje, pavyzdžiui, https://app.sursa.com/v1/…. Dabar API turi ir savo adresą: debesyje – https://api.sursa.com, jūsų diegime – https://api.<your domain>. Jis sukurtas integracijoms: plečiamas keliais serveriais už apkrovos balansavimo įrenginio ir aptarnauja tik API.

Pereiti neprivaloma. Pagrindinis adresas toliau aptarnauja /v1 esamoms integracijoms, be pabaigos datos ir be peradresavimo. Pereikite, kai jums patogu, kad gautumėte API adreso privalumus, o kiekvienai naujai integracijai naudokite jį.

Kas lieka taip pat

Keliai, parametrai, laukai, klaidų kodai ir įvykiai: GET /v1/cards abiem adresais yra ta pati užklausa.
API raktai. Tie patys kb_ ir kbsrc_ raktai veikia abiem adresais, su tuo pačiu vaidmeniu, apimtimis ir duomenų profiliu.
Idempotentiškumo raktai, užklausų dažnio limitai ir kvotos. Užklausos abiem adresais įskaičiuojamos į tas pačias organizacijos kvotas.
Webhook pranešimai. Pristatymai, parašai ir paslaptys nepriklauso nuo adreso, kuriuo kreipiatės.
Nuorodos atsakuose. Klaidos doc_url veda į šį portalą, o sąrašo puslapio antraštė Link – į API adresą, kad ir kuriuo adresu kreipiatės.

Kuo skiriasi API adresas

Pagrindiniu adresu	API adresu
Visos žiniatinklio programos operacijos, įskaitant vidines	Tik viešojo API žinyno operacijos. Bet kuris kitas kelias grąžina `404` su kodu `api.not_found`.
Raktas antraštėje `X-API-Key` arba `Authorization`, arba naršyklės sesijos slapukas	Raktas arba OAuth prieigos žetonas, geriausia antraštėje `Authorization: Bearer`. Slapukai ignoruojami.
`GET /auth/me`	`GET /v1/me`. Keliai, prasidedantys `/auth/`, neaptarnaujami.
Režimas „View as“ (žiūrėti kaip) pagal slapuką	Antraštė `X-View-As` raktams su vaidmeniu `admin`.
Vienas serveris arba fiksuotas jų rinkinys	Keli serveriai už apkrovos balansavimo įrenginio.

Paskutinė eilutė svarbi tik vienu atveju: srautu transliuojamam POST /v1/chat atsakymui. Nutrūkęs srautas nuo Last-Event-ID tęsiamas tik tame serveryje, kuris rašo atsakymą. Jei jūsų integracija tęsia srautus, kiekvienam klausimui suteikite request_id – tada pakartojimas kitame serveryje gaus išsaugotą atsakymą, o ne antrą. Žr. Nutrūkusio srauto tęsimas.

Prieš pereinant

Patikrinkite, ar kiekvienas iškvietimas yra viešas. Išvardykite kelius, kuriuos kviečia jūsų integracija, ir kiekvieną suraskite API žinyne arba palyginkite juos su naujo adreso specifikacija:

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

Kelias, kurio viešajame žinyne nėra, priklauso žiniatinklio programai. Pagrindiniu adresu jis vis dar veikia, bet API adresu neaptarnaujamas, o jo forma nėra viešas įsipareigojimas. Pakeiskite jį viešąja operacija arba tą integracijos dalį palikite pagrindiniu adresu ir praneškite savo kontaktiniam asmeniui Sursoje, ko jums reikia.

Patikrinkite, kaip autentifikuojatės. Jei integracija prisijungia naudotojo slaptažodžiu ir sesijos slapuku, pirmiausia perkelkite ją į API raktą. Jei ji siunčia X-API-Key, pereiti prie Authorization: Bearer rekomenduojama, bet neprivaloma.

Patikrinkite tinklą. Ugniasienėje ir tarpiniuose serveriuose leiskite išeinantį HTTPS ryšį į naują pagrindinio kompiuterio vardą.

Perėjimas žingsnis po žingsnio

Bazinį URL padarykite integracijos nustatymu, jei jis toks dar nėra.

Išbandykite naują adresą skaitymo užklausa:

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

Paleiskite integracijos testų rinkinį su nauju adresu, bandomuoju raktu ir bandomuoju rinkiniu.
Perjunkite dalį srauto, pavyzdžiui, vieną darbo procesą ar vieną aplinką, ir stebėkite žurnaluose 404 api.not_found, 401 ir 5xx. Kiekviename atsake yra X-Request-Id; saugokite jį kartu su žurnalais.
Perjunkite likusią dalį. Seną bazinį URL kurį laiką palikite konfigūracijoje, kad galėtumėte per kelias sekundes grįžti.

Ką patikrinti po perėjimo

GET /v1/health naujuoju adresu grąžina tą pačią version kaip senuoju.
Atsakuose yra RateLimit antraštės. Jei jūsų integracija pati sulėtina tempą pagal X-RateLimit-*, ji gali taip daryti ir toliau: siunčiami abu antraščių rinkiniai. Žr. Užklausų dažnio limitai ir kvotos.
Jei jūsų integracija veikia naršyklėje, jai nebereikia jūsų tarpinio serverio dėl CORS: API adresas leidžia užklausas iš bet kokios kilmės, be slapukų.