Skip to topic | Skip to bottom
Home

TechWeb13
TechWeb13.Protocollo09r1.12 - 23 Apr 2013 - 11:18 - AngeloDiIoriotopic end

Start of topic | Skip to actions

CityNotifier protocol
versione 0.9

Questa versione: Protocollo09

Ultima versione: Protocollo09

Versione Precedente: Nessuna

Autori: FabioVitali, AngeloDiIorio, SilvioPeroni, FrancescoPoggi

Abstract

Questo protocollo nasce all’interno del progetto City Notifier del corso di Tecnologie Web 2012/2013. L'obiettivo del progetto è di sviluppare una piattaforma per la notifica di problemi, situazioni particolari o emergenze all'amministrazione pubblica o agli altri utenti della piattaforma.

Il concetto primario gestito dal sistema è la notifica di una situazione, ossia di una circostanza o di un evento che un utente del sistema intende condividere in quanto di interesse pubblico. Ogni notifica è associata ad almeno due informazioni: un momento e una locazione geografica.

L’architettura City Notifier prevede due componenti principali: client (che consultano le situazioni del sistema, e possono a loro volta notificarne di nuove o segnalare modifiche dello stato di quelle presenti) e server (che si occupano di raccogliere le notifiche segnalate dai client, e di fornire le informazioni sulle situazioni). Ogni client comunica direttamente con il proprio server di riferimento, il quale si occuperà di rispondere con le informazioni che ha localmente, oppure integrandole con quelle mantenute dagli altri server qualora sia opportuno.

Stato del documento

Questo documento è stato redatto da FabioVitali, AngeloDiIorio, SilvioPeroni, FrancescoPoggi. Deve essere utilizzato come materiale di riferimento per il progetto CityNotifier 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à.

1. Introduzione

City Notifier è un sistema federato per la notifica dell'evoluzione di situazioni di interesse pubblico. E' quindi fondamentale associare un'identità ad ogni utente della piattaforma, e per ognuno di essi gestirne autorevolezza e credibilità. Inoltre, vista la natura distribuita del sistema, è importante implementare meccanismi per la corretta gestione delle notifiche (aggregazione di situazioni vicine sia temporalmente che a livello geografico, evoluzione nel tempo e sbiadimento, unificazione e risoluzione di situazioni gestite da altri sever, ecc.)

Il sistema è composto da un database di segnalazioni, che vengono presentate all'utente sotto forma di lista, tabella o cartina geografica. In particolare il database può descrivere notifiche di vario tipo:

  • di ordine pubblico (ad esempio: risse, scippi, rapine, atti vandalici);
  • sanitarie (incidenti, malori, ecc.);
  • di traffico (buche, cortei, code, lavori stradali);
  • ecc.

Ogni gruppo ha l'obbligo di implementare almeno una versione per PC e una versione mobile (iPhone, iPad o dispositivi Android) del client, e almeno un server. Per ogni gruppo, i sever hanno degli identificativi ben precisi che sono reperibili in determinati URL (pubblicati sulla pagina del gruppo, e raccolti in un catalogo accessibile via web), come descritto nella sezione 4.

2. Protocollo CN (CityNotifier)

CN è un protocollo HTTP che regola la comunicazione tra un client e un server CityNotifier. Lo stesso protocollo (in particolare le richieste GET di tipo local, dettagli in seguito) è usato nella comunicazione server-server. Di seguito sono descritte tutte le possibili richieste previste. Le richieste sono progettate secondo l'architettura REST.

Per ogni richiesta è indicato:

  • il metodo HTTP
  • la struttura dell'URL, i parametri ed eventualmente gli esempi
  • il body della richiesta
  • l'header (e i codici HTTP) e il body della risposta.

2.1 Richiesta situazioni

È possibile richiedere ad un particolare server, identificato da un URL, delle situazioni coerentemente a dei parametri specificati come input dal client.

Metodo: GET

URL: http://ltwxxxx.web.cs.unibo.it/<scope>/<type>/<lat>/<long>/<radius>/<status>/<servizio>/

