17. Integracijski API i API ključevi

Integracijski API služi tome da tvoj vlastiti program, tablica ili skripta strojno čitaju podatke tvojih projekata: popis projekata, popis kabela i materijala, tablicu strujnih krugova i popis stezaljki razdjelnika, izvod količina i sastavljanje paketa dokumentacije. API samo čita: crtež i projekt ne mijenja.

Tko može dobiti API ključ

API ključ odobrava operater po računu. Ako je tvoj račun dobio dopuštenje, na stranici Profil pojavljuje se kartica API ključevi; bez toga kartica nije vidljiva. Jedan račun može istodobno imati najviše 5 aktivnih ključeva.

Ključ vidi iste projekte kao i ti: tvoje vlastite i, na zahtjev, one koji su podijeljeni s tobom. Popise i izvod količina podijeljenog projekta daje samo ako dijeljenje dopušta i izvoz.

Izrada ključa

1. Na kartici API ključevi na stranici Profil klikni gumb Novi ključ.
2. Daj ključu naziv (na primjer naziv programa koji će ga koristiti).
3. Odaberi opseg: Čitanje projekata daje popis projekata i podatke projekata, Čitanje dokumenata daje popise, izvod količina i paket dokumentacije. Odaberi samo ono što je programu doista potrebno.
4. Odaberi istek: 30, 90 ili 365 dana. Istekao ključ više ne radi; umjesto njega izradi novi.
5. Upiši svoju trenutnu lozinku (za račun bez lozinke potrebna je svježa prijava). Kod prvog ključa prihvati uvjete korištenja API-ja.

Nakon izrade ključ se prikazuje samo jednom: kopiraj ga i spremi na sigurno mjesto. Poslije se na popisu vidi samo njegov prefiks (avk_…), s datumom izrade i isteka, zadnjim korištenjem i brojem poziva. O novom ključu šaljemo i obavijest e-poštom (bez samog ključa).

Opoziv ključa

Gumbom Opozovi pokraj ključa na kartici ključ odmah postaje neupotrebljiv; to se ne može poništiti. Opozovi ključ kad ga više ne koristiš, kad ukineš program koji ga je koristio ili kad sumnjaš da je procurio.

Sigurnosni savjeti

• S ključem postupaj kao s lozinkom: tko ga zna, može čitati tvoje projekte u dodijeljenom opsegu.
• Čuvaj ga u spremniku tajni (upravitelj lozinki, varijabla okruženja poslužitelja ili tajna varijabla CI-ja), a ne u izvornom kodu: ne stavljaj ga u git repozitorij, u zajedničku tablicu ni u e-poštu.
• Ne koristi ga u kodu koji se izvodi u pregledniku (web stranica, proširenje preglednika): tamo ga svatko može pročitati. Ključ pripada na poslužitelj, u skriptu ili u stolni program.
• Svaki program neka ima vlastiti ključ s najužim mogućim opsegom i kratkim istekom; tako opoziv jednog ključa ne zaustavlja ništa drugo.

Korištenje iz programa

Ključ se u zaglavlju zahtjeva šalje kao Bearer token: Authorization: Bearer avk_…. Krajnje točke nalaze se pod /api/v1/ (na primjer GET /api/v1/projects), a odgovor je JSON. Točan opis u OpenAPI obliku dostupan je na adresi /api/v1/openapi.json; većina razvojnih alata može ga učitati.

Broj poziva ograničen je po ključu i po računu (zadano 60 u minuti i 10 000 dnevno); pri prekoračenju poslužitelj odgovara s 429, pa pričekaj malo. Prijava na web stranicu (kolačić) ne otvara API, a ključ te ne prijavljuje u web sučelje.