Sensors

The sensors service is designed to monitor the value over time of certain variables.

Structure

La unidad básica para el uso de sensores son las variables. Estas están agrupadas en grupos llamados variable_groups. Finalmente, estos grupos corresponden a un par usuario/extension, es decir, para acceder a un grupo de variables se debe identificar al usuario y a la extenión a los que corresponde cada grupo.

The basic unit for the use of sensors are variables. These are grouped into variable_groups. Finally, these groups correspond to a user/extension pair, that is, to access a group of variables, the user and the extension, to which each group corresponds, must be identified.

Each variable can ingest values, and each value consists of a timestamp, a value, and optional metadata.

Access

Access to variables is done by group, which allows the management of all the variables within it.

Sensors is a tool tied to Extensions. groups/variables can only be created or edited by Extensions.

Extensions interact with sensors on behalf of a user, being able to access only variables created by that extension and for that user. Instead, the user can see his variables created by all extensions.

Variables model

Permissions

Each action on variables has an associated functionality. The user executing the action must have it enabled (according to the premium plan). Also, when an extension is where the action is executed from, it will be verified that it has the active functionality in the claimset.

Requires having the Variables and Variables Groups functionalities active in the claimset.

Functionalities

VARIABLE_GROUPS_CREATE: Create a group of variables for the extension and current user.
VARIABLE_GROUPS_READ: Read a group of variables from the current extension and user.
VARIABLE_GROUPS_UPDATE: Updates a group of variables of the current extension and user.
VARIABLE_GROUPS_DELETE: Deletes a group of variables from the current extension and user.
VARIABLES_CREATE: Create a variable for the current extension and user within a specific group.
VARIABLES_READ: Reads a variable from a group belonging to the extension and current user.
VARIABLES_UPDATE: Updates a variable of a group belonging to the extension and current user.
VARIABLES_DELETE: Deletes a variable from a group belonging to the extension and current user.

Objects

`variable_group` object:

group_uuid: string, group uuid.
created_at: string, creation date. Format YYYY-MM-DDTHH:MM:SSZ
deleted_at: string, date deleted. Format YYYY-MM-DDTHH:MM:SSZ. May be null (not deleted)
group_name: string, group name.
user_group_name: string, name of the group set by the user in auravant.
device: string, group serial number.
position: string, position on the map. can be null
user_position: string, position on the map set by the user in auravant. can be null
timezone_offset: integer, with the number of minutes offset from UTC of the group
metadata: object, with metadata. Contains only crop licenses. {"licenses": {}}
variables: array, with variable objects. It can be an empty array.

`variable` object:

variable_uuid: string, variable uuid
created_at: string, creation date. Format YYYY-MM-DDTHH:MM:SSZ
deleted_at: string, date deleted. Format YYYY-MM-DDTHH:MM:SSZ. May be null (not deleted)
variable_name: string, variable name.
user_variable_name: string, name of the variable set by the user in auravant.
device: string, variable serial number.
metadata: object, with metadata.
last_value: float, last value. can be null
last_value_time: string, date of last value. format YYYY-MM-DDTHH:MM:SSZ. It can be Null.
group_uuid: string, group uuid.

`values` object:

timestamps: array(string), array of dates. format YYYY-MM-DDTHH:MM:SSZ
values: array(float), array of values.
metadata: array(object), array of metadata objects.

All three arrays have the same length and elements in the same position correspond to each other. For example, for the element timestamps[0], the variable has the value values[0] and the metadata metadata[0].

API

BASE URL: https://api.auravant.com/sensors/v2

Groups

GET

This endpoint allows you to obtain the groups of variables created and their information.

Requires functionality Variable groups - read (R)

Authorization: Bearer TOKEN
GET /providers/variablegroups

If you want to obtain a specific variable_group, you must add the group_uuid in the query string.

Response example:

{
	"res": "ok",
	"data": [
		{
			"group_uuid": "e4f4f23b-037a-4a6f-b118-f453eae33c95",
			"created_at": "2022-06-13T21:22:33Z",
			"deleted_at": null,
			"group_name": "test-variable-group-1",
			"user_group_name": null,
			"device": "",
			"position": "",
			"user_position": null,
			"timezone_offset": 0,
			"metadata": {},
			"variables": []
		},
		{
			"group_uuid": "809cbdc8-30e2-406b-9740-8ce32b2bb6f0",
			"created_at": "2022-06-14T11:20:04Z",
			"deleted_at": null,
			"group_name": "test-variable-group-2",
			"user_group_name": null,
			"device": "",
			"position": "",
			"user_position": null,
			"timezone_offset": 0,
			"metadata": {},
			"variables": []
		},
		{
			"group_uuid": "5795a90e-b90e-40df-9b21-b68e1daf9609",
			"created_at": "2022-06-14T11:20:48Z",
			"deleted_at": null,
			"group_name": "test-variable-group-3",
			"user_group_name": null,
			"device": "",
			"position": "",
			"user_position": null,
			"timezone_offset": 0,
			"metadata": {},
			"variables": []
		}
	]
}

