REST API Design: naming conventions, status code e best practices

Ti è mai capitato di dover integrare un'API dove gli endpoint si chiamano /getUserById e /createNewOrder, mentre i campi della risposta usano snake_case ma in alcuni punti camelCase? Se lavori nel backend da un po', sai che questa è la ricetta per ore di debug, documentazione inaffidabile e sviluppatori frustrati. Noi, di Meteora Web, abbiamo costruito decine di API con Laravel e ne abbiamo integrate altrettante, anche su sistemi ERP che gestivano magazzino e fatturazione. Abbiamo visto che quando le convenzioni non sono solide, il costo non è solo tecnico: è economico. Un'API mal progettata rallenta lo sviluppo, moltiplica gli errori e, alla fine, fa perdere clienti. In questa guida ti portiamo le regole che usiamo ogni giorno per progettare API REST che si capiscono al volo, si mantengono senza ansia e scalano senza piangere. Niente teoria universitaria: solo naming conventions, status code e best practices che abbiamo testato su progetti veri.

Naming conventions: perché il nome dell'endpoint non è un dettaglio estetico

Il nome di una risorsa e la struttura dell'URL sono la prima cosa che un developer (o un client) vede della tua API. Se sono incoerenti, ogni richiesta diventa una scommessa. Noi partiamo da un principio: l'API va progettata come una collezione di risorse, non come un elenco di funzioni. Usa sempre nomi plurali per le risorse collezione: /users invece di /user o /getUsers. Le eccezioni sono le risorse singolari (es. /profile per l'utente loggato), ma anche lì, meglio /me o un prefisso esplicito.

Pluralità e gerarchia

REST non riguarda le azioni (quelle vanno nei metodi HTTP), ma le risorse. Quindi GET /users per leggere la lista, POST /users per crearne uno. Per le relazioni, annida con coerenza: GET /users/123/orders per gli ordini di un utente. Ma evita profondità eccessive: più di due livelli di nesting iniziano a puzzare. Se hai GET /users/123/orders/456/items, forse è meglio esporre GET /items?order_id=456. Scegli una convenzione e applicala dappertutto.

Case nei nomi e nei campi

Per gli URL, il mondo REST è diviso tra chi usa kebab-case (es. /user-addresses) e chi snake_case. Noi consigliamo kebab-case negli URL perché è più leggibile e case-insensitive di default in molti server. Per i campi JSON nella richiesta e risposta, invece, il web è spaccato: snake_case (Python, PHP) vs camelCase (JavaScript). L'importante è sceglierne uno e restare coerenti. Noi usiamo snake_case nei JSON perché il nostro backend è in PHP e Laravel, e il database già usa snake_case. Se il client è JavaScript, si può sempre trasformare con un middleware. Ma se cambi case a metà strada, prepari un disastro. Esempio di risposta coerente:

{
  "user_id": 42,
  "full_name": "Mario Rossi",
  "created_at": "2025-03-10T14:30:00Z"
}

E non mischiare verbi e sostantivi: /users/123 per ottenere i dettagli, non /users/getUser?id=123. Il metodo HTTP dice già cosa fare.

Errori comuni nei naming

Usare la versione nell'URL? Sì, ma sempre con /v1/ all'inizio. Non mischiare versioni a livello di risorsa.
Non usare mai azioni come /deleteUser – usa DELETE /users/123.
Evita underscores nei nomi delle risorse: /user_addresses va bene, ma è meglio kebab-case /user-addresses.
Non cambiare il nome di una risorsa dopo che è stata rilasciata. Se devi farlo, depreca con header Warning o versione nuova.

Status code: parlare HTTP senza parole

Gli status code sono il modo più rapido per comunicare l'esito di una richiesta. Usarli bene significa risparmiare ore di log e debug. Noi vediamo spesso API che rispondono sempre 200 con un campo error: true nel body. È un'abitudine terribile: il client deve parsare il JSON per sapere se è successo qualcosa. Invece, lascia che sia il protocollo a parlare.

I codici che devi conoscere e usare sempre

200 OK – richiesta andata a buon fine (GET, PUT, PATCH).
201 Created – risorsa creata con successo (POST). Includi nel body la risorsa appena creata e l'header Location con l'URL.
204 No Content – operazione senza corpo di risposta (DELETE, o PUT senza necessità di ritorno).
400 Bad Request – errore lato client (malformed JSON, parametri mancanti).
401 Unauthorized – autenticazione assente o non valida.
403 Forbidden – autenticato ma non autorizzato.
404 Not Found – risorsa inesistente.
409 Conflict – conflitto con lo stato attuale (es. duplicato, versione obsoleta).
422 Unprocessable Entity – validazione fallita (molto usato con framework come Laravel).
429 Too Many Requests – rate limit superato.
500 Internal Server Error – errore generico lato server.
503 Service Unavailable – server momentaneamente non disponibile (manutenzione, sovraccarico).

Risposta di errore uniforme

Non limitarti al codice. Restituisci sempre un body coerente con i dettagli dell'errore. Struttura che usiamo noi:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Il campo email è obbligatorio.",
    "details": {
      "email": ["L'email è obbligatoria."]
    }
  }
}

