Panoramica di REST. Parte 1: Cos'è REST? In questa parte, approfondiremo il modo in cui avviene la comunicazione tra un client e un server. Lungo la strada, scopriremo nuovi termini e li spiegheremo. Per garantire che tutto sia chiaro, analizzeremo la comunicazione client-server utilizzando un'applicazione RESTful come esempio. Supponiamo di sviluppare un'applicazione Web che memorizzi informazioni sui clienti e sui loro ordini. In altre parole, il nostro sistema è in grado di eseguire operazioni su determinate entità: crearle, modificarle, cancellarle e visualizzare informazioni su di esse. Queste entità saranno:
clienti (clienti)
ordini (ordini cliente)
articoli (prodotti)
In un'architettura RESTful, i client inviano richieste a un server per recuperare o modificare i dati, quindi i server inviano ai client le risposte alle loro richieste.
Richieste
Le richieste dei client vengono quasi sempre effettuate utilizzando il protocollo HTTP. In generale, le richieste HTTP sono costituite da diversi componenti:
Metodo HTTP
intestazione
URI
corpo della richiesta
Di seguito considereremo ogni componente in modo più dettagliato.
URI e risorse
I dati che i client ricevono o modificano tramite le richieste sono chiamati risorse. La comunicazione client-server riguarda la manipolazione delle risorse. In REST, le risorse sono qualsiasi cosa a cui puoi dare un nome. In un certo senso, sono come le classi in Java. In Java, possiamo creare una classe per qualsiasi cosa. Quindi in REST una risorsa può essere qualsiasi cosa: un utente, un documento, un report, un ordine. Può essere un'astrazione di qualche entità o qualcosa di specifico, ad esempio un'immagine, un video, un'animazione o un file PDF. Nel nostro esempio, abbiamo 3 risorse:
clienti (clienti)
ordini (ordini cliente)
articoli (prodotti)
I client inviano richieste a posizioni delle risorse note come endpoint. In parole povere, un endpoint è come un indirizzo sulla rete. Andando più a fondo, possiamo dire che un endpoint è un URI, cioè una sequenza di caratteri che identifica una risorsa astratta o fisica. Identificatore di risorsa uniforme (URI) A volte un endpoint, o URI, è chiamato percorso, ovvero il percorso di una risorsa. Ai fini di questo articolo, utilizzeremo il termine URI. Ogni risorsa specifica deve avere un URI univoco. Lo sviluppatore del server è responsabile di garantire che ogni risorsa abbia sempre il proprio URI. Nel nostro esempio, noi siamo gli sviluppatori, quindi lo faremo nel modo in cui sappiamo. Così come è spesso consuetudine assegnare identificatori numerici come chiavi primarie in un database relazionale, anche ogni risorsa ha il proprio ID in REST. L'ID risorsa in REST spesso corrisponde all'ID del record nel database che memorizza le informazioni sulla risorsa. Gli URI REST di solito iniziano con la forma plurale di un sostantivo che descrive una risorsa. Per esempio, "
/customers — URI di tutti i clienti disponibili
/clienti/23 — URI di un cliente specifico, ovvero il cliente con ID=23
/clienti/4 — URI di un cliente specifico, ovvero il cliente con ID=4.
Ma non è tutto. Possiamo estendere l'URI aggiungendo ordini:
/customers/4/orders — URI di tutti gli ordini effettuati dal cliente n. 4
/customers/1/orders/12 — URI dell'ordine n. 12 effettuato dal cliente n. 1.
Se continuiamo l'espansione aggiungendo più prodotti, otteniamo:
/customers/1/orders/12/items — URI dell'elenco di tutti i prodotti nell'ordine n. 12 realizzato dal cliente n. 1.
Man mano che aggiungiamo livelli di nidificazione, l'importante è rendere gli URI intuitivi.
Metodo HTTP
Il metodo HTTP è una sequenza di qualsiasi carattere (ad eccezione dei caratteri di controllo e dei delimitatori), che indica l'operazione principale eseguita sulla risorsa. Esistono diversi metodi HTTP comuni. Elencheremo quelli che vengono utilizzati più spesso nei servizi RESTful:
GET — Ottieni informazioni su una particolare risorsa (attraverso il suo ID) o su una raccolta di risorse
POST — Crea una nuova risorsa
PUT — Cambia una risorsa (attraverso il suo ID)
DELETE — Elimina una risorsa (attraverso il suo ID)
Intestazioni
Le richieste, così come le risposte, contengono intestazioni HTTP. Trasmettono informazioni aggiuntive sulla richiesta (o risposta). Le intestazioni sono coppie chiave-valore. Puoi visualizzare l'elenco delle intestazioni più comuni su Wikipedia . Come per REST, i client spesso inviano un'intestazione "Accetta" nelle richieste al server. Questa intestazione è necessaria per indicare al server in quale formato il client si aspetta di ricevere una risposta. Vari formati sono forniti in un elenco di tipi MIME. MIME (Multipurpose Internet Mail Extensions) è una specifica per la codifica delle informazioni e la formattazione dei messaggi in modo che possano essere inviati su Internet. Ogni tipo MIME è costituito da due parti separate da una barra: un tipo e un sottotipo. Esempi di tipi MIME per diversi tipi di file:
Ad esempio, una richiesta può avere un'intestazione come questa:
Accept:application/json
Questa intestazione indica al server che il client si aspetta di ricevere una risposta in formato JSON.
Richiesta corpo
Questo è il messaggio inviato dal client al server. Il fatto che la richiesta abbia o meno un corpo dipende dal tipo di richiesta HTTP. Ad esempio, le richieste GET e DELETE in genere non contengono alcun corpo della richiesta. Ma le richieste PUT e POST possono, dipende solo dallo scopo della richiesta. Dopotutto, per ricevere e/o eliminare dati utilizzando un ID (che viene passato nell'URL), non è necessario inviare dati aggiuntivi al server. Ma per creare una nuova risorsa (tramite una richiesta POST), è necessario inviare la risorsa. Lo stesso vale per la modifica di una risorsa esistente. In REST, il corpo della richiesta viene spesso inviato in formato XML o JSON. Il formato JSON è il più comune. Supponiamo di voler inviare una richiesta al server per creare una nuova risorsa. Se non hai dimenticato, abbiamo considerato l'esempio di un'applicazione che gestisce gli ordini dei clienti. Diciamo che vogliamo creare un nuovo cliente. Nel nostro caso, memorizziamo le seguenti informazioni sui clienti: nome, e-mail, numero di telefono. Quindi il corpo della richiesta potrebbe essere il seguente JSON:
Modifica il cliente n. 1 come segue:
Nome — Ben
Email — bigben@jr.com
Numero di telefono — +86 (868) 686-8686
DELETE /customers/12/orders/6
Eliminare dal sistema l'ordine n. 6 effettuato dal cliente n. 12
Risposte
Diciamo alcune parole sulle risposte del server. Una risposta di solito è composta dalle seguenti parti:
Codice di risposta
intestazioni
corpo di risposta
In generale, le intestazioni di risposta non sono molto diverse dalle intestazioni di richiesta. Inoltre, alcune intestazioni vengono utilizzate sia nelle risposte che nelle richieste. Penso che sia tutto chiaro anche per quanto riguarda il corpo della richiesta. Il corpo restituisce spesso le informazioni richieste dal cliente. Le informazioni restituite in risposta alle richieste GET possono anche essere in formato JSON. Ma l'ultima parte è un po' più interessante.
Codici di risposta HTTP
Consideriamo i codici di risposta HTTP in modo più dettagliato. Un codice di stato HTTP fa parte della prima riga di una risposta del server alle richieste effettuate tramite il protocollo HTTP. È un numero intero composto da tre cifre decimali. La prima cifra indica la classe del codice di stato della risposta. Il codice di risposta è solitamente seguito da una frase esplicativa in inglese, separata da uno spazio. Questa frase è un motivo leggibile dall'uomo per la risposta. Esempi:
201 Creato
401 Non autorizzato
507 Memoria insufficiente
Il codice di risposta comunica al client il risultato della richiesta e gli consente di determinare quali azioni intraprendere successivamente. I codici di risposta sono suddivisi in diverse classi o gruppi:
1XX — Informativo
2XX — Questi codici indicano che la richiesta del cliente è stata ricevuta ed elaborata con successo
3XX — Questi codici informano il cliente che è necessario effettuare una richiesta aggiuntiva, solitamente a un URI diverso, per completare con successo l'operazione
4XX — Errore del client. Tali codici possono derivare da una richiesta composta in modo errato. Un altro esempio è il noto codice "404 Not Found", che può verificarsi quando un client richiede una risorsa inesistente
5XX — Errore del server. Questi codici vengono restituiti al client se il server è responsabile del fallimento dell'operazione
Per garantire che tutto sia chiaro, analizzeremo la comunicazione client-server utilizzando un'applicazione RESTful come esempio. Supponiamo di sviluppare un'applicazione Web che memorizzi informazioni sui clienti e sui loro ordini. In altre parole, il nostro sistema è in grado di eseguire operazioni su determinate entità: crearle, modificarle, cancellarle e visualizzare informazioni su di esse. Queste entità saranno:
