API Storage
Intro
Allow information to be stored on our servers and then retrieved when needed. (See Storage Module).
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