Creare un client RESTful

I cinque principi analizzati nelle lezioni precedenti ci consentono di definire un Web Service aderente ad una architettura in stile REST. Ma cosa vuol dire questo in pratica? In questro capitolo vedremo proprio come sfruttare questi principi per interagire o sviluppare un servizio Web.

Iniziamo concentrandoci nell'interazione con un Web Service esistente. Creeremo un client RESTful, cioè in grado interagire con un Web Service di tipo REST, in questo modo metteremo in pratica quanto appreso sui principi REST. Ecco ciò di cui abbiamo bisogno:

• un client HTTP
• le URI delle risorse a cui vogliamo accedere
• la capacità di interpretare il formato delle rappresentazione delle risorse

Creare un client RESTful è in un certo senso simile a realizzare un piccolo browser Web specializzato nell'interpretazione delle risorse messe a disposizione dal Web Service.

Consumare le API di Blogger

Scendendo nel concreto, prendiamo il servizio Web RESTful esposto dalle Blogger API di Google, che consente di interagire con la nota piattaforma di blogging. Grazie a queste API un'applicazione può accedere ai post di un blog, può crearne di nuovi e modificare o eliminare quelli esistenti.

Seguendo le specifiche delle API proveremo a creare un semplice client per la gestione dei post di un ipotetico blog.

Si tratta essenzialmente di un esercizio a scopo didattico, per cui il codice che mostreremo non ha la pretesa di essere completo né affidabile. Ignoreremo ad esempio la necessità di un'autenticazione e tutti gli aspetti di sicurezza che verranno affrontati più avanti.

Come prima cosa abbiamo bisogno di un client HTTP. Potremmo pensare ad un classico browser Web, cosa da non trascurare come forma rudimentale di debugger, ma parlando della realizzazione di un client non possiamo prescindere da quello che lo specifico linguaggio e/o ambiente di programmazione ci mette a disposizone per gestire il protocollo HTTP.

Per i nostri esempi utilizzeremo la piattaforma .NET ed il linguaggio C#, sfruttando le classi WebRequest e WebResponse per la gestione del protocollo HTTP.

Non dovrebbe essere particolarmente complesso riportare le operazioni che vedremo in un altro ambiente di programmazione.

Evitiamo volutamente l'utilizzo di framework ed approcci a più alto livello perchè il nostro obiettivo in
questa sede è di concentrarci sui concetti di base dell'approccio REST.

La seconda cosa di cui abbiamo bisogno è l'insieme delle URI che individuano le risorse che andremo a gestire. Seguendo le specifiche delle Blogger API e supponendo che il nostro profileID sia 1234567890, possiamo riepilogare le risorse accessibili nel seguente modo:

La terza ed ultima cosa che ci occorre sapere è il formato con cui verranno rappresentate le risorse richieste. Nel costro caso, il formato previsto dalle Blogger API è Atom 1.0.

Effettuare una richiesta

Una volta stabilite le URI che identificano le risorse non ci resta vedere come ottenerne una sfruttando il metodo GET. Supponendo quindi di voler richiedere l'elenco dei post del blog con identificatore 12345 dovremmo scrivere del codice analogo al seguente:

HttpWebRequest request =  (HttpWebRequest)WebRequest.Create("http://www.blogger.com/feeds/12345/posts/default");
request.Method = "GET";
HttpWebResponse response = (HttpWebResponse)request.GetResponse();
if (response.StatusCode == HttpStatusCode.OK) {
	Stream responseStream = response.GetResponseStream();
	DecodeResource(responseStream);
}
response.Close()

In sintesi, creiamo una richiesta verso l'URI che identifica l'elenco dei post del nostro blog, specifichiamo il metodo GET, inviamo la richiesta e rimaniamo in attesa della risposta tramite il metodo GetResponse(). Se lo stato della risposta è OK, accediamo al contenuto della risposta tramite il metodo GetResponseStream() e lo interpretiamo tramite una ipotetica procedura DecodeResource().

