04 — API

Le API: la presa di corrente dei programmi

Un'API è il modo in cui un programma chiede qualcosa a un altro. Non serve scriverle: serve saperle leggere, per far fare a un'app quello che oggi fai a mano e per capire perché un'automazione si blocca.

Nessuno pretende che un architetto progetti il quadro elettrico. Ma chi lavora in uno studio sa che cosa è una presa, che cosa è la potenza disponibile e perché non si attaccano dieci apparecchi a una sola ciabatta. Le API sono la stessa cosa per i programmi: un punto di connessione con delle regole, una capacità e dei limiti.

Un'API è un indirizzo a cui un programma manda una richiesta e da cui riceve una risposta. Quello che cambia il lavoro non è scriverle — quelle le scrive l'AI — è saperle leggere: capire che cosa si può chiedere, che cosa serve per essere autorizzati, e che cosa significa un errore.

01

Che cos'è, con parole da cantiere

Immagina uno sportello. Bussi a un indirizzo preciso (*endpoint*), presenti un documento (*autenticazione*), chiedi una cosa (*richiesta*) e ricevi una scheda con i dati (*risposta*).

Le richieste sono di pochi tipi, sempre gli stessi: GET per leggere, POST per consegnare qualcosa di nuovo, PUT o PATCH per modificare, DELETE per cancellare. La risposta arriva in un formato leggibile — quasi sempre JSON — che è un elenco di campi e valori, come una tabella.

Tutto qui. Il resto sono dettagli del singolo servizio.

02

Perché conviene a uno studio tecnico

Per smettere di ricopiare. I dati di una commessa stanno nel gestionale, nel foglio di calcolo e nella mail. Con un'API si leggono da un punto solo e si scrivono dove servono, senza il passaggio a mano che introduce errori.

Per far parlare strumenti che non si conoscono. Il software del laboratorio prove, il portale del committente, il servizio di firma: raramente hanno un connettore pronto, quasi sempre hanno un'API.

Per capire perché si blocca. Quando un'automazione smette di funzionare, la risposta è quasi sempre lì: una chiave scaduta, un limite superato, un campo obbligatorio mancante. Chi sa leggere l'errore risolve in dieci minuti; chi non lo sa ricomincia da capo.

03

Le quattro cose da sapere

L'indirizzo. Ogni API ha una documentazione con gli endpoint: quali risorse esistono e con quale indirizzo si raggiungono.

L'autenticazione. Di solito una chiave o un token, da mettere nelle variabili d'ambiente del servizio, mai nel codice. Una chiave in un file è una chiave persa.

I limiti. Quante richieste al minuto sono ammesse, e quanto pesa una risposta. Servono a non far cadere il servizio — anche il tuo.

Gli errori. 400 richiesta sbagliata, 401 non autorizzato, 404 non trovato, 429 troppe richieste, 500 problema del servizio. Sono cinque numeri, e spiegano quasi tutto.

04

Come si legge la documentazione

Apri la pagina dell'API e cerca quattro cose, in quest'ordine: l'esempio di chiamata (spesso in curl), i parametri obbligatori, un esempio di risposta, e la sezione sui limiti.

Poi fai la cosa in cui l'AI è più brava: incolla la documentazione e chiedi «spiegami che cosa posso chiedere a questa API per ottenere l'elenco delle commesse con la data di consegna, e mostrami la chiamata completa». Ti risparmia mezz'ora di lettura e ti dà qualcosa da provare subito.

La prova vera, però, la fai tu: una chiamata, una risposta, un dato che riconosci.

05

API o connettore?

Un connettore è un'API già autorizzata e gestita per te: colleghi l'account, dai i permessi, e l'app può leggere e scrivere. Quando il connettore esiste, usalo: gestisce token, scadenze e rinnovi, che sono la parte noiosa e la più frequente fonte di guasti.

L'API diretta serve quando il connettore non c'è — un software di nicchia, un portale pubblico, il gestionale dello studio. È la stessa cosa, con più manutenzione: ogni tanto i token scadono, e qualcuno deve accorgersene.

In entrambi i casi vale la regola d'oro: le chiavi non si scrivono nel codice, e i permessi si danno nella misura minima che serve.

In una riga

Le API non sono un argomento da informatici: sono il punto di connessione tra i programmi. Chi le sa leggere smette di ricopiare dati e comincia a far lavorare gli strumenti tra loro.