L'approccio REST API consente di inviare e richiedere dati verso Xserv tramite ogni dispositivo in grado di fare delle semplici richieste HTTP.
Prima di iniziare bisogna definire il concetto di "topic", una sorta di canale con cui dare una logica ed organizzazione ai messaggi scambiati ed archiviati sul nostro cloud.
Ad esempio, in un app di ristorazione, i topic potrebbero essere i "tavoli", "ordini" o "piatti"; mentre in un instant messaging i topic sono le vere e proprie room di discussione.
Nell'approccio REST API ogni client puo' decidere di inviare o richiedere dati di un topic in ogni momento e non e' necessario definire questi valori a priori.
Esistono al momento 3 tipi di topic:
@
e l'uso di questo topic necessita una autenticazione.!<socket_id>
, ogni client connesso ad Xserv tramite WebSocket ha il suo e serve ad inviare un messaggio diretto one-to-one.Nella creazione dei topic, nel nome sono ammessi tutti i caratteri ad esclusione del carattere !
come primo carattere, utilizzato per il messaging one-to-one.
Tutti i topic che hanno come prefisso nel nome il carattere @
vengono riconosciuti e gestiti come topic privati,
quindi richiedono una autenticazione (a meno di non utlizzare le API con la secret
).
Create a FREE account, create your first application and make a note of her app_id
and secret
.
Questo comando consente di inviare dati one-to-many su un determinato topic.
I client sottoscritti sul topic, attraverso l'approccio WebSocket, riceveranno il messaggio in tempo reale.
Per inviare un messaggio one-to-one, a client connessi tramite la WebSocket, il campo topic deve essere composto dal
socket_id
del client destinataro preceduto dal carattere !
.
curl -X POST \
-H "X-Xserv-AppId: ${APP_ID}" \
-H "X-Xserv-Secret: ${SECRET}" \
-H "Content-Type: application/json" \
-d '{"topic": ${TOPIC}, "data": ${DATA}}' \
https://mobile-italia.com:8332/1/publish
topic
String - The name of the topic that the message is to be published on.
A client-to-client message must have a name formed by socket_id
prefixed with !
.data
(String | JSON) - The data to be sent.Questo comando consente di modificare un messaggio gia' archiviato in un topic attraverso il suo object_id
.
I client sottoscritti sul topic, attraverso l'approccio WebSocket, riceveranno nuovamente il messaggio con i nuovi dati ma stesso id in tempo reale.
curl -X PUT \
-H "X-Xserv-AppId: ${APP_ID}" \
-H "X-Xserv-Secret: ${SECRET}" \
-H "Content-Type: application/json" \
-d '{"topic": ${TOPIC}, "data": ${DATA}}' \
https://mobile-italia.com:8332/1/update/${OBJECT_ID}
topic
String - The name of the topic that the message is to be published on.object_id
String - The message identifier.data
(String | JSON) - The data to be sent.Questo comando consente di ottenere una lista dello storico dei messaggi di un topic.
E' possibile configurare un offset di inizio timestamp e/o un limit e/o una query custom, in stile MongoDB, sul proprio campo data
dei messaggi.
curl -X GET \
-H "X-Xserv-AppId: ${APP_ID}" \
-H "X-Xserv-Secret: ${SECRET}" \
-G \
--data-urlencode 'topic=${TOPIC}' \
--data-urlencode 'offset=${OFFSET}' \
--data-urlencode 'limit=${LIMIT}' \
--data-urlencode 'query=${MONGODB_QUERY}' \
https://mobile-italia.com:8332/1/history
topic
String - The name of the topic.params
JSON
offset
Integer [optional] - Timestamp of the message used to specify the start.limit
Integer [optional] - Value to limit the number of results. Positive is first N, negative is the last N (Default N = 1000).query
JSON [optional] - An object of data key/value pairs to filter messages on field data
(see MongoDB query find style).NOTA: Il campo query
e' applicabile solo se il vostro campo data
dei messaggi e' un JSON.
Xserv permettete di riportare il filtro esattamente a livello MongoDB, quindi sono permesse tutte le condizioni riportate nella guida
MongoDB - Query and Projection Operators.
Il comando topics consente di ottenere una lista di tutti i topic in cui c'e' almeno un messaggio.
curl -X GET \
-H "X-Xserv-AppId: ${APP_ID}" \
-H "X-Xserv-Secret: ${SECRET}" \
https://mobile-italia.com:8332/1/topics