API Storage

Intro

In order to use the storage functionalities, the developer must activate the 'Aurapps Storage' permissions in the extension's claimset.

Allow information to be stored on our servers and then retrieved when needed.

The information is stored in Key-Value format, i.e. a JSON object (Value) under a name (Key).

In addition, each Key-Value is associated with a scope: Users, Fields or Farms. This scope defines who can access the data. For example, if a Key-Value associated to a Field is created, all users who have read access to that Field will be able to retrieve that data, regardless of the user who stored it.

It is important to think correctly about the scope to be assigned to the Key-Value in order not to expose data.

On the scope of a User, Key-Values can be:

created/retrieved by the user in question.
created/retrieved by the administrator of the space to which the user belongs (in case of belonging to a space).
retrieved by the supervisor with read permission of the group to which the user belongs (in case of belonging to a supervisory group).
created/retrieved by the supervisor with edit permission of the group to which the user belongs (in case of belonging to a supervisory group).
deleted by the user itself or the supervisor or administrator (in case of belonging to a space)

Over the scope of a Field, Key-Values can be:
created/retrieved by users owning or having edit/add/administration permission on the Field.
retrieved by users with read permission on the Field.
deleted by users owning or having administration permission on the Field.

Over the scope of a Farm, Key-Values can be:

created/retrieved by users who own or have edit/add/administration permission on the Farm.
retrieved by the owning users or with some permission on the Farm.
deleted by users owning or having administration permission on the Farm.

Object names can be combinations of letters a-Z, numbers or underscore (_). You must check the regex "\w+".

For the same scope, the object name cannot be repeated.

API

The API has only one method, the POST method.

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

From it, we can access the different scopes described above.

Users scope

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

Fields scope

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

Farms scope

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

The 4 storage operations are found on the same endpoint, these are: PUT, PATCH, GET and DELETE

Parameter in the URL:
- operation: PUT/PATCH/GET/DELETE

PUT operation

Allows an object to be stored under a name (Key).

Parameters:

Receives an object that has the following properties:

id: Resource ID (User, Field or Farm) according to the scope.
key: Key of the object to be stored
data: Object to be stored
overwrite: (optional) bool indicating whether to overwrite the object if it already exists. If not specified, it is false by default.

Usage example:

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);
});

Response:

Promise with the response JSON object under the "info" key. This object has the "code" property indicating the result of the operation:

code	description
1	data missing
2	the Key is invalid, as it does not respect regex '^\w+$'
3	the user does not have permissions on the resource according to the scope requested
4	invalid Extension version
5	the Key already exists for the given scope. (Only possible if overwrite is false)
6	Error

In case "code" < 0, check general response codes

PATCH operation

Allows to modify an object under an existing name (Key).

Parameters:

Receives an object that has the following properties:

id: Resource ID (User, Field or Farm) according to the scope.
key: Key of the object to be modified
data: new object
append: false by default, boolean that, in case of being true, indicates that value must be added to the previous value saved under the same key. In case of false, indicates that the new value must replace the previous value saved under the same key.
create: false by default, boolean that indicates if key should or not be created if it didn't exist before.

Usage example:

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);
});

Response:

Promise with the response JSON object under the "info" key. This object has the "code" property indicating the result of the operation:

code	description
0	object successfully modified
1	data missing
2	the Key is invalid, as it does not respect regex '^\w+$'
3	the user does not have permissions on the resource according to the scope requested
4	invalid Extension version
5	the Key already exists for the given scope
6	Error

In case "code" < 0, check general response codes

GET operation

Allows to retrieve objects under one or several names (Keys). It is possible to obtain multiple Keys for multiple IDs in a single call.

Parameters:

Receives an object that has the following properties:

ids: array of resource IDs (User, Field or Farm) according to the scope.
keys: array of Keys to be recovered.

Each Key of the keys array shall be retrieved for each ID of the ids array, if they exist. In addition, in case of sending in ids an empty array for the scope Fields of Farms, the specified keys will be fetched for all the Fields/Farms for which the user has read permission.

Usage example:

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);
});

Response:

Promise with the response JSON object under the "info" key. This object has the "code" property indicating the result of the operation, and the "objects" property with the data:

code	description
0	object successfully recovered
1	data missing
2	at least one requested Key is invalid, as it does not respect regex '\w+'
3	user does not have permissions on at least one resource according to the requested scope
4	invalid Extension version
5	at least one requested ID is invalid

