Přechod na adresu API

Starší integrace volají API na hlavní adrese Sursy, té, kterou lidé otevírají v prohlížeči, například https://app.sursa.com/v1/…. API má teď i vlastní adresu: https://api.sursa.com v cloudu nebo https://api.<your domain> ve vaší instalaci. Je určená pro integrace: škáluje se přidáváním serverů za nástrojem pro vyrovnávání zátěže a neobsluhuje nic jiného než API.

Přecházet nemusíte. Hlavní adresa obsluhuje /v1 pro stávající integrace dál, bez data ukončení a bez přesměrování. Přejděte, až se vám to bude hodit, a získejte tak výhody adresy API; pro každou novou integraci ji používejte.

Co zůstává stejné

Cesty, parametry, pole, chybové kódy a události: GET /v1/cards je na obou adresách stejný požadavek.
Klíče API. Tytéž klíče kb_ a kbsrc_ fungují na obou adresách se stejnou rolí, rozsahy a datovým profilem.
Klíče idempotence, limity četnosti a kvóty. Požadavky na obě adresy se započítávají do stejných kvót organizace.
Webhooky. Doručení, podpisy a tajné klíče nezávisejí na adrese, kterou voláte.
Odkazy v odpovědích. doc_url chyby vede na tento portál a hlavička Link stránky seznamu vede na adresu API, ať voláte kteroukoli adresu.

Co je na adrese API jinak

Na hlavní adrese	Na adrese API
Všechny operace webové aplikace včetně interních	Jen operace veřejné reference API. Jakákoli jiná cesta odpoví `404` s kódem `api.not_found`.
Klíč v `X-API-Key` nebo `Authorization`, nebo cookie relace prohlížeče	Klíč nebo přístupový token OAuth, nejlépe v `Authorization: Bearer`. Cookies se ignorují.
`GET /auth/me`	`GET /v1/me`. Cesty pod `/auth/` se neobsluhují.
Režim „View as“ (zobrazení jako vybraná role a datový profil) pomocí cookie	Hlavička `X-View-As` pro klíče s rolí `admin`.
Jeden server nebo pevná sada serverů	Několik serverů za nástrojem pro vyrovnávání zátěže.

Poslední řádek je důležitý jen v jednom případě: u streamované odpovědi POST /v1/chat. Přerušený stream pokračuje od Last-Event-ID jen na serveru, který odpověď píše. Pokud vaše integrace streamy obnovuje, dejte každé otázce request_id, aby opakovaný pokus na jiném serveru dostal uloženou odpověď, a ne druhou. Viz Obnovte přerušený stream.

Před přechodem

Ověřte, že je každé volání veřejné. Vypište cesty, které vaše integrace volá, a každou vyhledejte v referenci API, nebo je porovnejte se specifikací nové 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, která ve veřejné referenci chybí, patří webové aplikaci. Na hlavní adrese dál funguje, ale na adrese API se neobsluhuje a její tvar není veřejným závazkem. Nahraďte ji veřejnou operací, nebo tuto část integrace ponechte na hlavní adrese a sdělte svému kontaktu v Surse, co potřebujete.

Ověřte, jak se autentizujete. Pokud se integrace přihlašuje heslem uživatele a cookie relace, převeďte ji nejdřív na klíč API. Pokud posílá X-API-Key, přechod na Authorization: Bearer se doporučuje, ale není povinný.

Ověřte svou síť. Ve firewallu a proxy povolte odchozí HTTPS na nový název hostitele.

Přechod krok za krokem

Udělejte ze základní URL nastavení své integrace, pokud jím ještě není.

Vyzkoušejte novou adresu požadavkem na čtení:

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

Spusťte testy své integrace proti nové adrese s testovacím klíčem a testovací kolekcí.
Přepněte část provozu, například jeden proces nebo jedno prostředí, a sledujte v protokolech 404 api.not_found, 401 a 5xx. Každá odpověď nese X-Request-Id; uchovávejte ho ve svých protokolech.
Přepněte zbytek. Starou základní URL si v konfiguraci nějakou dobu ponechte, aby bylo možné během několika sekund přepnout zpět.

Co zkontrolovat po přechodu

GET /v1/health na nové adrese vrací stejnou version jako na staré.
Odpovědi obsahují hlavičky RateLimit. Pokud se vaše integrace sama zpomaluje podle X-RateLimit-*, může v tom pokračovat: posílají se obě sady. Viz Limity četnosti a kvóty.
Pokud vaše integrace běží v prohlížeči, už nepotřebuje vlastní proxy kvůli CORS: adresa API povoluje požadavky z jakéhokoli původu, bez cookies.