Costruire una REST API che non faccia schifo è un’arte sottile. È come servire whisky d’annata in un bicchiere di plastica: anche se il contenuto è buono, l’esperienza crolla. E in un’era in cui ogni microservizio, SaaS o IoT toaster parla con un altro pezzo di software, la tua API è l’interfaccia diplomatica del tuo sistema. Mal progettata, diventa una dichiarazione di guerra.
Cominciamo da un classico che sembra semplice ma viene ignorato come le istruzioni del microonde: gli HTTP status code. Non è una tavolozza a caso. Restituire 200 OK per ogni chiamata è l’equivalente digitale di annuire mentre ti sparano. Se il client sbaglia, diglielo con un 400. Se sei tu a esplodere, abbi il coraggio di un 500. Non mascherare il malfunzionamento con falsi successi, o ti ritroverai con un client che balla sul Titanic.
L’idempotenza è uno di quei concetti che molti citano ma pochi capiscono. Non è solo un vezzo ingegneristico. È un’assicurazione sulla vita delle tue chiamate. Se premi “paga” una volta o dieci, non vuoi ricevere dieci fatture. GET, PUT, DELETE dovrebbero sempre essere idempotenti. POST no, ma almeno fai in modo che sia chiaro. L’assenza di idempotenza in un’API è come un bancomat che ogni tanto ti toglie due volte i soldi: inaccettabile.
Poi c’è l’abisso delle query string parameters. Pagination, filtering, sorting: tre parole che sembrano innocue finché non scopri che /products?page=1&size=10&sort=-price&category=funk-metal ti restituisce qualunque cosa tranne ciò che hai chiesto. Le API dovrebbero permettere navigazione e filtraggio come una ricerca su Google, non come decifrare un manoscritto copto.
Arriviamo all’autenticazione. Se la tua API non è pubblica, deve essere protetta. Punto. E no, un token passato come query string non è sicurezza, è un invito. OAuth2 è un incubo da implementare ma fa il suo lavoro, le JWT sono sexy ma vanno usate con cervello. Se usi API keys, almeno non loggare tutto in chiaro nei server di log. Non siamo più nel 2009.
La versioning è l’aspirina del software breaking change. Un /v1/ nel path non è elegante, ma è leggibile, stabile e gestibile. Usare headers come X-API-Version è più pulito, ma buona fortuna a farlo rispettare da tutti. Qualsiasi metodo tu scelga, ricordati che versionare è una promessa che le cose vecchie continueranno a funzionare. Non una scusa per ignorarle.
Sul fronte dei path semantici, la regola è una: rendili leggibili come fossero API da leggere ad alta voce. /users/123/posts/456/comments è poesia. /getAllCommentByPostId?uid=123&pid=456 è l’incubo di un DBA con problemi di autostima. Rifletti il modello di dominio. Se una cosa è una risorsa, trattala come tale. Se è un’azione, valutala due volte: forse stai usando REST per fare RPC.
I metodi HTTP sono cinque, non cinquanta. E ognuno ha una sua semantica. POST per creare, GET per leggere, PUT per sostituire tutto, PATCH per aggiornare parzialmente, DELETE per rimuovere. Se usi POST per tutto perché “il front-endista non capisce”, stai programmando con la stampella. E prima o poi, qualcuno ti spara una DELETE su produzione per sbaglio.
Poi c’è l’aspetto meno tecnico e più culturale: la documentazione. Se la tua API è una black box senza OpenAPI spec, Postman collection o almeno un README decente, hai fallito in partenza. Nessuno vuole indovinare i parametri guardando i log degli errori. La documentazione non è un optional, è l’esperienza utente del tuo sistema.
Ci sarebbero mille altre sfumature: rate limiting, errori semantici, headers personalizzati, fallback, test automatici con schema validation. Ma se non riesci a padroneggiare le basi, tutto il resto è maquillage su un cadavere.
Se davvero vuoi costruire un’API REST, guardati questo manifesto da leggere ogni lunedì mattina. Poi abbraccia l’ossessione per la coerenza. Perché un’API fatta male è come un’interfaccia grafica senza tasti: tutti si lamentano, nessuno la usa, e tu passi il weekend a rispondere a ticket.
E tu? Vuoi un’API che sia una promessa mantenuta o solo un endpoint verso l’inferno?