Skip to topic | Skip to bottom
Home

TechWeb13
TechWeb13.Protocollo902r1.1 - 14 May 2013 - 00:46 - GianmarcoNicolettitopic end

Start of topic | Skip to actions

CityNotifier protocol
versione 0.9.2

Questa versione: Protocollo092

Ultima versione: Protocollo092

Versione Precedente: Protocollo091

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 che un utente del sistema intende condividere in quanto di interesse pubblico. Ogni notifica è associata a diverse informazioni sulla natura dell'evento da segnalare, il luogo e il tempo della segnalazione. Si definisce evento un'aggregazione di notifiche riferite alla medesima situazione e manipolata dal server in un unico oggetto.

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

Stato del documento

Questo documento è un aggiornamento della versione redatta 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.2 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à.

La presente 0.9.2 non è la versione definitiva del protocollo. Il simbolo (?) indica che l'argomento è ancora oggetto di discussione.

1. Introduzione

City Notifier è un sistema federato per la notifica dell'evoluzione di eventi di interesse pubblico. È 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 notifiche vicine sia temporalmente che a livello geografico, evoluzione nel tempo e sbiadimento, unificazione e risoluzione di eventi gestiti da altri sever, ecc.).

Il sistema è composto da un database di notifiche e eventi; questi ultimi, già aggregati, vengono presentati all'utente sotto forma di lista, tabella o cartina geografica. In particolare il database può presentare eventi di questi tipi, a loro volta suddivisi in sottotipi (si noti che "altro" è un sottotipo vero e proprio e non un termine generico):

  • Problemi stradali: incidente, buca, coda, lavori in corso, altro;
  • Emergenze sanitarie: incidente, malore, ferito, altro;
  • Reati: furto, attentato, altro;
  • Problemi ambientali: incendio, tornado, terremoto, neve, alluvione, altro;
  • Eventi pubblici: partita, manifestazione, concerto, altro.

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.

Nello specifico, il client fa tre tipi di richieste: la prima, sincrona, di tipo local, richiede i dati locali al server di riferimento; la seconda, asincrona, di tipo remote, richiede i dati di tutti i server disponibili (e che rispondono entro 5 secondi); infine la terza, asincrona, di tipo local e ristretta alla posizione attuale del client, richiede gli eventi con status skeptical, in modo che il server possa interrogare il client riguardo il loro reale status.

Metodo: GET

URL: http://ltwxxxx.web.cs.unibo.it/richieste/<scope>/<type>/<lat>/<lng>/<radius>/<timemin>/<timemax>/<status>/

dove:

  • http://ltwxxxx.web.cs.unibo.it/richieste è l'url del server da contattare. Il campo richieste è una costante e indica il servizio richiesto;
  • <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: problemi_stradali, emergenze_sanitarie, reati, problemi_ambientali, eventi_pubblici;
  • <lat> è la latitudine del centro da utilizzare per localizzare la situazione. Valore di tipo FLOAT, con il simbolo "." per separare i decimali;
  • <lng> è 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 di tipo FLOAT, con il simbolo "." per separare i decimali;
  • <timemin> è l'inizio dell'intervallo di tempo al quale si è interessati. Il formato è quello dei timestamp UNIX (conversioni da formati "umani" sono da effettuarsi lato client);
  • <timemax> è la fine dell'intervallo di tempo al quale si è interessati. Il formato è quello dei timestamp UNIX (conversioni da formati "umani" sono da effettuarsi lato client);
  • <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/richieste/local/all/28.847607/57.084961/15.5/1368475200/1368486000/open/ chiede al server disponibile all'URL http://ltw1234.web.cs.unibo.it/richieste di restituire tutti gli eventi memorizzati localmente che hanno status aperto, sono situati nell'area avente come centro (28.847607,57.084961) con un raggio di quindici metri e mezzo e che sono stati notificati tra le 20 e le 23 del giorno 13 maggio 2013 (conversione dei timestamp UNIX dei valori "1368475200" e "1368486000"). Per verificare i campi relativi all'intervallo di tempo si utilizza il campo freshness dell'evento (vedi sezione 5).

