Pāreja uz API adresi

Agrākas integrācijas izsauc API Sursas galvenajā adresē – tajā, ko cilvēki atver pārlūkā, piemēram, https://app.sursa.com/v1/…. Tagad API ir arī sava adrese: https://api.sursa.com mākonī vai https://api.<your domain> jūsu instalācijā. Tā ir paredzēta integrācijām: tā mērogojas horizontāli aiz slodzes līdzsvarotāja un apkalpo tikai API.

Pāreja nav obligāta. Galvenā adrese turpina apkalpot /v1 esošajām integrācijām bez beigu datuma un bez novirzīšanas. Pārejiet, kad jums ērti, lai iegūtu API adreses priekšrocības, un izmantojiet to visām jaunajām integrācijām.

Kas paliek nemainīgs

• Ceļi, parametri, lauki, kļūdu kodi un notikumi: GET /v1/cards ir tas pats pieprasījums abās adresēs.
• API atslēgas. Tās pašas kb_ un kbsrc_ atslēgas darbojas abās adresēs ar to pašu lomu, tvērumiem un datu profilu.
• Idempotences atslēgas, pieprasījumu biežuma limiti un kvotas. Pieprasījumi abās adresēs tiek ieskaitīti tajās pašās organizācijas kvotās.
• Webhook paziņojumi. Piegādes, paraksti un noslēpumi nav atkarīgi no adreses, ko izsaucat.
• Saites atbildēs. Kļūdas doc_url ved uz šo portālu, bet saraksta lapas galvene Link ved uz API adresi neatkarīgi no tā, kuru adresi izsaucat.

Kas API adresē ir citādi

Pēdējā rinda ir svarīga tikai vienā gadījumā: POST /v1/chat straumēta atbilde. Pārtraukta straume turpinās no Last-Event-ID tikai tajā serverī, kas raksta atbildi. Ja jūsu integrācija turpina straumes, piešķiriet katram jautājumam request_id, lai atkārtojums citā serverī saņemtu saglabāto atbildi, nevis otru. Sk. Pārtrauktas straumes turpināšana.

Pirms pārejas

Pārbaudiet, vai katrs izsaukums ir publisks. Uzskaitiet ceļus, kurus izsauc jūsu integrācija, un atrodiet katru no tiem API rokasgrāmatā vai salīdziniet tos ar jaunās adreses specifikāciju:

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

Ceļš, kura nav publiskajā rokasgrāmatā, pieder tīmekļa lietotnei. Tas joprojām darbojas galvenajā adresē, bet API adresē netiek apkalpots, un tā forma nav publiska saistība. Aizstājiet to ar publisku operāciju vai atstājiet šo integrācijas daļu galvenajā adresē un pastāstiet savai kontaktpersonai Sursā, kas jums vajadzīgs.

Pārbaudiet, kā autentificējaties. Ja integrācija pierakstās ar lietotāja paroli un sesijas sīkdatni, vispirms pārceliet to uz API atslēgu. Ja tā sūta X-API-Key, pāreja uz Authorization: Bearer ir ieteicama, bet nav obligāta.

Pārbaudiet savu tīklu. Atļaujiet ugunsmūrī un starpniekserveros izejošu HTTPS savienojumu ar jauno resursdatora nosaukumu.

Pāreja soli pa solim

1. Padariet bāzes URL par iestatījumu savā integrācijā, ja tas tāds vēl nav.

2. Izmēģiniet jauno adresi ar lasīšanas pieprasījumu:

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

3. Palaidiet savas integrācijas testu komplektu pret jauno adresi ar testa atslēgu un testa kolekciju.

4. Pārslēdziet daļu datplūsmas, piemēram, vienu apstrādes procesu vai vienu vidi, un vērojiet žurnālos 404 api.not_found, 401 un 5xx. Katrā atbildē ir X-Request-Id; glabājiet to kopā ar žurnāliem.

5. Pārslēdziet pārējo. Kādu laiku paturiet veco bāzes URL konfigurācijā, lai dažās sekundēs varētu pārslēgties atpakaļ.

Kas jāpārbauda pēc pārejas

• GET /v1/health jaunajā adresē atgriež to pašu version kā vecajā.
• Atbildēs ir galvenes RateLimit. Ja jūsu integrācija palēnina tempu pēc X-RateLimit-*, tā var turpināt to darīt: tiek sūtītas abas galveņu kopas. Sk. Pieprasījumu biežuma limiti un kvotas.
• Ja jūsu integrācija darbojas pārlūkā, tai vairs nav vajadzīgs savs starpniekserveris CORS dēļ: API adrese atļauj pieprasījumus no jebkuras izcelsmes bez sīkdatnēm.