REST API - alex-konshin/f007th-rpi GitHub Wiki

If command line argument httpd is specified or configuration command httpd sets HTTP port then the utility can serve some REST API requests.
All currently supported REST API request are HTTP GET request with URLs with following format:

/api/<request_name>[/<parameter>][?<options>

Examples of valid requests:

/api/version
/api/sensors
/api/sensors?utc=1&celsius=1&format=brief
/api/temperature?scale=C10
/api/temperature/Alex+office?scale=F&utc=1
/api/humidity

Request version

Return the current version of the utility.
An example of response /api/version:

{"application_version":"5.0","api_version":"1.0"}

Request sensors

No parameters.
Options:

  • utc={0|1}
  • celsius={0|1}
  • format={0|1|full|brief} - Specifies the format of output JSON. The default value is 0 or full.

An example of response for request with format=0(default) or format=full:

[
{"time":"2020-12-24 13:49:16-0500","type":"F007TH","channel":"5","rolling_code":174,"name":"Kitchen","temperature":718,"humidity":26,"battery_ok":true,"t_hist":3,"h_hist":2},
{"time":"2020-12-24 13:51:27-0500","type":"00592TXR","channel":"A","rolling_code":92,"name":"Neighbor 1","temperature":537,"humidity":62,"battery_ok":true,"t_hist":7,"h_hist":2},
{"time":"2020-12-24 13:48:13-0500","type":"F007TH","channel":"1","rolling_code":13,"name":"Server room","temperature":813,"humidity":10,"battery_ok":true,"t_hist":2,"h_hist":2},
{"time":"2020-12-24 13:50:20-0500","type":"F007TH","channel":"4","rolling_code":12,"name":"Alex office","temperature":761,"humidity":26,"battery_ok":true,"t_hist":3,"h_hist":2},
{"time":"2020-12-24 13:51:52-0500","type":"00592TXR","channel":"A","rolling_code":146,"name":"Backyard","temperature":525,"humidity":69,"battery_ok":true,"t_hist":3,"h_hist":2},
{"time":"2020-12-24 13:48:20-0500","type":"TX7","rolling_code":104,"name":"Attic TX7U","temperature":681,"t_hist":2},
{"time":"2020-12-24 13:48:22-0500","type":"F007TH","channel":"8","rolling_code":227,"name":"Dining room","temperature":757,"humidity":24,"battery_ok":true,"t_hist":2,"h_hist":2},
{"time":"2020-12-24 13:49:48-0500","type":"F007TH","channel":"8","rolling_code":95,"name":"Dirty room","temperature":606,"humidity":79,"battery_ok":true,"t_hist":3,"h_hist":2},
{"time":"2020-12-24 13:49:29-0500","type":"F007TH","channel":"3","rolling_code":85,"name":"Roman room","temperature":714,"humidity":32,"battery_ok":true,"t_hist":3,"h_hist":2},
{"time":"2020-12-24 13:52:05-0500","type":"F007TH","channel":"6","rolling_code":139,"name":"TV room","temperature":708,"humidity":30,"battery_ok":true,"t_hist":3,"h_hist":2},
{"time":"2020-12-24 13:48:57-0500","type":"F007TH","channel":"7","rolling_code":249,"name":"Garage","temperature":526,"humidity":49,"battery_ok":true,"t_hist":2,"h_hist":2},
{"time":"2020-12-24 13:49:00-0500","type":"F007TH","channel":"2","rolling_code":184,"name":"Main bedroom","temperature":710,"humidity":33,"battery_ok":true,"t_hist":2,"h_hist":2}
]

An example of response for request with format=1 or format=brief:

[
{"name":"Kitchen","last":2,"temperature":71.8,"humidity":26,"battery_ok":true,"t_hist":3,"h_hist":2},
{"name":"Neighbor 1","last":0,"temperature":53.9,"humidity":62,"battery_ok":true,"t_hist":6,"h_hist":2},
{"name":"Server room","last":3,"temperature":81.3,"humidity":10,"battery_ok":true,"t_hist":2,"h_hist":2},
{"name":"Alex office","last":1,"temperature":76.1,"humidity":26,"battery_ok":true,"t_hist":3,"h_hist":2},
{"name":"Backyard","last":3,"temperature":52.7,"humidity":69,"battery_ok":true,"t_hist":2,"h_hist":2},
{"name":"Attic TX7U","last":3,"temperature":68.1,"t_hist":2},
{"name":"Dining room","last":3,"temperature":75.7,"humidity":24,"battery_ok":true,"t_hist":2,"h_hist":2},
{"name":"Dirty room","last":1,"temperature":60.6,"humidity":79,"battery_ok":true,"t_hist":3,"h_hist":2},
{"name":"Roman room","last":2,"temperature":71.4,"humidity":32,"battery_ok":true,"t_hist":3,"h_hist":2},
{"name":"TV room","last":2,"temperature":70.9,"humidity":30,"battery_ok":true,"t_hist":2,"h_hist":2},
{"name":"Garage","last":2,"temperature":52.6,"humidity":49,"battery_ok":true,"t_hist":2,"h_hist":2},
{"name":"Main bedroom","last":2,"temperature":71,"humidity":33,"battery_ok":true,"t_hist":2,"h_hist":2}
]

Request temperature

This request may have parameter - the name of the sensor.
Without the parameter it returns the current (actually the last received) temperatures from all sensors defined in the configuration of the utility.\
Options:

  • celsius={0|1} An example of response for request /api/temperature?scale=C:
{
"Kitchen":22.1,
"Neighbor 1":12.2,
"Server room":27.3,
"Alex office":24.5,
"Backyard":11.4,
"Attic TX7U":20.1,
"Dining room":24.2,
"Dirty room":15.7,
"Roman room":21.8,
"TV room":21.6,
"Garage":11.5,
"Main bedroom":21.6,
"Attic":20.5
}

If the parameter is specified then the response contains a history of temperature values for last 24 hours. Options:

  • utc={0|1}
  • celsius={0|1} The response is an array of JSON objects with fields t and y. The value of t is the time. The format of representation of time depends on the value of option utc. If utc=0(the default value) then time format is like 2020-12-24 13:48:19-0500. If utc=1 then the format is ISO 8601 like 2020-12-24T18:51:52Z.
    The value of y is temperature. The scale is defined by option celsius(default is 0 and it means Fahrenheit scale) but the value is always multiplied to 10. For example, if y=527 then the actual value is 52.7F.

An example of response for request /api/temperature/Backyard?scale=F10 (output is truncated):

[{"t":"2020-12-24 13:48:19-0500","y":527},{"t":"2020-12-24 13:48:19-0500","y":527},{"t":"2020-12-24 13:51:52-0500","y":525}]

Request humidity

TODO

⚠️ **GitHub.com Fallback** ⚠️