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

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.

{
  "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

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.

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

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.

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

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.

DELETE /storage/file/deletes/{folder}

Delete several files. The files will be deleted from the root directory when the folder variable is missing.

Parameters

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.

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

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.

[
    {
        "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

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.

GET /storage/folder/exists/{folder}
Checks if a folder with the requested name exists.

Parameters

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.

DELETE /storage/folder/delete/{folder}

Delete a folder and all its contents.

Parameters

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.

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.

["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

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

Response

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.