Che cos'è un'API, senza programmare

Capire

Sei seduto in sala. Non entri in cucina, non sai come si cucina, e soprattutto non ti serve saperlo: dici al cameriere che cosa vuoi, in un modo che lui capisce, e dopo un po' ti arriva il piatto. Un'API è esattamente questo: il modo concordato in cui due programmi si parlano. Uno chiede, l'altro risponde, e nessuno dei due deve sapere com'è fatto l'altro dentro.

La parola che conta è concordato, e quasi nessuno ci si ferma abbastanza. Il menù non lo scrivi tu: lo scrive chi cucina. Chi risponde decide che cosa gli si può chiedere e come. Se sul menù non c'è, non c'è — puoi chiederlo con tutta la gentilezza del mondo e la risposta sarà no. È la differenza fra «questo software si collega» e «questo software si collega per fare queste sei cose e nessun'altra», ed è tutta la lezione in una riga.

Che cosa vuol dire «chiedere» a un programma? Due cose molto diverse, e conviene tenerle separate fin da subito. Ci sono le richieste che chiedono e basta — dammi l'elenco dei clienti, dammi questa scheda — che non cambiano niente e si possono ripetere all'infinito senza danni. E ci sono le richieste che fanno succedere qualcosa — crea questa scheda, cambia questo stato — che invece lasciano un segno. Ripetere per sbaglio una richiesta del primo tipo non fa niente. Ripetere per sbaglio una del secondo crea due schede, due ordini, due appuntamenti.

Perché esiste un formato fisso? Perché il cameriere non deve interpretare. Se ordinassi «una cosa leggera, non troppo salata», dovrebbe indovinare; se ordini «tavolo 4, coperti 2, primo numero 12, senza glutine», non c'è niente da indovinare. Fra programmi vale lo stesso, ed è il motivo per cui i dati viaggiano scritti sempre allo stesso modo. Quel modo si chiama JSON ed è la lezione dopo: quando ti comparirà a schermo saprai già che cos'è.

Poi c'è la chiave. È la tessera che ti fa entrare: non dice chi sei come persona, dice che a te è permesso entrare e fare quelle certe cose. Chi ce l'ha in mano vale quanto te, verso quel programma. Per questo una chiave non si dà a nessuno, non si incolla in una chat, non si manda per email, non finisce in uno screenshot allegato a un ticket. Se è passata da un posto che non controlli, si butta e se ne fa un'altra: costa trenta secondi e non ha conseguenze.

E quando dall'altra parte qualcosa non va? Succedono tre cose, tutte e tre normali. La cucina è chiusa: il programma non risponde, e chi lo chiama deve accorgersene e riprovare più tardi. Il cameriere ti dice di aspettare: hai chiesto troppe cose troppo in fretta e c'è un limite, quasi sempre scritto nero su bianco. Il menù è cambiato: hanno aggiunto un piatto, o tolto un ingrediente, e quello che chiedevi ieri oggi torna diverso. Nessuna delle tre è un guasto: sono condizioni di lavoro, e chi le conosce prima non si spaventa quando arrivano.

Vedere

Claudio Bandini ha l'Autoscuola Bandini a Ferrara: tre istruttori, Silvia in segreteria, circa 240 allievi l'anno. Sul sito c'è un modulo «richiedi informazioni» e dal modulo arrivano 46 richieste al mese: quanto costa la patente B, quando comincia il prossimo corso, si può pagare a rate.

Silvia le legge, risponde, e poi le ricopia una per una nel gestionale delle pratiche: nome, cognome, telefono, email, che patente interessa. Sette minuti l'una: 322 minuti al mese, cioè cinque ore e ventidue. E c'è un secondo travaso, in senso opposto: ogni lunedì mattina apre il gestionale, guarda le date d'esame della settimana e le ricopia a mano nel calendario condiviso e nei promemoria agli allievi. Un'altra ora.

Sono due programmi che si ignorano da sei anni, e nel mezzo c'è una persona che fa da cameriere fra loro. Claudio era convinto che il gestionale «non si collegasse a niente»: gliel'aveva detto qualcuno, tempo prima, e non ci aveva più pensato. Quando lo ha chiesto all'assistenza, la risposta è arrivata in due giorni: la porta di servizio esiste, è documentata, e la chiave la genera lui stesso perché l'amministratore dell'account è lui.

Qui la storia si ferma, ed è giusto così: Claudio non ha costruito niente. Ha fatto una cosa sola — si è letto la documentazione — e ne è uscito con due elenchi e una decisione. Sapere che cosa si può chiedere a un programma, e che cosa no, vale già le tre pagine che costa.

Facciamolo insieme

La documentazione del gestionale di Claudio non posso dartela: è la sua. Ti do quella di un altro gestionale — quello di un'agenzia immobiliare — tre pagine vere di documentazione tecnica, in inglese, come sono quasi tutte. Il mestiere non conta: le cose da cercare sono identiche. E leggere la documentazione di un software che non è il tuo è anche il modo migliore per imparare a leggerla, perché non ti distrai a pensare a quello che vorresti farci.

