Introduction


L'approccio REST API consente di inviare e richiedere dati verso Xserv tramite ogni dispositivo in grado di fare delle semplici richieste HTTP.


Topic concept


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.


Tipologie di topic


Esistono al momento 3 tipi di topic:

  • Public topic permette l'uso a tutti quelli che ne conoscono il nome.
  • Private topic devono avere come prefisso nel nome @ e l'uso di questo topic necessita una autenticazione.
  • User topic nella forma !<socket_id>, ogni client connesso ad Xserv tramite WebSocket ha il suo e serve ad inviare un messaggio diretto one-to-one.

Naming convensions


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


Project setup


Create a FREE account, create your first application and make a note of her app_id and secret.


Publish


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.

Update


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.

History


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.


TOPICS


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