Descripción general
Los datos recibidos a través de la API se asocian a una estación o dispositivo. Dicho dispositivo viene identificado por un código único.
Para el envío de datos variable valor, se realizará una petición POST con un payload JSON como se especifica más adelante. En el caso de envío de imágenes, se realizará una petición POST en formato "multipart/form-data" como se especifica más adelante.
Todas las peticiones de envío de datos necesitarán proveer un API key en la cabecera HTTP "X-API-Key", que identifica a quién realiza el envío de datos, y deberán estar firmadas mediante HMAC-SHA256 provisto en la cabecera HTTP "X-Signature" como se describe más adelante, utilizando un API secret.
Envío de datos variable-valor
Formato de trama:
{
"HIST": {
"DATA": {
"VAR_1": 0.34,
"VAR_2": "texto"
},
"VERSION": "10.0.0",
"UTC": 1518778157,
"IMEI": "APP-FINCA1-CULTIVO1"
}
}
Las tramas son objetos JSON que representan datos de una estación concreta en una fecha y hora concretas.
- El campo VERSION se mantendrá por ahora siempre como en el ejemplo.
- El campo UTC contendrá el timestamp UNIX asociado a los datos que se están enviando.
- El campo IMEI contendrá el código único que identifica a la estación o dispositivo. Pueden utilizarse valores alfanuméricos y guiones. Todas las tramas que tengan el mismo valor en el campo IMEI se asociarán al mismo dispositivo.
- El campo DATA contendrá un objeto JSON con los códigos de las variables como claves, y sus valores, que podrán ser numéricos o cadenas de texto. Para simular valores booleanos puede enviarse como valor 1.0 para ON y 0.0 para OFF.
- Los códigos de variables deben ser consensuados con Nazaríes, ya que por defecto no se crean valores para variables que no hayan sido dadas de alta previamente. Actualmente ya existe una amplia lista de valores existentes, p.ej. temperatura, humedad, etc., que pueden ser utilizados; en caso de necesitar variables no existentes Nazaríes deberá darlas de alta previamente.
Ejemplo de petición:
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":"texto"},"VERSION":"10.0.0","UTC":1518778157,"IMEI":" APP-FINCA1-CULTIVO1"}}' URL
Cálculo de la firma:
- Componer la cadena de texto con la información a firmar:
"<<Método HTTP>><<URL de la petición>>?<<Trama JSON>>"
Ej. "POSTlocalhost:8080/submitData? {"HIST":{"DATA":{"VAR_1":0.34,"VAR_2":"texto"},"VERSION":"10.0.0","UTC":1518778157,"IMEI":" APP-FINCA1-CULTIVO1"}}
- Firmar la cadena de texto anterior mediante HMAC-SHA256, utilizando como secreto el API secret provisto por Nazaríes y codificar el resultado en base64
Envío de imágenes
Ejemplo de petición:
curl -i -X POST -H "X-API-Key: api-key" -H "X-Signature: signature" -F "image=@/path/imagen.png" -F "station_code=123456" -F "variable=image" URL
El envío se realizará en formato multipart/form-data, incluyendo los siguientes parámetros: "variable", siempre con valor image; "station_code", contendrá el identificador único de la estación; "image", contendrá la imagen a enviar.
Cálculo de la firma:
- Componer la cadena de texto con la información a firmar:
"<<Método HTTP>><<URL de la petición>>?station_code=<<Código de la estación>>&variable=image&image=<<Contenido de la imagen codificado en base64"
EJ. "POSTlocalhost:8080/submitImage?station_code=123456&variable=image&image=iVBORw0KGgoAAAANSUhEUg=="
- Firmar la cadena de texto anterior mediante HMAC-SHA256, utilizando como secreto el API secret provisto por Nazaríes y codificar el resultado en base64