Documentazione API e Web App

Rabbits è un message broker per IoT pensato per lo sviluppo di attività didattiche.
Un message broker è un componente software che svolge il ruolo da intermediario tra applicazioni o dispositivi che desiderano inviare e ricevere messaggi e smista i messaggi tra i vari dispositivi.
Spesso i message broker utilizzano protocolli dedicati all'IoT come MQTT; questo message broker invece per maggiore semplicità utilizza il protocollo HTTP.
Le informazioni sul message broker si presentano come variabili composte da coppie "chiave-valore" che sono esposte in una "dashboard" associata al broker.
Le variabili possono essere "readonly" e in questo caso hanno il significato di informazioni di stato che arrivano dai dispositivi oppure possono essere modificabili e in tale caso hanno il significato di "immagini di comando" per i dispositivi.
Con la soluzione HTTP le applicazioni e i dispositivi per mandare informazioni devono eseguire un API sotto forma di una richiesta HTTP con parametri GET e per conoscere lo stato di una variabile devono effettuare una interrogazione ciclica (polling) di richiesta della variabile che viene ristituita in formato JSON.

Nella prima sezione di questa pagina sono documentate le API disponibili e nella seconda sono presentate alcune webapp tra cui una DASHBOARD che potrà anche essere installata nei propri dispositivi.

Documentazione API

API time

Questa API restituisce l'ora corrente del server

Si invoca con 

https://www.schoolmakerday.it/rabbits/time.php

e restituisce un oggetto JSON con campi:

Esempio di risposta:

{"status":"OK","data":{"year":"2022","month":"03","day":"14","hour":"09","minute":"04","second":"41"}}

API set

Questa API consente la registrazione da parte del server di dati che vengono inviati in forma di coppie chiave-valore

Si invoca con 

https://www.schoolmakerday.it/rabbits/set.php?key=KKK&value=VVV

in cui i due parametri key e value sono obbligatori. Il valore per key deve essere di tipo string lungo fino a 10 caratteri, il valore per value deve esssere di tipo string lungo fino a 255 caratteri.

Alla registrazione della coppia key-value viene aggiunto anche il timestamp (data e ora)

Ad ogni set il dato viene aggiunto (e non sovrascritto al precedente) mantenendo quindi una successione storica, per non accumulare troppi dati nel tempo ad ogni inserimento vengono comunque rimossi i dati con stessa chiave e timestamp antecedente a 48 ore prima.

Restituisce un oggetto JSON con i dati ottenuti da una rilettura dei dati inseriti, in particolare i seguenti campi:

Esempio di chiamata corretta:

https://www.schoolmakerday.it/rabbits/set.php?key=esempio&value=12.34

risposta:

{"status":"OK","data":{"key":"esempio","value":"12.34","ts":"2023-02-08 10:10:16"}}

Esempio di chiamata errata:

https://www.schoolmakerday.it/rabbits/set.php?key=esempio

risposta:

{"status":"ERROR"}

API get

Questa API consente di ottenere il valore più recente associato ad una chiave

Si invoca con 

https://www.schoolmakerday.it/rabbits/get.php?key=KKK

in cui il parametro key è obbligatorio. Il valore per key deve essere di tipo string lungo fino a 10 caratteri.

Restituisce un oggetto JSON con campi:

Esempio di chiamata corretta:

https://www.schoolmakerday.it/rabbits/get.php?key=esempio

risposta:

{"status":"OK","data":{"key":"esempio","value":"12.34","ts":"2023-02-08 10:10:16"}}

Esempio di chiamata errata:

https://www.schoolmakerday.it/rabbits/get.php

risposta:

{"status":"ERROR"}

API getlog

Questa API consente di ottenere tutti i valori presenti sul server associati ad una chiave

Si invoca con 

https://www.schoolmakerday.it/rabbits/getlog.php?key=KKK

in cui il parametro key è obbligatorio. Il valore per key deve essere di tipo string lungo fino a 10 caratteri.

Restituisce un oggetto JSON con campi:

Esempio di chiamata corretta:

https://www.schoolmakerday.it/rabbits/getlog.php?key=esempio

risposta:

{"status":"OK","data":[{"key":"esempio","value":"12.34","ts":"2023-02-08 10:26:50"},{"key":"esempio","value":"12.34","ts":"2023-02-08 10:10:16"}]}

Esempio di chiamata errata:

https://www.schoolmakerday.it/rabbits/getlog.php

risposta:

{"status":"ERROR"}

API getkeys

Questa API consente di ottenere per più chiavi il corrispondente valore più recente associato

Si invoca con 

https://www.schoolmakerday.it/rabbits/getkeys.php?keys=["KK1","KK2",...]

in cui il parametro keys è obbligatorio. Il valore per keys deve essere un array JSON con le chiavi che interessano.

Restituisce un oggetto JSON con campi:

Esempio di chiamata corretta:

https://www.schoolmakerday.it/rabbits/getkeys.php?keys=["esempio","nonesiste"]

risposta:

{"status":"OK","data":{"esempio":{"key":"esempio","value":"12.34","ts":"2023-02-08 10:26:50"},"nonesiste":null}}

Esempio di chiamata errata:

https://www.schoolmakerday.it/rabbits/getkeys.php

risposta:

{"status":"ERROR"}

WebApp

WebApp LogView

All'indirizzo

https://www.schoolmakerday.it/rabbits/logview.php

è disponibile una webapp che consente di visionare tutte le registrazioni riferita ad una chiave specificata

WebApp Status

All'indirizzo

https://www.schoolmakerday.it/rabbits/status.php

è disponibile una webapp che consente di visionare il valore più recente corrispondente ad una chiave specificata e successivamente di inserire un nuovo valore

WebApp Monitor

All'indirizzo

https://www.schoolmakerday.it/rabbits/monitor.php

è disponibile una webapp che consente di visionare il valore più recente corrispondente ad una chiave specificata; la visualizzazione si aggiorna automaticamente ogni secondo

WebApp Dashboard

All'indirizzo

https://www.schoolmakerday.it/rabbits/dashboard

è disponibile una webapp che generalizza le funzioni di "status" e "monitor", consente cioè di impostare valore associato a una o più "chiave di comando" e tenere monitorato il valore di una o più "chiave di stato"