17. API integracyjne i klucze API

API integracyjne służy do tego, aby Twój własny program, arkusz lub skrypt odczytywał maszynowo dane Twoich projektów: listę projektów, zestawienie kabli i materiałów, tabelę obwodów i listę zacisków rozdzielnic, przedmiar oraz zestawienie pakietu planów. API tylko odczytuje: nie zmienia ani rysunku, ani projektu.

Kto może otrzymać klucz API

Klucz API włącza operator dla każdego konta osobno. Jeśli Twoje konto otrzymało dostęp, na stronie Profil pojawia się karta Klucze API; bez dostępu karta jest niewidoczna. Jedno konto może mieć jednocześnie co najwyżej 5 aktywnych kluczy.

Klucz widzi te same projekty co Ty: Twoje własne oraz, na życzenie, te udostępnione Tobie. Zestawienia i przedmiar udostępnionego projektu wydaje tylko wtedy, gdy udostępnienie pozwala także na eksport.

Tworzenie klucza

Na karcie Klucze API na stronie Profil kliknij Nowy klucz.
Nadaj kluczowi nazwę (na przykład nazwę programu, który będzie go używał).
Wybierz zakres: Odczyt projektów daje listę projektów i dane projektów, Odczyt dokumentów daje zestawienia, przedmiar i pakiet planów. Wybierz tylko to, czego program naprawdę potrzebuje.
Wybierz wygaśnięcie: 30, 90 lub 365 dni. Wygasły klucz przestaje działać; zamiast niego tworzysz nowy.
Podaj swoje obecne hasło (w przypadku konta bez hasła potrzebne jest świeże logowanie). Przy pierwszym kluczu zaakceptuj warunki korzystania z API.

Po utworzeniu klucz jest widoczny tylko jeden raz: skopiuj go i zapisz w bezpiecznym miejscu. Później na liście widać tylko jego prefiks (avk_…), z datą utworzenia i wygaśnięcia, ostatnim użyciem i liczbą wywołań. O nowym kluczu wysyłamy też powiadomienie e-mailem (bez samego klucza).

Unieważnianie klucza

Przyciskiem Unieważnij obok klucza klucz natychmiast staje się bezużyteczny; tego nie można cofnąć. Unieważnij klucz, jeśli już go nie używasz, jeśli likwidujesz program, który z niego korzystał, lub jeśli podejrzewasz, że wyciekł.

Wskazówki dotyczące bezpieczeństwa

Traktuj klucz jak swoje hasło: kto go zna, może w ramach nadanego zakresu odczytywać Twoje projekty.
Przechowuj go w magazynie sekretów (menedżer haseł, zmienna środowiskowa serwera lub sekretna zmienna CI), a nie w kodzie źródłowym: nie może trafić do repozytorium git, do udostępnionego arkusza ani do e-maila.
Nie używaj go w kodzie uruchamianym w przeglądarce (strona internetowa, rozszerzenie przeglądarki): tam każdy może go odczytać. Klucz należy do serwera, skryptu lub programu desktopowego.
Każdy program powinien mieć własny klucz o możliwie najwęższym zakresie i krótkim terminie ważności; dzięki temu unieważnienie jednego klucza nie zatrzyma niczego innego.

Użycie z poziomu programu

W nagłówku żądania klucz jest przesyłany jako token Bearer: Authorization: Bearer avk_…. Punkty końcowe znajdują się pod /api/v1/ (na przykład GET /api/v1/projects), a odpowiedź ma format JSON. Dokładny opis w formacie OpenAPI jest dostępny pod adresem /api/v1/openapi.json; większość narzędzi deweloperskich potrafi go zaimportować.

Liczba wywołań jest ograniczona na klucz i na konto (domyślnie 60 na minutę i 10 000 na dobę); po przekroczeniu serwer odpowiada kodem 429, wtedy chwilę poczekaj. Logowanie na stronie (cookie) nie otwiera API, a klucz nie loguje do interfejsu webowego.