File system operations
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", "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" 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 ( |
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 arodirectory/mydir/cannot be renamed, because it is contained in arodirectory- user cannot "CRUD" resources in
/shared/, because it isro - user can "CRUD" resources in
/mydir/, because it isrw
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
}
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": {}
}
}
}
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
5 comments
how to use fsp api in my index.html file or .js file.
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,
Hello,
Is it possible to edit Images inserted with the built-in image editor ?
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?
Hi David, could you please open a support ticket including an access to the FSP or a get list response thrown by your API?
Please sign in to leave a comment.