Sviluppare un webservice restful JSON -

Se hai la necessità di accedere on line al tuo database da un app ANDROID, IOS oppure Windows PHONE eccoti una semplice guida che si spiega passo come implementare un servizio REST che ti consente di accedere on line al tuo database. L’esempio è stato sviluppato utilizzando Microsoft Visual Studio 2013 Community Edition Con il termine REST (Representational State Transfer) si rappresenta un’architettura di sistema per lo scambio di dati in un’ambiente scalabil e utilizzabile da diversi dispositivi. Non parliamo di uno standard di fatto o di un protocollo ma di un metodo per sviluppare web services che consente la rappresentazione dei dati in un formato consumabile da diversi dispositivi e ambienti di sviluppo. Infatti, mentre all’inizio internet era concentrato solo su una richiesta HTTP che procedeva a generare una pagina HTML da consultare con un browser adesso le cose sono molto diverse e i server internet processano informazioni che posso scambiarsi con altre applicazioni e aggiornare dati presenti su server diversi sempre con richieste HTTP specifiche. Oggi questa architettura è usata da quasi tutte le società che erogano servizi o strumenti di sviluppo per i loro prodotti, ad esempio Google usa le chiamate REST su moltissime API per richiedere informazioni di qualsiasi genere, ad esempio google maps, youtube, calendar, management API, etc, etc. Anche su Amazon Web Services praticamente ogni servizio esistente può essere configurato o analizzato tramite AWS REST API Altra applicazione fondamentale dei servizi REST la troviamo nell’IOT (Internet delle Cose) perché rende semplice la condivisione e il controllo dello stato di oggetti tramite il web.

REST API – Descrizione generale

L’architettura REST si basa sostanzialmente su cinque principi fondamentali che devono essere rispettati durante la sua definizione, è importante capire questi concetti sia per chi deve solo utilizzare un’ambiente REST e sia per chi vuole costruirci un’applicazione.

1) Le risorse: rappresentano gli elementi fondamentali di un Server RESTful e vengono usate come elementi di elaborazione, ad esempio possiamo avere risorse come clienti, utenti, libri, giochi, server, video e qualsiasi cosa possa avere delle informazioni che possono essere lette o aggiornate. Ogni risorsa deve essere identificata in maniera univoca, e dato che parliamo di WEB non esiste di meglio che un URL.

1) https://example.com/cliente/12345
2) https://example.com/ordine/2014/12345
3) https://example.com/libro/12345
4) https://example.com/video/
5) https://example.com/video?genere=avventura

In questo esempio possiamo vedere una risorsa che rappresenta un cliente, un ordine specifico, un libro, l’elenco dei video disponibili e un elenco video solo di avventura. In poche parole ogni URL rappresenta una risorsa su cui posso essere richiesti diversi tipi di elaborazione, ad esempio le caratteristiche di un libro identificato da un particolare codice ma anche l’elenco di libri scritti da un determinato autore. Se vogliamo fare degli esempi concreti provate a cliccare su uno dei seguenti link e otterrete delle informazioni sulla risorse che andiamo a richiedere, ad esempio il primo link è una richiesta a youtube per richiedere i video con termine di ricerca “amazon”.

Come potete notare vi ho elencato alcuni link che generano informazioni pubbliche, infatti la maggior parte delle chiamate come vedremo anche in seguito necessitano di una autenticazione o di una chiave generata dal servizio stesso. 2) Utilizzo dei metodi HTTP: nel paragrafo precedente abbiamo visto come accedere alle risorse REST ed ottenere le informazioni richieste, però come facciamo per modificarle, aggiungerne di altre o eliminarle ? La risposta è quella di usare sempre lo stesso URL per identificare la risorsa ma cambiare il metodo HTTP con uno dei seguenti valori:

GET	Lettura	Informazioni risorsa
POST	Creazione	Nuova risorsa
PUT	Aggiornamento	Modifica risorsa
DELETE	Cancellazione	Elimina risorsa

Per chi non lo sapesse ogni richiesta HTTP viene accompagnata da un metodo standard, ad esempio quando indicate sul browser un’indirizzo URL in realtà il browser spedirà la richiesta al server di destinazione con un metodo GET. Ci sono casi ad esempio con i form HTML che vengono utilizzati anche i metodi POST, in ogni caso se usate un qualsiasi codice di programmazione potete specificare il metodo che desiderate.

1) https://example.com/changeBook?id=12345
2) https://example.com/book/12345 con metodo PUT