dove:

  • http://ltwxxxx.web.cs.unibo.it/<servizio> è l'url del server da contattare;
  • <scope> è la tipologia di richiesta da fare. Il valore può essere o local o remote. Nel primo caso, la richiesta deve restituire tutte le informazioni che ha il server in locale. Nel secondo caso, la richiesta deve restituire tutte le informazioni contenute negli altri server;
  • <type> è il tipo di situazione che si sta richiedendo. Il valore può essere o all (se interessano tutte le situazioni a prescindere dal tipo) o uno a scelta tra i seguenti: rissa, scippo, rapina, guerra civile, incidente stradale, malore, derby, buca, corteo, votazione presidente della repubblica, coda, lavori, liquidazioni;
  • <lat> è la latitudine del centro da utilizzare per localizzare la situazione; valore di tipo FLOAT, con il simbolo "." per separare i decimali
  • <long> è la longitudine del centro da utilizzare per localizzare la situazione; valore di tipo FLOAT, con il simbolo "." per separare i decimali.
  • <radius> è il raggio di azione (in metri) da considerare per localizzare la situazione a partire dal centro descritto dai due parametri precedenti; valore intero
  • <status> è il tipo di status assegnato alla situazione. Il valore può essere all (se interessano tutte le situazioni a prescindere dallo status) o uno a scelta tra i seguenti: open, closed, skeptical.

Esempio: http://ltw1234.web.cs.unibo.it/local/all/28.847607/57.084961/15.5/open/city/ chiede al server disponibile all'URL http://ltw1234.web.cs.unibo.it/city di restituire tutte le situazioni, memorizzate localmente, che hanno status aperto e sono situate nell'area avente come centro (28.847607,57.084961) e per raggio quindici metri e mezzo.

Header: Accept: text/json

Body: vuoto

Risposta

Header: Content-type: text/json

Body:

        {
            "s1" : {
                "type" : "incidente" ,
                "description" : "brutto incidente, quattro macchine" ,
                "lat" : "28.847607" ,
                "long" : "57.084961" ,
                "status" : "open" ,
                "numberofnotifications" : 15,
                "reputation" : 0.9322
                "freshness" : 327819731279
                "start" : 327819734444
            },
            "s2" : {
                "type" : "rissa" ,
                "description" : "che paura, se le danno di brutto..." ,
                "lat" : "28.847606" ,
                "long" : "57.084962" ,
                "status" : "open" ,
                "numberofnotifications" : 2,
                "reputation" : 0.88
                "freshness" : 898327198218
                "start" : 898327155555
            } 
        }  

Si noti che:

  • il valore reputation è un decimale compreso tra 0 e 1
  • i valor freshness e start sono timestamp Unix

2.2 Aprire una nuova segnalazione

È possibile richiedere ad un particolare server, identificato da un URL, di aprire una nuova segnalazione coerentemente a dei parametri specificati come input dal client.

Metodo: POST

URL: http://ltwxxxx.web.cs.unibo.it/<servizio>

che indica l'url del server da contattare;

I parametri del servizio sono espressi nel body, come spiegato in seguito.

Header: Accept: text/json

Body:

I parametri del servizio sono indicati, in JSON, usando le seguenti chiavi:

  • <type> è il tipo di situazione che si sta richiedendo. Il valore può essere o all (se interessano tutte le situazioni a prescindere dal tipo) o uno a scelta tra i seguenti: rissa, scippo, rapina, guerra civile, incidente stradale, malore, derby, buca, corteo, votazione presidente della repubblica, coda, lavori, liquidazioni;
  • <description> è una descrizione testuale dell'evento
  • <lat> è la latitudine del centro da utilizzare per localizzare la situazione;
  • <long> è la longitudine del centro da utilizzare per localizzare la situazione.

Esempio: http://ltw1234.web.cs.unibo.it/city chiede al server disponibile all'URL http://ltw1234.web.cs.unibo.it/city di aprire una nuova segnalazione di tipo incidente situata in un preciso punto identificato da una latitudine ed una longitudine, specificando il seguente body:

            {
                "type" : "incidente" ,
                "description" : "brutto incidente, quattro macchine",
                "lat" : "28.847607" ,
                "long" : "57.084961"
            }

Risposta

Header: Content-type: text/json

Body:

            "s1" : {
                "type" : "incidente" ,
                "description" : "brutto incidente, quattro macchine",
                "lat" : "28.847607" ,
                "long" : "57.084961" ,
                "status" : "open" ,
                "numberofnotifications" : 15,
                "reputation" : 0.9322,
                "freshness" : 327819731279
            }

2.3 Notificare lo stato di una situazione esistente

È possibile richiedere ad un particolare server, identificato da un URL, di notificare un nuovo stato per una situazione esistente conformemente a dei parametri specificati come input dal client.

Metodo: DELETE

URL: http://ltwxxxx.web.cs.unibo.it/<servizio>/<id>/<status>

