Connect your file storage system

As you may have noticed, when you create a new Beefree application, it comes with a default cloud storage option for files (images or files that the message uses or links to). This approach may fit well for applications that offer content creation for the first time, especially if they don’t need to share these files with other areas of the host application.

If you do want users to be able to access the same image and file directories that they use elsewhere in your application, we have a solution.

We created a way to connect to a custom file system provider, allowing you to use your own file storage, no matter which technology you use. A custom file system provider is an API that will allow the a Beefree application to perform actions with files outside of the Beefree system, connecting your file system to the Beefree File Manager.

It can be built with your preferred technology: just be sure to follow our instructions to ensure successful communication between the two systems.

Once successfully connected, when a user uploads a file or creates a new folder in the Beefree File Manager, this API will perform these actions in your storage, instead of our default cloud storage. Directories permissions, root directory to use, how thumbnails for images are generated, etc.: you decide.

Getting Started: data formats
Authentication
File System operations
Status codes
Error codes
Displaying thumbnails
Sample code

Getting Started: data formats

In order to let your Beefree application consume your FSP (File system provider) API, you will need to provide a Base URL to reach the API.

Base URL: https://myfsp.com/path/to/your/base/endpoint

Note that:

the Base URL must not end with a trailing slash (/)
it must be hosted on the HTTPS protocol

The API uses JSON as the input and output data format: Responses are JSEND standard compliant.

In case of a succesful response, the API returns a “success” status code (ex. 200 OK) and a JSON object like this one:




{
  "status": "success",
  "data": { /* ... */ }
}

In case of an unexpected error occured during request processing (i.e. missing mandatory request data), the API returns an “error” status code and a JSON object like this one:




{"status":"error","message":"something went wrong accessing backend filesystem"}

In case of request failure, the API returns the error codes described in the error messages section.

Authentication

Authentication is managed using Basic Authentication type. The Beefree system’s resource server works as a proxy for FSP (File system provider) and consumes FSP API endpoints adding the following fields to HTTP Request Headers. Please note that the API must use HTTPS to grant secure connections and safe data transfer.

User information is segmented by UID parameter.



Authorization: Basic base64(username:password)
X-BEE-ClientId: ClientId
X-BEE-Uid: uid

Field	Description
Authorization	Authentication used is Basic. A string formatted as username:password and encoded in base64 is passed
X-BEE-ClientId	The ClientId (to identify the integrator)
X-BEE-Uid	The uid (ex. useful to identify the user of an integrator)

The integrator must save…

Username
Password
Base URL

… in the Configuration section of the Beefree SDK Console.

File System operations

This section will show samples of successful requests to FSP (File system provider) API. A response contains meta data about directory and files.

Meta data

We can define:

Common meta
File-specific meta
Directory-specific meta

Common Meta

Field	Description	Type	Example
`mime-type`	application/directory for directories and specific mime-type for files	`string`	“application/directory”, “images/png”, …
`name`	resource name	`string`	“my file.jpg”
`path`	absolute path to resource in FSP	`string`	“/absolute/path/to/my file.jpg”, “/absolute/path/to/my directory/”, …
`last-modified`	UNIX time with (milliseconds) of last modification of this resource	`int`	`1445401740000` (stands for: Wed, 21 Oct 2015 04:29:00 GMT)
`size`	size (in byte) of the resource, this is zero (0) for directories	`int`	`2048`
`permissions`	defines the access grants to the resource, can be `ro` for read-only access or `rw` for read-write access	`string`	`ro` or `rw`
`extra`	generic extra data (for future extensions)	`object`

File specific Meta

Field	Description	Notes	Type
`public-url`	Public url of this file	This field must be url-encoded	`string`
`thumbnail`	Public url of the thumbnail of this file	This field is optional and must be url-encoded	`string`

Directory specific Meta

Field	Description	Notes	Type
`item-count`	number of contained items (directories + files)	This parameter is optional, if you don’t have this data, feel free to pass zero `0`	`string`

Listing Directories

Request



GET /
Authorization: Basic 5AMPL3
X-BEE-ClientId: BeeFree
X-BEE-Uid: 1111-2222-333-444

Response




{"status":"success","data":{"meta":{"mime-type":"application\/directory","name":"root","path":"\/","last-modified":1432982102000,"size":0,"permissions":"ro","item-count":2,"extra":[]},"items":[{"mime-type":"application\/directory","name":"shared","path":"\/shared\/","last-modified":1432984102000,"size":0,"permissions":"ro","item-count":13,"extra":[]},{"mime-type":"application\/directory","name":"mydir","path":"\/mydir\/","last-modified":1432982102000,"size":0,"permissions":"rw","item-count":3,"extra":[]}]}}

Each resource returned by the API has a meta field with metadata. Directory content is returned into items field as array of metadata of contained resources.

Resource access notes

Some notes about resources access management in the previous example:

/shared/ cannot be renamed, because it is contained in a ro directory
/mydir/ cannot be renamed, because it is contained in a ro directory
user cannot “CRUD” resources in /shared/, because it is ro
user can “CRUD” resources in /mydir/, because it is rw

Listing Directory content

Request



GET /mydir/
Authorization: Basic 5AMPL3
X-BEE-ClientId: BeeFree
X-BEE-Uid: 1111-2222-333-444

Response




