Pereiti prie turinio
Sursa Developers

API adresas ir aplinkos

Sursa API turi savo adresą, atskirą nuo adreso, kuriuo žmonės atidaro Sursą naršyklėje. Visi keliai prasideda /v1.

Kur veikia SursaAPI adresasŠis portalas
Sursos debesishttps://api.sursa.comhttps://developers.sursa.com
Jūsų diegimashttps://api.<your domain>, kaip nustatė jūsų administratorius/developers/ API adresu
Jūsų diegimas be atskiro API adresopagrindinis diegimo adresas/developers/ pagrindiniu adresu

API adresas aptarnauja tik API: jame nėra prisijungimo puslapio, slapukų ir žiniatinklio sąsajos. Kiekviena užklausa autentifikuojama API raktu arba OAuth prieigos žetonu. Adresą gali aptarnauti keli serveriai už apkrovos balansavimo įrenginio; jūsų integracijai nereikia žinoti, kiek jų yra.

Integracijos, kurios kviečia API pagrindiniu adresu (pavyzdžiui, https://app.sursa.com/v1), toliau veikia. Keli skirtumai ir perėjimas žingsnis po žingsnio aprašyti instrukcijoje Perėjimas prie API adreso.

Bazinis URL

Kiekvieną užklausą sudarykite iš vieno bazinio URL, nurodyto konfigūracijoje, – tada tas pats kodas veiks bet kurioje aplinkoje:

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

Naudokite tik HTTPS ir neleiskite raktui patekti į savo siunčiamų užklausų žurnalus.

Versija ir specifikacija

GET /v1/health parodo, ar adresas veikia, ir grąžina jį aptarnaujančios Sursos versiją. Ji atsako be rakto, todėl ją galima naudoti stebėsenai:

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

Tai Sursos išleistos versijos, o ne API versija. API versija – jos specifikacijos info.version. API OpenAPI 3.1 specifikacija skelbiama tuo pačiu adresu, be autentifikavimo:

KeliasTurinys
GET /openapi.jsonViešoji specifikacija su šiuo adresu lauke servers.
GET /v1/openapi-public.jsonTa pati specifikacija. Palaiko ETag ir If-None-Match.

Naudokite ją klientui sugeneruoti, API importuoti į įrankį, pavyzdžiui, Postman, arba CI patikrinti, kad jūsų integracija naudoja tik laukiamos versijos operacijas. Šio portalo API žinynas sudaromas iš to paties failo.

Testavimas

Atskiro bandomojo režimo Sursa neturi: kiekviena užklausa su raktu veikia tikrus savo organizacijos duomenis. Kad kurtumėte ir testuotumėte saugiai:

  • Kūrimui sukurkite atskirą raktą su siauriausiu vaidmeniu ir apimtimis, kurių reikia darbui.
  • Rašykite į tam skirtą rinkinį, pavyzdžiui, sandbox, kurį mato tik jūsų komanda, o kai baigsite darbą, jį ištrinkite.
  • Jei jūsų įmonė turi atskirą Sursos organizaciją ar diegimą testavimui, nukreipkite į jį bazinį URL ir raktą. Daugiau jūsų kode niekas nesikeičia.
  • Pakartojimus padarykite saugius nuo pat pradžių: su kiekviena POST ir PATCH užklausa siųskite Idempotency-Key.

Kiekviename API žinyno operacijos puslapyje esanti konsolė Išbandyti siunčia tikras užklausas su raktu, kurį į ją įklijuojate. Raktas laikomas tik naršyklės skirtuko atmintyje ir siunčiamas tik API adresu.

Tinklo reikalavimai

  • Išeinantis HTTPS (443 prievadas) iš jūsų serverių į API adresą.
  • Jei jūsų tinklas leidžia, ugniasienės taisyklėse leiskite pagrindinio kompiuterio vardą, o ne fiksuotus IP adresus: didinant pajėgumus, serveriai už adreso gali keistis.
  • Naršyklės programos gali kviesti API tiesiogiai: atsakai leidžia bet kokią kilmę (Access-Control-Allow-Origin: *) be slapukų. Atminkite, kad naršyklėje naudojamą raktą mato tos naršyklės naudotojas.