17. Integrācijas API un API atslēgas

Integrācijas API ļauj tavai programmai, tabulai vai skriptam automātiski nolasīt tavu projektu datus: projektu sarakstu, kabeļu un materiālu sarakstus, sadales skapju ķēžu tabulu un spaiļu sarakstu, daudzumu izrakstu un projekta komplekta sagatavošanu. API tikai lasa: zīmējumu un projektu tas nemaina.

Kas var saņemt API atslēgu

API piekļuvi atļauj operators katram kontam atsevišķi. Kad tavam kontam piekļuve ir piešķirta, lapā Profils parādās kartīte API atslēgas; bez tās kartīte ir paslēpta. Kontam vienlaikus var būt ne vairāk kā 5 aktīvas atslēgas.

Atslēga redz tos pašus projektus, ko tu: tavus paša un, pēc pieprasījuma, tos, kas ar tevi kopīgoti. Kopīgota projekta sarakstus un daudzumu izrakstu tā izsniedz tikai tad, ja kopīgošana atļauj arī eksportu.

Atslēgas izveide

Lapas Profils kartītē API atslēgas noklikšķini uz Jauna atslēga.
Dod atslēgai nosaukumu (piemēram, tās programmas nosaukumu, kas to izmantos).
Izvēlies darbības jomu: Projektu lasīšana dod projektu sarakstu un projektu datus, Dokumentu lasīšana dod sarakstus, daudzumu izrakstu un projekta komplektu. Izvēlies tikai to, kas programmai tiešām vajadzīgs.
Izvēlies derīgumu: 30, 90 vai 365 dienas. Beigusies atslēga vairs nedarbojas; tās vietā izveido jaunu.
Ievadi savu pašreizējo paroli (kontam bez paroles nepieciešama svaiga pieteikšanās). Pirmajai atslēgai apstiprini API lietošanas noteikumus.

Pēc izveides atslēga tiek parādīta tikai vienu reizi: nokopē to un glabā drošā vietā. Vēlāk sarakstā redzams tikai tās prefikss (avk_…) ar izveides un derīguma beigu datumu, pēdējo lietošanu un izsaukumu skaitu. Par jauno atslēgu sūtām arī e-pasta paziņojumu (bez pašas atslēgas).

Atslēgas atsaukšana

Ar pogu Atsaukt blakus atslēgai kartītē atslēga uzreiz kļūst nelietojama; to nevar atcelt. Atsauc atslēgu, kad to vairs neizmanto, kad likvidē programmu, kas to izmantoja, vai kad aizdomas, ka tā ir noplūdusi.

Drošības ieteikumi

Izturies pret atslēgu kā pret savu paroli: kas to zina, tas var lasīt tavus projektus piešķirtajā darbības jomā.
Glabā to noslēpumu glabātuvē (paroļu pārvaldnieks, servera vides mainīgais vai CI slepenais mainīgais), nevis pirmkodā: nepievieno to git repozitorijam, kopīgotai tabulai vai e-pastam.
Neizmanto to kodā, kas darbojas pārlūkprogrammā (tīmekļa lapa, pārlūka paplašinājums): tur to var nolasīt ikviens. Atslēgas vieta ir serverī, skriptā vai darbvirsmas programmā.
Dod katrai programmai savu atslēgu ar pēc iespējas šaurāku darbības jomu un īsu derīgumu; tā vienas atslēgas atsaukšana neapturēs neko citu.

Lietošana no programmas

Atslēgu pieprasījuma galvenē sūta kā Bearer token: Authorization: Bearer avk_…. Galapunkti atrodas zem /api/v1/ (piemēram, GET /api/v1/projects), un atbilde ir JSON. Precīzs apraksts OpenAPI formā ir pieejams adresē /api/v1/openapi.json; lielākā daļa izstrādes rīku to var importēt.

Izsaukumu skaits ir ierobežots katrai atslēgai un katram kontam (pēc noklusējuma 60 minūtē un 10 000 dienā); pārsniedzot to, serveris atbild ar 429, tāpēc nedaudz uzgaidi. Pieteikšanās tīmekļa vietnē (sīkfails) API neatver, un atslēga tevi tīmekļa saskarnē nepiesaista.