Cosa Significa REST? Cosa sono le REST API?

Il termine REST è acronimo di REpresentational State Transfer e appare per la prima volta nella tesi di dottorato dell'informatico statunitense Roy Fielding.

Con REST Fielding descrive un approccio architetturale alla creazione di web API basate sul protocollo HTTP che tenga conto delle seguenti caratteristiche

• Le risorse devono essere accessibili tramite endpoint URL.
• Bisogna utilizzare per la comunicazione e il formato JSON o XML.
• Deve essere senza stato quindi stateless come HTTP.
• Deve impiegare i principali metodi http quindi GET, POST, PUT e DELETE.

HTTP è l’acronimo di HyperText Transfer Protocol (in italiano Protocollo di Trasferimento di un Ipertesto) e si tratta di un insieme di procedure basate su un sistema di richieste e risposte per la trasmissione di informazioni sul Web

Questo scambio di informazioni avviene tipicamente quando un browser accede a un web server o quando un'app client accede a un'API.

Nello schema è rappresentato un ciclo richiesta-risposta in HTTP: il client invia un messaggio di richiesta al server, questi la processa e invia un messaggio di risposta.

Il messaggio di richiesta è composto da quattro parti:

• Riga di richiesta: rappresenta una descrizione della richiesta da implementare
• Sezione Header: che viene utilizzata per aggiungere eventuali informazioni extra
• Riga vuota: che indica che le meta-informazioni (ovvero le informazioni specifiche sulla richiesta in sé) sono state inviate
• Body: il corpo del messaggio stesso che è opzionale e viene quindi aggiunto qua

Un esempio di riga di richiesta può essere quella che riguarda la homepage di Google:

La riga di richiesta in sé è composta da tre parti:

• Il metodo della richiesta
• L’URI della risorsa che stiamo andando a richiedere
• La versione del protocollo che stiamo utilizzando quindi la 1.1 di HTTP

Abbiamo visto come una web API fa in modo che le funzionalità della nostra Web App possano essere usate da altre App Client o da altre parti della stessa Web App tramite appunto endpoint URL

Spesso a queste funzionalità corrispondono anche differenti tipi di azioni, come ad esempio ottenere informazioni su uno specifico Tweet, creare un nuovo Tweet a partire da dati da noi passati all’API in formato JSON, aggiornare le informazioni di un evento salvato su un calendario oppure cancellare un appuntamento.

Nell'architettura REST per convenzione il metodo HTTP utilizzato nell’effettuare una richiesta a un endpoint dell’API corrisponde alla tipologia di azione che vogliamo compiere:

• GET: recuperare una risorsa
• POST: creare una nuova risorsa
• PUT / PATCH: aggiornare una risorsa
• DELETE: cancellare una risorsa

Dove una risorsa rappresenta un'entità dati come un Tweet, un prodotto oppure il post di un blog.

Il messaggio di risposta è molto simile a quello di richiesta:

• Riga di Stato: contiene il codice di stato della richiesta che corrisponderà quindi al successo o al fallimento della richiesta stessa
• Sezione Header: contiene eventuali informazioni aggiuntive
• Riga vuota: indica che le meta-informazioni sono state inviate
• Body: opzionale

Ecco un esempio di riga di stato in un messaggio di risposta:

Che si compone di due parti:

• La versione del protocollo HTTP
• Il codice di stato della risposta stessa

A sinistra dello schema potete vedere alcuni esempi tipici di codici di stato, mentre a destra le 5 diverse categorie di risposta:

• 1XX: Richiesta ricevuta, continua l'elaborazione
• 2XX: Richieste che hanno avuto successo
• 3XX: Richieste che per cui il client deve eseguire ulteriori azioni perché si sono stati dei reindirizzamenti
• 4XX: Richieste che hanno degli errori o che non possono essere soddisfatte
• 5XX: Il Server non è in grado di soddisfare una richiesta anche se valida

Vediamo quali sono le richieste tipiche che potrebbero essere fatte alla RESTful API di un negozio Online:

Ottenere l’elenco dei prodotti

Abbiamo quindi /products/ che con il metodo GET ci fornisce in JSON un elenco di tutti i prodotti: otteniamo uno status code 200.

Ottenere i dettagli di uno specifico prodotto

Se chiediamo uno specifico prodotto esistente, ad esempio con primary key (chiave primaria) 17, utilizziamo anche stavolta il metodo GET perché stiamo andando a richiedere una risorsa e otteniamo quindi sempre in JSON i dettagli del prodotto con chiave primaria 17. Anche in questo caso otteniamo lo status code 200.

Chiedere i dettagli di un prodotto che non esiste

Se richiediamo un prodotto che non esiste (o perché è stato rimosso o perché non è stato caricato), ad esempio con pk 21, utilizzando il metodo GET non otterremo alcun JSON riguardate il prodotto ma un messaggio d'errore 404.

Aggiungere un nuovo prodotto

Per aggiungere un nuovo prodotto all'inventario possiamo effettuare una richiesta di tipo POST su /products/ inviando anche il corpo con la descrizione del prodotto in formato JSON. In tal caso ci aspettiamo in risposta il codice 201 created quindi tutto è andato bene e la risorsa è stata creata.

Aggiornare un prodotto esistente

Per aggiornare unp specifico articolo (ad esempio con una descrizione, una foto o un prezzo), in questo caso con chiave primaria 15, facciamo una richiesta di tipo PUT. Anche in questo caso ci aspettiamo come risposta il codice 200.

Eliminare un prodotto esistente

Per eliminare un prodotto quindi utilizziamo il metodo DELETE sempre magari sullo stesso you hell sullo stesso end point product 15. In risposta in questo caso ci aspettiamo uno status code 204, No Content.

Ho una notizia che penso potrebbe interessarti!

Se hai letto questo articolo è ragionevole assumere che tu stia iniziando il tuo percorso nel fantastico mondo delle Web API. Ti interesserà allora sapere che questa lezione è parte del nostro corso Guida per Sviluppatori a Django REST Framework e Vue JS. Il corso si concentra sullo sviluppo di REST API e applicazioni web complete, utilizzando Django REST Framework per gestire il backend e il Vue.js per lo sviluppo del lato frontend. L'obiettivo del corso è fornirti una solida comprensione di come utilizzare questi due framework insieme per creare applicazioni web moderne, performanti, sicure e scalabili. Scopri di più e inizia subito!