17. API de integrare și chei API

API-ul de integrare este util pentru ca propriul tău program, tabel sau script să citească automat datele proiectelor tale: lista proiectelor, lista de cabluri și de materiale, tabelul circuitelor și lista de borne ale tablourilor, situația cantităților și alcătuirea pachetului de planuri. API-ul doar citește: nu modifică nici desenul, nici proiectul.

Cine poate primi o cheie API

Cheia API este activată de operator, pentru fiecare cont în parte. Dacă contul tău a primit acces, pe pagina Profil apare cardul Chei API; fără acces cardul nu se vede. Un cont poate avea cel mult 5 chei active simultan.

Cheia vede aceleași proiecte ca tine: pe cele proprii și, la cerere, pe cele partajate cu tine. Listele și situația unui proiect partajat le oferă doar dacă partajarea permite și exportul.

Crearea unei chei

Pe cardul Chei API din pagina Profil, apasă pe Cheie nouă.
Dă un nume cheii (de exemplu numele programului care o va folosi).
Alege domeniul de acces: Citire proiecte oferă lista proiectelor și datele proiectelor, Citire documente oferă listele, situația cantităților și pachetul de planuri. Bifează doar ce are cu adevărat nevoie programul.
Alege expirarea: 30, 90 sau 365 de zile. O cheie expirată nu mai funcționează; creează în loc una nouă.
Introdu parola ta curentă (la un cont fără parolă este nevoie de o autentificare recentă). La prima cheie, acceptă condițiile de utilizare a API-ului.

După creare, cheia se afișează o singură dată: copiaz-o și păstreaz-o într-un loc sigur. Ulterior, în listă se vede doar prefixul ei (avk_…), cu data creării și a expirării, ultima utilizare și numărul de apeluri. Despre cheia nouă trimitem și o notificare prin e-mail (fără cheia propriu-zisă).

Revocarea unei chei

Cu butonul Revocă de lângă cheie, aceasta devine imediat inutilizabilă; acțiunea nu poate fi anulată. Revocă cheia dacă nu o mai folosești, dacă desființezi programul care o folosea sau dacă bănuiești că a ajuns pe mâini greșite.

Sfaturi de securitate

Tratează cheia ca pe parola ta: oricine o cunoaște îți poate citi proiectele, în limita domeniului de acces acordat.
Păstreaz-o într-un depozit de secrete (manager de parole, variabila de mediu a serverului sau variabila secretă a CI), nu în codul sursă: să nu ajungă în depozitul git, într-un tabel partajat sau într-un e-mail.
Nu o folosi în cod care rulează în browser (pagină web, extensie de browser): acolo o poate citi oricine. Locul cheii este pe un server, într-un script sau într-un program desktop.
Fiecare program să aibă propria cheie, cu cel mai îngust domeniu de acces posibil și cu expirare scurtă; astfel, revocarea unei chei nu oprește nimic altceva.

Utilizarea dintr-un program

În antetul cererii, cheia se trimite ca token Bearer: Authorization: Bearer avk_…. Punctele finale se află sub /api/v1/ (de exemplu GET /api/v1/projects), iar răspunsul este JSON. Descrierea exactă în format OpenAPI este disponibilă la adresa /api/v1/openapi.json; majoritatea instrumentelor de dezvoltare o pot importa.

Numărul de apeluri este limitat pe cheie și pe cont (implicit 60 pe minut și 10 000 pe zi); la depășire serverul răspunde cu 429, așa că așteaptă puțin. Autentificarea pe site (cookie) nu deschide API-ul, iar o cheie nu te autentifică în interfața web.