File Stores

ClearBlade’s File Stores enable the platform and code services to read and write arbitrary files.

Currently, the following file store types are supported:

Network: Files are sent over the network to the file hosting server.
S3: Files are stored as objects in a S3 bucket.
GCP Bucket: Files are stored as objects in a GCP bucket.
SFTP: Files are stored on a SFTP server.

File Store Setup

To create a file store, make a POST request to the create filestore endpoint. Then, the REST API or ClearbladeAsync JavaScript library may be used to do operations on the file store.

API:

Create File Store

URI: /api/v/1/filestore/{systemKey}

Method: POST

Description: Creates a new file store.

Body

JSON

{
    "name": "<string>",
    "storage_type": "<string>",
    "storage_config": {...},
    "read_auth_method": "<string>",
    "write_auth_method": "<string>"
}

The possible values for each key are as follows:

storage_type
- s3: S3 bucket
- gcp_bucket: GCP cloud bucket
- network: Send over network to file hosting server
- sftp: SFTP server
storage_config
- The expected value depends on the storage_type. See the storage configs section for more information.
read_auth_method / write_auth_method
- clearblade_auth: Token is fetched from the Clearblade-Devtoken, Clearblade-Usertoken, or Clearblade-Devicetokenheader.
- http_basic_auth: Token is fetched from Authorization header
- payload_auth: Token is fetched from the token key of the request body or the token query parameter.
- mtls_auth: Clients can only authenticate with mTLS
- no_auth: No authentication is required. All actions are done with the Anonymous role.

Note: Multiple auth methods can be specified by using a comma separated list
(I.e. clearblade_auth,mtls_auth)

Get File Stores

URI: /api/v/1/filestore/{systemKey}?decrypt={boolean}

Method: GET

Description: Gets all file stores for the system. If the decrypt param is set to true, the storage_config is present in the response for all file stores. Only developers may call this endpoint with decrypt=true.

Delete File Store

URI: /api/v/1/filestore/{systemKey}?name=<filestore_name>

Method: DELETE

Description: Deletes a filestore.

Get File Store

URI: /api/v/1/filestore/{systemKey}/{filestore}?decrypt={boolean}

Method: GET

Description: Gets a file store. If the decrypt param is set to true, the storage_config is present in the response. Only developers may call this endpoint with decrypt=true.

Update File Store

URI: /api/v/1/filestore/{systemKey}/{filestore}

Method: PUT

Description: Updates an existing file store.

Body: Same format as the create file store endpoint.

Read File

URI: /api/v/1/filestore/{systemKey}/{filestore}/file/{path}...

Method: GET

Description: Returns the contents of the file stored at the given path. Requests are authenticated according to the file store’s read_auth_method.

Write File

URI: /api/v/1/filestore/{systemKey}/{filestore}/file/{path}...

Method: PUT

Description: Creates or truncates the file at the given path with the content in the body.

Body: The bytes to write to the file. Requests are authenticated according to the file store’s write_auth_method.

Delete File

URI: /api/v/1/filestore/{systemKey}/{filestore}/file/{path}...

Method: DELETE

Description: Deletes the file at the given path. Requests are authenticated according to the file store’s write_auth_method.

Copy File

URI: /api/v/1/filestore/{systemKey}/{filestore}/copy/{source}...?destination={path}

Method: PUT

Description: Copies a file from the source path to the destination path. Requests are authenticated according to the file store’s write_auth_method.

Move File

URI: /api/v/1/filestore/{systemKey}/{filestore}/move/{source}...?destination={path}

Method: PUT

Description: Moves a file from the source path to the destination path. Requests are authenticated according to the file store’s write_auth_method.

List Files

URI: /api/v/1/filestore/{systemKey}/{filestore}/list/{path}...

Method: GET

Description: Returns a list of child directories and files of the given path. The response list may be broken up into multiple pages. Requests are authenticated according to the file store’s read_auth_method. The following URL parameters can be specified:

limit: The maximum number of items to return per page. Defaults to 100.
depth: The maximum depth of files/directories to return relative to the given path. Defaults to 1. Set -1 for no limit.
continuation_token: The continuation token returned in a previous response from this endpoint.

Storage Configurations

Network

The network store does not take any configuration. It should be omitted or set to null in the file store configuration.

S3

The s3 storage_config should be in the following format:

JSON

{
    "bucket_name": "Your S3 bucket name",
    "region": "The AWS region of your credentials",
    "access_key": "Your AWS access key",
    "secret": "Your AWS secret key"
}

GCP

The gcp storage_config should be in the following format:

JSON

{
    "bucket_name": "Your GCP bucket name",
    "credentials": { ... }
}

Where the value of ”credentials” is your JSON GCP service account credentials.

SFTP

The sftp storage_config should be in the following format:

CODE

{
    "host": "Your SFTP server address",
    "port": "Your SFTP server port",
    "username": "Your SFTP server username",
    "password": "Optional. Your SFTP server password",
    "private_key": "Optional. Your SFTP user private key",
    "insecure_host_verification": "Optional (Default false). Skip host versification",
    "host_key": "Optional. Your SFTP server host key",
    "connection_timeout_seconds": "Optional. Max connection timeout. Must be >= 30 and <= 300"
}