dove:

  • http://ltwxxxx.web.cs.unibo.it/<servizio> è l'url del server da contattare;
  • <id> è l'identificativo della situazione come specificato in precedenza dal server;
  • <status> è il tipo di status assegnato da associare alla situazione. Il valore può essere open se la situazione è ancora aperta, closed altrimenti.

Esempio: http://ltw1234.web.cs.unibo.it/city/s1/closed chiede al server disponibile all'URL http://ltw1234.web.cs.unibo.it/city di chiudere la situazione identificata come s1.

Risposta

Header: Accept: text/json

Body: vuoto

        {
            "s1" : {
                "type" : "incidente" ,
                "description" : "brutto incidente, quattro macchine",
                "lat" : "28.847607" ,
                "long" : "57.084961" ,
                "status" : "closed" ,
                "numberofnotifications" : 1,
                "reputation" : 1.0,
                "freshness" : 377819731279
            }
        }

3. Gestione degli errori

Nel caso in cui una richiesta generi un errore, il servizio DEVE rispondere utilizzando gli appropriati codici HTTP 4xx e 5xx. Le applicazioni DEVONO gestire ogni codice d'errore in maniera appropriata.

Le applicazioni DEVONO gestire almeno questi errori (con relativi codici HTTP):

401 Forbidden:
non è possibile accedere alla risorsa perché non si ha l'autorizzazione per farlo
404 Not available:
risorsa non disponibile
405 Method not allowed:
il servizio è stato chiamato con un metodo HTTP non previsto (ad esempio GET piuttosto che POST).
406 Not acceptable:
non è possibile erogare il servizio perché i vincoli della richiesta non sono soddisfacibili.
418 I'm a teapot:
la richiesta riguarda la disponibilità di caffè
500 Internal server error:
c'è stato un problema interno al servizio durante l'elaborazione dalla richiesta.
501 Not implemented:
il servizio richiesto non è fornito.
521 Event is in the future:
l'evento specificato non è ancora successo

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).

4. Catalogo

Ogni gruppo partecipante deve pubblicare da qualche parte un documento XML, detto catalogo, contenente informazioni riguardo al proprio server, ad esempio:

    <catalogo>
        <gruppo>Thank you for coding</gruppo>
        <server url="http://ltw1234.web.cs.unibo.it/city">Il server, unico e solo.</server>
    </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 URL (univoci) dei cataloghi in cui essi risiedono:

    <metaCatalogo>
        <catalogo gruppo="Thank you for coding" url="http://ltw1234.web.cs.unibo.it/catalogo" />
        <catalogo ... />
        ...
    </metaCatalogo>

5. Modello dei dati e dei formati

In questa sezione viene descritto il modello dei dati da utilizzare per restituire i risultati alle richieste fatte verso il server.

Dati

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:

  • Tipo. Un valore che identifichi la tipologia della situazione.
  • Latitudine. La latitudine in cui si trova la situazione.
  • Longitudine. La latitudine in cui si trova la situazione.
  • Stato corrente. Lo stato corrente (aperta, chiusa o scettica) in cui si trova la situazione.
  • Numero di notifiche. Il numero di notifiche ricevute per lo stato corrente.
  • Reputazione. La reputazione associata alle informazioni di stato che la situazione descrive.
  • Freschezza. Il tempo di ultimo aggiornamento della situazione.

Formati

Le informazioni introdotte nelle sezioni precedenti possono devono essere espressi in JSON (http://tools.ietf.org/html/rfc4627). Le chiavi dei vari oggetti da utilizzare per le informazioni da gestire sono:

  • Uno o più oggetti <id-situazione>, in cui sono contenuti:
    • Tipo. type
    • Latitudine. lat
    • Longitudine. long
    • Stato corrente. status
    • Numero di notifiche. numberofnotifications
    • Reputazione. reputation
    • Freschezza. freshness
        {
            "s1" : {
                "type" : "incidente" ,
                "lat" : "28.847607" ,
                "long" : "57.084961" ,
                "status" : "open" ,
                "numberofnotifications" : 15,
                "reputation" : 0.9322,
                "freshness" : 327819731279
            },
            ... 
        }  

  • Set ALLOWTOPICVIEW =
  • Set ALLOWTOPICCHANGE =

to top

You are here: TechWeb13 > Protocollo09

to top

Copyright © Fabio Vitali 2017 Last update of Protocollo09 on 23 Apr 2013 - 11:18 by AngeloDiIorio