17. Integracioni API i API ključevi

Integracioni API služi tome da tvoj sopstveni program, tabela ili skripta mašinski čitaju podatke tvojih projekata: spisak projekata, spisak kablova i materijala, tabelu strujnih kola i spisak rednih stezaljki razvodnih tabli, izvod količina i sastavljanje paketa dokumentacije. API samo čita: crtež i projekat ne menja.

Ko može dobiti API ključ

API ključ odobrava operater po nalogu. Ako je tvoj nalog dobio dozvolu, na stranici Profil pojavljuje se kartica API ključevi; bez toga kartica nije vidljiva. Jedan nalog može istovremeno imati najviše 5 aktivnih ključeva.

Ključ vidi iste projekte kao i ti: tvoje sopstvene i, na zahtev, one koji su podeljeni sa tobom. Spiskove i izvod količina podeljenog projekta daje samo ako deljenje dozvoljava i izvoz.

Pravljenje ključa

1. Na kartici API ključevi na stranici Profil klikni na dugme Novi ključ.
2. Daj ključu naziv (na primer naziv programa koji će ga koristiti).
3. Izaberi opseg: Čitanje projekata daje spisak projekata i podatke projekata, Čitanje dokumenata daje spiskove, izvod količina i paket dokumentacije. Izaberi samo ono što je programu zaista potrebno.
4. Izaberi istek: 30, 90 ili 365 dana. Istekao ključ više ne radi; umesto njega napravi novi.
5. Upiši svoju trenutnu lozinku (za nalog bez lozinke potrebna je sveža prijava). Kod prvog ključa prihvati uslove korišćenja API-ja.

Nakon pravljenja ključ se prikazuje samo jednom: kopiraj ga i sačuvaj na sigurnom mestu. Kasnije se na spisku vidi samo njegov prefiks (avk_…), sa datumom pravljenja i isteka, poslednjim korišćenjem i brojem poziva. O novom ključu šaljemo i obaveštenje e-poštom (bez samog ključa).

Opoziv ključa

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

Bezbednosni saveti

• Sa ključem postupaj kao sa lozinkom: ko ga zna, može da čita tvoje projekte u dodeljenom opsegu.
• Čuvaj ga u skladištu tajni (menadžer lozinki, promenljiva okruženja servera ili tajna promenljiva CI-ja), a ne u izvornom kodu: ne stavljaj ga u git repozitorijum, u zajedničku tabelu ni u e-poštu.
• Ne koristi ga u kodu koji se izvršava u pregledaču (veb stranica, dodatak za pregledač): tamo ga svako može pročitati. Ključ pripada na server, u skriptu ili u desktop program.
• Svaki program neka ima sopstveni ključ sa najužim mogućim opsegom i kratkim istekom; tako opoziv jednog ključa ne zaustavlja ništa drugo.

Korišćenje iz programa

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

Broj poziva ograničen je po ključu i po nalogu (podrazumevano 60 u minuti i 10 000 dnevno); pri prekoračenju server odgovara sa 429, pa sačekaj malo. Prijava na veb sajt (kolačić) ne otvara API, a ključ te ne prijavljuje u veb interfejs.