In case "code" < 0, check general response codes.

DELETE operation

Allows to delete of one or multiple objects under existing names (Keys).

Parameters:

Receives an object that has the following properties:

id: ID of the resource (User, Field or Farm) depending on the scope.
keys: array with the Keys to delete.

Usage example:

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);
});

Response:

Promise with the response JSON object under the "info" key. This object has the "code" property indicating the result of the operation:

code	description
0	object successfully modified
1	the Key was not provided
2	the Key is invalid, as it does not respect regex '^\w+$'
3	the user does not have permissions on the resource according to the scope requested
4	Extension version invalid
6	Error

In case "code" < 0, check the general response codes

File Storage

File Storage allows an extension to store files for a user, field or farm. The scopes are the same as those explained in the conventional storage section.

User scope

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

Field scope

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

Farm scope

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

GET operation

Query to obtain information about the files stored in storage. The parameter with the corresponding operation is added in the POST:

?operation=GET

Body

keys: array of keys to query - Mandatory
ids: array of ids to filter resources to search for keys:
- depending on the scope, they will be ids of users, fields or farms.
- in the scope of users, if not included, it is assumed that it is being queried by the user making the query.
- in the fields and farms scopes, if not included the requested keys are searched for in all the fields/farms to which the user has access.
get_url: bool indicates whether or not to include the download url in the response.

Response:

{
  "objects": {
    "resource_id_1": {
      "key_1": {
        "file_name": "d5fa71aa-1f35-11ef-a2b9-ab5cffcaca66.pdf",
        "file_size_kb": 150.5,
        "created_at": "2024-01-01T00:00:00Z",
        "url": "..."
      }
    },
    "resource_id_1": {...}
  }
}

file_name: string representing the file name.
file_size_kb: file weight in kilobytes.
created_at: date and time the file was saved in storage.
url: string of the url to download the file.

In case of requesting keys for the scope of users and not indicating ids, as the query is made for the same user, the response is different since the resource level is not included.

Response without resource level:

{
  "objects": {
    "key_1": {
      "file_name": "d5fa71aa-1f35-11ef-a2b9-ab5cffcaca66.pdf",
      "file_size_kb": 150.5,
      "created_at": "2024-01-01T00:00:00Z",
      "url": "..."
    },
    "key_2": {...}
  }
}

PUT operation

This endpoint allows us to create a key and as a response we will obtain a url to upload the file to the storage. Then, when making this query, the new key will be generated and will appear in the list of GET queries, but until the client uploads the new file with the URL provided, it will not be available. In case of overwriting a key, the replaced file will be deleted at the time of the query.

The parameter with the corresponding operation is added in the POST:

?operation=PUT

Body

key: string on which you want to save the file.
original_file_name: string representing the name of the file to be uploaded.
md5: MD5 hash string encoded in base64 of the file to upload. This is the value that must be sent when uploading the file.
file_size_kb: float size in kb of the file to upload.
overwrite: boolean that indicates whether to overwrite the key in case it already exists. By default it is false so if the indicated key already exists, the endpoint will respond with error.
user: UID-XXXX encrypted id. Only mandatory in the users scope, indicating the id of the user on which you want to save.
field: uuid/int only mandatory in the fields scope, indicating the id of the field on which you want to save.
farm: uuid/int only mandatory in the scope farms, indicating the id of the farm on which you want to save.

Javascript code to obtain the md5 required in the query body:

const reader = new FileReader();
reader.readAsBinaryString(blob);
reader.onloadend = () => {
  resolve(CryptoJS.enc.Base64.stringify(CryptoJS.MD5(CryptoJS.enc.Latin1.parse(reader.result.toString()))));
};

Response

{
  "data": {
    "url": "....",
    "fields": {
      "f1": "...",
      "f2": "...",
      "f3": "..."
    }
  }
}

After a successful answer, the key is already stored and the next step is to upload the file. For this, the object returned under the key data is used in the following way:

A POST must be made to the returned url, with a Content-Type multipart/form-data and a Body that includes all the key-values that are under the key fields of the returned object in the same PUT response. In addition, a Content-MD5 field with the MD5 hash of the file to upload must be included in the form.

Information to be considered

The upload url is valid for 10 seconds.
The maximum file size is set to 10MB.
Only one URL is provided for the file download and it is downloaded via a GET.
The download url is valid for 10 seconds.

Possible errors

