Přejít na obsah
Sursa Developers

Adresa API a prostředí

Sursa API má vlastní adresu, oddělenou od adresy, na které lidé otevírají Sursu v prohlížeči. Všechny cesty začínají na /v1.

Kde Sursa běžíAdresa APITento portál
Cloud Sursahttps://api.sursa.comhttps://developers.sursa.com
Vaše vlastní instalacehttps://api.<your domain>, jak ji nastavil váš administrátor/developers/ na adrese API
Vaše instalace bez samostatné adresy APIhlavní adresa instalace/developers/ na hlavní adrese

Adresa API obsluhuje jen API: není na ní přihlašovací stránka, cookies ani webové rozhraní. Každý požadavek se autentizuje klíčem API nebo přístupovým tokenem OAuth. Adresu může obsluhovat několik serverů za nástrojem pro vyrovnávání zátěže; vaše integrace nemusí vědět, kolik jich je.

Integrace, které volají API na hlavní adrese (například https://app.sursa.com/v1), fungují dál. Těch několik rozdílů a postup přechodu krok za krokem najdete v návodu Přechod na adresu API.

Základní URL

Každý požadavek sestavujte z jedné základní URL ve své konfiguraci, aby stejný kód běžel proti jakémukoli prostředí:

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

Používejte jen HTTPS a nedávejte klíč do protokolů odesílaných požadavků.

Verze a specifikace

GET /v1/health sděluje, zda je adresa v provozu, a vrací verzi Sursy, která ji obsluhuje. Odpovídá bez klíče, takže ho můžete používat v monitoringu:

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

Jde o verzi vydání Sursy, ne o verzi API. Verzi API udává info.version jeho specifikace. Specifikace API ve formátu OpenAPI 3.1 je zveřejněná na stejné adrese, bez autentizace:

CestaObsah
GET /openapi.jsonVeřejná specifikace s touto adresou v servers.
GET /v1/openapi-public.jsonTatáž specifikace. Podporuje ETag a If-None-Match.

Použijte ji k vygenerování klienta, k importu API do nástroje, jako je Postman, nebo ke kontrole v CI, že vaše integrace používá jen operace očekávané verze. Reference API tohoto portálu se sestavuje ze stejného souboru.

Testování

Sursa nemá samostatný testovací režim: každý požadavek s klíčem pracuje se skutečnými daty své organizace. Pro bezpečný vývoj a testování:

  • Pro vývoj vytvořte samostatný klíč s co nejužší rolí a rozsahy, které práce vyžaduje.
  • Zapisujte do vyhrazené kolekce, například sandbox, kterou vidí jen váš tým, a po skončení ji smažte.
  • Pokud má vaše firma pro testování samostatnou organizaci nebo instalaci Sursy, nasměrujte na ni základní URL a klíč. Nic jiného se ve vašem kódu nemění.
  • Od začátku zajistěte bezpečné opakování: s každým POST a PATCH odesílejte Idempotency-Key.

Konzole Vyzkoušet na stránce každé operace v referenci API odesílá skutečné požadavky s klíčem, který do ní vložíte. Klíč zůstává v paměti karty prohlížeče a odesílá se jen na adresu API.

Požadavky na síť

  • Odchozí HTTPS (port 443) z vašich serverů na adresu API.
  • Kde to vaše síť dovoluje, povolte v pravidlech firewallu název hostitele, ne pevné IP adresy: servery za adresou se mohou měnit s přidáváním kapacity.
  • Aplikace v prohlížeči mohou API volat přímo: odpovědi povolují jakýkoli původ (Access-Control-Allow-Origin: *) bez cookies. Mějte na paměti, že klíč použitý v prohlížeči vidí uživatel tohoto prohlížeče.