Flytt til API-adressen

Tidligere integrasjoner kaller API-et på Sursas hovedadresse, den folk åpner i nettleseren, for eksempel https://app.sursa.com/v1/…. API-et har nå også sin egen adresse, https://api.sursa.com i skyen eller https://api.<your domain> i installasjonen din. Den er laget for integrasjoner: Den skalerer ut bak en lastbalanserer og betjener ikke noe annet enn API-et.

Du trenger ikke å flytte. Hovedadressen fortsetter å betjene /v1 for eksisterende integrasjoner, uten sluttdato og uten omdirigering. Flytt når det passer deg, for å få fordelene med API-adressen, og bruk den for alle nye integrasjoner.

Hva som forblir det samme

• Banene, parameterne, feltene, feilkodene og hendelsene: GET /v1/cards er den samme forespørselen på begge adressene.
• API-nøkler. De samme kb_- og kbsrc_-nøklene virker på begge adressene, med samme rolle, scopes og dataprofil.
• Idempotensnøkler, hastighetsgrenser og kvoter. Forespørsler på begge adressene teller mot de samme kvotene for organisasjonen.
• Webhooks. Leveranser, signaturer og hemmeligheter avhenger ikke av hvilken adresse du kaller.
• Lenker i svar. doc_url i et feilsvar peker til denne portalen, og Link-headeren på en listeside peker til API-adressen, uansett hvilken adresse du kaller.

Hva som er annerledes på API-adressen

Den siste raden har betydning i bare ett tilfelle: et strømmet svar fra POST /v1/chat. En avbrutt strøm fortsetter fra Last-Event-ID bare på serveren som skriver svaret. Hvis integrasjonen din gjenopptar strømmer, gir du hvert spørsmål en request_id, slik at et nytt forsøk på en annen server mottar det lagrede svaret i stedet for et nytt svar. Se Gjenoppta en avbrutt strøm.

Før du flytter

Kontroller at alle kall er offentlige. Lag en liste over banene integrasjonen din kaller, og slå opp hver av dem i API-referansen, eller sammenlign dem med spesifikasjonen på den nye 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 bane som mangler i den offentlige referansen, hører til nettapplikasjonen. Den virker fortsatt på hovedadressen, men betjenes ikke på API-adressen, og formen på den er ingen offentlig forpliktelse. Erstatt den med en offentlig operasjon, eller behold den delen av integrasjonen på hovedadressen og fortell kontaktpersonen din hos Sursa hva du trenger.

Kontroller hvordan du autentiserer. Hvis integrasjonen logger på med en brukers passord og en øktinformasjonskapsel, flytter du den først over til en API-nøkkel. Hvis den sender X-API-Key, anbefales det å bytte til Authorization: Bearer, men det er ikke påkrevd.

Kontroller nettverket ditt. Tillat utgående HTTPS til det nye vertsnavnet i brannmuren og proxyene dine.

Flytt steg for steg

1. Gjør basis-URL-en til en innstilling i integrasjonen din, hvis den ikke allerede er det.

2. Prøv den nye adressen med en leseforespørsel:

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

3. Kjør testpakken for integrasjonen din mot den nye adressen, med en testnøkkel og en testsamling.

4. Flytt en del av trafikken, for eksempel én arbeidsprosess eller ett miljø, og se etter 404 api.not_found, 401 og 5xx i loggene dine. Hvert svar har X-Request-Id; ta vare på den sammen med loggene.

5. Flytt resten. Behold den gamle basis-URL-en i konfigurasjonen en stund, slik at du kan bytte tilbake på sekunder.

Dette bør du kontrollere etter flyttingen

• GET /v1/health på den nye adressen returnerer samme version som på den gamle.
• RateLimit-headerne finnes i svarene. Hvis integrasjonen din bremser seg selv etter X-RateLimit-*, kan den fortsette med det: Begge settene sendes. Se Hastighetsgrenser og kvoter.
• Hvis integrasjonen din kjører i en nettleser, trenger den ikke lenger din egen proxy for CORS: API-adressen tillater forespørsler fra alle opprinnelser, uten informasjonskapsler.