Modalità di comunicazione.

Il web service comunica tramite richieste http rispondendo con un contenuto serializzato JSON che può essere o meno compresso in modalità gzip.

Ogni richiesta deve essere accompagnata da una API-KEY valida al fine di essere correttamente evasa. Ottenuta in maniera automatica tramite il modulo di richiesta al termine di questa pagina.

Comandi Riconosciuti

Ogni richiesta inoltrata al web service dovrà essere formulata nel seguente modo:

http://webservice.around.bari.it? API = _APIKEY_ & REQEST_1 {& REQUEST_2 & LINGUA & VERSIONE & EXTRA }

• API indica l’APIKEY precedentemente menzionata
• REQUEST_1 indica l’azione principale che si vuole svolgere, può essere di 3 tipi
  • POI_LIST richiede la lista completa dei poi disponibili sulla piattaforma, la richiesta fornisce le seguenti informazioni
    • Codice UNIVOCO del POI {POI_ID}
    • Nome
    • Coordinate GPS
    • Versione della Descrizione
    • Lingua
    • Immagine Principale
    • Tipo
  • POI_DATA + POI_ID richiede la lista completa delle informazioni disponibile sul poi. Il dettaglio delle informazioni sarà fornito successivamente
  • POI_MIN_DATA + POI_ID fornisce un subset minimale di informazioni sul POI quali
    • Nome
    • Coordinate
    • Tipo
    • Descrizione Breve
    • Descrizione
    • Immagine principale
    • Indirizzo
    • Sito web
    • Mail
    • Telefono / Infoline
  • POI_MEDIA_INFO + POI_ID fornisce il dettaglio per ogni immagine o file allegato alla pagina. La lista comprende
    • File URL
    • File Name
    • File Description
    • File code {MEDIA_ID}
  • MEDIA_INFO + MEDIA_ID fornisce il dettaglio per il singolo file indicato. La lista comprende
    • File URL
    • File Name
    • File Description
  • LINGUA {opzionale} questo campo richiede la lingua delle informazioni, in caso di mancanza di questo parametro sarà usata la lingua standard della piattaforma, le opzioni di richiesta sono fornite da POI_LIST
  • REQUEST_2 {opzionale} questo campo indica quale versione delle informazioni si richiede, in mancanza di questo dato sarà indicata l’opzione standard, le opzioni di richiesta sono fornite da POI_LIST
  • EXTRA {opzionale} in questo campo è possibile intervenire sul tipo di risposta del web service.
    • GZIP l’intera risposta del web service sarà compressa in formato gzip per risparmiare banda e trasmesso con codifica BASE64, il guadagno in termini di compressione è stimato del 40%
    • NEAR aggiunge i 10 POI_ID più vicini a quello richiesto.

Limiti di risposta del web service

Ad ogni APIKEY è associato un numero massimo di richieste gestibili in un secondo, il valore attuale è 10, ma esso può essere modificato sia a livello ‘’globale’’ che a livello della singola APIKEY.

Il web service tenterà di soddisfare le richieste nel minore tempo possibili fino al raggiungimento della quota indicata. Al superamento di questa soglia il web service evaderà la richiesta con un sempre maggiore ritardo fino ad un massimo di 10 secondi.

ESEMPIO

• Richiesta 09 – delay 0 s
• Richiesta 10 – delay 0 s
• Richiesta 11 – delay 1 s
• Richiesta 12 – delay 2 s
• […]
• Richiesta 19 – delay 9 s
• Richiesta 20 – delay 10 s
• Richiesta 21 – delay 10 s

Se però l’intervento di ritardo si prolunga nel tempo, un sistema di avviso indicherà ad un amministratore il problema in modo tale che si possa agire opportunamente.

La risposta del Web Service

Il web service risponde con una struttura JSON del seguente tipo:

{“status”:”OK”,”payload”:[],”next_poi”:[],”server_time”:”0.36797100 1446634448″}

Dove status può essere:

• OK – Operazione andata a buon fine
• FAIL – Operazione non andata a buon fine, causa dell’errore nel payload
• DELAY – Operazione andata a buon fine ma con un ritardo imposto
• BANNED – Operazione non andata a buon fine a causa di apikey errata o bloccata da un amministratore
• NO_LANG – la risorsa non è disponibile nella lingua o nella versione richiesta, pertanto verrà fornita la versione nella lingua o versione standard

Il payload è il contenuto effettivo della risposta, esso potrà essere compresso o meno in caso di richiesta del’utente.

next_poi indica i 10 POI_ID più vicini al poi indicato ove sia stata fatta la richiesta ‘’NEAR’’

Infine server_time indica l’ora dell’elaborazione in secondi Epoch time per propositi di sincronizzazione.