code	description
2	invalid key format
3	you do not have permission on the resource (user/field/farm) specified
5	the specified key already exists for the specified resource, and the overwrite flag was not sent
7	the file exceeds the maximum allowed size

PATCH operation

This endpoint is used to update the file stored under a key. First the modification is made in the endpoint, obtaining the new url to upload the new file.

When this query is performed, the new value replaces the old one and the replaced file is immediately deleted. In GET queries the new file will be listed but until the client uploads it with the provided URL, it will not be available.

The parameter with the corresponding operation is added in the POST:

?operation=PATCH

Body

key: string on which you want to overwrite the file.
original_file_name: string name of the file to upload.
md5: string MD5 hash encoded in base64 of the file to upload.This is the value that must be sent when uploading the file.
file_size_kb: float size in kb of the file to upload.
create: boolean indicates whether to create the key in case it does not exist. By default it is false, so if the indicated key does not exist, the endpoint will respond with an error.
user: UID-XXXX encrypted id. Only mandatory in the users scope, indicating the id of the user on which you want to save.
field: uuid/int only mandatory in the fields scope, indicating the id of the field on which you want to save.
farm: uuid/int only mandatory in the scope farms, indicating the id of the farm on which you want to save.

Response

The response and the procedure to follow afterwards to make the file upload effective are the same as explained for the PUT.

Possible errors

code	description
2	invalid key format
3	you do not have permission on the resource (user/field/farm) specified
5	the specified key does not exist for the specified resource, and the create flag was not sent
7	the file exceeds the maximum allowed size

DELETE operation

This service allows us to delete keys from storage. You can delete a key or a group of keys for all the resources in the scope or filter by resource id.

The parameter with the corresponding operation is added in the POST:

?operation=DELETE

Body

keys: this is a mandatory parameter, it is the array of keys to delete.
id: this parameter is optional, it can be a string or an int id of the resource.

Response

{
  "data": {
    "keys": ["eliminated_key_1", "eliminated_key_2"]
  }
}

Possible errors

code	description
2	invalid key format
3	you do not have permission on the resource (user/field/farm) specified

This functionality allows sharing data in and between extensions in such a way that the information is more accessible at different levels and between different users. In the following we will detail how it works and what are the uses that can be given to it.

Base URL:

https://api.aurapps.com/

In all the endpoints we use for this service we have the possibility of sending a parameter called 'client_id', which is optional. If we send this parameter, the queries we perform will return only those data stored in the storage of the extension to which this client_id corresponds under the key (sent by parameter) that begins with the prefix 'public_ext_'. So, if in an extension we store information that we want to share with other extensions, we must store such data under a key that begins with the prefix mentioned above and the only thing we must do from the other extensions is to send a query passing by parameter the same key (without the prefix) and the client_id of the extension from which we want to extract such data.

Otherwise, if we do not send the 'client_id' parameter, the query will return all the data stored (in the extension from which the query is being made) under the key sent by parameter starting with the prefixes 'public_priv_' and 'public_ext_'. This means that by executing the GET in this way we will get all the information that has been saved both to be displayed within the extension itself and to be shared with other extensions.

Public Values

This module allows us to share between the extensions data stored in the storage in three different levels: user, field and farm.

User

GET publicvalues/user

Parameters:

key: string that we define as the key under which the information was saved in the storage without the 'public_'.
client_id: public identifier of the extension. This parameter is optional, it is only applied if the user needs to see information of a particular extension from another extension.
users: comma separated list of user uuids. This parameter is optional, if used the endpoint will only return information of the consulted users.
dev: boolean that defines if the information will be searched in the dev storage (if true) or the production storage (if false).

Response example:

[
  {
    "user": "UID-5112320dasd0112f2afd2eac1bb53b5190",
    "value": {
      "key_storage_1": "value_1",
      "key_storage_2": "value_2",
      "key_storage_3": "value_3"
    }
  }
]

Inside the array we receive objects, which have the following properties:

user: uuid of the user where the data was saved.
value: object containing all the data stored at this level under the key sent by parameter in the query.

Field

GET publicvalues/field

Parameters:

key: string that we define as the key under which the information was saved in the storage.
client_id: public identifier of the extension. This parameter is optional, it is only applied if the user needs to see information of a particular extension from another extension.
fields: comma separated list of batch ids. This parameter is mandatory. The user must have read permission on the queried fields (permission number 320). If the user does not have read permission on any of the queried fields, the endpoint will respond with a 401. Otherwise, it will return information on the fields for which the user does have read permission.

