Adresa API-ja i okruženja

Sursa API ima vlastitu adresu, odvojenu od adrese na kojoj ljudi otvaraju Sursu u pregledniku. Sve putanje počinju s /v1.

Gdje Sursa radi	Adresa API-ja	Ovaj portal
Oblak Surse	`https://api.sursa.com`	`https://developers.sursa.com`
Vaša vlastita instalacija	`https://api.<your domain>`, kako ju je postavio vaš administrator	`/developers/` na adresi API-ja
Vaša instalacija bez zasebne adrese API-ja	glavna adresa instalacije	`/developers/` na glavnoj adresi

Adresa API-ja služi samo API-ju: na njoj nema stranice za prijavu, kolačića ni web-sučelja. Svaki se zahtjev autentificira API ključem ili OAuth pristupnim tokenom. Adresu može posluživati više poslužitelja iza uravnoteživača opterećenja; vaša integracija ne mora znati koliko ih ima.

Integracije koje pozivaju API na glavnoj adresi (na primjer https://app.sursa.com/v1) i dalje rade. U vodiču Prijelaz na adresu API-ja opisano je nekoliko razlika i prijelaz korak po korak.

Osnovni URL

Svaki zahtjev gradite od jednog osnovnog URL-a u svojoj konfiguraciji, kako bi isti kod radio u bilo kojem okruženju:

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

Koristite samo HTTPS i ne zapisujte ključ u zapisnike zahtjeva koje šaljete.

Verzija i specifikacija

GET /v1/health pokazuje radi li adresa i vraća verziju Surse koja je poslužuje. Odgovara bez ključa, pa ga možete koristiti za nadzor:

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

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

To je verzija izdanja Surse, a ne API-ja. Verzija API-ja je info.version njegove specifikacije. Specifikacija API-ja u formatu OpenAPI 3.1 objavljena je na istoj adresi, bez autentifikacije:

Putanja	Sadržaj
`GET /openapi.json`	Javna specifikacija, s ovom adresom u `servers`.
`GET /v1/openapi-public.json`	Ista specifikacija. Podržava `ETag` i `If-None-Match`.

Koristite je za generiranje klijenta, za uvoz API-ja u alat kao što je Postman ili za provjeru u CI-ju da vaša integracija koristi samo operacije verzije koju očekujete. Referenca API-ja na ovom portalu izgrađena je iz iste datoteke.

Testiranje

Sursa nema zaseban testni način rada: svaki zahtjev s ključem djeluje na stvarne podatke njegove organizacije. Da biste sigurno razvijali i testirali:

Za razvoj stvorite zaseban ključ s najužom ulogom i opsezima koji su potrebni za posao.
Pišite u namjensku zbirku, na primjer sandbox, koju vidi samo vaš tim, i izbrišite je kad završite.
Ako vaša tvrtka ima zasebnu organizaciju ili instalaciju Surse za testiranje, usmjerite osnovni URL i ključ na nju. Ništa se drugo u vašem kodu ne mijenja.
Od početka osigurajte da su ponovni pokušaji sigurni: uz svaki POST i PATCH pošaljite Idempotency-Key.

Konzola Isprobajte na stranici svake operacije u referenci API-ja šalje stvarne zahtjeve s ključem koji u nju zalijepite. Ključ ostaje u memoriji kartice preglednika i šalje se samo na adresu API-ja.

Mrežni preduvjeti

Odlazni HTTPS (priključak 443) s vaših poslužitelja prema adresi API-ja.
U pravilima vatrozida, gdje vaša mreža to dopušta, dopustite naziv hosta umjesto fiksnih IP adresa: poslužitelji iza adrese mogu se mijenjati kako se dodaje kapacitet.
Aplikacije u pregledniku mogu izravno pozivati API: odgovori dopuštaju bilo koji origin (Access-Control-Allow-Origin: *) bez kolačića. Imajte na umu da je ključ koji se koristi u pregledniku vidljiv korisniku tog preglednika.