Where data is an array of data objects: variable_groups

POST

This endpoint allows you to create a new group of variables

Requires functionality Variable groups - create (C)

Authorization: Bearer TOKEN
Content-Type: application/json
POST /providers/variablegroups
Body: 
{
    "group_uuid": <GROUP_UUID>,
    "created_at": <CREATED_AT>,
    "deleted_at": <DELETED_AT>,
    "group_name": <GROUP_NAME> `required`,
    "user_group_name": <USER_GROUP_NAME>,
    "device": <DEVICE>,
    "position": <POSITION>,
    "user_position": <USER_POSITION>,
    "timezone_offset": <TIMEZONE_OFFSET>,
    "metadata": <METADATA>,
    "variables": <VARIABLES>
}

NOTAS

created_at will be assigned automatically with the current date if was not sent

deleted_at, user_group_name & user_position will be assigned as null if was not sent

timezone_offset will be assigned as 0 if was not sent. Cannot be null

metadata will be assigned as an empty object if was not sent

variables will be assigned as an empty array if was mot sent

Response example:

{
	"res": "ok",
	"data": {
		"group_uuid": "5795a90e-b90e-40df-9b21-b68e1daf9609",
		"created_at": "2022-06-14T11:20:48Z",
		"deleted_at": null,
		"group_name": "test-variable-group-3",
		"user_group_name": null,
		"device": "",
		"position": "",
		"user_position": null,
		"timezone_offset": 0,
		"metadata": {},
		"variables": []
	},
	"info": "variable group created successfully"
}

Where data is an object of the variable_group type with the loaded data.

PATCH

This endpoint allows updating or modifying a group of variables

Requires functionality Variable groups - update (U)

Authorization: Bearer TOKEN
Content-Type: application/json
PATCH /providers/variablegroups
Body: 
{
    "group_uuid": <GROUP_UUID> `required`,
    "created_at": <CREATED_AT>,
    "deleted_at": <DELETED_AT>,
    "group_name": <GROUP_NAME>,
    "device": <DEVICE>,
    "position": <POSITION>,
    "timezone_offset": <TIMEZONE_OFFSET>,
    "metadata": <METADATA>,
    "variables": <VARIABLES>
}

NOTES

Note that all the fields of the object variable_group can be modified except for the data that corresponds to the user: user_group_name and user_position

Only properties to be modified should be sent

Response example:

{
	"res": "ok",
	"data": {
		"group_uuid": "e4f4f23b-037a-4a6f-b118-f453eae33c95",
		"created_at": "2022-06-13T21:22:33Z",
		"deleted_at": null,
		"group_name": "test-variable-group-1",
		"user_group_name": null,
		"device": "",
		"position": "",
		"user_position": null,
		"timezone_offset": 4,
		"metadata": {},
		"variables": []
	},
	"info": "variable group updated successfully"
}

Where data is an object of the variable_groups type with the new data.

DELETE

This endpoint allows you to delete a group of variables

Requires functionality Variable groups - delete (D)

Authorization: Bearer TOKEN
Content-Type: application/json
DELETE /providers/variablegroups
Body: 
{
    "group_uuid": <GROUP_UUID>, `required`
}

Where group_uuid is a string corresponding to the uuid of the group.

Response example:

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

Variables

POST

This enpoint allows to create a new variable within a group

Requires functionality Variables - create (C)

Authorization: Bearer TOKEN
Content-Type: application/json
POST /providers/variables
Body: 
{
    "group_uuid": <GROUP_UUID> `requerido`,
    "variable": {
        "variable_name": <VARIABLE_NAME> `requerido`,
        "device": <DEVICE>,
        "metadata: <METADATA>
    }
}

Ejemplo de respuesta:

