API-adresse og miljøer

Sursas API har sin egen adresse, atskilt fra adressen folk bruker når de åpner Sursa i nettleseren. Alle baner begynner med /v1.

Hvor Sursa kjører	API-adresse	Denne portalen
Sursa-skyen	`https://api.sursa.com`	`https://developers.sursa.com`
Din egen installasjon	`https://api.<your domain>`, slik administratoren din har satt den opp	`/developers/` på API-adressen
Installasjonen din uten egen API-adresse	hovedadressen til installasjonen	`/developers/` på hovedadressen

API-adressen betjener bare API-et: Den har ingen påloggingsside, ingen informasjonskapsler og ikke noe nettgrensesnitt. Hver forespørsel autentiseres med en API-nøkkel eller et OAuth-tilgangstoken. Adressen kan betjenes av flere servere bak en lastbalanserer; integrasjonen din trenger ikke å vite hvor mange det er.

Integrasjoner som kaller API-et på hovedadressen (for eksempel https://app.sursa.com/v1), fungerer fortsatt. Se Flytt til API-adressen for de få forskjellene og en flytting steg for steg.

Basis-URL

Bygg alle forespørsler fra én basis-URL i konfigurasjonen din, slik at den samme koden kjører mot alle miljøer:

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

Bruk bare HTTPS, og hold nøkkelen utenfor loggene over forespørslene du sender.

Versjon og spesifikasjon

GET /v1/health forteller om adressen er oppe, og returnerer versjonen av Sursa som betjener den. Den svarer uten nøkkel, så du kan bruke den i overvåkingen:

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

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

Dette er versjonen av Sursa-utgivelsen, ikke av API-et. Versjonen av API-et er info.version i spesifikasjonen. OpenAPI 3.1-spesifikasjonen for API-et er publisert på samme adresse, uten autentisering:

Bane	Innhold
`GET /openapi.json`	Den offentlige spesifikasjonen, med denne adressen i `servers`.
`GET /v1/openapi-public.json`	Den samme spesifikasjonen. Støtter `ETag` og `If-None-Match`.

Bruk den til å generere en klient, til å importere API-et i et verktøy som Postman eller til å kontrollere i CI at integrasjonen din bare bruker operasjoner fra den versjonen du forventer. Portalens API-referanse bygges fra den samme filen.

Teste trygt

Sursa har ingen egen testmodus: Hver forespørsel med en nøkkel arbeider på de faktiske dataene i organisasjonen nøkkelen tilhører. Slik utvikler og tester du trygt:

Opprett en egen nøkkel for utvikling med den smaleste rollen og de færreste scopene arbeidet krever.
Skriv til en egen samling, for eksempel sandbox, som bare teamet ditt kan se, og slett den når du er ferdig.
Hvis bedriften din har en egen Sursa-organisasjon eller -installasjon for testing, peker du basis-URL-en og nøkkelen mot den. Ingenting annet i koden din endres.
Gjør nye forsøk trygge fra starten av: Send en Idempotency-Key med hver POST og PATCH.

Konsollen Prøv på hver operasjonsside i API-referansen sender ekte forespørsler med en nøkkel du limer inn i den. Nøkkelen lagres bare i minnet til nettleserfanen og sendes bare til API-adressen.

Nettverkskrav

Utgående HTTPS (port 443) fra serverne dine til API-adressen.
Tillat vertsnavnet i stedet for faste IP-adresser i brannmurreglene der nettverket ditt gjør det mulig: Serverne bak adressen kan endres når kapasiteten utvides.
Nettleserapplikasjoner kan kalle API-et direkte: Svarene tillater alle opprinnelser (Access-Control-Allow-Origin: *) uten informasjonskapsler. Husk at en nøkkel som brukes i en nettleser, er synlig for brukeren av nettleseren.