File system operations – BEE support

We have a shiny, new BEE Plugin technical docs site.
You can find a new version of this page here.

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

File specific meta

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

Directory specific meta

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

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
}

Getting file metadata

Request

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

Response

 {
  "status": "success",
  "data": {
    "meta": {
      "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": {}
    }
  }
}

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 BEE's resource APIs, which are in charge of enforcing the maximum file size (5-10 Mb) and the maximum image size.
uploads from stage will be POSTed to "/editor_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
}

[ ! ] WARNING: 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.

Next: Status codes | Sample code

Comments

dprakash612 December 15, 2015 09:30

how to use fsp api in my index.html file or .js file.

Comment actions Permalink
M SALAMAT March 17, 2017 15:46

Hello, can I change the request url format like sending the image's name in the request's parameters instead of using her url.

Thanks,

Comment actions Permalink
M SALAMAT May 29, 2017 13:20

Hello,
Is it possible to edit Images inserted with the built-in image editor ?

Comment actions Permalink
David, Liu August 28, 2017 07:04

Hi support,

I have created an FSP, but when I integrate with beefree, I found Some errors during get list items in FSP. How to get the detail error?

Comment actions Permalink
Guillermo Padilla September 04, 2017 15:43

Hi David, could you please open a support ticket including an access to the FSP or a get list response thrown by your API?

Comment actions Permalink