Header: Accept: application/json

Body: vuoto

Risposta

Header: Content-type: application/json

Body: (?)

Esempio:

       {
      "last_request" : 1368095111,
      "server_message" : "OK",
      "from_server" : "caccattp://serverTW_1.unibo.it",
      "events" : [
         "s1" : {
            "remote_id" : "potrebbe_essere_comodo_sapere_id_che_l_evento_ha_in_remoto",
            "type" : { "type" : "problema stradale", "sub_type" : "incidente"},
            "description" : ["ommioddio","come na catapulta","","",""],
            "start_time" : 1368045665,
            "freshness" : 1368085800,
            "status" : "open",
            "avg_reputation" : 0.8,
            "avg_assiduity" : 1.0,
            "number_of_notifications" : 2,
            "locations" : [
               {
                "lat" : 37.42291810,
                "lng" : -122.08542120
               },
               {
                "lat" : 37.42291810,
                "lng" : -122.08542120
                }
            ]    
         },
         "s2: {
            "remote_id" : "my_id",
            "type" : { "type" : "problema stradale", "sub_type" : "incidente"},
            "description" : ["mi hanno tamponato","dottore chiami un dottore","che guaio","descr4","descr5"],
            "start_time" : 1368105698,
            "freshness" : 1368106058,
            "status" : "open",
            "avg_reputation" : 1.0,
            "avg_assiduity" : 0.9,
            "number_of_notifications" : 6,
            "locations" : [
               {
                "lat" : 37.42291810,
                "lng" : -122.08542120
               },
               {
                "lat" : 37.42291811,
                "lng" : -122.08542121
               },
               {
                "lat" : 37.42291812,
                "lng" : -122.08542122
               },
               {
                "lat" : 37.42291813,
                "lng" : -122.08542123
               },
               {
                "lat" : 37.42291814,
                "lng" : -122.08542124
                      }
            ]    
         }
   ]
}

Si noti la presenza di un oggetto esterno con alcuni valori di riferimento del server, e che la lista degli eventi è contenuta nel suo campo events. Per quanto riguarda i campi degli eventi:

  • i valori freshness e start_time sono timestamp UNIX
  • il valore description è una lista di 5 oggetti, scelti e ordinati in base alla reputazione degli utenti che hanno segnalato l'evento; in caso di parità di reputazione, viene scelta la segnalazione più recente
  • il valore type ha due sottocampi, uno ad indicare il tipo vero e proprio e l'altro il sottotipo, come descritto nella sezione 1
  • valori come avg_reputation e avg_assiduity sono medie dei valori degli utenti che hanno effettuato le notifiche, mentre valori come locations sono liste di tutti i punti di tutte le segnalazioni

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/segnalazione

che indica l'url del server da contattare.

I parametri della nuova segnalazione sono espressi nel body, come spiegato in seguito.

Header: Accept: application/json

Body:

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

  • <type> è il tipo di situazione che si sta segnalando. Il valore del sottocampo type e di quello sub_type sono specificati nella sezione 1;
  • <description> è una descrizione testuale dell'evento;
  • <lat> è la latitudine del centro da utilizzare per localizzare la situazione;
  • <lng> è la longitudine del centro da utilizzare per localizzare la situazione.

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

            {
                "type" : { "type" : "problema stradale", "sub_type" : "incidente"},
                "description" : "io ho visto tutto",
                "lat" : "28.847607" ,
                "lnng" : "57.084961"
            }

Risposta

Header: Content-type: application/json

Body:

Un semplice JSON con un unico campo per segnalare eventuali errori.

            {
                "result" : "segnalazione aperta con successo"
            }

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: POST

URL: http://ltwxxxx.web.cs.unibo.it/notifica/