{"status":"success","data":{"meta":{"mime-type":"application\/directory","name":"mydir","path":"\/mydir\/","last-modified":1432982102000,"size":0,"permissions":"rw","item-count":3,"extra":[]},"items":[{"mime-type":"application\/directory","name":"docs","path":"\/mydir\/docs\/","last-modified":1432984102000,"size":0,"permissions":"rw","item-count":4,"extra":[]},{"mime-type":"image\/png","name":"my pic1.png","path":"\/mydir\/my pic1.png","last-modified":1432982102000,"size":100000,"permissions":"rw","public-url":"https:\/\/resources-bucket.s3.amazonaws.com\/1111-2222-333-444\/my%20pic1.png","thumbnail":"https:\/\/my-thumbnail-service.com\/my%20pic1.png","extra":[]},{"mime-type":"image\/png","name":"my pic2.png","path":"\/mydir\/my pic2.png","last-modified":1432982102000,"size":200000,"permissions":"rw","public-url":"https:\/\/resources-bucket.s3.amazonaws.com\/1111-2222-333-444\/my%20pic2.png","thumbnail":"https:\/\/my-thumbnail-service.com\/my%20pic2.png","extra":[]}]}}

Creating a new directory

Request



POST /mydir/new%20dir/
Authorization: Basic 5AMPL3
X-BEE-ClientId: BeeFree
X-BEE-Uid: 1111-2222-333-444

Response




{"status":"success","data":{"meta":{"mime-type":"application\/directory","name":"new dir","path":"\/mydir\/new dir","last-modified":1432982102000,"size":0,"permissions":"rw","item-count":0,"extra":[]}}}

Create operation notes:

in order for the create directory operation to succeed, the containing directory must exist, and the contained (new) directory must not exist
directory names will match the following regular expression: [ a-zA-Z0-9._- \(\)]+

Deleting a directory

You can only delete empty directories.

Request



DELETE /my%20dir/docs/
Authorization: Basic 5AMPL3
X-BEE-ClientId: BeeFree
X-BEE-Uid: 1111-2222-333-444

Response




{"status":"success","data":null}

Uploading a file

Request



POST /mydir/my%20pic3.png
Authorization: Basic 5AMPL3
X-BEE-ClientId: BeeFree
X-BEE-Uid: 1111-2222-333-444
Content-Type: application/json
 
{
  "source": "http://www.remotehost.com/remotepic.png"
}

Response




{"status":"success","data":{"meta":{"mime-type":"image\/png","name":"my pic3.png","path":"\/mydir\/my pic3.png","last-modified":1432982102000,"size":400000,"permissions":"rw","public-url":"https:\/\/resources-bucket.s3.amazonaws.com\/1111-2222-333-444\/my%20pic3.png","thumbnail":"https:\/\/my-thumbnail-service.com\/my%20pic3.png","extra":[]}}}

Upload operation notes

in order for the upload file operation to succeed, the containing directory must exist
if the uploaded file already exists, it’s in charge of FSP API do decide if:
- silently overwrite old file with the new one;
- create a new file with a different name, in this case returned metadata must be coherent with the new file created;
- return a 403 FORBIDDEN error;
uploads are proxied by Beefree’s resource APIs, which are in charge of enforcing the maximum file size (20 Mb) and the maximum image size.
uploads from stage will be POSTed to “/editor_images/{filename}”
uploads from page builder favicons will be POSTed to “/favicon_images/{filename}”
the name of files uploaded from stage will match the following regular expression: [ a-zA-Z0-9._- \(\)]+

Deleting a file

Request



DELETE /mydir/my%20pic2.png
Authorization: Basic 5AMPL3
X-BEE-ClientId: BeeFree
X-BEE-Uid: 1111-2222-333-444

Response




{"status":"success","data":null}

The trailing slash (/) on the request matters!

The FSP API uses the trailing slash (/) on the resource path to understand if the required resource is a file (no trailing slash) or a directory (with trailing slash).

For example, if the FSP API receives a GET request for /sample.jpg it will return sample.jpg file metadata, whereas if it receives a GET request for /sample.jpg/ it will return a list of the content located in the sample.jpg directory.

Status codes

The FSP (File system provider) API uses standard HTTP status codes to manage success and error responses. Status codes include:

Action	On success	On error	On failure
List directory	`200 OK`	`503 Service unavailable`	`401 Unauthorized` `404 Not Found`
Create directory	`201 Created`	`503 Service unavailable`	`401 Unauthorized` `403 Forbidden` (parent is read-only or non-existent; new dir already exists)
Delete directory	`200 OK`	`503 Service unavailable`	`401 Unauthorized` `403 Forbidden`(if parent is read-only) `404 Not Found`
Get file metadata	`200 OK`	`503 Service unavailable`	`401 Unauthorized` `404 Not Found`
Upload file	`201 Created`	`503 Service unavailable`	`401 Unauthorized` `403 Forbidden`(if parent is read-only or non-existent)
Delete file	`200 OK`	`503 Service unavailable`	`401 Unauthorized` `403 Forbidden`(if parent is read-only) `404 Not Found`

Error codes

In case of errors, the API returns a JSON object structured like this:




{"code":3200,"message":"Resource Not Found","details":"http:\/\/myfsp.com\/docs\/errorcodes\/404"}

To read the full list of possible errors, please refer to this page.

Displaying thumbnails

Thumbnail generation is up to the developer of the file system provider.

In case you don’t want to develop your own thumbnail generation procedure, you can use a service like http://rethumb.com to create a thumbnail URL.

The thumbnail field is optional, so if you don’t want a thumbnail for your file, do not pass the field and the Beefree system will show you a generic icon based on the mime type you passed.

The thumbnail image must be contained in a 200px by 200px virtual square (see pictures below).

Sample code

In the sample code page, you can download an example file system provider API written in Python (Django).