Progettare API REST

Aggiornato maggio 2026 · 9 min di lettura

Un’API ben progettata è un investimento. Una mal progettata è un debito tecnico che rallenta ogni feature successiva e che non puoi ritirare senza rompere i client esistenti.

Risorse e URL

Le URL devono rappresentare risorse (sostantivi), non azioni (verbi). La struttura gerarchica riflette le relazioni tra entità:

# corretto
GET  /articoli
GET  /articoli/42
POST /articoli
GET  /utenti/7/ordini

# da evitare
GET /getArticolo?id=42
POST /creaArticolo

Usare sempre il plurale per le collezioni. La gerarchia va limitata a due livelli: /risorse/id/sotto-risorse. Oltre diventa difficile da gestire e da cachare.

Metodi HTTP

GET — lettura, idempotente, non cambia stato
POST — creazione di una nuova risorsa
PUT — sostituzione completa (richiede tutti i campi)
PATCH — modifica parziale (solo i campi da aggiornare)
DELETE — eliminazione, idempotente

Status code

Usare i codici HTTP standard:

200 OK, 201 Created, 204 No Content
400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
422 Unprocessable Entity per errori di validazione
500 Internal Server Error per errori lato server

Autenticazione

JWT (JSON Web Token) per API stateless: il token contiene le informazioni necessarie, il server non mantiene sessioni. OAuth 2.0 per delegare l’autenticazione a provider esterni. Nei dettagli di implementazione, le best practice di sicurezza web sono imprescindibili: validare sempre l’input, non esporre dettagli interni negli errori.

Versionamento

Preferire il versioning nell’URL (/v1/articoli) rispetto agli header: più leggibile, più semplice da testare, più facile da cachare. La versione cambia solo quando si rompono le API esistenti, non per ogni nuova feature.

Documentazione

OpenAPI (Swagger) è lo standard per documentare le API REST. La documentazione generata dal codice è più affidabile di quella scritta a mano: non può divergere dall’implementazione reale.

Un’API pubblica è un contratto. Cambiarla rompe i client: pianifica la compatibilità dal giorno zero.

Le API esposte su internet richiedono attenzione al deploy e alla gestione delle versioni: la guida a DevOps e deploy web mostra come gestire le release in modo controllato. I client JavaScript che consumano queste API traggono vantaggio dalla tipizzazione con TypeScript.