1. Scarica il documento e aprilo. Guardalo per trenta secondi senza leggerlo: serve solo a farti l'occhio a com'è fatto. Tabelle, riquadri grigi, sigle. Fa paura da lontano e molto meno da vicino.
2. Non leggerlo tutto. Non si legge tutto una documentazione, mai: si va a cercare due cose sole — che cosa si può chiedere e che cosa non si può chiedere. Tutto il resto, per adesso, non ti riguarda.
3. Allega il documento all'assistente e usa la richiesta qui sotto. Chiede quattro cose e nessuna di queste è «come si fa»: che programma è, i due elenchi, che cosa serve per entrare, quali regole impone a chi lo chiama.
4. Leggi per primo l'elenco di quello che non si può fare. È la parte che nessuno guarda e l'unica che ti risparmia mesi: qui dentro, per esempio, c'è scritto che questo programma non cancella niente e non manda email per conto tuo.
5. Controlla che ci siano dei numeri. «Ci sono dei limiti» non è un'informazione; «120 richieste al minuto» lo è.
6. Cerca la riga sui doppioni. In questo documento c'è, e dice una cosa che vale per quasi tutte le API: la stessa richiesta mandata due volte crea due schede, perché nessuno controlla se è già arrivata. Tienila a mente: nella lezione sui flussi torna.
7. Stampa la scheda che ti è uscita, o salvala. Non serve a costruire: serve il giorno in cui parlerai con l'assistenza, o con chi il collegamento te lo costruisce, e ti servirà sapere di che cosa state parlando.

Ti allego tre pagine di documentazione tecnica di un gestionale. Io non programmo: ho un'autoscuola a Ferrara con tre istruttori e una persona in segreteria, e voglio soltanto capire che cosa si può chiedere a un programma attraverso quella che mi hanno chiamato «la sua API».

Il documento è in inglese: rispondimi in italiano.

CHE COSA VOGLIO DA TE
1) In tre righe: che programma è, e a che cosa serve questa porta di servizio.
2) Due elenchi, uno sotto l'altro:
   - QUELLO CHE SI PUÒ CHIEDERE: una riga per voce, scritta come la direi a voce, e accanto se quella cosa si limita a leggere oppure cambia qualcosa.
   - QUELLO CHE NON SI PUÒ CHIEDERE: una riga per voce, e accanto in che punto del documento c'è scritto.
3) Per entrare che cosa serve? Chi lo crea, che cosa succede se lo perdo, e dove non va messo mai.
4) Quali regole impone a chi lo chiama: quante richieste posso fare e in quanto tempo, che cosa succede se esagero, e che cosa succede se mando due volte per sbaglio la stessa identica richiesta.
5) Se un giorno cambiassero qualcosa in questo programma, che cosa dice il documento? Guarda che cosa c'è scritto sulle versioni.

REGOLE
- Usa soltanto il documento allegato. Se una cosa non c'è scritta, dimmi «non è documentato» invece di dedurla da come funzionano di solito le API.
- Non scrivermi codice e non darmi indirizzi da copiare: voglio capire che cosa è possibile, non collegare niente oggi.
- Spiegami ogni sigla la prima volta che la usi.
- Se una cosa nel documento è scritta in modo ambiguo, dimmi che è ambigua invece di scegliere tu.

CHE PROGRAMMA È
Il gestionale di un'agenzia immobiliare: tiene il catalogo degli immobili,
le richieste di informazioni che arrivano dai clienti e l'elenco degli
agenti. La porta di servizio serve a far parlare questo gestionale con un
altro programma — per esempio il modulo di un sito — senza che una persona
ricopi niente a mano.

QUELLO CHE SI PUÒ CHIEDERE
- l'elenco degli immobili, un po' per volta (massimo 100 per richiesta)  · legge
- un singolo immobile, a partire dal codice che l'agenzia usa già         · legge
- creare una nuova richiesta di informazioni, agganciata a un immobile    · CAMBIA
- rileggere una richiesta già creata                                     · legge
- aggiornare una richiesta: lo stato, l'agente assegnato, le note interne · CAMBIA
- l'elenco degli agenti attivi                                           · legge

QUELLO CHE NON SI PUÒ CHIEDERE (sta a pagina 1, sezione «What this API
does not do»)
- contratti, atti, provvigioni e dati contabili: restano nel modulo
  Amministrazione e da qui non si vedono
- cancellare qualcosa: si può archiviare, non eliminare
- caricare tutto insieme: una richiesta per volta, niente elenchi in blocco
- mandare email o SMS al posto tuo: le notifiche si impostano dentro il
  prodotto, non da qui

PER ENTRARE
Serve una chiave. La crea un amministratore dell'account. Si vede UNA VOLTA
SOLA, nel momento in cui nasce, e dopo non è più recuperabile: se si perde
non si ritrova, si revoca e se ne fa un'altra. Non scade da sola. La revoca
ha effetto entro sessanta secondi. Conviene farne una per ogni collegamento,
con un nome che dica a che cosa serve. Non va mai messa dentro una pagina
del sito o dentro un'applicazione per telefono: lì sarebbe pubblica.

