L’approccio REST è uno dei più diffusi nella progettazione e nello sviluppo delle web API. All’interno dell’architettura REST, basata su HTTP, le operazioni avvengono tramite “verbi” specifici noti come Metodi HTTP, che permettono di interagire con le risorse.

I 5 Metodi HTTP più comuni nello sviluppo di API RESTful sono GET, PUT, DELETE, POST e PATCH: questi “verbi” essenziali permettono di eseguire le cosiddette operazioni CRUD (Create, Read, Update, Delete), ovvero consentono di creare, leggere, aggiornare e cancellare le risorse.

REST API: cosa sono

Le API REST, o REStful, sono quelle che seguono i principi del Representational State Transfer (REST), uno stile architettonico definito nel 2000 dall’informatico Roy Fielding che prevede, tra le altre cose, la netta separazione di client e server, l'adozione di interfacce uniformi e la creazione di una struttura stratificata in cui ogni livello ha le sue specifiche responsabilità.

Quando si avanza una richiesta tramite un’API REST, quest’ultima trasferisce al client non la risorsa vera e propria, ma una rappresentazione del suo stato, che però è sufficiente a soddisfare la richiesta.

Per essere considerata RESTful, un’API deve essere conforme ai seguenti principi:

• Comunicazione client-server stateless: ogni richiesta è separata e non vengono memorizzate informazioni;
• Possibilità di memorizzare i dati su cache;
• Interfaccia uniforme: ciò significa che le risorse devono essere identificabili e separate dalle rappresentazioni inviate al client e devono poter essere manipolate attraverso tale rappresentazione;
• Sistema stratificato che organizza i server in gerarchie precise (invisibili al client).

L’applicazione di questi concetti permette di sviluppare API veloci, leggere e facili da scalare, ed è oggi alla base dello sviluppo delle web API.

Il ruolo dei Metodi HTTP nelle API RESTful

In una richiesta API RESTful, l’informazione (ovvero la rappresentazione della risorsa) può essere trasferita in diversi formati, dal JSON all’HTML. La comunicazione, però, avviene sempre tramite HTTP request.

I Metodi HTTP, in particolare, sono componenti cruciali di ogni API REST, in quanto permettono al client di specificare l’azione da eseguire sulla risorsa e quindi di interagire con essa. Noti anche come “verbi” HTTP, questi elementi sono presenti in ogni richiesta API RESTful e consentono al client di fare azioni CRUD (Create, Read, Update, and Delete) sulle risorse in modo standardizzato e predicibile.

In un’architettura API REST si usano sia HTTP Methods idempotenti come GET e PUT, che permettono di sviluppare un web service efficiente e con un’alta tolleranza agli errori, sia metodi non idempotenti. La differenza è sostanziale: usando metodi idempotenti, più chiamate diverse con gli stessi parametri producono lo stesso effetto di una singola chiamata, senza moltiplicare i possibili effetti dell’operazione sul server e restituendo sempre la stessa informazione. Quando si usano “verbi” non idempotenti come POST e PATCH, al contrario, si può modificare lo stato del server esponendo il sistema a diversi effetti collaterali, tra cui la creazione di risorse indesiderate.

I 5 Metodi HTTP fondamentali nei RESTful API service

Tra i Metodi HTTP più comuni nelle API REST ci sono GET, PUT, DELETE, POST e PATCH, che permettono al client di leggere una risorsa, crearla, cancellarla oppure modificarla:

• GET: è il Metodo più comune nelle richieste API. Serve a richiedere al server una vista dei dati ed è idempotente: ripetere la stessa richiesta più volte restituirà la stessa rappresentazione, senza modificare lo stato del server;
• PUT: aggiorna una risorsa esistente sostituendone l‘intero contenuto oppure ne crea una nuova; viene utilizzato soprattutto per aggiornare le risorse. In fase di creazione, infatti, comporta il rischio di generare risorse per sbaglio;
• DELETE: elimina una risorsa. Può essere considerato idempotente, ma potrebbe lasciare disponibile l’URL della risorsa cancellata, con possibili ripercussioni sulla coerenza delle risposte successive da parte del server;
• POST: è l’unico metodo che opera soprattutto su raccolte di risorse. Serve infatti a creare una risorsa subordinata dotata di URL all’interno di una raccolta associandola a una gerarchia precisa. Non è intrinsecamente idempotente: ogni chiamata può potenzialmente generare una nuova risorsa;
• PATCH: come PUT, viene utilizzato per aggiornare le risorse. Funziona modificando parzialmente i contenuti delle risorse tramite modifiche espresse in formato standard come JSON e XML. La ripetizione della stessa richiesta PATCH può portare la risorsa ad assumere stati diversi, perciò non si può parlare di idempotenza (il verbo, tuttavia, può essere usato in maniera tale da essere idempotente).

Soltanto i metodi idempotenti possono essere considerati sicuri, in quanto non influiscono sullo stato del server e permettono di prevedere gli effetti delle operazioni del client sul server e sulle singole risorse. Tuttavia, anche i metodi non idempotenti come POST e PATCH, possono essere utilizzati in maniera sicura implementando adeguati sistemi di autenticazione, autorizzazione e gestione delle chiamate API.

Altri Metodi HTTP per lo sviluppo di API

Oltre ai cinque Metodi HTTP descritti, legati alle operazioni CRUD, ve ne sono altri molto utili nello sviluppo di API RESTful, in quanto non modificano lo stato della risorsa ma permettono di eseguire azioni importanti come verificare il suo stato o seguire il percorso di una richiesta:

• HEAD: serve per interrogare i metadati delle risorse, per esempio per verificarne la dimensione o lo stato prima di procedere con un’altra richiesta;
• OPTIONS: permette di ottenere un elenco dei metodi supportati dalla risorsa interrogata, e quindi di determinare quali operazioni è possibile eseguire sulla stessa;
• TRACE: può essere usato come strumento di debug in quanto consente al client di vedere come la sua richiesta viene modificata dai server intermedi lungo il percorso. Non modifica lo stato del server ma è un metodo molto delicato, in quanto può esporre dati sensibili. Non a caso esiste un tipo di attacco informatico, noto come Cross-Site Tracing (XST), che si basa esclusivamente su questo Metodo HTTP. 

I Metodi HTTP sono uno dei pilastri fondamentali nello sviluppo di API RESTful: definendo le operazioni in modo standardizzato e prevedibile, rendono le API interoperabili e facilitano la loro integrazione all’interno delle applicazioni. L’uso dello standard, inoltre, rende le API più intuitive e semplici da usare anche per il client.