Mine sisu juurde
Sursa Developers

API-aadress ja keskkonnad

Sursa API-l on oma aadress, mis on eraldi aadressist, millega inimesed avavad Sursa brauseris. Kõik teed algavad osaga /v1.

Kus Sursa töötabAPI-aadressSee portaal
Sursa pilvhttps://api.sursa.comhttps://developers.sursa.com
Teie oma paigaldushttps://api.<your domain>, nagu administraator on selle seadistanud/developers/ API-aadressil
Teie paigaldus ilma eraldi API-aadressitapaigalduse põhiaadress/developers/ põhiaadressil

API-aadress teenindab ainult API-t: sellel ei ole sisselogimislehte, küpsiseid ega veebiliidest. Iga päring autenditakse API-võtmega või OAuth-juurdepääsuloaga. Aadressi võib teenindada mitu serverit koormusjaoturi taga; teie integratsioon ei pea teadma, mitu neid on.

Integratsioonid, mis kutsuvad API-t põhiaadressil (näiteks https://app.sursa.com/v1), töötavad edasi. Väheseid erinevusi ja samm-sammult üleminekut kirjeldab juhend Üleminek API-aadressile.

Baas-URL

Koostage iga päring konfiguratsioonis oleva ühe baas-URL-i põhjal, et sama kood töötaks mis tahes keskkonnas:

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

Kasutage ainult HTTPS-i ja ärge laske võtmel sattuda oma päringute logidesse.

Versioon ja spetsifikatsioon

GET /v1/health ütleb, kas aadress töötab, ja tagastab seda teenindava Sursa versiooni. See vastab ilma võtmeta, seega saate seda kasutada seires:

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

See on Sursa väljalaske versioon, mitte API versioon. API versioon on selle spetsifikatsiooni info.version. API OpenAPI 3.1 spetsifikatsioon on avaldatud samal aadressil ilma autentimiseta:

TeeSisu
GET /openapi.jsonAvalik spetsifikatsioon, mille väljal servers on see aadress.
GET /v1/openapi-public.jsonSama spetsifikatsioon. Toetab päiseid ETag ja If-None-Match.

Kasutage seda kliendi genereerimiseks, API importimiseks tööriista, näiteks Postmani, või CI-s kontrollimiseks, et teie integratsioon kasutab ainult oodatud versiooni toiminguid. Selle portaali API teatmik on ehitatud samast failist.

Testimine

Sursal ei ole eraldi testrežiimi: iga võtmega tehtud päring mõjutab selle organisatsiooni päris andmeid. Turvaliseks arendamiseks ja testimiseks:

  • Looge arenduseks eraldi võti, millel on töö jaoks vajalik kitsaim roll ja ulatused.
  • Kirjutage selleks ette nähtud kogusse, näiteks sandbox, mida näeb ainult teie meeskond, ja kustutage see, kui olete lõpetanud.
  • Kui teie ettevõttel on testimiseks eraldi Sursa organisatsioon või paigaldus, suunake baas-URL ja võti sellele. Muu teie koodis ei muutu.
  • Muutke korduskatsed algusest peale turvaliseks: saatke iga päringuga POST ja PATCH päis Idempotency-Key.

API teatmiku iga lõpp-punkti lehel olev konsool Proovi saadab päris päringuid võtmega, mille sinna kleebite. Võti jääb brauseri vahekaardi mällu ja see saadetakse ainult API-aadressile.

Võrgunõuded

  • Väljuv HTTPS-ühendus (port 443) teie serveritest API-aadressile.
  • Kui teie võrk seda võimaldab, lubage tulemüüri reeglites hostinimi, mitte kindlad IP-aadressid: aadressi taga olevad serverid võivad võimsuse lisamisel muutuda.
  • Brauserirakendused võivad API-t otse kutsuda: vastused lubavad mis tahes päritolu (Access-Control-Allow-Origin: *) ilma küpsisteta. Pidage meeles, et brauseris kasutatav võti on selle brauseri kasutajale nähtav.