Glossario

REST (Representational State Transfer)

REST (Representational State Transfer) è uno stile architetturale per costruire servizi web, descritto da Roy Fielding nel 2000. Le risorse sono identificate da indirizzi e si manipolano con i metodi del protocollo HTTP. Un'API che segue questi principi si dice RESTful ed è oggi il tipo di API più diffuso.

Cos’è REST e come funziona

REST è un insieme di principi di progettazione, senza un protocollo o uno standard ufficiale. Ogni elemento che il servizio gestisce, come un cliente, un ordine o un prodotto, è una risorsa con un proprio indirizzo, ad esempio /clienti/42. Il client chiede di leggere, creare, modificare o cancellare la risorsa usando i metodi HTTP, e il server risponde con una rappresentazione dei dati, di norma in JSON.

I metodi HTTP principali in REST

  • GET: legge una risorsa o un elenco, senza modificarli.
  • POST: crea una nuova risorsa.
  • PUT: sostituisce una risorsa con una nuova versione.
  • PATCH: modifica solo alcuni campi di una risorsa.
  • DELETE: elimina una risorsa.

La risposta contiene un codice di stato: 200 per il successo, 201 per una creazione, 400 per una richiesta errata, 401 e 403 per problemi di accesso, 404 per una risorsa non trovata, 500 per un errore del server.

I vincoli dell’architettura REST

  • Client e server separati: l’interfaccia e la gestione dei dati evolvono in modo indipendente.
  • Assenza di stato: ogni richiesta contiene tutte le informazioni necessarie, e il server non conserva memoria tra una richiesta e l’altra.
  • Cache: le risposte indicano se possono essere riutilizzate, per ridurre il traffico.
  • Interfaccia uniforme: tutte le risorse si trattano con le stesse regole.
  • Sistema a strati: tra client e server possono esserci intermediari, come proxy e bilanciatori.

Differenza tra REST, GraphQL e SOAP

Un’API REST espone molte risorse, ognuna con il proprio indirizzo. GraphQL espone un solo punto di accesso e lascia a chi chiama il compito di descrivere i campi che vuole. SOAP è un protocollo più vecchio e rigido, basato su XML. REST è la scelta più comune per la semplicità e per il legame diretto con il funzionamento del web.

REST GraphQL SOAP
Formato dei dati Di norma JSON JSON XML
Punti di accesso Molti indirizzi, uno per risorsa Uno solo Uno solo
Chi sceglie i campi Il server Chi chiama l’API Il contratto del servizio
Uso tipico API web e servizi pubblici App con dati molto variabili Sistemi aziendali più datati

Buone pratiche per un’API REST

Gli indirizzi usano sostantivi al plurale e non verbi. Le versioni compaiono nell’indirizzo, ad esempio /v1/. L’accesso richiede un token e una connessione cifrata. Gli errori restituiscono un codice e un messaggio chiaro, e un web server o un gateway applica limiti al numero di richieste.

Come si progettano risorse e indirizzi

Il primo passo è decidere quali sono le risorse, come clienti, ordini e fatture, e come si legano tra loro. Un indirizzo come /clienti/42/ordini esprime in modo leggibile che si tratta degli ordini del cliente 42. I nomi usano il plurale, le parole si scrivono in minuscolo e le azioni sono lasciate ai metodi HTTP, quindi non si crea un indirizzo come /cancellaCliente. Le operazioni che non rientrano nei quattro verbi principali si modellano come risorse a sé, ad esempio una risorsa «pagamenti» per eseguire un pagamento.

Paginazione, filtri e ordinamento

Un elenco di migliaia di elementi non si restituisce in un’unica risposta. L’API divide i risultati in pagine, con parametri come il numero di elementi per pagina e un riferimento alla pagina successiva. I filtri e l’ordinamento si indicano con parametri nell’indirizzo, per esempio lo stato di un ordine o la data da cui partire. Fissare un limite massimo alla dimensione della pagina protegge il server da richieste troppo pesanti.

Documentare e versionare con OpenAPI

La specifica OpenAPI descrive gli indirizzi, i parametri, le risposte e i metodi di autenticazione di un’API in un file, di solito in formato YAML o JSON. Da quel file si generano la documentazione consultabile, i test e persino parte del codice per i client. Quando un’API cambia in modo incompatibile si pubblica una nuova versione e si mantiene la vecchia per un periodo annunciato, in modo che chi l’ha integrata abbia il tempo di aggiornarsi.

Sicurezza di un’API REST

Ogni richiesta viaggia su connessione cifrata e porta un token con i soli permessi necessari. Il server controlla i dati ricevuti, limita il numero di richieste per utente e restituisce messaggi di errore che non rivelano dettagli interni. I browser applicano la politica CORS, che stabilisce da quali siti un’API può essere chiamata. Le operazioni che si possono ripetere senza effetti ulteriori, come la lettura o la sostituzione di una risorsa, rendono sicuro riprovare in caso di errore di rete.

Come restituire gli errori

Un’API chiara usa il codice di stato adatto alla situazione: 400 per una richiesta formulata male, 401 quando manca l’autenticazione, 403 quando l’utente non ha il permesso, 404 per una risorsa assente, 409 per un conflitto e 429 per troppe richieste. Il corpo della risposta spiega il problema in un formato prevedibile. Lo standard RFC 9457 definisce una struttura comune, con un tipo di errore, un titolo, un dettaglio e un riferimento all’occorrenza. Messaggi che indicano il campo sbagliato e come correggerlo riducono le richieste all’assistenza.

Fonti e approfondimenti