17. Integracijski API in ključi API

Integracijski API je namenjen temu, da tvoj lasten program, preglednica ali skripta strojno prebere podatke tvojih projektov: seznam projektov, seznam kablov in materiala, tabelo tokokrogov in seznam sponk razdelilnikov, obračun količin ter sestavo paketa načrtov. API samo bere: risbe in projekta ne spreminja.

Kdo lahko dobi ključ API

Ključ API omogoči upravljavec za vsak račun posebej. Če je tvoj račun dobil dovoljenje, se na strani Profil pojavi kartica Ključi API; brez dovoljenja kartice ni videti. Račun ima lahko hkrati največ 5 aktivnih ključev.

Ključ vidi enake projekte kot ti: tvoje lastne in na zahtevo tiste, ki so bili deljeni s teboj. Sezname in obračun deljenega projekta izda le, če deljenje dovoljuje tudi izvoz.

Ustvarjanje ključa

1. Na kartici Ključi API na strani Profil klikni Nov ključ.
2. Ključu daj ime (na primer ime programa, ki ga bo uporabljal).
3. Izberi obseg: Branje projektov daje seznam projektov in podatke projektov, Branje dokumentov daje sezname, obračun in paket načrtov. Navedi le tisto, kar program res potrebuje.
4. Izberi potek: 30, 90 ali 365 dni. Ključ, ki je potekel, ne deluje več; namesto njega ustvariš novega.
5. Vnesi svoje trenutno geslo (pri računu brez gesla je potrebna sveža prijava). Pri prvem ključu sprejmi pogoje uporabe API.

Po ustvarjanju je ključ viden le enkrat: kopiraj ga in shrani na varno mesto. Pozneje je na seznamu viden le njegova predpona (avk_…), z datumom nastanka in poteka, zadnjo uporabo in številom klicev. O novem ključu pošljemo tudi obvestilo po e-pošti (brez samega ključa).

Preklic ključa

Z gumbom Prekliči ob ključu ta takoj postane neuporaben; tega ni mogoče razveljaviti. Ključ prekliči, če ga ne uporabljaš več, če ukineš program, ki ga je uporabljal, ali če sumiš, da je pricurljal v napačne roke.

Varnostni nasveti

• S ključem ravnaj kot s svojim geslom: kdor ga pozna, lahko v dodeljenem obsegu bere tvoje projekte.
• Hrani ga v shrambi skrivnosti (upravitelj gesel, okoljska spremenljivka strežnika ali skrivna spremenljivka CI), ne v izvorni kodi: ne sme končati v repozitoriju git, v deljeni preglednici ali v e-pošti.
• Ne uporabljaj ga v kodi, ki teče v brskalniku (spletna stran, razširitev brskalnika): tam ga lahko prebere kdor koli. Ključ sodi na strežnik, v skripto ali v namizni program.
• Vsak program naj ima svoj ključ z najožjim možnim obsegom in kratkim potekom; tako preklic enega ključa ne ustavi ničesar drugega.

Uporaba iz programa

V glavi zahteve se ključ pošilja kot žeton Bearer: Authorization: Bearer avk_…. Končne točke so pod /api/v1/ (na primer GET /api/v1/projects), odgovor pa je v obliki JSON. Natančen opis v obliki OpenAPI je na voljo na naslovu /api/v1/openapi.json; večina razvojnih orodij ga zna uvoziti.

Število klicev je omejeno na ključ in na račun (privzeto 60 na minuto in 10 000 na dan); ob preseganju strežnik odgovori s kodo 429, takrat malo počakaj. Spletna prijava (piškotek) API-ja ne odpre, ključ pa te ne prijavi v spletni vmesnik.