La rappresentazione della risorsa richiesta sarà qualcosa di simile a quanto segue:

<?xml version='1.0' encoding='utf-8'?>
<?xml-stylesheet href="http://www.blogger.com/styles/atom.css" type="text/css"?>
<feed xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"D08FQn8-eip7ImA9WxZbFEw."'>
  <id>tag:blogger.com,1999:blog-12345</id>
  <updated>2011-04-17T00:03:33.152-07:00</updated>
  <title>Il mio blog</title>
  <subtitle type='html'></subtitle>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'href='http://ilmioblog.blogspot.com/feeds/posts/default' />
  <link rel='self' type='application/atom+xml' href='http://www.blogger.com/feeds/12345/posts/default' />
  <link rel='alternate' type='text/html' href='http://ilmioblog.blogspot.com/' />
  <author>
    <name>Mario Rossi</name>
	<uri>http://www.blogger.com/profile/1234567890</uri>
	<email>noreply@blogger.com</email>
  </author>
  <generator version='7.00' uri='http://www2.blogger.com'>Blogger</generator>
  <entry gd:etag='W/"D0YHRn84eip7ImA9WxZUFk8."'>
    <id>tag:blogger.com,1999:blog-12345.post-67890</id>
	<published>2011-04-07T20:25:00.005-07:00</published>
	<updated>2011-04-07T20:25:37.132-07:00</updated>
	<title>Il mio primo post</title>
	<content type='html'>Questo È il mio primo post per il mio nuovo blog</content>
	<link rel='edit' type='application/atom+xml' href='http://www.blogger.com/feeds/12345/posts/default/67890' />
	<link rel='self' type='application/atom+xml' href='http://www.blogger.com/feeds/12345/posts/default/67890' />
	<link rel='alternatÈ type='text/html' href='http://ilmioblog.blogspot.com/2011/04/ilmioprimopost.html' />
    <author>
	  <name>Mario Rossi</name>
	  <uri>http://www.blogger.com/profile/1234567890</uri>
	  <email>noreply@blogger.com</email>
	</author>
  </entry>
</feed>

In questo feed Atom si trova la rappresentazione dell'elenco dei post del nostro blog che nel caso specifico si tratta di un unico post. Il compito della procedura DecodeResource() consiste nell'interpretare questa rappresentazione e trasformarla in un oggetto facilmente manipolabile da parte del client, come potrebbe essere ad esempio il risultato di una deserializzazione.

Come possiamo vedere, all'interno della rappresentazione dell'elenco dei post si trova l'URI dell'unico post

http://www.blogger.com/feeds/12345/posts/default/67890

e l'URI del profilo dell'autore

http://www.blogger.com/profile/1234567890

Si tratta delle risorse collegate alla risorsa corrente. Quindi se la nostra applicazione avrà bisogno di accedere a queste risorse sarà sufficiente utilizzare i corrispondenti URI.

Le specifiche delle Blogger API prevedono la possibilità si selezionare un sottoinsieme dei post di un blog specificando dei criteri come ad esempio le date di pubblicazione. Ad esempio, se vogliamo selezionare i post pubblicati nella prima metà del 2011 possiamo eseguire una GET sul seguente URI:

http://www.blogger.com/feeds/12345/posts/default?published-min=2011-01-01T00:00:00&published-max=2011-06-30T23:59:59

A prima vista questo modo di indicare una risorsa potrebbe apparire in contrasto con i principi RESTful. La presenza di parametri nell'URI potrebbe far pensare ad una chiamata di procedura piuttosto che ad un identificatore di risorsa.

In realtà l'approccio è del tutto legittimo in quanto la stringa è univoca ed identifica esattamente la risorsa che vogliamo ottenere senza alcun effetto collaterale. La presenza dei parametri ci da la sensazione di una chiamata di procedura (e con ogni probabilità l'implementazione sottostante lo è) ma da un punto di vista REST non si tratta che di una sequenza di caratteri per l'identificazione di una risorsa.