Questa versione: Protocollo09
Ultima versione: Protocollo09
Versione Precedente: Nessuna
Autori: FabioVitali, SilvioPeroni, FrancescoPoggi
Questo protocollo nasce all’interno del progetto Meta Market del corso di Tecnologie Web 2011/2012. L'obiettivo del progetto è di un motore per la creazione di rappresentazioni visuali e comprensibili di collezioni di dati numerici.
Il protocollo si compone in realtà di due protocolli diversi: Descrittore-Aggregatore (DA) e Narratore-Descrittore (ND). L’architettura Meta Market prevede infatti tre componenti principali: un aggregatore (per rispondere a richieste inerentemente ai dati crudi da esso gestiti), uno o più descrittori (per l'elaborazione sofisticata dei dati forniti dall'aggregatore) e almeno due navigatori per la presentazione dei dati ricevuti dai descrittori. Ogni narratore comunica coi descrittori tramite il protocollo ND, mentre ogni descrittore comunica con l'aggregatore tramite il protocollo DA.
Questo documento è stato redatto da FabioVitali?, SilvioPeroni? e FrancescoPoggi?. Deve essere utilizzato come materiale di riferimento per il progetto Meta Market per garantire l’interoperabilità fra i gruppi. Questo documento è la versione 0.9 del protocollo ed è soggetto a modifiche da parte dei working group organizzati secondo le regole del W3C (http://www.w3.org/Consortium/Process/). I WG potranno emettere i documenti di riferimento aggiornati, numerati e versionati, che verranno usati per le specifiche di interoperabilità.
Metamarket è composto da un data base di strutture commerciali e e non, presentato all'utente sotto forma di tabella o cartina geografica. In particolare, il database può descrivere:
Inoltre, grazie ad una interfaccia via browser, l'utente può filtrare i risultati visualizzati:
Ogni gruppo ha l'obbligo di implementare almeno un aggregatore e un numero variabile di descrittori. Per ogni gruppo, l'aggregatore e i descrittori hanno degli identificativi ben precisi e sono reperibili in determinati URL. Tutte le informazioni su aggregatore e descrittori sono pubblicate online sotto forma di catalogo (vedi sezione 4).
DA è un protocollo HTTP che regola la comunicazione tra un descrittore e un aggregatore. Di seguito sono descritte tutte le possibili richieste previste. Le richieste sono progettate secondo l'architettura REST.
Per ogni richiesta è indicato:
È possibile richiedere ad un particolare aggregatore, identificato da un URL, dei dati coerentemente a dei parametri specificati come input dal descrittore.
Metodo: GET
URL: http://ltwxxxx.web.cs.unibo.it/<aggregatore>/<key>/<comp>/<value>[/<sorting>/<sortingKey>]?
dove:
http://ltwxxxx.web.cs.unibo.it/<aggregatore> è l'URL dell'aggregatore da consultare<key> è una delle chiavi definite nel modello dei dati (vedi sezione 6).<comp> è un confrontatore a scelta tra LT (minore di), GT (maggiore di), LE (minore o uguale a), GE (maggiore o uguale a), EQ (uguale a), NE (diverso da), CONTAINS (contiene).<value> è il valore da confrontare per la chiave specificata.<sorting> specifica di ordinanare i risultati in modo ascendente (quando specificato a ASC) o discendente (se specificato a DESC).<sortingKey> è la chiave secondo il quale ordinare i risultati.
Esempio: http://ltw1234.web.cs.unibo.it/aggregatoreltw11/tipologia/NE/farmacia/ASC/nome chiede all'aggregatore disponibile all'URL http://ltw1234.web.cs.unibo.it/aggregatoreltw11/ di restituire tutte le attività che non sono farmacie, ordinando i risulati in maniera crescente secondo la chiave nome.
Header: Accept: text/turtle, application/rdf+xml, text/plain, text/json, application/xml
Body: vuoto
Header: Content-type: <mime-type>
dove:
<mime-tipe> è uno a scelta tra text/turtle | application/rdf+xml | text/plain | text/json | application/xml a seconda del formato di cui dispone l'aggregatore.Body: (con application/rdf+xml formato restituito)
<locations>
<metadata>
<creator>Fabio Vitali</creator>
<created>10/09/2011</created>
<version>1.1</version>
<source>http://cs.unibo.it</source>
<valid>31/12/2011</valid>
</metadata>
<location id="cs" lat="28.847607" long="57.084961">
<category>Dipartimento, Università</category>
<name>Dipartimento di Scienze dell'Informazione</name>
<address>Mura Anteo Zamboni 7, 40127, Bologna, Italy</address>
<opening>mon-fri: 8:30-20:00, sat: 8:30-12:30</opening>
<closing>04/10/2011 , 25/12/2011</closing>
</location>
<location id="eatly" lat="44.494516" long="11.344512">
<category>Ristorante, Bar, Alimentare, Libreria</category>
<name>Eatly - alti cibi</name>
<address>Via degli Orefici 19, 40126, Bologna, Italy</address>
<opening>mon-sat: 8:00-24:00, sun: 10:00-24:00</opening>
<closing>01/01/2011 , 15/08/2011, 25/12/*, 26/12/2011, 01/01/2012</closing>
</location>
...
</locations>
ND è un protocollo HTTP che regola la comunicazione tra un narratore e un descrittore. Di seguito sono descritte tutte le possibili richieste previste. Le richieste sono progettate secondo l'architettura REST.
Per ogni richiesta è indicato:
È possibile richiedere ad un particolare descrittore, identificato da un URL, dei dati coerentemente a dei parametri specificati come input dal narratore.
Metodo: GET
URL: http://ltwxxxx.web.cs.unibo.it/<descr>/<aggregatore1>[/<aggregatore_i>]*/[params/[<param/>]+]*
dove:
http://ltwxxxx.web.cs.unibo.it/<descr> è l'URL del descrittore<catalogo1> è l'identificativo del catalogo contenente l'URL dell'aggregatore a cui il descrittore deve attingere i dati crudi<catalogo_i> sono gli identificativi di altri cataloghi contenenti gli URL di eventuali aggregatori aggiuntivi da considerare nel caso in cui il descrittore debba attingere a dati contenuti in più aggregatori contemporaneamente<param/> sono dei parametri opzionali eventualmente richiesti dal descrittore per funzionareEsempio: http://ltw1234.web.cs.unibo.it/vicino-a/farmacie-e-supermercati/farmacie-bologna/params/28.847607/57.084961/farmacia/10 chiede al descrittore di restituire le 10 farmacie più vicine alla locazione (data dalla latitudine e longitudine) specificata, considerando i dati gestiti dagli aggregatori dei cataloghi farmacie-e-supermercati
e farmacie-bologna
.
Header: Accept: <mime-type>
dove:
<mime-tipe> è uno a scelta tra text/turtle | application/rdf+xml | text/csv | text/json | application/xml per restituire un formato strutturato oppure text/plain per restituire un formato letteraleBody: vuoto
Header: Content-type: <mime-type>
dove:
<mime-tipe> è uno a scelta tra text/turtle | application/rdf+xml | text/csv | text/json | application/xml | text/plain per restituire un formato letterale a seconda del formato richiesto dal narratore.Body (con text/turtle formato restituito):
@prefix : <http://ltwxxxx.web.cs.unibo.it/resource/> .
@prefix time: <http://www.w3.org/2006/time#> .
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .
@prefix lode: <http://linkedevents.org/ontology/> .
@prefix cs: <http://cs.unibo.it/ontology/> .
:farmacia-comunale a vcard:VCard
; vcard:category "Farmacia" , "Luogo pubblico"
; vcard:fn "Farmacia Comunale Centrale"
; vcard:extended-address "Piazza Maggiore 6, 40121, Bologna, Italy"
; vcard:latitude "28.847607"
; vcard:longitude "57.084961"
; cs:opening "mon-sun: 8:00-20:30" .
...
Nel caso in cui una richiesta generi un errore, l'aggregatore/descrittore DEVE rispondere utilizzando gli appropriati codici HTTP 4xx e 5xx. I descrittori/narratore DEVONO gestire ogni codice d'errore in maniera appropriata.
Descrittori e narratori DEVONO gestire almeno questi errori (con relativi codici HTTP):
In aggiunta ai codici d'errore HTTP, il contenuto fornito dal server deve fornire più indicazioni possibili sull'errore generato e fornire suggerimenti su come risolverlo. I servizi sono liberi di usare qualsiasi tipo di dato per il contenuto restituito, tenendo comunque in considerazione la richiesta originaria del client (fornite nell'header Accept o in altro modo).
Ogni gruppo partecipante deve pubblicare da qualche parte un documento XML, detto catalogo, contenente informazioni riguardo al proprio aggregatore, ai descrittori e ai navigatori sviluppati, ad esempio:
<catalogo id="farmacie-e-supermercati" gruppo="Thank you for coding">
<aggregatore url="http://ltw1234.web.cs.unibo.it/aggregatore/">Dati riguardo le maggiori farmacie e supermercati di Bologna città, con locazioni, indirizzi e orari di apertura.</aggregatore>
<descrittori>
<descrittore url="http://ltw1234.web.cs.unibo.it/vicino-a" desc="Restituisce i luoghi più vicini al punto specificato">
<params>
<param name="latitude" required="yes">La latitudine di partenza</param>
<param name="longitude" required="yes">La longitudine di partenza</param>
<param name="category" required="yes">La tipologia di luogo da ricercare. Usare '*' se si vogliono considerare tutte le tipologie.</param>
<param name="number of result" required="no">Parametro opzionale, in cui specificare il massimo numero di risultati che si vuol ricevere in risposta.</param>
</params>
</descrittore>
<descrittore>
...
</descrittore>
...
</descrittori>
<narratori>
<narratore url="http://ltw1234.web.cs.unibo.it/vicino-a/mappa">Visualizza le locazioni su una mappa grazie all'ausilio delle API Google Maps.</narratore>
<narratore url=...> ... </narratore>
...
</narratori>
</catalogo>
Tutti i cataloghi di tutti i gruppi devono essere registrati in un ulteriore file XML chiamato meta-catalogo, il cui URL deve essere chiaramente indicato in queste specifiche. Nel meta-catalogo si trovano gli identificativi (univoci) dei cataloghi e i relativi URL in cui essi risiedono:
<metaCatalogo>
<catalogo id="farmacie-e-supermercati" gruppo="Thank you for coding" url="http://ltw1234.web.cs.unibo.it/catalogo" />
<catalogo ... />
...
</metaCatalogo>
In questa sezione viene descritto il modello dei dati da utilizzare per restituire i risultati alle richieste fatte verso l'aggregatore o verso un descrittore.
I dati da gestire devono riguardare luoghi (fisici o virtuali), devono essere geolocalizzabili e devono avere specificati degli orari di apertura e di chiusura. Conseguentemente, i campi che devono essere gestiti sono:
Informazioni sui vari documenti in cui sono salvati i dati, come quelle riguardanti la freschezza, la versione, l'intervallo di validità e le informazioni per il riaccesso ai dati aggiornati. In particolare:
Le informazioni introdotte nelle sezioni precedenti possono essere espresse in cinque diversi formati: Comma-Separated Values (CVS), JSON, XML, RDF/XML e Turtle.
Di seguito vengono descritti tutti i formati e vengono proposti relativi esempi inerentemente alla seguente descrizione: nel documento, creato da Fabio Vitali il 10 settembre 2011 e modificato l'ultima volta da Silvio peroni il 12 ottobre 2011, sono inserite informazioni riguardo gli orari di apertura del Dipartimento di Scienze dell'Informazione dell'Università di Bologna.
Il formato CSV (http://tools.ietf.org/html/rfc4180) è formato da un header, che indica i nomi dei vari campi, che è seguito da un numero arbitrario di record (ovvero righe) contenenti i vari dati. I campi possibili per questo formato sono:
ID , TYPE, NAME , LAT , LONG , ADDRESS , OPEN , CLOSE , CREATOR , CREATED , VERSION , SOURCE , VALID
cs , "Dipartimento , Università" , Dipartimento di Scienze dell'Informazione , 28.847607 , 57.084961 , "Mura Anteo Zamboni 7 , 40127 , Bologna , Italy" , "mon-fri: 8:30-20:00 , sat: 8:30-12:30" , "04/10/2011 , 25/12/2011" , Fabio Vitali , 10/09/2011 , 1.1 , http://cs.unibo.it , 31/12/2011
Il formato JSON (http://tools.ietf.org/html/rfc4627) permette di definire oggetti per specificare le varie informazioni. Le chiavi dei vari oggetti da utilizzare per le informazioni da gestire sono:
{
"cs" : {
"categories" : ["Dipartimento" , "Università"] ,
"name" : "Dipartimento di Scienze dell'Informazione" ,
"lat" : "28.847607" ,
"long" : "57.084961" ,
"address" : "Mura Anteo Zamboni 7, 40127, Bologna, Italy" ,
"opening" : [ "mon-fri: 8:30-20:00" , "sat: 8:30-12:30" ] ,
"closing" : [ "04/10/2011" , "25/12/2011" ] ,
} ,
"metadata" : {
"creator" : "Fabio Vitali"
"created" : "10/09/2011"
"version" : "1.1"
"source" : "http://cs.unibo.it"
"valid" : "31/12/2011"
}
}
Il formato XML (http://www.w3.org/XML/) permette di descrivere i dati attraverso elementi e attributi di markup. Il vocabolario e i content model degli elementi e attributi del formato devono essere esplicitamente definiti dal working group sotto forma di grammatica (DTD, RelaxNG? o XML Schema) in modo da evitare possibili ambiguità.
Ogni documento in formato XML deve iniziare con l'elemento document. Tutte le informazioni vanno gestite con i seguenti elementi:
<locations>
<metadata>
<creator>Fabio Vitali</creator>
<created>10/09/2011</created>
<version>1.1</version>
<source>http://cs.unibo.it</source>
<valid>31/12/2011</valid>
</metadata>
<location id="cs" lat="28.847607" long="57.084961">
<category>Dipartimento , Università</category>
<name>Dipartimento di Scienze dell'Informazione</name>
<address>Mura Anteo Zamboni 7, 40127, Bologna, Italy</address>
<opening>mon-fri: 8:30-20:00 , sat: 8:30-12:30</opening>
<closing>04/10/2011 , 25/12/2011</closing>
</location>
</document>
Il formato RDF/XML (http://www.w3.org/TR/REC-rdf-syntax/) e Turtle (http://www.w3.org/TR/turtle/) permettono di descrivere i dati per il Semantic Web, in modo che possano essere facilmente integrati all'interno del Linked Data. I dati devono essere descritti nel rispetto di specifiche ontologie, in particolare:
Tutte le informazioni vanno gestite con le seguenti risorse:
<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:xsd="http://www.w3.org/2001/XMLSchema#" xmlns:vcard="http://www.w3.org/2006/vcard/ns#" xmlns:cs="http://cs.unibo.it/ontology/" xmlns:dcterms="http://purl.org/dc/terms/">
<rdf:Description rdf:about="http://ltwxxxx.web.cs.unibo.it/resource/cs">
<vcard:category>Dipartimento</vcard:category>
<vcard:category>Università</vcard:category>
<vcard:fn>Dipartimento di Scienze dell'Informazione</vcard:fn>
<vcard:extended-address>Mura Anteo Zamboni 7, 40127, Bologna, Italy</vcard:extended-address>
<vcard:latitude>28.847607</vcard:latitude>
<vcard:longitude>57.084961</vcard:longitude>
<cs:opening>mon-fri: 8:30-20:00</cs:opening>
<cs:opening>sat: 8:30-12:30</cs:opening>
<cs:closing>04/10/2011</cs:closing>
<cs:closing>25/12/2011</cs:closing>
</rdf:Description>
<rdf:Description rdf:about="http://ltwxxxx.web.cs.unibo.it/result">
<dcterms:creator>Fabio Vitali</dcterms:creator>
<dcterms:created rdf:datatype="http://www.w3.org/2001/XMLSchema#date">2011-09-10</dcterms:created>
<dcterms:description>1.1</dcterms:description>
<dcterms:valid rdf:datatype="http://www.w3.org/2001/XMLSchema#date">2011-12-31</dcterms:valid>
<dcterms:source>http://cs.unibo.it</dcterms:source>
</rdf:Description>
</rdf:RDF>
@prefix : <http://ltwxxxx.web.cs.unibo.it/resource/> .
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .
@prefix cs: <http://cs.unibo.it/ontology/> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@base <http://ltwxxxx.web.cs.unibo.it/result> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
:cs
vcard:category "Dipartimento" , "Università"
; vcard:fn "Dipartimento di Scienze dell'Informazione"
; vcard:extended-address "Mura Anteo Zamboni 7, 40127, Bologna, Italy"
; vcard:latitude "28.847607"
; vcard:longitude "57.084961"
; cs:opening "mon-fri: 8:30-20:00" , "sat: 8:30-12:30"
; cs:closing "04/10/2011" , "25/12/2011" .
<>
dcterms:creator "Fabio Vitali"
; dcterms:created "2011-09-10"^^xsd:date
; dcterms:description "1.1"
; dcterms:valid "2011-12-31"^^xsd:date
; dcterms:source "http://cs.unibo.it" .
-- SilvioPeroni - 09 Nov 2011