API-adresse og miljøer

Sursas API har sin egen adresse, adskilt fra den adresse, folk bruger til at åbne Sursa i browseren. Alle stier begynder med /v1.

Hvor Sursa kører	API-adresse	Denne portal
Sursas cloud	`https://api.sursa.com`	`https://developers.sursa.com`
Din egen installation	`https://api.<your domain>`, som din administrator har sat den op	`/developers/` på API-adressen
Din installation uden separat API-adresse	installationens hovedadresse	`/developers/` på hovedadressen

API-adressen leverer kun API’et: Der er ingen loginside, ingen cookies og ingen webgrænseflade på den. Hver anmodning autentificeres med en API-nøgle eller et OAuth-adgangstoken. Adressen kan betjenes af flere servere bag en load balancer; din integration behøver ikke vide, hvor mange der er.

Integrationer, der kalder API’et på hovedadressen (fx https://app.sursa.com/v1), bliver ved med at virke. Se Flyt til API-adressen for de få forskelle og en flytning trin for trin.

Basis-URL

Byg alle anmodninger ud fra én basis-URL i din konfiguration, så den samme kode kører mod ethvert miljø:

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

Brug kun HTTPS, og hold nøglen ude af logge over de anmodninger, du sender.

Version og specifikation

GET /v1/health fortæller, om adressen er oppe, og returnerer versionen af den Sursa-udgivelse, der betjener den. Den svarer uden nøgle, så du kan bruge den i din overvågning:

curl https://api.sursa.com/v1/health

{"ok": true, "version": "v1.4.0"}

Det er versionen af Sursa-udgivelsen, ikke af API’et. API’ets version er info.version i dets specifikation. API’ets OpenAPI 3.1-specifikation er udgivet på samme adresse uden autentificering:

Sti	Indhold
`GET /openapi.json`	Den offentlige specifikation med denne adresse i `servers`.
`GET /v1/openapi-public.json`	Den samme specifikation. Understøtter `ETag` og `If-None-Match`.

Brug den til at generere en klient, til at importere API’et i et værktøj som Postman eller til i CI at kontrollere, at din integration kun bruger operationer fra den version, du forventer. Portalens API-reference bygges ud fra den samme fil.

Test

Sursa har ingen separat testtilstand: Hver anmodning med en nøgle udføres på organisationens rigtige data. Sådan udvikler og tester du sikkert:

Opret en separat nøgle til udvikling med den snævreste rolle og de snævreste scopes, som arbejdet kræver.
Skriv i en særskilt samling, fx sandbox, som kun dit team kan se, og slet den, når du er færdig.
Har din virksomhed en separat Sursa-organisation eller -installation til test, så lad basis-URL’en og nøglen pege på den. Intet andet i din kode ændres.
Gør nye forsøg sikre fra starten: Send en Idempotency-Key med hver POST og PATCH.

Konsollen Afprøv på hver operationsside i API-referencen sender rigtige anmodninger med en nøgle, som du indsætter i den. Nøglen bliver kun i browserfanens hukommelse og sendes kun til API-adressen.

Netværkskrav

Udgående HTTPS (port 443) fra dine servere til API-adressen.
Tillad værtsnavnet frem for faste IP-adresser i firewallregler, hvor dit netværk tillader det: Serverne bag adressen kan skifte, når der tilføjes kapacitet.
Browserapplikationer kan kalde API’et direkte: Svarene tillader enhver oprindelse (Access-Control-Allow-Origin: *) uden cookies. Husk, at en nøgle, der bruges i en browser, er synlig for den, der bruger browseren.