17. Integračné API a API kľúče

Integračné API slúži na to, aby tvoj vlastný program, tabuľka alebo skript strojovo načítal údaje tvojich projektov: zoznam projektov, zoznam káblov a materiálu, tabuľku obvodov a zoznam svoriek rozvádzačov, výkaz množstiev a zostavenie balíka plánov. API iba číta: výkres ani projekt nemení.

Kto môže dostať API kľúč

API kľúč povoľuje prevádzkovateľ pre každý účet zvlášť. Ak tvoj účet získal oprávnenie, na stránke Profil sa zobrazí karta API kľúče; bez neho sa karta nezobrazuje. Jeden účet môže mať naraz najviac 5 aktívnych kľúčov.

Kľúč vidí tie isté projekty ako ty: tvoje vlastné a na požiadanie tie, ktoré s tebou zdieľali. Zoznamy a výkaz zdieľaného projektu vydá iba vtedy, ak zdieľanie povoľuje aj export.

Vytvorenie kľúča

Na karte API kľúče na stránke Profil klikni na Nový kľúč.
Daj kľúču názov (napríklad názov programu, ktorý ho bude používať).
Vyber rozsah: Čítanie projektov poskytuje zoznam projektov a údaje projektov, Čítanie dokumentov poskytuje zoznamy, výkaz a balík plánov. Zadaj iba to, čo program naozaj potrebuje.
Vyber platnosť: 30, 90 alebo 365 dní. Kľúč, ktorému platnosť skončila, už nefunguje; namiesto neho vytvoríš nový.
Zadaj svoje aktuálne heslo (pri účte bez hesla je potrebné čerstvé prihlásenie). Pri prvom kľúči prijmi podmienky používania API.

Po vytvorení sa kľúč zobrazí iba raz: skopíruj ho a ulož na bezpečné miesto. Neskôr sa v zozname zobrazí iba jeho predpona (avk_…) s dátumom vytvorenia a skončenia platnosti, posledným použitím a počtom volaní. O novom kľúči posielame aj e-mailové upozornenie (bez samotného kľúča).

Zrušenie kľúča

Tlačidlom Zrušiť kľúč vedľa kľúča sa kľúč okamžite stane nepoužiteľným; to sa nedá vrátiť späť. Kľúč zruš, ak ho už nepoužívaš, ak zrušíš program, ktorý ho používal, alebo ak máš podozrenie, že unikol.

Bezpečnostné rady

S kľúčom zaobchádzaj ako so svojím heslom: kto ho pozná, môže v rámci daného rozsahu čítať tvoje projekty.
Ukladaj ho do úložiska tajomstiev (správca hesiel, premenná prostredia servera alebo tajná premenná CI), nie do zdrojového kódu: nesmie sa dostať do repozitára git, do zdieľanej tabuľky ani do e-mailu.
Nepoužívaj ho v kóde, ktorý beží v prehliadači (webová stránka, rozšírenie prehliadača): tam ho môže prečítať ktokoľvek. Kľúč patrí na server, do skriptu alebo do desktopového programu.
Každý program nech má vlastný kľúč s čo najužším rozsahom a krátkou platnosťou; zrušenie jedného kľúča tak nezastaví nič iné.

Použitie z programu

V hlavičke požiadavky sa kľúč posiela ako token Bearer: Authorization: Bearer avk_…. Koncové body sú pod /api/v1/ (napríklad GET /api/v1/projects) a odpoveď je vo formáte JSON. Presný opis vo formáte OpenAPI je dostupný na adrese /api/v1/openapi.json; väčšina vývojárskych nástrojov ho vie načítať.

Počet volaní je obmedzený na kľúč aj na účet (predvolene 60 za minútu a 10 000 za deň); pri prekročení server odpovie kódom 429, vtedy chvíľu počkaj. Webové prihlásenie (cookie) API neotvorí a kľúč ťa do webového rozhrania neprihlási.