Definire un Server REST

All’interno di questo capitolo analizzeremo la creazione di un Web Service REST collegato ad un generico sito di e-commerce, tale web server avrà il compito di fornire le informazioni riguardanti gli ordini effettuati dagli utenti e le relative fatture.

La definizione del Web Service dovrà essere preceduta dalla definizione delle risorse esposte (ordini, fatture, eccetera). Durante questa fase dovremo cercare di separare il più possibile l’implementazione degli oggetti dalla loro interfaccia, in questo modo sarà più facile evidenziare le informazioni che dovranno essere presentate dal nostro Web Service. Nello sviluppare la nostra applicazione, ad esempio, non dovremo inserire tra le risorse esposte l’elenco dei clienti o dei fornitori registrati all’interno dell’e-commerce. Ci limiteremo a mappare alcune delle informazioni riguardanti gli ordini già effettuati, restringendo le operazioni ammissibili su tali risorse alle sole indispensabili.

Ci preoccuperemo poi di collegare tra loro le risorse, ad esempio, collegheremo le fatture emesse agli ordini a cui sono associate, e viceversa.

Definire gli URI

Completata la definizione delle nostre risorse, dovremo procedere con la realizzazione degli URI che le identificheranno (REST non fornisce alcuno standard per la definizione degli URI). Il nostro Web Service REST, ad esempio, potrebbe identificare in questo modo l’ordine con codice ‘123’: http://www.site.com/orders/123, oppure http://www.site.com/orders/?id=123.

Durante la definizione degli URI dovremmo tenere a mente alcuni concetti utili:

  • Preferire i nomi ai verbi, l’uso dei verbi (ad esempio: http://www.site.com/getOrders/123, oppure http://www.site.com/viewOrders/123) può essere forviante, potrebbe indurre a pensare che all’URI in questione sia associata un’azione, piuttosto che una risorsa. In ambito REST gli URI individuano sempre delle risorse, mentre le azioni sono demandate ai metodi HTTP;
  • Utilizzare uno schema posizionale, un modello di URI che sfrutta la struttura gerarchica delle informazioni è sempre da preferirsi rispetto ad un modello che richiede il passaggio di più argomenti. Ad esempio, se vogliamo individuare gli ordini in base alla data, è da preferire lo schema http://www.site.com/viewOrders/2019/01/25, al posto di http://www.site.com/orders/?year=2019&month=01&day=25;
  • Nascondere le estensioni, durante la definizione degli URI è bene evitare l’inserimento di estensioni che vincolano un Web Service alla sua implementazione. Ad esempio, è da preferire un URI del tipo: http://www.site.com/orders/?id=123 ad uno del tipo: http://www.site.com/orders/order.php?id=123;
  • Contenere la lunghezza degli URI.

Definire i metodi sulle risorse

Al processo di definizione delle risorse seguirà l’individuazione dei metodi HTTP che potranno essere eseguiti su di esse. A questo proposito può essere utile creare una tabella in grado di riassumere l’insieme delle operazioni ammesse. Nel nostro caso:

URI GET PUT POST DELETE
/orders/?id=xxx SI SI SI DIPENDE
/articoli/?id=xxx SI NO NO NO
/fatture/?id=xxx SI NO NO NO

Ad esempio: le operazioni di lettura, modifica e creazione di un ordine sono sempre ammesse, tuttavia l’eliminazione è eseguibile solamente in alcune circostanze.

Rappresentazione delle risorse

Come abbiamo già sottolineato in precedenza, REST non impone alcuno standard per la rappresentazione delle risorse. Tuttavia, al fine di rendere fruibile il nostro servizio da più utilizzatori possibili, dovremo considerare l’utilizzo di un formato standard, largamente utilizzato e compatibile con un vasto numero di linguaggi. Per questo motivo, la maggior parte dei Web Service REST oggi disponibili restituiscono i dati in formato XML, oppure in formato JSON.

Tornando al nostro caso d’esempio, potremmo utilizzare il seguente documento XML per ritornare le informazioni di un generico ordine:

<order xmlns="http://scheme.ecommerce.com/order">
  <id>123</id>
  <date>01/07/2011</date>
  <customer>Mario Rossi</customer>
  <state>EVASO</state>
  <products>
    <product>
      <article>Libro</article>
      <qty>1</qty>
    </product>
    <product>
      <article>CD</article>
      <qty>5</qty>
    </product>
  </products>
</order>