Includi un codice interno (più specifico dell'HTTP), un messaggio per lo sviluppatore e dettagli aggiuntivi. Mai esporre stack trace in produzione. Mai mandare messaggi di errore che rivelano dettagli interni (tipo di database, versione del software).

Best practices per un design che regge nel tempo

Versioning fin dal giorno zero

Non esiste API che non cambi. Metti la versione nell'URL (/v1/) o nell'header Accept: application/vnd.api.v1+json. Noi preferiamo l'URL perché è più esplicito e funziona con qualsiasi client. Anche se oggi sembra stabile, tra sei mesi un requisito può stravolgere tutto. Con il versioning, puoi evolvere senza rompere i client esistenti.

Paginazione, filtri e ordinamento

Ogni lista deve essere paginata. Usa parametri page e per_page o offset/limit. Includi metadati nella risposta: total, current_page, last_page. Per filtri, usa parametri dedicati: ?status=active o ?created_after=2025-01-01. Per ordinamento, ?sort=created_at,-name (ascendente default, - per discendente).

Idempotenza e sicurezza

GET, PUT, DELETE devono essere idempotenti: chiamarli più volte produce lo stesso risultato. POST no. Usa token idempotenti (header Idempotency-Key) per operazioni sensibili (es. pagamenti) per evitare duplicati. E, per favore, usa HTTPS sempre. Un'API senza HTTPS è una falla di sicurezza che espone credenziali e dati sensibili. Lo vediamo spesso: clienti che usano HTTP in produzione. Risolvi subito.

Documentazione con OpenAPI

Una API non documentata è una API che non esiste. Scrivi la specifica OpenAPI (ex Swagger) a partire dal design – prima ancora di scrivere il codice. Noi lo facciamo con OpenAPI 3.1. Ti obbliga a definire ogni endpoint, parametro, schema. Inoltre, puoi generare client SDK e validazione automatica.

Rate limiting e caching

Proteggi la tua API dal sovraccarico: restituisci 429 Too Many Requests e includi header Retry-After. Per il caching, usa header Cache-Control e ETag per le risposte GET che non variano spesso. Evita di cacare dati sensibili.

In sintesi: cosa fare adesso

Rivedi i nomi delle risorse nella tua API: usa plurali in inglese, kebab-case negli URL, snake_case nei JSON. Rinomina ciò che non è coerente (con attenzione alla compatibilità).
Standardizza gli status code e le risposte di errore. Ogni endpoint deve restituire il codice HTTP corretto e un body uniforme. Non usare 200 per errori.
Inserisci versioning dal prossimo deployment: /v1/ in testa a tutti gli endpoint. I client esistenti continueranno a funzionare sulla versione non versionata fino a deprecazione.
Documenta con OpenAPI: crea un file YAML/JSON che descrive l'intera API. Ci sono tool gratuiti come Swagger Editor. Ti costerà qualche ora, ma ti farà risparmiare decine di ore di supporto.
Verifica ogni endpoint per sicurezza (HTTPS, rate limiting, idempotenza delle operazioni di modifica). Non aspettare che scoppi un incidente.

Noi, di Meteora Web, abbiamo iniziato queste pratiche anni fa quando gestivamo API per sistemi contabili e di magazzino. Credici: un design pulito non è solo estetica, è una scelta economica. Meno bug, onboarding più veloce, clienti soddisfatti. E se vuoi un confronto su come strutturare la tua API, parlane con noi.