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

Type

Description

Sample data

mime-type

string

application/directoryfor 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

Have more questions? Submit a request

Comments

  • Avatar
    dprakash612

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

  • Avatar
    M SALAMAT

    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,

    Edited by M SALAMAT
  • Avatar
    M SALAMAT

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

  • Avatar
    David, Liu

    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?

    Edited by David, Liu
  • Avatar
    Guille Padilla

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