API-cím és környezetek

A Sursa API-nak saját címe van, külön attól a címtől, amelyen a felhasználók a böngészőben megnyitják a Sursát. Minden útvonal /v1 előtaggal kezdődik.

Ahol a Sursa fut	API-cím	Ez a portál
Sursa-felhő	`https://api.sursa.com`	`https://developers.sursa.com`
Saját telepítés	`https://api.<your domain>`, ahogy az adminisztrátorod beállította	`/developers/` az API-címen
Saját telepítés külön API-cím nélkül	a telepítés fő címe	`/developers/` a fő címen

Az API-cím csak az API-t szolgálja ki: nincs rajta bejelentkezési oldal, nincsenek sütik és nincs webes felület. Minden kérés API-kulccsal vagy OAuth-hozzáférési tokennel hitelesül. A címet egy terheléselosztó mögött több szerver is kiszolgálhatja; az integrációdnak nem kell tudnia, hány van belőlük.

A fő címen (például https://app.sursa.com/v1) hívó integrációk tovább működnek. A néhány eltérést és a lépésenkénti átállást az Átállás az API-címre útmutató írja le.

Alap-URL

Minden kérést a konfigurációd egyetlen alap-URL-jéből építs fel, hogy ugyanaz a kód bármely környezetben fusson:

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

Csak HTTPS-t használj, és a kulcsot tartsd távol az általad küldött kérések naplóitól.

Verzió és specifikáció

A GET /v1/health megmutatja, hogy a cím elérhető-e, és visszaadja az azt kiszolgáló Sursa verzióját. Kulcs nélkül is válaszol, így a monitorozásban is használhatod:

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

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

Ez a Sursa-kiadás verziója, nem az API-é. Az API verziója a specifikációjának info.version mezője. Az API OpenAPI 3.1-specifikációja ugyanezen a címen, hitelesítés nélkül érhető el:

Útvonal	Tartalom
`GET /openapi.json`	A nyilvános specifikáció, a `servers` mezőben ezzel a címmel.
`GET /v1/openapi-public.json`	Ugyanez a specifikáció. Támogatja az `ETag` és az `If-None-Match` fejlécet.

Használd kliens generálására, az API importálására egy eszközbe, például a Postmanbe, vagy arra, hogy a CI-ban ellenőrizd: az integrációd csak a várt verzió műveleteit használja. A portál API-referenciája ugyanebből a fájlból készül.

Tesztelés

A Sursának nincs külön tesztmódja: a kulccsal küldött minden kérés a szervezete valódi adataival dolgozik. A biztonságos fejlesztéshez és teszteléshez:

Hozz létre külön fejlesztői kulcsot a munkához szükséges legszűkebb szerepkörrel és hatókörökkel.
Egy erre a célra létrehozott gyűjteménybe írj, például sandbox, amelyet csak a csapatod lát, és ha végeztél, töröld.
Ha a cégednek külön Sursa-szervezete vagy -telepítése van tesztelésre, arra irányítsd az alap-URL-t és a kulcsot. A kódodban semmi más nem változik.
Kezdettől fogva tedd biztonságossá az újrapróbálkozást: minden POST és PATCH kéréssel küldj Idempotency-Key fejlécet.

Az API-referencia minden végpontoldalán található Kipróbálás konzol valódi kéréseket küld a bele bemásolt kulccsal. A kulcs a böngészőlap memóriájában marad, és a konzol csak az API-címre küldi el.

Hálózati követelmények

Kimenő HTTPS (443-as port) a szervereidről az API-címre.
Ahol a hálózatod megengedi, a tűzfalszabályokban a gépnevet engedélyezd, ne rögzített IP-címeket: a cím mögötti szerverek a kapacitás bővítésével változhatnak.
A böngészős alkalmazások közvetlenül is hívhatják az API-t: a válaszok sütik nélkül bármely eredetet megengednek (Access-Control-Allow-Origin: *). Ne feledd: a böngészőben használt kulcsot a böngésző felhasználója látja.