Se volete divertirvi a testare la differenza tra i vari metodi POST, GET; PUT DELETE potete utilizzare la pagina web www.requestmaker.com che Vi consente di interagire con qualsiasi tipo di servizio RESTFUL. Vi riporto queste due righe che identificano due URL per cambiare ad esempio una risorsa libro, la prima riga non è ammessa in un’architettura REST e rappresenta la chiamata ad uno script specifico, mentre la seconda riga rappresenta la maniera giusta di richiedere una modifica alla risorsa, stesso URL ma utilizzo di un metodo diverso. 3) Risorse autodescrittive: una volta che viene eseguita una richiesta REST il risultato può e deve essere ritornato in un formato descrittivo che non deve essere per forza collegato alla struttura di un database, ad esempio possiamo restituire sempre un formato JSON o XML a prescindere dalla complessità dei dati che hanno generato l’informazione. Nulla vieta di utilizzare un formato proprietario, però per facilitare i client è sempre meglio utilizzare un formato standard come ad esempio JSON. 4) Collegamenti tra risorse: nell’architettura REST i collegamenti delle risorse devono sempre avvenire tramite degli URL e anche le informazioni che compongono le diverse parti di una risorsa devo rispettare questo principio. Ad esempio se richiedo con un GET una risorsa “libro” gli eventuali dati come “autore“, “editore“, etc, etc, devono essere specificati sempre tramite un URL che può essere utilizzato per ottenere altre info. 5) Comunicazione stateless: la comunicazione senza stato è una caratteristica propria del protocollo HTTP e indica il fatto che una richiesta client non ha nessuna relazione con le richieste precedenti o successive. Le applicazioni RESTful devono rispettare lo stesso principio, i benefici sono diversi ma il più importante è la scalabilità, infatti se ogni richiesta rimane svincolata dalle altre può essere eseguita su qualsiasi server che non deve mantenere ricordo storico, questo facilita la distribuzione delle informazioni su applicazioni diverse e il bilanciamento automatico del carico di lavoro.

Formato JSON – Descrizione generale

Abbiamo appena visto che in REST si ottengono e si modificano le informazioni tramite delle chiamate URL particolari. Il formato dei dati che viene scambiato può essere di diversi tipi, però dato che JSON è uno dei più popolari ed è quello che è stato scelto da WordPress per l’integrazione nel core ci soffermeremo solo su questo formato. JSON (JavaScript Object Notation) è un semplice formato per lo scambio di dati. Per le persone è facile da leggere e scrivere e per le macchine risulta facile da elaborare con i vari linguaggi di programmazione. La sua popolarità è dovuta al successo di AJAX che permetteva di eseguire del codice asincrono in una pagina HTML che richiedeva ad un un server informazioni specifiche. JSON è basato su due strutture:

Coppie nome/valore: In diversi linguaggi, questo è realizzato come un oggetto, un record, un dizionario, una tabella hash, un elenco di chiavi o un array associativo.
Un elenco ordinato di valori: Nella maggior parte dei linguaggi di programmazione questo si realizza con un array, un vettore, un elenco o una sequenza.

Qui di seguito vi riporto l’esempio di una struttura JSON che come potete vedere è molto meno prolissa di una sintassi XML e un esempio di codice PHP per farvi vedere con quale semplicità è possibile richiedere una risorsa REST e convertirla in array:

// Struttura di esempio per formato JSON
// che può essere generato dopo una richiesta REST
{"employees":[
  {"firstName":"John", "lastName":"Doe"},
  {"firstName":"Anna", "lastName":"Smith"},
  {"firstName":"Peter","lastName":"Jones"}
]}
// Esempio PHP per esecuzione richiesta GET e
// conversione del risultato in un array
$jurl = "https://gdata.youtube.com/feeds/api/videos?q=amazon&alt=json";
$json = file_get_contents($jurl);
$data = json_decode($json,TRUE);

L’esempio di codice PHP riportato non prevede autenticazione, quindi se volete fare delle prove utilizzate degli URL che permettano delle interrogazione pubbliche.

REST API – Autenticazione

Ovviamente non tutte le risorse disponibili su WordPress sono accessibili con chiamata pubblica, molte necessitano di un’autenticazione prima di effettuare la chiamata. Al momento i metodi di autenticazione sono un pochino sparsi con l’installazione di plugin aggiuntivi che trovate nella documentazione sezione autenticazione. Però nel rilascio ufficiale il metodo sarà OAuth 2.0 e sarà disponibile direttamente nel core. Ad esempio chi utilizza già le API di Google o Amazon saprà che si tratta di generare un token che sarà utilizzato in ogni chiamata REST fino alla sua scadenza.

WordPress REST API – Conclusioni

Questo articolo non è stato scritto per spiegare le chiamate REST API con dettagliati esempi di codice, è stato più un tentativo di mettere sulla giusta strada chi utilizza PHP per sviluppare su WordPress e che dovrà nel prossimo futuro fare i conti con questa tecnologia. Spero di aver raggiunto questo obiettivo augurandovi tante belle applicazioni che useranno come protagonista sempre il nostro caro WordPress.

Nel prossimo articolo pubblicheremo un esempio completo di servizio RESTFUL JSON sviluppato in c#. Seguici!