che indica l'url del server da contattare.

I parametri della notifica sono espressi nel body, come spiegato in seguito.

Header: Content-type: application/x-www-form-urlencoded

Body:

id_evento=id+stato=valore

Dove valore può essere "open" o "closed". "Open" indica lo stato di perduranza dell'evento.

Esempio: http://ltw1234.web.cs.unibo.it/notifica chiede al server disponibile all'URL http://ltw1234.web.cs.unibo.it/notifica di chiudere la situazione identificata come s1 specificando il seguente body:

id_evento=s1+stato=closed

(?) È il server a dedurre dati come il tempo della notifica o la reputazione dell'utente che l'ha fatta.

Risposta

Header: Content-type: application/json

Body:

Un semplice JSON con un unico campo per segnalare eventuali errori.

            {
                "result" : "notifica inviata con successo"
            }

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

403 Forbidden:
non è possibile accedere alla risorsa perché non si ha l'autorizzazione per farlo
404 Not found:
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.
500 Internal server error:
c'è stato un problema interno al servizio durante l'elaborazione dalla richiesta.
501 Not implemented:
il servizio richiesto non è fornito.

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 deve inviare i propri dati per permettere la costruzione di un catalogo dei server, un file XML chiamato catalogo, il cui URL sarà indicato in queste specifiche. Nel catalogo si trovano coppie di nomi di gruppi e URL (univoco) sul quale risiede il relativo server, secondo questo formato:

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

5. Modello dei dati e dei formati (?)

In questa sezione viene descritto il modello dei dati da utilizzare per restituire al client i risultati delle richieste fatte verso il server (notifiche aggregate in eventi).

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. Con relativi campi "type" e "sub_type", descritti nella sezione 1.
  • Descrizione. Una lista di 5 descrizioni, ordinate secondo la reputazione dell'utente che le ha inserite.
  • Tempo di inizio. L'ora (timestamp UNIX) della prima segnalazione.
  • Freschezza. Il tempo di ultimo aggiornamento della situazione.
  • Stato corrente. Lo stato corrente (aperto, chiuso o scettico) in cui si trova l'evento.
  • Reputazione. La reputazione associata alle informazioni di stato che la situazione descrive.
  • Assiduità. Una media dell'assiduità degli utenti che hanno notificato l'evento (?).
  • Numero di notifiche. Il numero di notifiche ricevute per lo stato corrente.
  • Luoghi. Una lista di coppie latitudine-longitudine, ad indicare tutti i luoghi dove è stato segnalato l'evento.

Formati

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

  • Un unico oggetto "lista di eventi", il cui campo events è una lista di eventi il cui singolo elemento è così descritto:
    • Tipo. type
    • Descrizione. description
    • Tempo di inizio. start_time
    • Freschezza. freshness
    • Stato corrente. status.
    • Reputazione. avg_reputation
    • Assiduità. avg_assiduity (?)
    • Numero di notifiche. number_of_notifications
    • Luoghi. locations
        "s2: {
            "remote_id" : "my_id",
            "type" : { "type" : "problema stradale", "sub_type" : "incidente"},
            "description" : ["mi hanno tamponato","dottore chiami un dottore","che guaio","descr4","descr5"],
            "start_time" : 1368105698,
            "freshness" : 1368106058,
            "status" : "open",
            "avg_reputation" : 1.0,
            "avg_assiduity" : 0.9,
            "number_of_notifications" : 6,
            "locations" : [
               {
                "lat" : 37.42291810,
                "lng" : -122.08542120
               },
               {
                "lat" : 37.42291815,
                "lng" : -122.08542125
               }
            ]    
         }

  • Set ALLOWTOPICVIEW =
  • Set ALLOWTOPICCHANGE =

to top

You are here: TechWeb13 > Protocollo902

to top

Copyright © Fabio Vitali 2017 Last update of Protocollo902 on 14 May 2013 - 00:46 by GianmarcoNicoletti