[EN] Posting data to IoT API

Owned by Rafael Ramón (Unlicensed)
Last updated: Aug 03, 2022
2 min read

General description


The data received through the API is associated with a station or device. This device is identified by a unique code.
To send variable value data, a POST request will be made with a JSON payload as specified below. In the case of sending images, a POST request will be made in "multipart/form-data" format as specified below.
All requests to send data will provide an API key in the HTTP header "X-API-Key", which identifies who is sending the data, and must be signed using HMAC-SHA256 provided in the HTTP header "X-Signature " as described below, using an API secret.

Send variable-value data


Frame format:
{
"HIST": {
"DATA": {
"VAR_1": 0.34,
"VAR_2": "text"
},
"VERSION": "10.0.0",
"UTC": 1518778157,
"IMEI": "APP-FARM1-CROP1"
}
}
Frames are JSON objects that represent data from a specific station at a specific date and time.

  • The VERSION field will remain for now always as in the example.
  • The UTC field will contain the UNIX timestamp associated with the data being sent.
  • The IMEI field will contain the unique code that identifies the station or device. Alphanumeric values ​​and hyphens can be used. All frames that have the same value in the IMEI field will be associated to the same device.
  • The DATA field will contain a JSON object with the codes of the variables as keys, and their values, which may be numeric or text strings. To simulate Boolean values, it can be sent as a value of 1.0 for ON and 0.0 for OFF.
  • The variable codes must be agreed with Nazaríes, since by default values ​​are not created for variables that have not been previously registered. Currently there is already an extensive list of existing values, eg temperature, humidity, etc., that can be used; If you need non-existent Nazaríes´ variables, you must register them previously.


Query example:


curl -i -XPOST -H "X-API-Key: api-key" -H "X-Signature: signature" -H "Content-Type: application/json" -H "Accept: application/json" -d '{"HIST":{"DATA":{"VAR_1":0.34,"VAR_2":"tex"},"VERSION":"10.0.0","UTC":1518778157,"IMEI":" APP-FARM1-CROP1"}}' URL


Signature calculation:

  1. signature: Compose the text string with the information to sign:


"<<Method HTTP>><<URL of the petition>>?<<JSON frame>>"


Ex. "POSTlocalhost:8080/submitData? {"HIST":{"DATA":{"VAR_1":0.34,"VAR_2":"text"},"VERSION":"10.0.0","UTC":1518778157,"IMEI":"APP-FARM1-CROP1"}}

  1. Sign the above text string using HMAC-SHA256, using the API secret provided by Nazaríes as a secret and encode the result in base64
  2. localhost:8080 should be replaced by the correct URL provided by Nazaríes.