Web services - Configurazione

Sorvoliamo sulla installazione e abilitazione del modulo che è quella classica per Drupal. Le dipendenze del modulo services sono ctools e libraries, come indicato nella documentazione.
Una volta installati i moduli occorre abilitare ctools, libraries, servicies, e Server REST (è disponibile anche XMLRPC Server).

Rest server

REST e XMLRPC, senza voler approfondire, sono due dei possibili meccanismi per scambiare e rappresentare informazioni.

Negli esempi che seguono, saranno creati due endpoint, che identificano il punto (path) di accesso al servzio. Li chiamerò, arbitrariamente, naws e aws. Il primo per l'accesso ai services senza autenticazione e il secondo con autenticazione. In pratica, l'endpoint, è la parte di URL che identifica l'accesso ai web services, ad esempio www.sito.com/aws.

E' bene precisare che l'accesso dei dati via WS è possibile solo se l'utente (anonimo, nel caso di assenza di autenticazione) ha i dovuti permessi pertanto, se utente anonimo non ha il permesso ad accedere a determinate informazioni, le informazioni non saranno accessibili nemmeno via WS.

La configurazione di WS inizia con la definizione dell'endpoint e delle risorse, fra tutte quelle disponibili, che verranno messe a disposizione nell'endpoint. Possono essere definiti più endpoint, ognuno con le caratteristiche e le risorse desiderate.

Partiamo senza autenticazione e aggiungiamo l'endpoint, selezioniamo aggiungi www.sito.com/admin/structure/services:

Aggiunta endpoint

Il nome dell'endpoint è bene che sia qualcosa di significativo per l'amministratore dei WS.

Configurazione endpoint

La voce 2 in figura, Server, non è disponibile se non è stato abilitato il modulo REST Server.

Salvate le impostazioni occorre definire le risorse.

Aggiungi risorse

Le risorse sono gli 'oggetti' che Drupal può mettere a disposizione. Si tratta dei nodi, di utenti, della tassonomia, di parametri del sistema e altro.
Nell'esempio verranno abilitate le risorse nodi e utenti e tutte le sottorisorse disponibili. Le sottorisorse, sono le azioni possibili sulla risorsa. Ad esempio si può rendere disponibile il metodo GET sulla risorsa nodo, ma non il metodo DELETE.

Risorse Azioni sulle risorse

E' bene sottolineare che rendere disponibile un metodo, ad esempio DELETE, non significa consentire la cancellazione dei nodi a tutti via WS: la cancellazione sarà consentita solo agli utenti autorizzati quindi, di default, non all'utente anonimo.

Un ultimo sforzo serve per definire quali formati dati vengono resi disponibili. REST non definisce uno specifico formato per i dati scambiati, ma ne può utilizzare diversi. fra i più comuni ci sono XML (eXtensible Markup Language) e JSON (JavaScript Object Notation), quest'ultimo è particolarmente indicato per scambiare dati con applicazioni java. Se il client che utilizza i dati è una procedura scritta in PHP, formato PHP può essere quello opportuno.
I vari formati possono coesistere. La richiesta alla risorsa definirà il formato desiderato (fra quelli rese disponibili.
XML (ma anche json e php) hanno la caratteristica di essere facilmente leggibili anche da una persona (oltre che, ovviamente, da una macchina).

REST Formatter

La voce Request parsing, definisce quali MIME media type sono resi disponibili dai WS.

Salvate le configurazioni i WS sono disponibili e funzionanti. Basta provare.

Il modo più semplice per accedere ai WS vede l'utilizzo di un normale browser, inserendo l'opportuno URL. Proviamo a vedere quali sono i nodi inseriti nel sito (quelli per cui l'utente anonimo ha i permessi).

L'URL è www.sito.com/naws/node  (nomesito/endpoint/risorsa)

Si tratta del nome del sito seguito dall'endpoint e dal nome della risorsa. Il risultato è l'elenco (list) dei nodi in formato XML.

Node list

Lo stesso elenco è disponibile in formato json, semplicemente aggiungendo .json all'URL della richiesta: www.sito.com/naws/node.json Un po' difficile da leggere se non si riorganizza la risposta.

Json Node list 

{
                "nid":"40",
                "vid":"40",
                "type":"article",
                "language":"it",
                "title":"Il mio nodo",
                "uid":"13",
                "status":"1",
                "created":"1470060869",
...

Per accedere ad uno specifico nodo, basta aggiungere il numero del nodo all'URL: www.sito.com/naws/node/1 (www.sito.com/naws/node/1.json per il formato json)

Nodo in json

Le operazioni si complicano se si vogliono testare i WS con richieste più complesse, ad esempio per postare un nodo.

In questo caso non è possibile utilizzare l'URL del browser per richiamare il metodo POST. Occorre, inoltre compilare correttamente l'header della richiesta HTTP e passare ai WS i dati necessari (non possibile via URL).

Per prove occorrono strumenti adeguati, come plugin del browser o programmi ad hoc. Ad esempio per Firefox si può usare Hottprequester o Postman in Crome.

Questo però alla prossima puntata.

Si conclude con un paio di video che in modo semplice illustrano le varie operazioni.

 

 

 

Tipologia: