Siirtyminen API-osoitteeseen

Aiemmat integraatiot kutsuvat API:a Sursan pääosoitteessa, jonka ihmiset avaavat selaimessa, esimerkiksi https://app.sursa.com/v1/…. Nyt API:lla on myös oma osoitteensa: pilvessä https://api.sursa.com ja omassa asennuksessasi https://api.<your domain>. Se on tehty integraatioita varten: se skaalautuu kuormantasaajan takana, eikä se palvele mitään muuta kuin API:a.

Sinun ei ole pakko siirtyä. Pääosoite palvelee edelleen /v1-polkuja olemassa oleville integraatioille ilman päättymispäivää ja ilman uudelleenohjausta. Siirry, kun se sopii sinulle, niin saat API-osoitteen hyödyt, ja käytä sitä kaikissa uusissa integraatioissa.

Mikä pysyy ennallaan

Polut, parametrit, kentät, virhekoodit ja tapahtumat: GET /v1/cards on sama pyyntö molemmissa osoitteissa.
API-avaimet. Samat kb_- ja kbsrc_-avaimet toimivat molemmissa osoitteissa samalla roolilla, samoilla käyttöalueilla ja samalla dataprofiililla.
Idempotenssiavaimet, nopeusrajoitukset ja kiintiöt. Molempien osoitteiden pyynnöt lasketaan organisaation samoihin kiintiöihin.
Webhookit. Toimitukset, allekirjoitukset ja salaisuudet eivät riipu siitä, mitä osoitetta kutsut.
Vastausten linkit. Virheen doc_url osoittaa tähän portaaliin, ja listan sivun Link-otsake osoittaa API-osoitteeseen, kutsuitpa mitä osoitetta tahansa.

Mikä on toisin API-osoitteessa

Pääosoitteessa	API-osoitteessa
Kaikki verkkosovelluksen päätepisteet, myös sisäiset	Vain julkisen API-viitteen päätepisteet. Mikä tahansa muu polku palauttaa `404`-vastauksen ja koodin `api.not_found`.
Avain `X-API-Key`- tai `Authorization`-otsakkeessa tai selaimen istuntoeväste	Avain tai OAuth-käyttöoikeustunnus, mieluiten muodossa `Authorization: Bearer`. Evästeet ohitetaan.
`GET /auth/me`	`GET /v1/me`. Polkuja, jotka alkavat `/auth/`, ei palvella.
”View as” -tila (näkymä toisen käyttäjän silmin) evästeen avulla	`X-View-As`-otsake avaimille, joilla on rooli `admin`.
Yksi instanssi tai kiinteä joukko instansseja	Useita API-instansseja kuormantasaajan takana.

Viimeisellä rivillä on merkitystä vain yhdessä tapauksessa: kun vastaus tulee POST /v1/chat -pyynnön virtana. Katkennut virta jatkuu Last-Event-ID-otsakkeen kohdasta vain siinä API-instanssissa, joka kirjoittaa vastausta. Jos integraatiosi jatkaa katkenneita virtoja, anna jokaiselle kysymykselle request_id, jotta toisessa instanssissa tehty uusintayritys saa tallennetun vastauksen eikä uutta, toista vastausta. Ks. Jatka katkennutta virtaa.

Ennen siirtymistä

Tarkista, että jokainen kutsu on julkinen. Luettele polut, joita integraatiosi kutsuu, ja etsi kukin niistä API-viitteestä tai vertaa niitä uuden osoitteen määrittelyyn:

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

Polku, jota julkisessa viitteessä ei ole, kuuluu verkkosovellukseen. Se toimii edelleen pääosoitteessa, mutta API-osoitteessa sitä ei palvella, eikä sen rakenne ole julkinen sitoumus. Korvaa se julkisella päätepisteellä tai pidä tämä integraation osa pääosoitteessa ja kerro yhteyshenkilöllesi Sursassa, mitä tarvitset.

Tarkista, miten todennat. Jos integraatio kirjautuu käyttäjän salasanalla ja istuntoevästeellä, siirrä se ensin käyttämään API-avainta. Jos se lähettää X-API-Key-otsakkeen, siirtymistä Authorization: Bearer -muotoon suositellaan, mutta se ei ole pakollista.

Tarkista verkkosi. Salli palomuurissasi ja välityspalvelimissasi lähtevä HTTPS-liikenne uuteen isäntänimeen.

Siirtyminen vaihe vaiheelta

Tee perus-URL:stä integraatiosi asetus, jos se ei vielä ole sellainen.

Kokeile uutta osoitetta lukupyynnöllä:

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

Aja integraatiosi testisarja uutta osoitetta vasten testiavaimella ja testikokoelmalla.
Vaihda osa liikenteestä, esimerkiksi yksi työprosessi tai yksi ympäristö, ja seuraa lokeistasi vastauksia 404 api.not_found, 401 ja 5xx. Jokaisessa vastauksessa on X-Request-Id; säilytä se lokiesi yhteydessä.
Vaihda loput. Pidä vanha perus-URL konfiguraatiossasi jonkin aikaa, jotta voit vaihtaa takaisin sekunneissa.

Tarkistettavaa siirtymisen jälkeen

GET /v1/health palauttaa uudessa osoitteessa saman version-arvon kuin vanhassa.
RateLimit-otsakkeet ovat mukana vastauksissa. Jos integraatiosi hidastaa itseään X-RateLimit-*-otsakkeiden mukaan, se voi jatkaa niin: molemmat otsakejoukot lähetetään. Ks. Nopeusrajoitukset ja kiintiöt.
Jos integraatiosi toimii selaimessa, se ei enää tarvitse omaa välityspalvelinta CORS-pyyntöjä varten: API-osoite sallii pyynnöt mistä tahansa alkuperästä ilman evästeitä.