Flyt til API-adressen

Tidligere integrationer kalder API’et på Sursas hovedadresse, den, som folk åbner i browseren, fx https://app.sursa.com/v1/…. API’et har nu også sin egen adresse, https://api.sursa.com i Sursas cloud eller https://api.<your domain> i din installation. Den er bygget til integrationer: Den skalerer ud bag en load balancer, og den leverer kun API’et.

Du behøver ikke flytte. Hovedadressen bliver ved med at levere /v1 til eksisterende integrationer, uden slutdato og uden omdirigering. Flyt, når det passer dig, for at få fordelene ved API-adressen, og brug den til alle nye integrationer.

Hvad der forbliver det samme

• Stier, parametre, felter, fejlkoder og hændelser: GET /v1/cards er den samme anmodning på begge adresser.
• API-nøgler. De samme kb_- og kbsrc_-nøgler virker på begge adresser med samme rolle, scopes og dataprofil.
• Idempotensnøgler, hastighedsgrænser og kvoter. Anmodninger på begge adresser tæller med i organisationens samme kvoter.
• Webhooks. Leveringer, signaturer og hemmeligheder afhænger ikke af den adresse, du kalder.
• Links i svar. En fejls doc_url peger på denne portal, og headeren Link på en listeside peger på API-adressen, uanset hvilken adresse du kalder.

Hvad der er anderledes på API-adressen

Den sidste række har kun betydning i ét tilfælde: et streamet svar fra POST /v1/chat. En afbrudt stream fortsætter fra Last-Event-ID kun på den server, der skriver svaret. Genoptager din integration streams, så giv hvert spørgsmål et request_id, så et nyt forsøg på en anden server modtager det gemte svar i stedet for et nyt. Se Genoptag en afbrudt stream.

Før du flytter

Kontrollér, at alle kald er offentlige. Lav en liste over de stier, din integration kalder, og slå hver af dem op i API-referencen, eller sammenlign dem med specifikationen på den nye adresse:

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 sti, der mangler i den offentlige reference, hører til webapplikationen. Den virker stadig på hovedadressen, men den leveres ikke på API-adressen, og dens form er ikke et offentligt tilsagn. Erstat den med en offentlig operation, eller behold den del af integrationen på hovedadressen, og fortæl din kontaktperson hos Sursa, hvad du har brug for.

Kontrollér, hvordan du autentificerer. Logger integrationen ind med en brugers adgangskode og en sessionscookie, så flyt den først over på en API-nøgle. Sender den X-API-Key, anbefales det at skifte til Authorization: Bearer, men det er ikke påkrævet.

Kontrollér dit netværk. Tillad udgående HTTPS til det nye værtsnavn i din firewall og dine proxyer.

Flyt trin for trin

1. Gør basis-URL’en til en indstilling i din integration, hvis den ikke allerede er det.

2. Afprøv den nye adresse med en læseanmodning:

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

3. Kør testsuiten for din integration mod den nye adresse med en testnøgle og en testsamling.

4. Skift en del af trafikken, fx én worker eller ét miljø, og hold øje med 404 api.not_found, 401 og 5xx i dine logge. Hvert svar har X-Request-Id; gem det sammen med dine logge.

5. Skift resten. Behold den gamle basis-URL i din konfiguration et stykke tid, så du kan skifte tilbage på få sekunder.

Hvad du skal kontrollere efter flytningen

• GET /v1/health på den nye adresse returnerer den samme version som på den gamle.
• Svarene har RateLimit-headerne. Bremser din integration sig selv efter X-RateLimit-*, kan den fortsætte med det: Begge sæt sendes. Se Hastighedsgrænser og kvoter.
• Kører din integration i en browser, behøver den ikke længere din egen proxy til CORS: API-adressen tillader anmodninger fra enhver oprindelse uden cookies.