Ciao, e benvenuto nella sesta puntata della quarantatreesima stagione. Nelle scorse puntate abbiamo visto come si chiede qualcosa a un'API: verbo più indirizzo, richiesta completa. Oggi guardiamo l'altra metà del dialogo: la risposta. Quando chiedi qualcosa a un servizio, come fa lui a dirti com'è andata? Ha funzionato? È fallito? E se è fallito, di chi è la colpa? La risposta è un piccolo linguaggio condiviso, fatto di codici di stato. Oggi capiamo come i programmi si dicono, con onestà e in poche cifre, com'è andata.
Partiamo dal bisogno, perché è ovvio ma cruciale. Quando fai una richiesta, non ti basta ricevere dei dati: devi sapere se è andata bene. Magari la cosa che cercavi non esisteva. Magari non avevi il permesso di vederla. Magari il servizio, dentro, si è rotto. Un dialogo tra programmi ha bisogno di un modo chiaro, immediato, per dire l'esito: successo o fallimento, e in caso di fallimento, di che tipo. Senza questo, chi riceve la risposta brancolerebbe nel buio, incapace di distinguere un dato valido da un errore travestito da dato.
Voglio darti la soluzione dei codici, perché è di nuovo il riuso del web. REST, fedele alla sua idea, riusa un linguaggio che il web ha già: i codici di stato. Sono brevi segnali, dei numeri, che accompagnano ogni risposta e ne dichiarano l'esito. Non è un linguaggio inventato da ogni servizio: è lo stesso identico per tutti, perché è quello del web. Sono organizzati in famiglie, ed è la cosa più utile da sapere. C'è la famiglia del tutto bene, la richiesta è andata a buon fine. C'è la famiglia dell'hai sbagliato tu, il problema è nella tua richiesta. E c'è la famiglia dell'ho sbagliato io, il servizio, che si è rotto da solo.
Voglio soffermarmi su quella distinzione di colpa, perché è più profonda di quanto sembri. Nota quanto è onesto e utile distinguere tra il tuo errore e il mio. Se la cosa va storta, il servizio non si limita a dire non ha funzionato: ti dice se il problema sei tu, per esempio hai chiesto una cosa che non esiste, o non avevi il permesso, oppure sono io, che mi sono guastato dentro. Sapere di chi è la colpa cambia tutto per chi deve reagire: se l'errore è tuo, correggi la richiesta; se è del servizio, aspetti e riprovi, o segnali il guasto. Quella piccola onestà, dirti da che parte sta il problema, ti risparmia ore di confusione. È comunicazione chiara, non un generico è andata male.
Voglio nominare il codice più famoso, perché lo conosci di sicuro. C'è un codice che hai incontrato tante volte navigando: quello che significa non trovato. Quando finisci su una pagina che non esiste, il web ti risponde proprio con quel segnale, non trovato. È un membro della famiglia hai sbagliato tu: hai chiesto qualcosa che non c'è. Ecco, quello stesso identico codice, che il tuo browser incontra sulle pagine, è quello che un programma riceve da un'API REST quando chiede una risorsa che non esiste. Stesso linguaggio, stessi segnali, per gli umani che navigano e per i programmi che dialogano. È sempre la stessa idea: riusare il web.
Voglio darti l'immagine che rende chiara questa idea, perché è quotidiana. Pensa a un semaforo. Verde, giallo, rosso: gli stessi tre segnali significano la stessa cosa per ogni automobilista, in ogni incrocio, in ogni città. Non devi reimparare i colori a ogni semaforo: è un linguaggio condiviso e universale. I codici di stato sono i semafori delle risposte: pochi segnali, sempre gli stessi, che ogni programma capisce all'istante, ovunque. Oppure pensa agli stati di una spedizione, consegnato, indirizzo errato, danneggiato: chiunque li capisce, senza spiegazioni. È la potenza di un vocabolario condiviso per dire com'è andata.
Voglio trarre la lezione generale, perché vale oltre REST. Ecco la verità: mettersi d'accordo su un piccolo vocabolario condiviso per dire gli esiti rende la comunicazione tra programmi affidabile e onesta. Se ogni servizio inventasse il suo modo di dire è andata male, nessuno capirebbe nessuno senza un manuale. Avendo invece segnali comuni, tutti si intendono al volo. E distinguere di chi è la colpa, il tuo errore o il mio, è un piccolo atto di chiarezza che vale oro. Un buon linguaggio di risposte non dice solo cosa è successo: dice di chi è la responsabilità, così ognuno sa come reagire. Concordare i segnali comuni è metà della buona comunicazione.
Per oggi ci fermiamo qui. Abbiamo visto l'altra metà del dialogo: la risposta, e come un servizio dice com'è andata. Lo fa con i codici di stato, brevi segnali che REST riusa dal web, uguali per tutti, organizzati in famiglie: tutto bene, hai sbagliato tu, ho sbagliato io. E quella distinzione di colpa è preziosa: sapere da che parte sta il problema ti dice come reagire. Il codice più famoso, non trovato, è lo stesso che il tuo browser incontra sulle pagine: stesso linguaggio per umani e programmi. Come i colori di un semaforo, uguali per tutti ovunque. La lezione: un piccolo vocabolario condiviso per dire gli esiti rende la comunicazione affidabile e onesta. Nella prossima puntata vediamo la cosa e la sua fotografia: risorse e rappresentazioni. Nelle note trovi qualche spunto. Se ti è utile, condividila. Grazie per l'ascolto, e ci sentiamo alla prossima.