API-adress och miljöer

Sursa API har en egen adress, skild från adressen som folk använder för att öppna Sursa i webbläsaren. Alla sökvägar börjar med /v1.

Var Sursa körs	API-adress	Den här portalen
Sursa-molnet	`https://api.sursa.com`	`https://developers.sursa.com`
Din egen installation	`https://api.<your domain>`, så som din administratör har konfigurerat den	`/developers/` på API-adressen
Din installation utan separat API-adress	installationens huvudadress	`/developers/` på huvudadressen

API-adressen betjänar bara API:et: där finns ingen inloggningssida, inga cookies och inget webbgränssnitt. Varje anrop autentiseras med en API-nyckel eller en OAuth-åtkomsttoken. Adressen kan betjänas av flera servrar bakom en lastbalanserare; din integration behöver inte veta hur många de är.

Integrationer som anropar API:et på huvudadressen (till exempel https://app.sursa.com/v1) fortsätter att fungera. Se Flytta till API-adressen för de få skillnaderna och en flytt steg för steg.

Bas-URL

Bygg varje anrop utifrån en enda bas-URL i din konfiguration, så att samma kod kan köras mot vilken miljö som helst:

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

Använd bara HTTPS och håll nyckeln borta från loggarna över de anrop som du gör.

Version och specifikation

GET /v1/health visar om adressen är i drift och returnerar versionen av Sursa som betjänar den. Den svarar utan nyckel, så du kan använda den i övervakningen:

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

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

Det här är versionen av Sursa, inte av API:et. API:ets version är info.version i dess specifikation. API:ets specifikation i OpenAPI 3.1 publiceras på samma adress, utan autentisering:

Sökväg	Innehåll
`GET /openapi.json`	Den offentliga specifikationen, med den här adressen i `servers`.
`GET /v1/openapi-public.json`	Samma specifikation. Stöder `ETag` och `If-None-Match`.

Använd den för att generera en klient, för att importera API:et i ett verktyg som Postman eller för att i CI kontrollera att din integration bara använder åtgärder i den version som du förväntar dig. Portalens API-referens byggs från samma fil.

Testning

Sursa har inget separat testläge: varje anrop med en nyckel påverkar organisationens riktiga data. Så här utvecklar och testar du säkert:

Skapa en separat nyckel för utveckling med den snävaste roll och de snävaste omfång som arbetet kräver.
Skriv till en särskild samling, till exempel sandbox, som bara ditt team kan se, och ta bort den när du är klar.
Om ditt företag har en separat Sursa-organisation eller installation för testning riktar du bas-URL:en och nyckeln mot den. Inget annat i din kod ändras.
Gör nya försök säkra från början: skicka en Idempotency-Key med varje POST och PATCH.

Konsolen Prova på varje slutpunktssida i API-referensen skickar riktiga anrop med en nyckel som du klistrar in i den. Nyckeln finns bara i webbläsarflikens minne och skickas bara till API-adressen.

Krav på nätverket

Utgående HTTPS (port 443) från dina servrar till API-adressen.
Tillåt värdnamnet i stället för fasta IP-adresser i brandväggsreglerna där ditt nätverk medger det: servrarna bakom adressen kan ändras när mer kapacitet läggs till.
Webbläsarprogram kan anropa API:et direkt: svaren tillåter alla ursprung (Access-Control-Allow-Origin: *) utan cookies. Tänk på att en nyckel som används i en webbläsare syns för användaren av den webbläsaren.