Storage
The storage system offers the necessary endpoints to upload, download, list, delete and organize any amount of unstructured data. The services are presented in three sections, namely Files, Folder, and Administration. Notice that the API is designed to be idempotent. Therefore, consecutive calls to the same endpoint with equal parameters will always have the same effect.
Files
These are the available endpoints for file operations, allowing to store and retrieve any kind of data.
POST /storage/file/upload/{folder}
Upload a file to a folder. When the folder variable is missing, it is uploaded to the root directory.
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
folder | Query | String | Destination folder | |
file | Form | ✓ | Multipart file | File |
curl -L -X POST 'https://api.sherpalive.com/v2/storage/file/upload/my-folder' \
-H "Authorization: Bearer XXXX-SHERPA-TOKEN-XXXX" \
-H 'Accept-Language: es-ES' \
-H 'Content-Type: multipart/form-data'
-H 'Time-Zone: Europe/Madrid' \
-F 'file=@/path/to/aFile.txt'
Response
The service will return the file and folder names. It returns a 404 error if the folder does not exist.
Code | Name |
---|---|
200 | OK |
401 | Unauthorized |
404 | Not found |
500 | Internal Server Error |
{
"file": "aFile.txt",
"folder": "my-folder"
}
GET /storage/file/download/{folder}/{file}
Download a file. The file is downloaded from the root directory when no folder is indicated.
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
folder | Query | String | Source folder | |
file | Query | ✓ | String | File |
curl -L -X GET 'https://api.sherpalive.com/v2/storage/file/download/my-folder/aFile.txt' \
-H "Authorization: Bearer XXXX-SHERPA-TOKEN-XXXX" \
-H 'Accept-Language: es-ES' \
-H 'Time-Zone: Europe/Madrid'
Response
The service will return the raw file. It returns a 404 error if the file does not exist.
Code | Name |
---|---|
200 | OK |
401 | Unauthorized |
404 | Not found |
500 | Internal Server Error |
GET /storage/file/exists/{folder}/{file}
Checks if a file with the requested name exists in the target folder. When the folder variable is missing, it will check for existance in the root directory.
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
folder | Query | String | Folder | |
file | Query | ✓ | String | File |
curl -L -X GET 'https://api.sherpalive.com/v2/storage/file/exists/my-folder/aFile.txt' \
-H "Authorization: Bearer XXXX-SHERPA-TOKEN-XXXX" \
-H 'Accept-Language: es-ES' \
-H 'Time-Zone: Europe/Madrid'
Response
The file return true
or false
.
Code | Name |
---|---|
200 | OK |
401 | Unauthorized |
500 | Internal Server Error |
DELETE /storage/file/delete/{folder}/{file}
Delete a file. The file will be deleted from the root directory when the folder variable is missing.
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
folder | Query | String | Folder | |
file | Query | ✓ | String | File |
curl -L -X DELETE 'https://api.sherpalive.com/v2/storage/file/delete/my-folder/aFile.txt' \
-H "Authorization: Bearer XXXX-SHERPA-TOKEN-XXXX" \
-H 'Accept-Language: es-ES' \
-H 'Time-Zone: Europe/Madrid'
Response
The service ensures that the file does not exist. Therefore, the same response is provided whether the file specified in the request was found or not.
Code | Name |
---|---|
204 | No response |
401 | Unauthorized |
500 | Internal Server Error |
DELETE /storage/file/deletes/{folder}
Delete several files. The files will be deleted from the root directory when the folder variable is missing.
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
folder | Query | String | Folder | |
files | Form | ✓ | List of strings | Names of the files to be deleted |
curl -L -X DELETE 'https://api.sherpalive.com/v2/storage/file/delete/my-folder/' \
-H "Authorization: Bearer XXXX-SHERPA-TOKEN-XXXX" \
-H 'Accept-Language: es-ES' \
-H 'Time-Zone: Europe/Madrid' \
-F 'files=a-file.txt,otherFile,another_file.mp3'
Response
The service ensures that the files do not exist. Therefore, the same response is provided whether the files were found or not.
Code | Name |
---|---|
204 | No response |
401 | Unauthorized |
500 | Internal Server Error |
GET /storage/file/list/{folder}?prefix={prefix}&suffix={suffix}&from={from}&to={to}&minSize={minSize}&maxSize={maxSize}
List the files located in the requested folder. If the folder variable is missing, list the files in the root directory. The request allows to filter the results using the following additive criteria: returning only files with names that start with a prefix and/or end with a suffix, files last modified later that a from timestamp and/or earlier than a to timestamp, and files bigger than and/or smaller than the provided minSize and maxSize parameters. All the filtering parameters are optional.
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
folder | Query | String | Folder name | |
prefix | Query | String | Prefix | |
suffix | Query | String | Suffix | |
from | Query | Long | Timestamp in UNIX time milliseconds | |
to | Query | Long | Timestamp in UNIX time milliseconds | |
minSize | Query | Long | Minimum size in bytes | |
maxSize | Query | Long | Maximum size in bytes |
curl -L -X GET 'https://api.sherpalive.com/v2/storage/file/list/my-folder?prefix=API&'\
'suffix=json&from=0&to=5000000000000&minSize=150000&maxSize=1000000' \
-H "Authorization: Bearer XXXX-SHERPA-TOKEN-XXXX" \
-H 'Accept-Language: es-ES' \
-H 'Time-Zone: Europe/Madrid'
Response
The response is a JSON array of objects. For each file, the following information is provided: The file name, the size (in bytes) and the last modification UTC Unix timestamp (the number of milliseconds from the epoch of 1970-01-01T00:00:00Z). The service does not check if the request folder exists; it returns an empty array when the folder is empty or when it does not exist.
Code | Name |
---|---|
200 | OK |
401 | Unauthorized |
500 | Internal Server Error |
[
{
"name": "aFile.txt",
"size": 194426,
"lastModified": 1604911035000
}
]
Folders
These are the available endpoints for folder operations, allowing to create, list or delete folders. The API allows one level of depth, i.e. all created folders will be located in the root directory.
PUT /storage/folder/create/{folder}
Create a folder.
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
folder | Query | ✓ | String | Folder name |
curl -L -X PUT 'https://api.sherpalive.com/v2/storage/folder/my-folder' \
-H "Authorization: Bearer XXXX-SHERPA-TOKEN-XXXX" \
-H 'Accept-Language: es-ES' \
-H 'Time-Zone: Europe/Madrid'
Response
The service ensures that the folder exists. It will not return an error code if the folder already exists.
Code | Name |
---|---|
200 | OK |
401 | Unauthorized |
500 | Internal Server Error |
GET /storage/folder/exists/{folder}
Checks if a folder with the requested name exists.
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
folder | Query | ✓ | String | Folder |
curl -L -X GET 'https://api.sherpalive.com/v2/storage/folder/exists/my-folder' \
-H "Authorization: Bearer XXXX-SHERPA-TOKEN-XXXX" \
-H 'Accept-Language: es-ES' \
-H 'Time-Zone: Europe/Madrid'
Response
The file return true
or false
.
Code | Name |
---|---|
200 | OK |
401 | Unauthorized |
500 | Internal Server Error |
DELETE /storage/folder/delete/{folder}
Delete a folder and all its contents.
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
folder | Query | ✓ | String | Folder |
curl -L -X DELETE 'https://api.sherpalive.com/v2/storage/folder/delete/my-folder' \
-H "Authorization: Bearer XXXX-SHERPA-TOKEN-XXXX" \
-H 'Accept-Language: es-ES' \
-H 'Time-Zone: Europe/Madrid'
Response
The service ensures that the folder does not exist. Therefore, the same response is provided whether the folder specified in the request was found or not.
Code | Name |
---|---|
204 | No response |
401 | Unauthorized |
500 | Internal Server Error |
GET /storage/folder/list
List the folders in the user's workspace.
Parameters
This request does not require any parameters
curl -L -X GET 'https://api.sherpalive.com/v2/storage/file/list' \
-H "Authorization: Bearer XXXX-SHERPA-TOKEN-XXXX" \
-H 'Accept-Language: es-ES' \
-H 'Time-Zone: Europe/Madrid'
Response
The response is an array of folder names, empty if there are not any folders.
Code | Name |
---|---|
200 | OK |
401 | Unauthorized |
500 | Internal Server Error |
["test-folder", "another-folder"]
Administration
These endpoints perform management tasks in the workspace.
GET /storage/total-size
Gets the total size of the used storage space in the workspace. This quantity is calculated by adding the sizes (in bytes) of all the files contained in the client's workspace.
Response
Code | Name |
---|---|
200 | OK |
401 | Unauthorized |
500 | Internal Server Error |
The response is a numeric value, the total amount of storage space (in bytes) used.
DELETE /storage/clear/{token}
Deletes all the files and folders in the user's workspace. When the token variable is not included, this service creates a hash token that has a short expiration date. The token is returned to the user, so he or she may use it in a subsequent call in order to confirm the total erasure of the workspace storage contents.
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
token | Query | String | Confirmation token |
Response
Code | Name |
---|---|
200 | OK |
401 | Unauthorized |
500 | Internal Server Error |
Usage example
curl -L -X GET 'https://api.sherpalive.com/v2/storage/clear' \
-H "Authorization: Bearer XXXX-SHERPA-TOKEN-XXXX" \
-H 'Accept-Language: es-ES' \
-H 'Time-Zone: Europe/Madrid'
The endpoint returns a temporary token:
cb0c4826-d119-42d5-9a4a-373437d66e1d
curl -L -X GET 'https://api.sherpalive.com/v2/storage/clear/cb0c4826-d119-42d5-9a4a-373437d66e1d' \
-H "Authorization: Bearer XXXX-SHERPA-TOKEN-XXXX" \
-H 'Accept-Language: es-ES' \
-H 'Time-Zone: Europe/Madrid'
All the user workspace storage is deleted.