Prejdite na adresu API

Staršie integrácie volajú API na hlavnej adrese Sursy, na tej, ktorú ľudia otvárajú v prehliadači, napríklad https://app.sursa.com/v1/…. API má teraz aj vlastnú adresu: https://api.sursa.com v cloude alebo https://api.<your domain> vo vašej inštalácii. Je určená pre integrácie: škáluje sa za vyrovnávačom záťaže a neposkytuje nič okrem API.

Prechádzať nemusíte. Hlavná adresa naďalej poskytuje /v1 pre existujúce integrácie, bez dátumu ukončenia a bez presmerovania. Prejdite, keď vám to bude vyhovovať, aby ste získali výhody adresy API, a používajte ju pre každú novú integráciu.

Čo zostáva rovnaké

Cesty, parametre, polia, chybové kódy a udalosti: GET /v1/cards je na oboch adresách tá istá požiadavka.
Kľúče API. Tie isté kľúče kb_ a kbsrc_ fungujú na oboch adresách s rovnakou rolou, rozsahmi a dátovým profilom.
Kľúče idempotencie, limity frekvencie a kvóty. Požiadavky na oboch adresách sa započítavajú do tých istých kvót organizácie.
Webhooky. Doručenia, podpisy a tajné kľúče nezávisia od adresy, ktorú voláte.
Odkazy v odpovediach. doc_url chyby smeruje na tento portál a hlavička Link stránky zoznamu smeruje na adresu API bez ohľadu na to, ktorú adresu voláte.

Čím sa adresa API líši

Na hlavnej adrese	Na adrese API
Všetky operácie webovej aplikácie vrátane interných	Len operácie verejnej referencie API. Každá iná cesta odpovie `404` s kódom `api.not_found`.
Kľúč v `X-API-Key` alebo `Authorization`, alebo súbor cookie relácie prehliadača	Kľúč alebo prístupový token OAuth, prednostne v `Authorization: Bearer`. Súbory cookie sa ignorujú.
`GET /auth/me`	`GET /v1/me`. Cesty pod `/auth/` sa neposkytujú.
Režim „View as“ cez súbor cookie	Hlavička `X-View-As` pre kľúče s rolou `admin`.
Jeden server alebo pevná sada serverov	Niekoľko serverov za vyrovnávačom záťaže.

Posledný riadok je dôležitý len v jednom prípade: pri streamovanej odpovedi POST /v1/chat. Prerušený stream pokračuje od Last-Event-ID len na serveri, ktorý odpoveď píše. Ak vaša integrácia obnovuje streamy, dajte každej otázke request_id, aby opakovanie na inom serveri dostalo uloženú odpoveď a nie druhú. Pozri Obnovte prerušený stream.

Pred prechodom

Overte, že každé volanie je verejné. Vypíšte cesty, ktoré vaša integrácia volá, a každú vyhľadajte v referencii API alebo ich porovnajte so špecifikáciou novej adresy:

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

Cesta, ktorá vo verejnej referencii chýba, patrí webovej aplikácii. Na hlavnej adrese funguje ďalej, na adrese API sa však neposkytuje a jej tvar nie je verejným záväzkom. Nahraďte ju verejnou operáciou alebo nechajte túto časť integrácie na hlavnej adrese a povedzte svojej kontaktnej osobe v Surse, čo potrebujete.

Overte, ako sa prihlasujete. Ak sa integrácia prihlasuje heslom používateľa a súborom cookie relácie, najprv ju prepnite na kľúč API. Ak posiela X-API-Key, prechod na Authorization: Bearer sa odporúča, ale nie je povinný.

Overte svoju sieť. Vo firewalle a proxy povoľte odchádzajúce HTTPS na nový názov hostiteľa.

Prechod krok za krokom

Urobte zo základnej URL nastavenie svojej integrácie, ak ním ešte nie je.

Vyskúšajte novú adresu požiadavkou na čítanie:

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

Spustite testy svojej integrácie proti novej adrese s testovacím kľúčom a testovacou kolekciou.
Prepnite časť prevádzky, napríklad jeden proces alebo jedno prostredie, a sledujte v logoch 404 api.not_found, 401 a 5xx. Každá odpoveď nesie X-Request-Id; uchovávajte ho spolu s logmi.
Prepnite zvyšok. Starú základnú URL si nejaký čas ponechajte v konfigurácii, aby ste sa mohli za pár sekúnd prepnúť späť.

Čo overiť po prechode

GET /v1/health na novej adrese vráti rovnakú version ako na starej.
Odpovede obsahujú hlavičky RateLimit. Ak vaša integrácia spomaľuje podľa X-RateLimit-*, môže v tom pokračovať: posielajú sa obe sady. Pozri Limity frekvencie a kvóty.
Ak vaša integrácia beží v prehliadači, už nepotrebuje vlastnú proxy kvôli CORS: adresa API povoľuje požiadavky z ľubovoľného pôvodu, bez súborov cookie.