LE REGOLE CHE IMPONE A CHI LO CHIAMA
- 120 richieste al minuto per ogni chiave, contate sugli ultimi sessanta
  secondi
- oltre il limite risponde «troppe richieste» e dice quanti secondi
  aspettare; se si insiste il blocco si allunga
- tre minuti di fila fuori limite e la chiave viene sospesa, con un'email
  all'amministratore
- ATTENZIONE: la stessa richiesta mandata due volte crea DUE schede. Il
  documento lo dice esplicitamente: non c'è nessun controllo dei doppioni

SE UN GIORNO CAMBIANO QUALCOSA
Il documento dice che la versione 1 è stabile e che possono aggiungere campi
nuovi alle risposte senza avvisare: chi le riceve deve ignorare quelli che
non conosce, invece di fermarsi. Che cosa succederebbe se un giorno uscisse
una versione 2 non è documentato.

Perché ha funzionato

• Chiedere due elenchi invece di una spiegazione ha reso leggibile un documento che nessuno in autoscuola avrebbe aperto. Una spiegazione di un'API produce un riassunto che si legge e si dimentica; due elenchi producono una decisione, perché il secondo elenco ti dice subito che cosa non chiedere mai.
• «E accanto se quella cosa si limita a leggere oppure cambia qualcosa» è la colonna che vale di più. Sono due mestieri diversi: le prime sei si possono riprovare cento volte senza conseguenze, le altre due lasciano un segno nel gestionale di qualcuno. È anche la distinzione che spiega, tre righe più in basso, perché i doppioni sono un problema.
• «Se una cosa non c'è scritta, dimmi non è documentato» ha prodotto l'ultima riga della scheda. Le API si assomigliano tutte, e un assistente che non trova un dettaglio tende a completarlo con il modo in cui funzionano di solito: ottieni una risposta plausibile e inventata, e non hai nessun modo di distinguerla dalle altre.
• «Non darmi indirizzi da copiare e non scrivermi codice» ha tenuto la risposta al livello giusto. Senza quella riga arriva un blocco di testo tecnico che sembra utilissimo e che non sai né leggere né verificare: sarebbe stata una risposta a una domanda che Claudio non aveva fatto.
• La riga sui doppioni non l'aveva chiesta nessuno esplicitamente, ed è la più preziosa delle tre pagine. Dice che se qualcosa manda due volte la stessa richiesta, nel gestionale nascono due schede identiche e nessuno se ne accorge. È il tipo di dettaglio che si scopre da un cliente arrabbiato, e qui è costato una riga di lettura.
• Il tempo. Diciotto minuti in tutto, di cui otto per leggere la scheda uscita e controllare due punti nel documento. E il risultato non è un collegamento: è che Claudio adesso sa che cosa è possibile e che cosa no — e non lo saprebbe nemmeno dopo tre riunioni con un consulente.

Prova tu

Il modello pronto

Ti allego la documentazione tecnica di {{NOME DEL SOFTWARE}}. Io non programmo: ho {{ATTIVITÀ}} a {{CITTÀ}}, siamo in {{QUANTI SIETE}}, e voglio soltanto capire che cosa si può chiedere a questo programma dall'esterno.

{{SE IL DOCUMENTO È IN INGLESE: il documento è in inglese, rispondimi in italiano.}}

CHE COSA VOGLIO DA TE
1) In tre righe: che programma è, e a che cosa serve questa porta di servizio.
2) Due elenchi, uno sotto l'altro:
   - QUELLO CHE SI PUÒ CHIEDERE: una riga per voce, scritta come la direi a voce, e accanto se quella cosa si limita a leggere oppure cambia qualcosa.
   - QUELLO CHE NON SI PUÒ CHIEDERE: una riga per voce, e accanto in che punto del documento c'è scritto.
3) Per entrare che cosa serve? Chi lo crea, che cosa succede se lo perdo, e dove non va messo mai.
4) Quali regole impone a chi lo chiama: quante richieste posso fare e in quanto tempo, che cosa succede se esagero, e che cosa succede se mando due volte per sbaglio la stessa identica richiesta.
5) Che cosa dice il documento sulle versioni e sui cambiamenti futuri.

IN FONDO
Scrivimi le due cose che, secondo questo documento, questo programma NON potrà mai fare per me. Voglio poterle rileggere fra sei mesi.

REGOLE
- Usa soltanto il documento allegato. Se una cosa non c'è scritta, dimmi «non è documentato» invece di dedurla da come funzionano di solito le API.
- Non scrivermi codice e non darmi indirizzi da copiare: voglio capire che cosa è possibile, non collegare niente oggi.
- Spiegami ogni sigla la prima volta che la usi.
- Se una cosa nel documento è scritta in modo ambiguo, dimmi che è ambigua invece di scegliere tu.

Errore comune

Livello successivo

Trasformare quei due elenchi in un collegamento che funziona davvero — la chiave, la chiamata, i dati che vanno avanti e che cosa fare quando torna un errore — è il mestiere del corso «Automazioni con l'AI».