Cos'è una REST API e come funziona

REST è di gran lunga lo stile di API più diffuso al mondo: se lavori con il web, prima o poi (anzi, subito) ci avrai a che fare. In questo articolo ti spiego cos'è una REST API, su quali principi si basa e come funziona concretamente, con esempi chiari. Se non hai ancora chiaro cosa sia un'API in generale, parti da cos'è un'API.

Cos'è una REST API in parole semplici

Una REST API è un'API che segue i principi dell'architettura REST e usa il protocollo HTTP per far comunicare client e server in modo semplice e standardizzato. REST sta per Representational State Transfer, ma il nome conta meno dei concetti pratici che porta con sé.

In pratica, una REST API organizza tutto attorno a risorse (es. utenti, prodotti, articoli), ognuna identificata da un URL, e usa i metodi standard di HTTP per operare su di esse.

I principi fondamentali di REST

REST si basa su alcuni principi chiave. I più importanti da conoscere:

• Risorse identificate da URL: ogni "cosa" ha il suo indirizzo (es. /utenti/42).
• Operazioni tramite metodi HTTP: si usano i verbi standard di HTTP per agire sulle risorse.
• Stateless: ogni richiesta è indipendente e contiene tutto il necessario; il server non conserva lo stato tra una richiesta e l'altra.
• Formato standard: i dati viaggiano in formati strutturati, di solito JSON.

La caratteristica stateless è importante: rende le REST API scalabili e prevedibili, perché ogni richiesta è autosufficiente.

I metodi HTTP

Il cuore pratico di REST sono i metodi HTTP, che corrispondono alle operazioni che puoi fare su una risorsa:

Metodo	Operazione	Esempio
GET	Leggere dati	Ottenere la lista degli utenti
POST	Creare dati	Aggiungere un nuovo utente
PUT / PATCH	Aggiornare dati	Modificare un utente esistente
DELETE	Eliminare dati	Rimuovere un utente

Questa corrispondenza tra verbi HTTP e operazioni è ciò che rende le REST API intuitive: una volta capito lo schema, sai già come interagire con qualsiasi API REST ben fatta.

Esempio pratico

Immagina un'API per gestire articoli di un blog. Ecco come apparirebbero le operazioni:

• GET /articoli → ottieni tutti gli articoli
• GET /articoli/10 → ottieni l'articolo con id 10
• POST /articoli → crea un nuovo articolo
• PUT /articoli/10 → aggiorna l'articolo 10
• DELETE /articoli/10 → elimina l'articolo 10

Pulito e prevedibile: questo è il bello di REST.

Gli status code

Ogni risposta di una REST API include un codice di stato HTTP che indica l'esito. I principali gruppi:

• 2xx — Successo: la richiesta è andata a buon fine (es. 200 OK, 201 Created).
• 4xx — Errore del client: qualcosa nella richiesta è sbagliato (es. 404 Not Found, 401 Unauthorized).
• 5xx — Errore del server: problema lato server.

Saper leggere questi codici è fondamentale per capire cosa succede. Li approfondisco tutti in tutti i codici di errore HTTP.

REST vs altri stili

REST non è l'unico modo di costruire API. Le alternative principali:

• GraphQL: permette al client di chiedere esattamente i dati che vuole. Vedi cos'è GraphQL.
• SOAP: più vecchio, rigido e verboso, ancora presente in contesti enterprise.

REST resta lo standard dominante per la sua semplicità, la diffusione e l'ottimo equilibrio tra potenza e facilità d'uso.

In sintesi

Una REST API organizza la comunicazione attorno a risorse identificate da URL e usa i metodi HTTP (GET, POST, PUT, DELETE) per operare su di esse, restituendo dati in formato JSON e codici di stato che indicano l'esito. È stateless, prevedibile e semplice da usare: per questo è lo standard più diffuso per le API moderne.

Per il quadro generale, vedi cos'è un'API; per l'alternativa più moderna, cos'è GraphQL.