Saltar al contenido principal

API Storage

Introducción

Permite almacenar información de las extensiones en nuestros servidores para luego recuperarla cuando sea necesario. (Véase tambíen Módulo Storage del SDK).

La información se almacena en formato Key-Value, es decir, un objeto JSON (Value) bajo un nombre (Key).

Además, cada Key-Value se asocia a un alcance: Usuarios, Lotes o Campos. Este alcance define quién puede acceder a los datos. Por ejemplo, si se crea un Key-Value asociado a un Lote, todos los usuarios que tengan acceso de lectura sobre dicho lote podrán recuperar ese dato, independientemente del usuario que lo almacenó.

Es importante pensar correctamente el alcance que se le va asignar al Key-Value para no exponer datos.

Sobre el alcance de un Usuario, los Key-Values pueden ser:

  • creados/recuperados por el usuario en cuestión.
  • creados/recuperados por el administrador del espacio al que el usuario pertenece (en caso de pertenecer a un espacio).
  • recuperados por el supervisor con permiso de lectura del grupo al que el usuario pertenece (en caso de pertenecer a un grupo de supervisión).
  • creados/recuperados por el supervisor con permiso de edición del grupo al que el usuario pertenece (en caso de pertenecer a un grupo de supervisión).
  • eliminados por el mismo usuario o su supervisor o administrador (en caso de formar parte de un espacio)

Sobre el alcance de un Lote, los Key-Values pueden ser:

  • creados/recuperados por los usuarios dueños o con permiso de edición/agregado/administración sobre el Lote.
  • recuperados por los usuarios con permiso de lectura sobre el Lote.
  • eliminados por los usuarios con permiso de administración sobre el lote.

Sobre el alcance de un Campo, los Key-Values pueden ser:

  • creados/recuperados por los usuarios dueños o con permiso de edición/agregado/administración sobre el Campo.
  • recuperados por los usuarios dueños o con algún permiso sobre el Campo.
  • eliminados por los usuarios con permiso de administración sobre el campo.

Los nombres de los objetos pueden ser combinaciones de letras a-Z, números o guión bajo (_). Debe verificar el regex "\w+"

Para un mismo alcance, no se puede repetir el nombre del objeto.

API

La API posee solo un método, el método POST.

Content-Type: application/json
POST api/mktplace/storage

A partir de el, podemos acceder a los distintos alcances descritos anteriormente.

Alcance de usuario

Content-Type: application/json
POST api/mktplace/storage/users

Alcance de lote

Content-Type: application/json
POST api/mktplace/storage/fields

Alcance de campo

Content-Type: application/json
POST api/mktplace/storage/farms

A su vez, en el mismo endpoint se encuentran las 4 operaciones del storage, estas son: PUT, PATCH, GET y DELETE

  • Parámetro en la URL:
    • operation: PUT/PATCH/GET/DELETE

Operación PUT

Permite almacenar un objeto bajo un nombre (Key).

Parámetros:

Recibe un solo parámetro de tipo objeto que cuenta con las siguientes propiedades:

  • id: ID del recurso (Usuario, Lote o Campo) según el alcance
  • key: Key del objeto a almacenar
  • value: objeto a almacenar
  • overwrite: (opcional) bool indicando si se debe sobreescribir el objeto en caso de ya existir. De no especificarse, por defecto toma el valor false.

Ejemplo de uso:

fetch("https://api.auravant.com/api/mktplace/storage/users?operation=PUT", {
method: "POST",
headers: {
authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
id: "UID-dbaefe8503fe6cdb7909611e8953e74f",
key: "test_key",
value: { name: "juan", lastname: "perez" },
overwrite: true,
}),
}).then(async (resp) => {
const response = await resp.json();
console.log(response);
});

Respuesta:

Promesa con el objeto JSON de respuesta bajo la llave "info". Este objeto tiene la propiedad "code" que indica el resultado de la operación:

codedescripción
1faltan datos
2la Key es inválida, al no respetar regex '^\w+$'
3el usuario no tiene permisos sobre el recurso según el alcance solicitado
4versión de Extensión inválida
5la Key ya existe para el alcance dado. (Solo posible si overwrite es false)
6Error

En caso que "code" < 0, revisar los códigos de respuesta generales.

Operación PATCH

