Cos'è un'API — i mattoncini, e le mani che li montano

Tre lettere che senti dappertutto#

API. L'API di Google, l'API di WhatsApp, la Revit API. Il nome completo è Application Programming Interface, e diciamo la verità: da solo non dice niente. Serve un'immagine, e l'immagine giusta ce l'hai in casa da quando avevi sei anni.

I mattoncini#

Da una parte c'è una scatola piena di pezzi già costruiti da qualcun altro. In programmazione quella scatola si chiama libreria. Dall'altra parte ci sei tu, con le tue mani: il linguaggio di programmazione, nel nostro caso Python. Due mondi separati, i pezzi di qualcun altro e le tue mani. Dove si parlano?

Si parlano nell'incastro. Ogni mattoncino ha i bottoni sopra e i tubi sotto, e quelle forme sono uguali per tutti i pezzi della scatola. L'API è proprio questo: non è i pezzi, non è le mani, è la forma degli incastri.

Nome, ingresso, uscita#

1. come si chiama;
2. che cosa gli devi dare;
3. che cosa ti dà indietro.

Prendi l'incastro «arrotonda»: nome, arrotonda; ingresso, un numero con la virgola; uscita, il numero intero più vicino. Questa terna ha un nome preciso: si chiama contratto. Se sai leggere un contratto, sai usare qualsiasi libreria del mondo.

E nota una cosa: come fa il pezzo ad arrotondare, che calcoli faccia lì dentro, non lo sai e non ti serve. Il mattoncino è chiuso. Tu usi la forma, mai il contenuto.

La tua giornata è piena di contratti così. La presa di corrente: due fori, una forma uguale per tutti, fra chi offre l'energia e chi la usa. Le API del web sono la stessa idea, solo che il mattoncino sta su un computer lontano.

E Revit?#

Il primo montaggio: contare i muri#

• FilteredElementCollector: apre lo schedario del modello;
• OfClass: gli dici quale tipo di pezzi vuoi, i muri;
• GetElementCount: non gli dai niente, e ti dà un numero.

Quarantadue. Il modello ha quarantadue muri. Tre righe, nessuna magia: tre contratti letti bene.

E se sbagli? Se al collector passi una parola invece del documento, Revit ti risponde con un messaggio di errore. Quel messaggio è tuo amico: non è il codice che si rompe, è il contratto che ti dice cosa si aspettava.

Il libretto di istruzioni#

Da dove vengono questi nomi? Ogni scatola LEGO ha il suo libretto, e la scatola di Revit ha il suo: la documentazione della Revit API, dove ogni incastro è scritto con nome, ingresso e uscita.

E la scala è sempre questa: prima impari a leggere il modello, poi a filtrare e contare, poi a scrivere. Sempre in quest'ordine, sempre con gli stessi mattoncini. Non cambia la scatola: cambia quello che sai montare.

Guarda il video#

Nove minuti, dal clic dei mattoncini al primo codice, senza prerequisiti. Il video mostra i pezzi che si incastrano, il contratto letto riga per riga, la scatola di Revit che si apre e l'errore vero sullo schermo.

Il video completo è su YouTube: se ti è piaciuto, iscriviti al canale e attiva la campanella per i prossimi episodi.