API adrese un vides

Sursa API ir sava adrese, atsevišķa no adreses, ko cilvēki atver pārlūkā, lai strādātu ar Sursu. Visi ceļi sākas ar /v1.

Kur darbojas Sursa	API adrese	Šis portāls
Sursas mākonis	`https://api.sursa.com`	`https://developers.sursa.com`
Jūsu instalācija	`https://api.<your domain>`, kā to iestatījis jūsu administrators	`/developers/` API adresē
Jūsu instalācija bez atsevišķas API adreses	instalācijas galvenā adrese	`/developers/` galvenajā adresē

API adrese apkalpo tikai API: tajā nav pierakstīšanās lapas, sīkdatņu un tīmekļa saskarnes. Katrs pieprasījums tiek autentificēts ar API atslēgu vai OAuth piekļuves marķieri. Adresi var apkalpot vairāki serveri aiz slodzes līdzsvarotāja; jūsu integrācijai nav jāzina, cik to ir.

Integrācijas, kas izsauc API galvenajā adresē (piemēram, https://app.sursa.com/v1), turpina darboties. Nedaudzās atšķirības un pāreju soli pa solim sk. ceļvedī Pāreja uz API adresi.

Bāzes URL

Veidojiet katru pieprasījumu no viena bāzes URL savā konfigurācijā, lai tas pats kods darbotos jebkurā vidē:

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

Izmantojiet tikai HTTPS un neļaujiet atslēgai nonākt jūsu pieprasījumu žurnālos.

Versija un specifikācija

GET /v1/health parāda, vai adrese darbojas, un atgriež Sursas versiju, kas to apkalpo. Tā atbild bez atslēgas, tāpēc to var izmantot uzraudzībā:

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

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

Tā ir Sursas laidiena versija, nevis API versija. API versija ir tā specifikācijas info.version. API OpenAPI 3.1 specifikācija ir publicēta tajā pašā adresē bez autentifikācijas:

Ceļš	Saturs
`GET /openapi.json`	Publiskā specifikācija ar šo adresi laukā `servers`.
`GET /v1/openapi-public.json`	Tā pati specifikācija. Atbalsta `ETag` un `If-None-Match`.

Izmantojiet to, lai ģenerētu klientu, importētu API rīkā, piemēram, Postman, vai CI pārbaudītu, ka jūsu integrācija izmanto tikai gaidītās versijas operācijas. Šī portāla API rokasgrāmata ir veidota no tā paša faila.

Testēšana

Sursai nav atsevišķa testa režīma: katrs pieprasījums ar atslēgu darbojas ar tās organizācijas reālajiem datiem. Lai droši izstrādātu un testētu:

Izveidojiet izstrādei atsevišķu atslēgu ar šaurāko lomu un tvērumiem, kas darbam vajadzīgi.
Rakstiet atsevišķā kolekcijā, piemēram, sandbox, kuru redz tikai jūsu komanda, un izdzēsiet to, kad esat pabeiguši.
Ja jūsu uzņēmumam testēšanai ir atsevišķa Sursas organizācija vai instalācija, norādiet uz to bāzes URL un atslēgu. Nekas cits jūsu kodā nemainās.
Jau no sākuma padariet atkārtojumus drošus: ar katru POST un PATCH nosūtiet Idempotency-Key.

Konsole Izmēģināt katrā API rokasgrāmatas operācijas lapā sūta reālus pieprasījumus ar atslēgu, kuru tajā ielīmējat. Atslēga glabājas pārlūka cilnes atmiņā un tiek sūtīta tikai uz API adresi.

Tīkla prasības

Izejošs HTTPS savienojums (ports 443) no jūsu serveriem uz API adresi.
Ugunsmūra noteikumos, kur jūsu tīkls to ļauj, atļaujiet resursdatora nosaukumu, nevis fiksētas IP adreses: serveri aiz adreses var mainīties, kad tiek palielināta jauda.
Pārlūka lietotnes var izsaukt API tieši: atbildes atļauj jebkuru izcelsmi (Access-Control-Allow-Origin: *) bez sīkdatnēm. Ņemiet vērā, ka pārlūkā izmantota atslēga ir redzama šī pārlūka lietotājam.