17. Integrační API a API klíče

Integrační API slouží k tomu, aby tvůj vlastní program, tabulka nebo skript strojově načítal data tvých projektů: seznam projektů, seznam kabelů a materiálu, tabulku obvodů a seznam svorek rozvaděčů, výkaz množství a sestavení balíku plánů. API pouze čte: výkres ani projekt nemění.

Kdo může získat API klíč

API klíč povoluje provozovatel pro každý účet zvlášť. Pokud tvůj účet získal oprávnění, na stránce Profil se zobrazí karta Klíče API; bez něj se karta nezobrazuje. Jeden účet může mít najednou nejvýše 5 aktivních klíčů.

Klíč vidí stejné projekty jako ty: tvé vlastní a na požádání ty, které s tebou někdo sdílel. Seznamy a výkaz sdíleného projektu vydá pouze tehdy, pokud sdílení povoluje i export.

Vytvoření klíče

Na kartě Klíče API na stránce Profil klikni na Nový klíč.
Dej klíči název (například název programu, který jej bude používat).
Vyber rozsah: Čtení projektů poskytuje seznam projektů a data projektů, Čtení dokumentů poskytuje seznamy, výkaz a balík plánů. Zadej jen to, co program skutečně potřebuje.
Vyber platnost: 30, 90 nebo 365 dní. Klíč s prošlou platností už nefunguje; místo něj vytvoříš nový.
Zadej své aktuální heslo (u účtu bez hesla je nutné čerstvé přihlášení). U prvního klíče přijmi podmínky používání API.

Po vytvoření se klíč zobrazí pouze jednou: zkopíruj jej a ulož na bezpečné místo. Později se v seznamu zobrazí jen jeho předpona (avk_…) s datem vytvoření a konce platnosti, posledním použitím a počtem volání. O novém klíči posíláme také e-mailové upozornění (bez samotného klíče).

Zrušení klíče

Tlačítkem Zrušit klíč vedle klíče se klíč okamžitě stane nepoužitelným; to nelze vzít zpět. Klíč zruš, pokud jej již nepoužíváš, pokud zrušíš program, který jej používal, nebo pokud máš podezření, že unikl.

Bezpečnostní rady

S klíčem zacházej jako se svým heslem: kdo jej zná, může v rámci daného rozsahu číst tvé projekty.
Ukládej jej do úložiště tajemství (správce hesel, proměnná prostředí serveru nebo tajná proměnná CI), ne do zdrojového kódu: nesmí se dostat do repozitáře git, do sdílené tabulky ani do e-mailu.
Nepoužívej jej v kódu, který běží v prohlížeči (webová stránka, rozšíření prohlížeče): tam jej může přečíst kdokoli. Klíč patří na server, do skriptu nebo do desktopového programu.
Každý program ať má vlastní klíč s co nejužším rozsahem a krátkou platností; zrušení jednoho klíče tak nezastaví nic jiného.

Použití z programu

V hlavičce požadavku se klíč posílá jako token Bearer: Authorization: Bearer avk_…. Koncové body jsou pod /api/v1/ (například GET /api/v1/projects) a odpověď je ve formátu JSON. Přesný popis ve formátu OpenAPI je dostupný na adrese /api/v1/openapi.json; většina vývojářských nástrojů jej umí načíst.

Počet volání je omezen na klíč i na účet (výchozí 60 za minutu a 10 000 za den); při překročení server odpoví kódem 429, v takovém případě chvíli počkej. Webové přihlášení (cookie) API neotevře a klíč tě do webového rozhraní nepřihlásí.