Preskočiť na obsah
Sursa Developers

Adresa API a prostredia

Sursa API má vlastnú adresu, oddelenú od adresy, na ktorej ľudia otvárajú Sursu v prehliadači. Všetky cesty začínajú na /v1.

Kde Sursa bežíAdresa APITento portál
Cloud Sursahttps://api.sursa.comhttps://developers.sursa.com
Vaša vlastná inštaláciahttps://api.<your domain>, ako ju nastavil váš administrátor/developers/ na adrese API
Vaša inštalácia bez samostatnej adresy APIhlavná adresa inštalácie/developers/ na hlavnej adrese

Adresa API slúži len pre API: nie je na nej prihlasovacia stránka, súbory cookie ani webové rozhranie. Každá požiadavka sa overuje kľúčom API alebo prístupovým tokenom OAuth. Adresu môže obsluhovať niekoľko serverov za vyrovnávačom záťaže; vaša integrácia nepotrebuje vedieť, koľko ich je.

Integrácie, ktoré volajú API na hlavnej adrese (napríklad https://app.sursa.com/v1), fungujú ďalej. Niekoľko rozdielov a postup krok za krokom nájdete v návode Prejdite na adresu API.

Základná URL

Každú požiadavku skladajte z jednej základnej URL vo svojej konfigurácii, aby rovnaký kód fungoval v ľubovoľnom prostredí:

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

Používajte len HTTPS a kľúč nezapisujte do logov požiadaviek, ktoré posielate.

Verzia a špecifikácia

GET /v1/health oznámi, či adresa beží, a vráti verziu Sursy, ktorá ju obsluhuje. Odpovedá bez kľúča, takže ju môžete použiť v monitoringu:

curl https://api.sursa.com/v1/health
{"ok": true, "version": "v1.4.0"}

Ide o verziu vydania Sursy, nie o verziu API. Verzia API je info.version jeho špecifikácie. Špecifikácia API vo formáte OpenAPI 3.1 je zverejnená na tej istej adrese, bez autentifikácie:

CestaObsah
GET /openapi.jsonVerejná špecifikácia s touto adresou v servers.
GET /v1/openapi-public.jsonTá istá špecifikácia. Podporuje ETag a If-None-Match.

Použite ju na vygenerovanie klienta, na import API do nástroja, napríklad Postman, alebo na kontrolu v CI, že vaša integrácia používa len operácie verzie, ktorú očakávate. Referencia API tohto portálu vzniká z toho istého súboru.

Testovanie

Sursa nemá samostatný testovací režim: každá požiadavka s kľúčom pracuje so skutočnými údajmi svojej organizácie. Ak chcete bezpečne vyvíjať a testovať:

  • Vytvorte si na vývoj samostatný kľúč s najužšou rolou a rozsahmi, aké práca potrebuje.
  • Zapisujte do vyhradenej kolekcie, napríklad sandbox, ktorú vidí len váš tím, a po skončení ju vymažte.
  • Ak má vaša firma na testovanie samostatnú organizáciu alebo inštaláciu Sursy, nasmerujte na ňu základnú URL a kľúč. Nič iné sa vo vašom kóde nemení.
  • Opakovanie požiadaviek zabezpečte od začiatku: s každou požiadavkou POST a PATCH odošlite Idempotency-Key.

Konzola Vyskúšať na stránke každej operácie v referencii API posiela skutočné požiadavky s kľúčom, ktorý do nej vložíte. Kľúč zostáva v pamäti karty prehliadača a odosiela sa len na adresu API.

Sieťové požiadavky

  • Odchádzajúce HTTPS (port 443) z vašich serverov na adresu API.
  • V pravidlách firewallu povoľte, ak to vaša sieť umožňuje, radšej názov hostiteľa než pevné IP adresy: servery za adresou sa môžu meniť, keď pribúda kapacita.
  • Aplikácie v prehliadači môžu volať API priamo: odpovede povoľujú ľubovoľný pôvod (Access-Control-Allow-Origin: *) bez súborov cookie. Majte na pamäti, že kľúč použitý v prehliadači vidí používateľ tohto prehliadača.