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:

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

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:

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

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"],
    keys: ["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:

code	descripción
0	objeto recuperado exitosamente
1	faltan datos
2	al menos una Key solicitada es inválida, al no respetar regex '\w+'
3	el usuario no tiene permisos sobre al menos un recurso según el alcance solicitado
4	versión de Extensión inválida
5	al 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:

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

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