Proseguiamo con la nostra progettazione con la definizione degli URI che identificheranno le nostre risorse. In linea di massima, dal momento che il numero effettivo delle risorse non è definito a priori e nella maggior parte dei casi è potenzialmente infinito, vengono definiti dei modelli di URI per l'individuazione delle risorse.
Ad esempio, nel nostro caso un ordine con identificatore 123 può essere individuato da un URI della forma http://www.mionegozio.com/ordini/123 oppure http://www.mionegozio.com/ordini/?id=123.
Non esiste una regola per determinare se un URI è migliore di un altro. Un URI è solo una stringa per individuare
una risorsa. È utile comunque seguire alcune indicazioni per definire gli URI del proprio Web Service:
| Raccomandazione | Descrizione |
|---|---|
| preferire l'utilizzo di nomi a quello di verbi | un URI del tipo http://www.mionegozio.com/gestisciOrdini/123, anche se a tutti gli effetti valido per individuare una risorsa, è un pò fuorviante perchè induce a pensare che ad esso è associata un'azione invece che una risorsa; ricordiamoci che in ambito REST gli URI individuano risorse e che le azioni sono demandate ai metodi HTTP |
| contenere la lunghezza degli URI | si tratta di una indicazione pratica che favorisce la leggibilità delle specifiche, ma anche di un limite fisico mposto dalla maggior parte dei Web server |
| preferire uno schema posizionale | in linea di massima è da preferire un modello di URI che sfrutta la struttura gerarchica di un percorso piuttosto che la presenza di più argomenti; ad esempio, se vogliamo individuare gli ordini in base alla data, è da preferire lo schema
|
| evitare le estensioni | è bene tener presente che gli URI introducono un vincolo di accoppiamento con il client, quindi occorre fare molta attenzione nella loro definizione in quanto eventuali modifiche successive del modello hanno conseguenze sul client. In questa ottica sono da evitare le estensioni che legano un Web Service alla sua implementazione. Ad esempio è da preferire un URI del tipohttp://www.mionegozio.com/ordini/?id=123 ad uno del tipo http://www.mionegozio.com/ordini/ordine.php?id=123 |
Per esigenze implementative che vedremo in seguito, per il nostro Web Service utilizzeremo URI della forma:
http://www.mionegozio.com/ordini/?id=123
Definire i metodi sulle risorse
Il quarto passo della nostra analisi ci porta ad individuare quali metodi HTTP possono essere eseguiti sulle singole risorse e con quale significato. A questo proposito può essere utile creare una tabella che riassume l'insieme delle operazioni possibili, come nel seguente esempio:
| URI | GET | PUT | POST | DELETE |
|---|---|---|---|---|
/ordini/?id=xxx |
X | X | X | ? |
/articoli/?id=xxx |
X | - | - | - |
/fatture/?id=xxx |
X | - | - | - |
La prima colonna della tabella contiene i modelli di URI scelti per le nostre risorse, mentre le altre colonne rappresentano i quattro metodi principali del protocollo HTTP. In ciascuna cella corrispondente all'incrocio tra risorsa e metodo abbiamo inserito schematicamente un'informazione che indica l'applicabilità del metodo.
Ad esempio, con una "X" indichiamo che è possibile leggere, modificare e creare un ordine, mentre l'eliminazione, contrassegnata con "?", dipende da determinate condizioni come lo stato in cui esso si trova (ad esempio, non è possible eliminare un ordine già evaso).
Per le altre risorse l'unica operazione possibile è l'acquisizione tramite GET.
La rappresentazione delle risorse
Sappiamo che REST non stabilisce nessun formato standard per la rappresentazione delle risorse, quindi siamo liberi di utilizzare il formato che ci è più familiare o comodo: dal semplice testo a XML. Tuttavia dobbiamo tener presente che un Web Service è pensato per essere utilizzato da un client scritto da altri e molto probabilmente vorremmo avere un utilizzo da parte di un ampio numero e tipo di client. Questo ci porta a prendere in considerazione un formato che sia il più possibile condiviso e possibilmente standardizzato, in modo che sia facilitata l'interpretazione e gestione da parte dei
vari possibili client.
Quindi, in linea di massima, se esiste un formato di rappresentazione di risorse universalmente accettato e che può essere utilizzato per i nostri scopi, allora è bene adottarlo. Ad esempio, se dobbiamo gestire documenti per cui (X)HTML è sufficientemente espressivo nella rappresentazione, perchè non utilizzarlo?
Riallacciandoci al nostro piccolo progetto, nel nostro caso utilizzeremo un formato ad hoc basato su XML. Ad esempio, un ordine potrebbe essere rappresentato come segue:
<ordine xmlns="http://schemi.mionegozio.com/ordine">
<id>123</id>
<data>01/07/2011</data>
<cliente>Mario Rossi</cliente>
<stato>EVASO</stato>
<dettagli>
<dettaglio>
<articolo>Libro</articolo>
<quantita>1</quantita>
</dettaglio>
<dettaglio>
<articolo>CD</articolo>
<quantita>5</quantita>
</dettaglio>
</dettagli>
</ordine>Naturalmente questa è una versione molto semplificata di un ordine reale, ma quello che ci interessa in questa fase è dare un'idea di cosa si intende per rappresentazione di una risorsa.