17. API di integrazione e chiavi API

L'API di integrazione serve a far leggere in modo automatico i dati dei tuoi progetti al tuo programma, foglio di calcolo o script: l'elenco dei progetti, la distinta dei cavi e dei materiali, la tabella dei circuiti e l'elenco dei morsetti dei quadri, il computo delle quantità e la composizione del pacchetto di progetto. L'API è di sola lettura: non modifica né il disegno né il progetto.

Chi può ottenere una chiave API

La chiave API viene abilitata dal gestore per ogni account. Se il tuo account ha ricevuto l'autorizzazione, nella pagina Profilo compare la scheda Chiavi API; senza autorizzazione la scheda non è visibile. Un account può avere al massimo 5 chiavi attive contemporaneamente.

La chiave vede gli stessi progetti che vedi tu: i tuoi e, su richiesta, quelli condivisi con te. Le distinte e il computo di un progetto condiviso vengono restituiti solo se la condivisione consente anche l'esportazione.

Creare una chiave

Nella scheda Chiavi API della pagina Profilo fai clic sul pulsante Nuova chiave.
Assegna un nome alla chiave (per esempio il nome del programma che la userà).
Scegli l'ambito: Lettura progetti fornisce l'elenco dei progetti e i loro dati, Lettura documenti fornisce le distinte, il computo e il pacchetto di progetto. Indica solo ciò di cui il programma ha davvero bisogno.
Scegli la scadenza: 30, 90 o 365 giorni. Una chiave scaduta smette di funzionare; ne crei una nuova al suo posto.
Inserisci la tua password attuale (per un account senza password serve un accesso recente). Per la prima chiave accetta le condizioni d'uso dell'API.

Dopo la creazione la chiave viene mostrata una sola volta: copiala e conservala in un luogo sicuro. In seguito nell'elenco compare solo il suo prefisso (avk_…), con la data di creazione e di scadenza, l'ultimo utilizzo e il numero di chiamate. Per la nuova chiave inviamo anche una notifica via e-mail (senza la chiave).

Revocare una chiave

Con il pulsante Revoca accanto alla chiave nella scheda, la chiave diventa subito inutilizzabile; l'operazione non è reversibile. Revoca la chiave quando non la usi più, quando dismetti il programma che la usava o se sospetti che sia trapelata.

Consigli di sicurezza

Tratta la chiave come la tua password: chi la conosce può leggere i tuoi progetti entro l'ambito indicato.
Conservala in un archivio di segreti (gestore di password, variabile d'ambiente del server o variabile segreta della CI), non nel codice sorgente: non finisca nel repository git, in un foglio di calcolo condiviso o in una e-mail.
Non usarla in codice eseguito nel browser (pagina web, estensione del browser): lì chiunque può leggerla. Il posto della chiave è su un server, in uno script o in un programma desktop.
Ogni programma abbia la propria chiave, con l'ambito più ristretto possibile e una scadenza breve; così la revoca di una chiave non ferma gli altri.

Uso da un programma

Nell'intestazione della richiesta la chiave viene inviata come token Bearer: Authorization: Bearer avk_…. Gli endpoint si trovano sotto /api/v1/ (per esempio GET /api/v1/projects) e la risposta è in JSON. La descrizione precisa in formato OpenAPI è disponibile all'indirizzo /api/v1/openapi.json; la maggior parte degli strumenti di sviluppo sa importarla.

Il numero di chiamate è limitato per chiave e per account (di default 60 al minuto e 10 000 al giorno); in caso di superamento il server risponde con 429, quindi attendi un po'. L'accesso web (cookie) non apre l'API, e la chiave non ti fa accedere all'interfaccia web.