Permite modificar un objeto bajo un nombre (Key) ya existente.

Parámetros:

Recibe un solo parámetro de tipo objeto que cuenta con las siguientes propiedades:

  • id: ID del recurso (Usuario, Lote o Campo) según el alcance
  • key: Key del objeto a modificar
  • value: objeto nuevo
  • append: false por defecto, booleano que, en caso de ser true, indica que el value debe agregarse al valor existente bajo la misma key. En caso de ser false, indica que el value debe reemplazar el valor previo bajo la misma key.
  • create: false por defecto, booleano que indica si debe o no crearse la key, en caso de no existir previamente.

Ejemplo de uso:

fetch("https://api.auravant.com/api/mktplace/storage/users?operation=PATCH", {
method: "POST",
headers: {
authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
id: "UID-dbaefe8503fe6cdb7909611e8953e74f",
key: "test_key",
value: { name: "jane", lastname: "doe" },
create: true,
}),
}).then(async (resp) => {
const response = await resp.json();
console.log(response);
});

Respuesta:

Promesa con el objeto JSON de respuesta bajo la llave "info". Este objeto tiene la propiedad "code" que indica el resultado de la operación:

codedescripción
0objeto modificado exitosamente
1faltan datos
2la Key es inválida, al no respetar regex '^\w+$'
3el usuario no tiene permisos sobre el recurso según el alcance solicitado
4versión de Extensión inválida
5la Key ya existe para el alcance dado
6Error

En caso que "code" < 0, revisar los códigos de respuesta generales.

Operación GET

Permite recuperar los objetos bajo uno o varios nombres (Keys). Es posible obtener múltiples Keys para múltiples IDs en una única llamada.

Parámetros:

Recibe un solo parámetro de tipo objeto que cuenta con las siguientes propiedades:

  • ids: array de IDs de los recursos (Usuario, Lote o Campo) según el alcance.
  • keys: array de las Keys a recuperar.

Se recuperará cada Key del array keys para cada ID del array ids, si es que existen. Además, en caso de enviar en ids un array vacío para el alcance Lotes o Campos, se buscarán las keys indicadas para todos los Lotes/Campos sobre los que el usuario tenga permiso de lectura.

Ejemplo de uso:

fetch("https://api.auravant.com/api/mktplace/storage/users?operation=GET", {
method: "POST",
headers: {
authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
ids: ["UID-dbaefe8503fe6cdb7909611e8953e74f"],
key: ["test_key", "no_key"],
}),
}).then(async (resp) => {
const response = await resp.json();
console.log(response);
});

Respuesta:

Promesa con el objeto JSON de respuesta bajo la llave "info". Este objeto tiene la propiedad "code" que indica el resultado de la operación, y la propiedad "objects" con los datos:

codedescripción
0objeto recuperado exitosamente
1faltan datos
2al menos una Key solicitada es inválida, al no respetar regex '\w+'
3el usuario no tiene permisos sobre al menos un recurso según el alcance solicitado
4versión de Extensión inválida
5al menos un ID solicitado es inválido

En caso que "code" < 0, revisar los códigos de respuesta generales.

Operación DELETE

Permite eliminar uno o múltiples objetos bajo nombres (Keys) ya existentes.

Parámetros:

Recibe un solo parámetro de tipo objeto que cuenta con las siguientes propiedades:

  • id: ID del recurso (Usuario, Lote o Campo) según el alcance
  • keys: array con las Keys a eliminar.

Ejemplo de uso:

fetch("https://api.auravant.com/api/mktplace/storage/users?operation=DELETE", {
method: "POST",
headers: {
authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
id: "UID-dbaefe8503fe6cdb7909611e8953e74f",
keys: ["test_key"],
}),
}).then(async (resp) => {
const response = await resp.json();
console.log(response);
});

Respuesta:

Promesa con el objeto JSON de respuesta bajo la llave "info". Este objeto tiene la propiedad "code" que indica el resultado de la operación:

codedescripción
0objeto modificado exitosamente
1la Key no fue provista
2la Key es inválida, al no respetar regex '^\w+$'
3el usuario no tiene permisos sobre el recurso según el alcance solicitado
4versión de Extensión inválida
6Error

En caso que "code" < 0, revisar los códigos de respuesta generales.