C’è un libro che ogni tanto riemerge nelle discussioni tra designer con lo sguardo ispirato e la tazza di caffè monorigine in mano: La caffettiera del masochista di Donald Norman.
Molti lo archiviano mentalmente sotto la voce: “UX/UI, pulsanti, maniglie, cose belle da vedere”.
E invece no. O meglio: sì, ma non solo.
Perché La caffettiera del masochista non parla di estetica decorativa. Parla di oggetti progettati senza tenere conto di chi li usa. Di porte che non sai se spingere o tirare. Di fornelli con quattro manopole identiche allineate in fila come soldatini, ma senza nessuna mappatura sensata rispetto ai fuochi.
Ora sostituiamo “fornello” con “API REST”.
E iniziamo a sudare.
“Ma le API non hanno bisogno di UX…”
Questa è una delle più grandi bugie che ci raccontiamo nel mondo dello sviluppo software.
C’è un pregiudizio diffuso: UX uguale a interfacce grafiche, API uguale roba tecnica brutta e noiosa per sviluppatori veri, quelli con la barba e le regex tatuate sul braccio
Come se gli sviluppatori non fossero esseri umani. Come se non provassero frustrazione. Come se non bestemmiassero davanti a un 400 Bad Request senza messaggio.
Le API sono interfacce. Solo che invece di essere usate con il mouse, vengono usate con curl, SDK e chiamate HTTP.
E un’interfaccia può (e deve) essere: ergonomica, comprensibile, coerente, elegante.
Oppure può essere… una caffettiera progettata per punire chi la usa.
Caso 1: API tecnicamente impeccabile, umanamente crudele
Immagina un’API con: 100% coverage dei test, performance da benchmark della NASA, documentazione OpenAPI generata automaticamente e naming perfettamente coerente secondo le migliori pratiche REST.
Tutto bellissimo. Poi la usi e scopri che per creare un utente devi:
- Fare una chiamata a
/entity - Ottenere un
entityId - Fare una seconda chiamata a
/entity-metadata - Poi una terza a
/entity-context - Poi una quarta a
/entity-activation - E infine una quinta a
/entity-permissions/init
Tecnicamente? Pulitissima.
Architetturalmente? Inappuntabile.
Esperienza d’uso? Una maratona burocratica tra gli sportelli dell’INPS di venerdì mattina.
È la versione software del rubinetto con due manopole identiche, una per l’acqua calda e una per l’acqua fredda, ma invertite rispetto a tutto il resto del mondo.
Caso 2: Error handling progettato per spezzare l’anima
Un classico:
{
"error": "Invalid request"
}Grazie.
Invalid cosa?
Quale campo?
Perché?
Con quale regola sto violando l’ordine cosmico?
Dal punto di vista tecnico è tutto corretto: la richiesta è invalida.
Dal punto di vista umano è un biglietto con scritto: “Hai sbagliato. Indovina dove.”
È come una porta senza maniglia e senza scritta “spingere” o “tirare”.
E tu che provi entrambe le cose, sentendoti progressivamente stupido.
Una buona API dovrebbe essere come un buon cameriere: ti dice cosa non va, ti suggerisce cosa fare e non ti giudica quando gli chiedi un altra bottiglia di vino.
Caso 3: Naming semantico… per chi?
Esempio reale (più o meno):
execute()perform()runTask()triggerOperation()
Quattro metodi diversi. Differenze? Sottili. Sottilissime. Filosofiche.
Internamente il sistema è modellato con una purezza ontologica degna di un trattato di metafisica distribuita. Ma per chi integra l’API, è come scegliere tra: attiva, esegui, lancia, avvia.
Sapendo che una sola farà davvero quello che vuoi.
Quando Norman parla di affordance e mapping, sta parlando anche di questo: il nome di una funzione dovrebbe suggerire chiaramente cosa fa.
Se devo leggere il codice sorgente per capirlo, abbiamo un problema.
Caso 4: Coerenza locale, incoerenza globale
Altro grande classico:
GET /usersPOST /usersDELETE /user/{id}
Aspetta. users o user?
È come avere in casa: una porta che si apre spingendo, una tirando, una scorrendo e una che funziona solo se prima fai un piccolo inchino.
Ogni singola scelta può avere una giustificazione tecnica, ma l’insieme non è coerente.
E l’essere umano vive di pattern.
Le API dovrebbero essere prevedibili. Se capisco una parte, dovrei poter intuire il resto.
Quando non succede, stiamo costruendo caffettiere masochiste.
Ma quindi le API devono essere “belle”?
Sì, ma non nel senso Dribbble.
Belle nel senso informatico: coerenti, leggibili, prevedibili, minimali, con errori chiari, con flussi mentali semplici, con meno passaggi possibili.
Un’API elegante è quella che ti fa dire: “Ah, certo. Ha senso.”
Non: “Ok, funziona… ma perché?”
L’estetica invisibile
Nel mondo del codice esiste un’estetica invisibile.
Non è fatta di gradienti e ombre morbide, è fatta di: convenzioni rispettate, simmetrie nei path, strutture JSON armoniche, gerarchie comprensibili, errori parlanti, default intelligenti, ecc…
È l’estetica che si percepisce quando qualcosa non ti fa perdere tempo.
Quando l’integrazione non è una lotta.
Quando non devi aprire 17 tab di documentazione.
Quando non devi leggere il codice per capire come usarla.
Quella è ergonomia per sviluppatori.
La verità scomoda
Molti team sono ossessionati da: scalabilità, resilienza, performance e architettura pulita.
E fanno bene. Ma spesso si dimenticano di chiedersi: Quanto è facile usare questa cosa?
Perché un sistema può essere distribuito, fault-tolerant, event-driven, cloud-native, CQRS, DDD, LGBTQIA+ e pure VEGAN. Ma se per usarlo mi sento stupido e mi fai bestemmiare in sanscrito, hai costruito una caffettiera per masochisti.
La domanda giusta
Forse la domanda non è: È una buona architettura?
Ma: È una buona esperienza per chi la integra?
Ogni volta che progettiamo un’API dovremmo immaginare una persona dall’altra parte:
- che ha una deadline
- che non conosce il nostro modello mentale
- che non era in quella riunione in cui tutto “aveva senso”
- che vuole solo far funzionare una cosa
Se per farla funzionare deve attraversare cinque endpoint, interpretare tre ambiguità, decifrare un errore criptico e trovare il cuore di David Jones… stiamo progettando male.
Anche se il codice è perfetto.
meno masochismo, più empatia
La caffettiera del masochista ci ricorda una cosa fondamentale: non progettiamo oggetti per dimostrare quanto siamo intelligenti o bravi. Li progettiamo per essere usati, e le API non fanno eccezione.
La prossima volta che disegni un endpoint, chiediti:
- È chiaro cosa fa?
- È coerente con il resto?
- Riduce i passaggi inutili?
- Gli errori aiutano davvero?
- Se non fossi io l’autore, la capirei al volo?
Se la risposta è “più o meno”, forse non è un problema tecnico, hai solo progettato una caffettiera con il manico al contrario. E no, non è colpa dello sviluppatore che la usa.