Response example:

[
  {
    "field": 12345,
    "value": {
      "key_storage_1": "value_1",
      "key_storage_2": "value_2",
      "key_storage_3": "value_3"
    }
  }
]

Inside the array we receive objects, which have the following properties:

field: id of the field in which the data was saved.
value: object containing all the data stored at this level under the key sent by parameter in the query.

Farm

GET publicvalues/farm

Parameters:

key: string that we define as the key under which the information was saved in the storage.
client_id: public identifier of the extension. This parameter is optional, it is only applied if the user needs to see information of a particular extension from another extension.
farms: list of farm ids separated by commas. This parameter is mandatory. The user must have read permission on the queried farms (permission number 320). If the user does not have read permission on any of the queried farms, the endpoint will respond with a 401. Otherwise, it will return information on the farms for which it does have such permission.

Response example:

[
  {
    "farm": 12345,
    "value": {
      "key_storage_1": "value_1",
      "key_storage_2": "value_2",
      "key_storage_3": "value_3"
    }
  }
]

Inside the array we receive objects, which have the following properties:

farm: id of the farm in which the data was saved.
value: object containing all the data stored at this level under the key sent by parameter in the query.

Public Files

This module allows us to share files stored in the filestorage between extensions at two different levels: field and farm (at user level it is not yet implemented).

Farm

GET publicfiles/farm

Parameters:

Same Parameters as for /publicvalues/farm

Response example:

{
  "12345": {
    "storage_key": {
      "file_name": "1458480-0e39-47f6-1112-1212121.pdf",
      "file_size_kb": 2357.9092,
      "created_at": "2025-01-06T13:00:23Z",
      "url": "https://avt-aurapps-storage....."
    }
  }
}

The endpoint returns a set of objects, for which each key is the id of the queried farms; within these come more objects, each of which represents a file stored in storage for that particular farm (the key of these objects is the identifier under which the file was stored in storage). Each file returns the following data:

file_name: file name,
file_size_kb: weight in kilobytes of the file.
created_at: date and time the file was saved in storage.
url: pre-sign key that gives access to the file for a small amount of time (100 seconds). By making a query to it and as long as this is done during the access time, the file can be downloaded.

Field

GET publicfiles/field

Parameters:

Same Parameters as for /publicvalues/field

Response example:

{
  "6789": {
    "storage_key": {
      "file_name": "107565-as39-47074-av2-04780.pdf",
      "file_size_kb": 1257.012,
      "created_at": "2025-02-12T13:00:23Z",
      "url": "https://avt-aurapps-storage....."
    }
  }
}

The endpoint returns the same response scheme as for publicfiles/farm, with the difference that in this case the key of the objects are the ids of the queried fields. The properties that come inside the objects that represent the files stored in storage are also the same as the previous example.

Intro​

API​

Users scope​

Fields scope​

Farms scope​

PUT operation​

Parameters:​

Response:​

PATCH operation​

Parameters:​

Response:​

GET operation​

Parameters:​

Response:​

DELETE operation​

Parameters:​

Response:​

File Storage​

User scope​

Field scope​

Farm scope​

GET operation​

Body​

Response:​

Response without resource level:​

PUT operation​

Body​

Response​

Information to be considered​

Possible errors​

PATCH operation​

Body​

Response​

Possible errors​

DELETE operation​

Body​

Response​

Possible errors​

Share data between extensions​

What means sharing data in and between extensions?​

Public Values​

User​

Parameters:​

Response example:​

Field​

Parameters:​

Response example:​

Farm​

Parameters:​

Response example:​

Public Files​

Farm​

Parameters:​

Response example:​

Field​

Parameters:​

Response example:​

Intro

API

Users scope

Fields scope

Farms scope

PUT operation

Parameters:

Response:

PATCH operation

Parameters:

Response:

GET operation

Parameters:

Response:

DELETE operation

Parameters:

Response:

File Storage

User scope

Field scope

Farm scope

GET operation

Body

Response:

Response without resource level:

PUT operation

Body

Response

Information to be considered

Possible errors

PATCH operation

Body

Response

Possible errors

DELETE operation

Body

Response

Possible errors

Share data between extensions

What means sharing data in and between extensions?

Public Values

User

Parameters:

Response example:

Field

Parameters:

Response example:

Farm

Parameters:

Response example:

Public Files

Farm

Parameters:

Response example:

Field

Parameters:

Response example: