Documentación

Backend Sensors

Este microservicio contiene las APIs del módulo de variables de Auravant y los workers de Celery para procesar alarmas.

Estructura

Sensores está diseñado para monitorear el valor en el tiempo de variables, que están agrupadas (posiblemente geográficamente) en variable_groups.

Se pueden ingestar values a cada variable. Cada value consiste de un timestamp, un valor y una metadata opcional.

Acceso

El acceso a variables se hace por grupo, es decir usuario -> grupo, lo que le da acceso a todas las variables dentro de él.

Sensores es una herramienta atada a extensiones. Los grupos/variables sólo pueden ser creados/editados por extensiones. Por lo tanto, un grupo pertenece a un (usuario, extensión).

Las extensiones interactúan con Sensores en nombre de un usuario, pudiendo acceder sólo a las variables creadas por esa extensión, para ese usuario. En cambio, el usuario puede ver sus variables creadas por todas las extensiones.

Por eso hay 2 sets de APIs. Uno para el usuario, desde el que puede operar sobre todas sus variables, y uno para los proovedores (extensiones) desde el que se pueden operar las variables de un usuario de la extensión en cuestión.

Permisos

Cada acción sobre variables tiene una funcionalidad asociada. El usuario que ejecute la acción debe tenerla habilitada (estará dada por el plan y probablemente para todos). Además, cuando sea una extensión la ejecuta la acción (como crear un grupo), se verificará que la misma tenga dicha funcionalidad en el claimset.

Las funcionalidades finales son la intersección entre las FXs del usuario y el claimset de la extensión.

Funcionalidades:

VARIABLE_GROUPS_CREATE = 600
VARIABLE_GROUPS_READ = 601
VARIABLE_GROUPS_UPDATE = 602
VARIABLE_GROUPS_DELETE = 603
VARIABLES_CREATE = 604
VARIABLES_READ = 605
VARIABLES_UPDATE = 606
VARIABLES_DELETE = 607

Está pendiente la funcionalidad de ingesta

Objetos

Variable groups

objeto variable_group:

group_uuid: string uuid del grupo.
created_at: string fecha de creación. formato YYYY-MM-DDTHH:MM:SSZ
deleted_at: string fecha de eliminación. formato YYYY-MM-DDTHH:MM:SSZ. Puede ser nula (no eliminado)
group_name: string Nombre del grupo.
user_group_name: string Nombre del grupo seteado por el usuario en auravant.
device: string Número de serie del grupo.
position: string Posición en el mapa. Puede ser nula
user_position: string Posición en el mapa seteado por el usuario en auravant. Puede ser nula
timezone_offset: int con la cantidad de minutos de offset respecto a UTC del grupo
metadata: object con metadata. Contiene únicamente las licencias de cultivos. {"licenses": {}}
variables: array con objetos variables. Puede ser un array vacío.

objeto variable:

variable_uuid: string uuid de la variable
created_at: string fecha de creación. formato YYYY-MM-DDTHH:MM:SSZ
deleted_at: string fecha de eliminación. formato YYYY-MM-DDTHH:MM:SSZ. Puede ser nula (no eliminado)
variable_name: string Nombre de la variable.
user_variable_name: string Nombre de la variable seteado por el usuario en auravant.
device: string Número de serie de la variable.
metadata: object con metadata.
last_value: float último valor. Puede ser Nulo
last_value_time: string fecha del último valor. formato YYYY-MM-DDTHH:MM:SSZ. Puede ser Nulo.

objeto values:

dates: array(string) array de fechas. formato YYYY-MM-DDTHH:MM:SSZ
values: array(float) array de valores.
data: array(object) array de objetos.

Los tres arrays tienen el mismo largo y los elementos en la misma posición se corresponden entre si. Por ejemplo, para el dates[0], la variable tiene el valor values[0] y la metadata data[0].

Alcance de usuarios y extensiones

Como se mencionó antes, hay un set de APIs para los usuarios y otra para las extensiones.

Las extensiones pueden:

CRUD de grupos/variables
Ingestar values en cada variable.
Leer values de variables.

Los usuarios pueden:

UD de grupos/variables
Leer values de variables.

Si bien ambos pueden hacer un UPDATE sobre los grupos y variables, la acción se ejecuta sobre distintas propiedades. Los usuarios sólo pueden modificar user_group_name y user_position en los grupos y user_variable_name en las variables. Por el otro lado, las extensiones pueden modificar todos los parámetros excepto los anteriores.

Esto permite que el usuario pueda renombrar o reubicar los grupos/variables de una manera distinta a la que lo hace la extensión.

Alarmas

La herramienta de alarma permite alertar al usuario cuando el valor de una variable se comporta de cierta manera. Por ahora, las opciones son:

cuando el valor de la variable supera un umbral superior
cuando el valor de la variable supera un umbral inferior

Cuando el usuario configura una alarma sobre una variable, periódicamente se revisan los valores de ésta en el tiempo y en caso de cumplirse la condición especificada, se da aviso por mail.

APIs

todos las URIs son relativas a BASE_URL

Producción: BASE_URL = https://api.auravant.com/sensors

Testing: BASE_URL = http://api.testing.auravant.com/sensors

Errores generales

En caso de fallar algúna consulta, la respuesta tendrá un código http > 400 y un cuerpo en formato json con un código que indicará lo sucedido.

Ejemplo:

{
 "res": "error", 
 "code": <CODE>, 
 "info": <INFO>
}

Según el código, se le debe informar al usuario lo que sucedió. Existen códigos de error generales que pueden ocurrir en todos los endpoints. A su vez, cada endpoint tiene códigos especificos detallados en la especificación de cada uno.

codigos generales:

CODE	INFO	descripcion
GENERAL_ERROR	The requested action failed to execute	error general, es generalmente un error no atajado
EXPIRED_AUTHENTICATION	Expired Authentication token	token vencido, no deberia ocurrir desde la extensión
INVALID_AUTH	Invalid Authentication token	token inválido, no debería ocurrir desde la extensión
PARAMETER_ERROR	Parameters error	los parámetros enviados al backend no coinciden con los esperados
UNAUTHORIZED_EXTENSION	Unauthorized attempt to access an Extensions resource	se está consultando un endpoint no habilitado para extensiones
UNAUTHORIZED_USER	Unauthorized attempt to access a protected endpoint	usuario no autenticado, falta autenticación en la request
ACCESS_ERROR	The User does not have access to the requested resource	Se está intentando acceder a un grupo/variable sobre el cual no tiene acceso
PERMISSION_ERROR	The User is not allowed to execute the specified action over the requested resource	El usuario no cuenta con la funcionalidad para ejecutar la acción solicitada

codigos específicos:

CODE	INFO	descripcion
VARIABLEGROUP_NOT_FOUND	Variable group could not be found	No se encontró el grupo solicitado
VARIABLEGROUP_CREATE_ERROR	Variable group could not be created	No se pudo crear el grupo
VARIABLEGROUP_UPDATE_ERROR	Variable group could not be updated	No se pudo actualizar el grupo
VARIABLEGROUP_DELETE_ERROR	Variable group could not be deleted	No se pudo eliminar el grupo
VARIABLE_NOT_FOUND	Variable could not be found	No se encontró la variable solicitada
VARIABLE_CREATE_ERROR	Variable could not be created	No se pudo crear la variable
VARIABLE_UPDATE_ERROR	Variable could not be updated	No se pudo actualizar la variable
VARIABLE_DELETE_ERROR	Variable could not be deleted	No se pudo eliminar la variable

APIs usuarios

GROUPS

GET

Ver grupos. FX requerida: VARIABLE_GROUPS_READ

Authorization: Bearer TOKEN
GET /users/variablegroups

Respuesta:

{
 "res": "ok",
 "data": []
}

Donde data es un array de objetos de variable_groups.

PATCH

Modificar grupo. FX requerida: VARIABLE_GROUPS_UPDATE

Authorization: Bearer TOKEN
Content-type: application/json
PATCH /users/variablegroups
Body:
 {
 "group_uuid": <group_uuid>
 "user_group_name": <user_group_name>
 "user_position": <user_position>
 }

Donde:

<group_uuid> (str, obligatorio) es el uuid del grupo
<user_group_name> (str, opcional) es el nombre custom
<user_position> (str, opcional) es la posición custom

Enviar sólo lo que se desea modificar. Tanto user_group_name como user_position pueden ser nulos.

importante: user_group_name es de un máximo de 100 caracteres.

Respuesta:

{
 "res": "ok",
 "info": "variable group updated successfully",
 "data": {}
}

Donde data es un objeto de variable_groups, con los datos nuevos.

Errores:

VARIABLEGROUP_UPDATE_ERROR

DELETE

Eliminar un grupo. FX requerida: VARIABLE_GROUPS_DELETE

Authorization: Bearer TOKEN
Content-type: application/json
DELETE /users/variablegroups
Body:
 {
 "group_uuid": <group_uuid>
 }

Donde:

<group_uuid> (str, obligatorio) es el uuid del grupo

Respuesta:

{
 "res": "ok",
 "info": "variable group deleted successfully"
}

Errores:

VARIABLEGROUP_DELETE_ERROR

VARIABLES

PATCH

Modificar Variable. FX requerida: VARIABLES_UPDATE

Authorization: Bearer TOKEN
Content-type: application/json
PATCH /users/variables
Body:
 {
 "variable_uuid": <variable_uuid>
 "user_variable_name": <user_variable_name>
 }

Donde:

<group_uuid> (str, obligatorio) es el uuid del grupo
<user_variable_name> (str, opcional) es el nombre custom

importante: user_variable_name es de un máximo de 100 caracteres y puede ser nulo.

Respuesta:

{
 "res": "ok",
 "info": "variable updated successfully",
 "data": {}
}

Donde data es un objeto de variables, con los datos nuevos.

Errores:

VARIABLE_NOT_FOUND
VARIABLE_UPDATE_ERROR

VALUES

VALUES POR GRUPO

Permite obtener los values de todas las variables de uno o más grupos

Authorization: Bearer TOKEN
Content-type: application/json
POST /users/values/variablegroups
Body:
 {
 "group_uuids": <group_uuids>
 "since": <since>,
 "to": <to>
 }

Donde:

<group_uuids> ([str], obligatorio) es un array con los group_uuid de los grupos
<to> (str, opcional) fecha hasta la cual obtener datos. formato YYYY-MM-DDTHH:MM:SSZ. De no enviarse, el default es now() (UTC)
<since> (str, opcional) fecha desde la cual obtener datos. formato YYYY-MM-DDTHH:MM:SSZ. De no enviarse, el default es now() - 30 días

Respuesta:

{
 "res": "ok",
 "data": {}
}

Donde data es un objeto cuyas keys son variable_uuids y sus values objetos values

VALUES POR VARIABLE

Permite obtener los values de una o más variables

Authorization: Bearer TOKEN
Content-type: application/json
POST /users/values/variables
Body:
 {
 "variable_uuids": <variable_uuids>
 "since": <since>,
 "to": <to>
 }

Donde:

<variable_uuids> ([str], obligatorio) es un array con los variable_uuid de las variables
<to> (str, opcional) fecha hasta la cual obtener datos. formato YYYY-MM-DDTHH:MM:SSZ. De no enviarse, el default es now() (UTC)
<since> (str, opcional) fecha desde la cual obtener datos. formato YYYY-MM-DDTHH:MM:SSZ. De no enviarse, el default es now() - 30 días

Respuesta:

{
 "res": "ok",
 "data": {}
}

Donde data es un objeto cuyas keys son variable_uuids y sus values objetos values

ALARMS

Objeto alarm:

alarm_uuid: string uuid de la alarma
variable_uuid: string el variable_uuid de la variable sobre la cual setear la alarma.
trigger_type: string tipo de condición
value: float valor asociado a la condición
created_at: string timestamp de creación de la alarma.

trigger_types:

TRIGGER_UP: cuando la variable supera un valor
TRIGGER_DOWN: cuando la variable cae por debajo de un valor

POST

Crear alarma.

Authorization: Bearer TOKEN
Content-type: application/json
POST /users/variables/alarms
Body:
 {
 "trigger_type": <trigger_type>,
 "value": <value>,
 "variable_uuid": <variable_uuid>
 }

Donde:

<trigger_type> (str, obligatorio) es el tipo de condición.
<value> (float, obligatorio) es el valor de la condición.
<variable_uuid> (str, obligatorio) es el variable_uuid de la variable sobre la cual setear la alarma.

Respuesta:

{
 "res": "ok",
 "info": "alarm created",
 "data": {}
}

Donde data es un objeto de alarm, con los datos nuevos.

GET

Obtener las alarmas del usuario.

Authorization: Bearer TOKEN
GET /users/variables/alarms

Opcionalmente, se puede filtrar por variable_uuid, par aobtener las alarmas de una única variable. Para ello, incluir el parámetro variable_uuid en el query string.

Respuesta:

{
 "res": "ok",
 "data": []
}

Donde data es un array de objetos alarm.

PATCH

Modificar alarma.

Authorization: Bearer TOKEN
Content-type: application/json
PATCH /users/variables/alarms
Body:
 {
 "alarm_uuid": <alarm_uuid>,
 "trigger_type": <trigger_type>,
 "value": <value>,
 }

Donde:

<alarm_uuid> (str, obligatorio) es el uuid de la alarma a eliminar.
<trigger_type> (str, opcional) es el tipo de condición.
<value> (float, opcional) es el valor de la condición.

Respuesta:

{
 "res": "ok",
 "info": "alarm created",
 "data": {}
}

Donde data es un objeto de alarm, con los datos nuevos.

DELETE

Eliminar alarma.

Authorization: Bearer TOKEN
Content-type: application/json
DELETE /users/variables/alarms
Body:
 {
 "alarm_uuid": <alarm_uuid>,
 }

Donde:

<alarm_uuid> (str, obligatorio) es el uuid de la alarma a eliminar.

Respuesta:

{
 "res": "ok",
 "info": "alarm deleted",
 "data": {"alarm_uuid": "alarm_uuid"}
}

Documentación

Backend Sensors

Estructura​

Acceso​

Permisos​

Objetos​

Variable groups​

Alcance de usuarios y extensiones​

Alarmas​

APIs​

Errores generales​

APIs usuarios​

GROUPS​

GET​

PATCH​

DELETE​

VARIABLES​

PATCH​

VALUES​

VALUES POR GRUPO​

VALUES POR VARIABLE​

ALARMS​

POST​

GET​

PATCH​

DELETE​

Estructura

Acceso

Permisos

Objetos

Variable groups

Alcance de usuarios y extensiones

Alarmas

APIs

Errores generales

APIs usuarios

GROUPS

GET

PATCH

DELETE

VARIABLES

PATCH

VALUES

VALUES POR GRUPO

VALUES POR VARIABLE

ALARMS

POST

GET

PATCH

DELETE