SIS REST API
Sviluppata da
Alessio Vertemati e Diego Bernini
Versione
2.0.14 branch
Introduzione
La SIS API espone l'accesso alle funzionalità della piattaforma SIS mediante un web service RESTful la cui codifica dei messaggi è basata su UTF-8 e la serializzazione è realizzata mediante formato JSON.
L'intera API consta di 5 endpoint raggiungibili mediante protocollo HTTP: 1. eventsmediator: che permette di effettuare le operazioni di pubblicazione e sottoscrizione 2. mappingsinspector: che permette di effettuare l'ispezione dei mapping presenti nell'istanza della piattaforma 3. mappingsmanager: che permette di gestire la configurazione dei mapping 4. spacesinspector: che permette l'esplorazione degli spazi configurati 5. spacesmanager: che permette la configurazione degli spazi
In aggiunta a questi endpoint trovano posto altri 2 servizi legati alle WebSocket (protocollo WS) per permettere la notifica asincrona di eventi: 1. EventsWebSockets: per ricevere le notifiche legate ad una sottoscrizione 2. MappingsWebSockets: per ricevere le notifiche di cambiamento dei mapping (sempre legate a una precedente sottoscrizione)
Nel seguito si suppone che l'istanza di SIS sia raggiungibile mediante il seguente url:
http://www.sal.disco.unimib.it/sis/2/
e che l'API rest sia raggiungibile appendendo al path precedente la stringa
rest/token/
dove token è l’identificativo personale (questa struttura cambierà in futuro quindi ove possibile si consiglia di utilizzare la SISAbstraction).
eventsmediator
Il servizio eventsmediator permette l'accesso alle primitive di pubblicazione e sottoscrizione basate sulla metafora multi-spaziale.
Publish
Url path: publish/
Method: POST
La publish permette di effettuare una pubblicazione di una informazione tematica su uno o più contesti spaziali.
Il contenuto della richiesta POST prevede un oggetto JSON contenente:
- l’array di contesti spaziali su cui effettuare la pubblicazione:
publicationContexts; - la thematic information che deve essere pubblicata: thematicInfo.
{
"publicationContexts": [
{
"type": "enumerative",
"locationNames": [
"465"
],
"spaceName": "impulso.RFIDTags"
}
],
"thematicInfo": {
"object": "publish-list-ThematicInfo"
}
}
Sync Subscribe
Url path: path
Method: GET,POST,PUT,DELETE
description
Async Subscribe
Url path: path
Method: GET,POST,PUT,DELETE
description
Get Matchings
Url path: path
Method: GET,POST,PUT,DELETE
description
mappingsinspector
to be described
mappingsmanager
to be described
spacesinspector
to be described
spacesmanager
to be described
Protocollo di comunicazione inerente alle WebSocket
Considerando l’indirizzo specificato nell’introduzione le web socket sono raggiungibili rispettivamente ai seguenti url:
ws://www.sal.disco.unimib.it/sis/2/EventsWebSockets/ws://www.sal.disco.unimib.it/sis/2/MappingsWebSockets/
la procedura prevede che all'apertura della websocket il client invii al server un payload formattato come segue:
login$subscription_handle
dove subscription_handle è l’identificativo della sottoscrizione ritornato a fronte di una richiesta di sottoscrizione precedentemente effettuata.
FAQ e risoluzione problemi
- ...
Curiosità
...