{
	"res": "ok",
	"data": {
		"variable_uuid": "3120deb3-3079-4d78-92a0-b5a82000e921",
		"variable_name": "test-variable-1",
		"user_variable_name": null,
		"group_id": 582,
		"created_at": "2022-06-14T13:14:50Z",
		"deleted_at": null,
		"device": null,
		"metadata": null,
		"last_value": null,
		"last_value_time": null
	},
	"info": "variable created successfully"
}

Where data is an object of the variable type with the data loaded

PATCH

This endpoint allows you to update or modify a created variable.

Requires functionality Variable groups - update (U)

Authorization: Bearer TOKEN
Content-Type: application/json
PATCH /providers/variables
Body: 
{
    "variable_uuid": <VARIABLE_UUID> `requerido`,
    "variable_name": <VARIABLE_NAME>,
    "device": <DEVICE>,
    "metadata": <METADATA>
}

NOTE - Only specified values can be modified. When trying to modify any other key changes are not applied

Response example:

{
	"res": "ok",
	"data": {
		"variable_uuid": "b3e18dbf-f60c-4403-808f-59ead5796304",
		"variable_name": "test-variable-1",
		"user_variable_name": null,
		"group_id": 582,
		"created_at": "2022-06-14T13:03:18Z",
		"deleted_at": null,
		"device": "medidor-1",
		"metadata": {
			"key-1": "metadata-1"
		},
		"last_value": null,
		"last_value_time": null
	},
	"info": "variable updated successfully"
}

Where data is an object of variable with the new data

DELETE

This endpoint allows you to delete a created variable.

Requires functionality Variables - delete (D)

Authorization: Bearer TOKEN
Content-Type: application/json
DELETE /providers/variables
Body: 
{
    "variable_uuid": <VARIABLE_UUID>, `required`
}

Where variable_uuid is a string corresponding to the uuid of the variable.

Response example:

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

Values

POST

Requires functionality Variables - create (C)

This endpoint allows you to insert values for a certain variable.

Authorization: Bearer TOKEN
Content-Type: application/json
POST /providers/values/variables
Body: 
{
    "data": [
        {
            "variable_uuid": <VARIABLE_UUID> `required`,
            "values": <VALUES> `required`,
            "metadata": <DATA>,
            "timestamps": <DATES> `required`
        },
        {...},
        ...
    ]
}

IMPORTANT - The maximum number of values that can be entered is 2,000,000

Response example:

{
    "res": "ok",
    "info": "values inserted"
}

If no value is sent, the endpoint returns an http code 204 with the message: "no values were inserted".

If the number of values to insert is greater than the specified, the endpoint responds with the message: "Total number of values to insert must not exceed 2,000,000"

General errors

If any query fails, the response will have an http code greater than 400 and a body in json format with a code that will indicate what happened.

Example:

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

According to the code, the user should be told what happened. There are general error codes that can occur on all endpoints. In turn, each endpoint has specific codes detailed in the specification of each one.

General codes

CODE	INFO
GENERAL_ERROR	The requested action failed to execute
EXPIRED_AUTHENTICATION	Expired Authentication token
INVALID_AUTH	Invalid Authentication token
PARAMETER_ERROR	Parameters error
UNAUTHORIZED_EXTENSION	Unauthorized attempt to access an Extensions resource
UNAUTHORIZED_USER	Unauthorized attempt to access a protected endpoint
ACCESS_ERROR	The User does not have access to the requested resource
PERMISSION_ERROR	The User is not allowed to execute the specified action over the requested resource

Specific codes

CODE	INFO
VARIABLEGROUP_NOT_FOUND	Variable group could not be found
VARIABLEGROUP_CREATE_ERROR	Variable group could not be created
VARIABLEGROUP_UPDATE_ERROR	Variable group could not be updated
VARIABLEGROUP_DELETE_ERROR	Variable group could not be deleted
VARIABLE_NOT_FOUND	Variable could not be found
VARIABLE_CREATE_ERROR	Variable could not be created
VARIABLE_UPDATE_ERROR	Variable could not be updated
VARIABLE_DELETE_ERROR	Variable could not be deleted

Structure​

Access​

Permissions​

Functionalities​

Objects​

variable_group object:​

variable object:​

values object:​

API​

Groups​

GET​

POST​

PATCH​

DELETE​

Variables​

POST​

PATCH​

DELETE​

Values​

POST​

General errors​

General codes​

Specific codes​

Structure

Access

Permissions

Functionalities

Objects

`variable_group` object:

`variable` object:

`values` object:

API

Groups

GET

POST

PATCH

DELETE

Variables

POST

PATCH

DELETE

Values

POST

General errors

General codes

Specific codes