Flytta till API-adressen

Tidigare integrationer anropar API:et på Sursas huvudadress, den som folk öppnar i webbläsaren, till exempel https://app.sursa.com/v1/…. API:et har nu också en egen adress, https://api.sursa.com i molnet eller https://api.<your domain> i din installation. Den är byggd för integrationer: den skalar ut bakom en lastbalanserare, och den betjänar ingenting annat än API:et.

Du behöver inte flytta. Huvudadressen fortsätter att betjäna /v1 för befintliga integrationer, utan slutdatum och utan omdirigering. Flytta när det passar dig, för att få fördelarna med API-adressen, och använd den för varje ny integration.

Vad som förblir detsamma

• Sökvägarna, parametrarna, fälten, felkoderna och händelserna: GET /v1/cards är samma anrop på båda adresserna.
• API-nycklarna. Samma nycklar kb_ och kbsrc_ fungerar på båda adresserna, med samma roll, omfång och dataprofil.
• Idempotensnycklar, hastighetsbegränsningar och kvoter. Anrop på båda adresserna räknas mot samma kvoter för organisationen.
• Webhookar. Leveranser, signaturer och hemligheter beror inte på vilken adress du anropar.
• Länkar i svaren. doc_url i ett fel pekar på den här portalen, och huvudet Link på en sida i en lista pekar på API-adressen, oavsett vilken adress du anropar.

Vad som skiljer sig på API-adressen

Den sista raden spelar roll i bara ett fall: ett strömmat svar från POST /v1/chat. En avbruten ström fortsätter från Last-Event-ID bara på den server som skriver svaret. Om din integration återupptar strömmar ger du varje fråga ett request_id, så att ett nytt försök på en annan server får det sparade svaret i stället för ett andra svar. Se Återuppta en avbruten ström.

Innan du flyttar

Kontrollera att varje anrop är offentligt. Lista sökvägarna som din integration anropar och slå upp var och en i API-referensen, eller jämför dem med specifikationen för den nya adressen:

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

En sökväg som saknas i den offentliga referensen hör till webbapplikationen. Den fungerar fortfarande på huvudadressen, men den betjänas inte på API-adressen, och dess form är inget offentligt åtagande. Ersätt den med en offentlig slutpunkt, eller behåll den delen av integrationen på huvudadressen och berätta för din kontaktperson på Sursa vad du behöver.

Kontrollera hur du autentiserar. Om integrationen loggar in med en användares lösenord och en sessionscookie flyttar du den först till en API-nyckel. Om den skickar X-API-Key rekommenderas ett byte till Authorization: Bearer, men det är inte nödvändigt.

Kontrollera ditt nätverk. Tillåt utgående HTTPS till det nya värdnamnet i din brandvägg och dina proxyservrar.

Flytta steg för steg

1. Gör bas-URL:en till en inställning i din integration, om den inte redan är det.

2. Prova den nya adressen med ett läsanrop:

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

3. Kör integrationens testsvit mot den nya adressen, med en testnyckel och en testsamling.

4. Flytta en del av trafiken, till exempel en arbetsprocess eller en miljö, och håll utkik efter 404 api.not_found, 401 och 5xx i dina loggar. Varje svar har X-Request-Id; spara det i dina loggar.

5. Flytta resten. Behåll den gamla bas-URL:en i din konfiguration ett tag, så att du kan byta tillbaka på några sekunder.

Att kontrollera efter flytten

• GET /v1/health på den nya adressen returnerar samma version som på den gamla.
• Huvudena RateLimit finns i svaren. Om din integration saktar ned sig själv utifrån X-RateLimit-* kan den fortsätta med det: båda uppsättningarna skickas. Se Hastighetsbegränsningar och kvoter.
• Om din integration körs i en webbläsare behöver den inte längre din egen proxy för CORS: API-adressen tillåter anrop från alla ursprung, utan cookies.