API-osoite ja ympäristöt

Sursa API:lla on oma osoitteensa, joka on eri kuin osoite, jolla ihmiset avaavat Sursan selaimessa. Kaikki polut alkavat merkkijonolla /v1.

Missä Sursa toimii	API-osoite	Tämä portaali
Sursan pilvi	`https://api.sursa.com`	`https://developers.sursa.com`
Oma asennuksesi	`https://api.<your domain>` ylläpitäjäsi määrityksen mukaan	`/developers/` API-osoitteessa
Oma asennuksesi ilman erillistä API-osoitetta	asennuksen pääosoite	`/developers/` pääosoitteessa

API-osoite palvelee vain API:a: siinä ei ole kirjautumissivua, evästeitä eikä verkkokäyttöliittymää. Jokainen pyyntö todennetaan API-avaimella tai OAuth-käyttöoikeustunnuksella. Osoitetta voi palvella useampi API-instanssi kuormantasaajan takana; integraatiosi ei tarvitse tietää, montako niitä on.

Integraatiot, jotka kutsuvat API:a pääosoitteessa (esimerkiksi https://app.sursa.com/v1), toimivat edelleen. Muutamat erot ja siirtymisen vaihe vaiheelta kuvaa opas Siirtyminen API-osoitteeseen.

Perus-URL

Muodosta jokainen pyyntö yhdestä konfiguraatiossasi määritetystä perus-URL:stä, jotta sama koodi toimii missä tahansa ympäristössä:

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

Käytä vain HTTPS:ää ja pidä avain poissa tekemiesi pyyntöjen lokeista.

Versio ja määrittely

GET /v1/health kertoo, onko osoite toiminnassa, ja palauttaa osoitetta palvelevan Sursan version. Se vastaa ilman avainta, joten voit käyttää sitä valvonnassa:

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

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

Tämä on Sursa-julkaisun versio eikä API:n versio. API:n versio on sen määrittelyn info.version. API:n OpenAPI 3.1 -määrittely julkaistaan samassa osoitteessa ilman todennusta:

Polku	Sisältö
`GET /openapi.json`	Julkinen määrittely, jonka `servers`-kentässä on tämä osoite.
`GET /v1/openapi-public.json`	Sama määrittely. Tukee `ETag`- ja `If-None-Match`-otsakkeita.

Käytä sitä asiakaskirjaston luomiseen, API:n tuomiseen esimerkiksi Postmanin kaltaiseen työkaluun tai sen tarkistamiseen CI:ssä, että integraatiosi käyttää vain odottamasi version toimintoja. Tämän portaalin API-viite rakennetaan samasta tiedostosta.

Testaus

Sursassa ei ole erillistä testitilaa: jokainen avaimella tehty pyyntö kohdistuu sen organisaation todellisiin tietoihin. Näin kehität ja testaat turvallisesti:

Luo kehitystä varten erillinen avain, jolla on suppein työn vaatima rooli ja käyttöalueet.
Kirjoita erilliseen kokoelmaan, esimerkiksi sandbox, jonka vain tiimisi näkee, ja poista se, kun olet valmis.
Jos yritykselläsi on testausta varten erillinen Sursa-organisaatio tai -asennus, ohjaa perus-URL ja avain siihen. Muu koodisi ei muutu.
Tee uusintayrityksistä turvallisia alusta alkaen: lähetä Idempotency-Key jokaisen POST- ja PATCH-pyynnön mukana.

API-viitteen jokaisen päätepistesivun Kokeile-konsoli lähettää todellisia pyyntöjä avaimella, jonka liität siihen. Avain säilyy selaimen välilehden muistissa ja lähetetään vain API-osoitteeseen.

Verkkovaatimukset

Lähtevä HTTPS-liikenne (portti 443) palvelimiltasi API-osoitteeseen.
Salli palomuurisäännöissä mieluummin isäntänimi kuin kiinteät IP-osoitteet, jos verkkosi sen sallii: osoitteen takana olevat instanssit voivat vaihtua, kun kapasiteettia lisätään.
Selainsovellukset voivat kutsua API:a suoraan: vastaukset sallivat minkä tahansa alkuperän (Access-Control-Allow-Origin: *) ilman evästeitä. Muista, että selaimessa käytetty avain näkyy selaimen käyttäjälle.