Ciao, e benvenuto nell'ottava puntata della quarantatreesima stagione. Finora abbiamo visto i meccanismi di REST. Oggi saliamo dal meccanismo al mestiere, e affrontiamo una verità che cambia il modo di vedere le API: un'API non è solo un ponte tecnico, è un prodotto. E come ogni prodotto, ha degli utenti. Solo che i suoi utenti non sono persone qualsiasi: sono altri programmatori, spesso incluso te stesso, tra sei mesi. Oggi capiamo perché progettare bene un'API sia un atto di empatia, e cosa lo rende un buon lavoro.
Partiamo dal riconoscere chi userà la tua API, perché cambia tutto. Quando costruisci un'API, tendi a pensare al meccanismo: funziona, restituisce i dati giusti. Ma dall'altra parte c'è qualcuno che dovrà usarla per costruire qualcosa: un altro sviluppatore, di un'altra squadra, o di un'altra azienda, oppure tu stesso tra qualche mese, che avrai dimenticato ogni dettaglio. Quella persona vivrà con la tua API ogni giorno. Se è ben fatta, sarà una gioia: la impara in fretta e vola. Se è fatta male, sarà un tormento quotidiano, pieno di sorprese e trappole. Progettare un'API è, prima di tutto, avere cura di chi la userà.
Voglio darti il primo principio, la coerenza, perché è il più importante. Il primo segno di un'API ben fatta è la coerenza: chiamare le cose allo stesso modo, dappertutto. Se in un punto una cosa si comporta in un modo, in un altro punto una cosa simile deve comportarsi allo stesso modo. Stessi schemi, stesse convenzioni, ovunque. Perché? Perché la coerenza permette di imparare una volta e dedurre tutto il resto. Se scopro come funziona una parte, e il resto segue lo stesso schema, allora posso indovinare correttamente come funziona tutto, senza rileggere il manuale ogni volta. La coerenza trasforma l'apprendimento in intuizione. L'incoerenza, al contrario, ti costringe a memorizzare ogni eccezione.
Voglio darti il secondo principio, la prevedibilità, perché discende dal primo. Da qui viene la prevedibilità: seguire le convenzioni che abbiamo imparato in queste puntate, cose come risorse, indirizzi logici, pochi verbi, codici standard, fa sì che chi conosce REST possa indovinare come funziona la tua API, ancora prima di leggerne la documentazione. Un'API prevedibile è una che rispetta le aspettative: si comporta come uno si aspetta che si comporti. Le sorprese, in un'API, non sono divertenti: sono ostacoli. La virtù più sottovalutata di un'interfaccia è essere noiosa nel senso buono, cioè fare esattamente ciò che ti aspetti, senza colpi di scena.
Voglio darti il terzo principio, la stabilità, perché tocca la responsabilità. E qui arriviamo alla cosa più delicata: la stabilità nel tempo. Se altre persone hanno costruito sopra la tua API, non puoi cambiarla a cuor leggero, perché ogni cambiamento improvviso romperebbe tutto ciò che si appoggia su di lei. La tua API, nel momento in cui qualcuno la usa, diventa una promessa: mi comporterò così, potrai contare su di me. Per questo le API serie evolvono con cura, spesso offrendo versioni diverse, così da aggiungere il nuovo senza rompere il vecchio, mantenendo le promesse fatte a chi si fidava. Cambiare senza rompere è una delle arti più difficili, e più rispettose, del mestiere.
Voglio farti apprezzare il peso di questa responsabilità, perché è un filo che torna. Ripensa a un'idea che ci accompagna: quando qualcosa diventa centrale, quando in tanti ci fanno affidamento, la sua affidabilità smette di essere un optional e diventa un dovere. Vale per un registro di eventi, come vedemmo, e vale per un'API. Una volta che degli altri costruiscono sul tuo lavoro, tu hai verso di loro una responsabilità: essere coerente, essere stabile, non tradire le aspettative che hai creato. Un'API è un bene comune per chi ci si appoggia, e trattarla con la serietà di una promessa è ciò che permette a un intero ecosistema di fiorirci sopra.
Voglio darti l'immagine che lega tutto, e la lezione. Progettare una buona API è come progettare un buon edificio pubblico: i cartelli coerenti, la disposizione intuitiva, le entrate dove uno se le aspetta, così che chiunque, anche senza guida, si orienti. E una volta che la gente ha imparato a usarlo, non sposti gli ingressi da un giorno all'altro. La lezione è questa: le migliori interfacce si progettano con empatia per chi le userà, trattando la coerenza e la stabilità come promesse. Un'interfaccia da cui altri dipendono non è solo una comodità tecnica: è una responsabilità. E averne cura è ciò che distingue un lavoro fatto bene da uno fatto e basta.
Per oggi ci fermiamo qui. Siamo saliti dal meccanismo al mestiere: un'API non è solo un ponte tecnico, è un prodotto, e i suoi utenti sono altri programmatori, incluso te tra sei mesi. Progettarla bene è un atto di empatia, retto da tre principi. La coerenza: chiamare le cose allo stesso modo ovunque, così da imparare una volta e dedurre il resto. La prevedibilità: seguire le convenzioni, così che chi conosce REST possa indovinare. E la stabilità: una volta che altri ci costruiscono sopra, la tua API diventa una promessa, da far evolvere senza rompere. La lezione: un'interfaccia da cui altri dipendono è una responsabilità, non solo una comodità. Nella prossima puntata affrontiamo il tema onesto: REST non è l'unica via. Nelle note trovi qualche spunto. Se ti è utile, condividila. Grazie per l'ascolto, e ci sentiamo alla prossima.