Understanding storage & content delivery options

When you configure a builder application, you have four options for image & file storage:

• Beefree SDK storage: unless you select another option, images will be hosted in Beefree SDK’s own AWS S3 bucket. See below for details about potential fees associated with this option.

• An existing builder application: to connect the selected application’s storage to an already existing application. After selecting this option the two applications will share their storage.

• Your own AWS S3 bucket: instead of using Beefree SDK’s AWS S3 bucket to store & deliver files, you can use your own. See Configuring your own S3 bucket.

• Your own file system: if your application already has a place where images and other assets are stored, you can leverage it. This option is only available on Beefree SDK paid plans. See using your file system.

Custom File System Provider

When working with your own custom file system provider, there are many considerations to keep in mind. Follow the steps outlined in the Move Files in the File Manager documentation to ensure you configure this feature successfully for this storage option.

Images vs. other files

End users can upload images, PDFs, and other documents to the builder. For instance, they can link a button to download a PDF report.

Reference the white label end-user documentation to learn more about the end user experience with the File manager.

If you need more control on what files users should be able to upload, you may activate file manager limitations in the Privacy & Security section of your app’s configuration. In alternative, you may consider connecting the builder to your file system.

About Beefree SDK storage

How images are stored & delivered

By default, images used in emails and pages created with the builder are stored in Beefree SDK’s file storage system. Beefree SDK uses Amazon Web Service’s S3 service for storage, and leverages Amazon’s Content Delivery Network (CloudFront) for fast content delivery.

Storage and delivery fees

• There are no charges for storing images & other documents.

• There are no charges for delivering images & other documents up to a total of 5TB of delivery traffic per 30-day period.

• Above 5TB of data traffic recorded in a 30-day period, you will be billed $0.01 per GB of data transferred.

• Beefree SDK customers that exceed 50 GB of image data traffic on the Free plan in a given month will be moved to our Essentials plan.

Enabling the Move File Feature for Your File Manager

You can enable the move icon for files within the File manager. This move icon allows your end users to move their files between folders, locations, and so on within the File manger. They can access the move icon directly on the file within the File manager. The move icon is a folder with an arrow pointing right inside it. End users click this icon to initiate the process of relocating the corresponding file to a new destination.

If you are using the Beefree AWS S3 Bucket, take the following steps to enable this feature for your File manager.

Using the Beefree AWS S3 Bucket

If you are using your own AWS S3 bucket, take the following steps to activate the Move File feature:

1. Ensure that your FSP is updated to the latest version.

2. Navigate to the Beefree SDK Developer Console.

3. Locate the Move File configuration toggle.

4. Toggle the feature on.

The Move Feature will be available in your application.

FAQs on Beefree SDK Storage fees

Why do you charge for traffic when using BEE storage?

When you use the Beefree SDK S3 storage, your images are delivered via a Content Delivery Network (AWS Cloudfront), and AWS bills us based on the traffic generated by those assets when you send emails or publish web pages created with Beefree SDK. A large amount of monthly traffic (5TB) is included in your Beefree SDK paid subscription at no charge.

If you exceed the 5TB monthly traffic allotment, we ask you to cover the cost of the service (for a few of our customers that generate a lot of image data traffic, that cost has grown to exceed their Beefree SDK subscription fee). Also, note that this scenario is quite rare: it applies to less than 3% of our customers.

When does the traffic counter reset?

• If you’re on a paid plan, billed monthly, the counter will reset on the same days as your UIDs and CSAPI calls, i.e., on the day your subscription to Beefree SDK is renewed.

• If you’re on a paid plan, billed yearly, the counter will reset on the 1st day of each month.

• If you’re on a free plan, the counter will reset on the 1st day of each month.

You can always see when the current period starts and ends in your application details, in the Statistics widget:

I’m on an annual plan. If I exceed the traffic quota in a month, when will I be billed?

You’ll be billed annually by summing up any paid traffic you may have accumulated during the past 12 months, unless such total were to exceed $1,000. In that case, we will send you an invoice. The same is true for additional user fees (UIDs) and additional API calls.

Do I get notified when I’m about to exceed the quota?

For the moment, only subscriptions on paid plans will be notified by our Customer Success team. If you’re on a free plan, you may check your usage by logging into the Beefree SDK Console, and going into the application details, in the Statistics widget.

I’m using Beefree SDK storage. What can I do to avoid getting charged?

You can switch to using your S3 storage or connect your file storage.

I connected my application’s storage to an already existing one. How will the billing work?

All traffic generated is charged to the shared storage. E.g.: an Email Builder application shares its storage with a Popup and a Page applications. In this case, the Email Builder application will be charged for the traffic generated by Email + Popup + Page.

Are there any restrictions when connecting an application’s storage to an already existing one?

• It’s not possible to link a development app to a production app.

• An app can be linked to another just once.

• The same shared storage can be shared across different applications within the same subscription

Can I connect my dev app storage to a production app?

No, this is not possible. You can either connect production apps included in the same subscription or dev apps included in the same subscription.

Can I get a history of my monthly traffic usage?

Please contact your account manager for this. If you are not sure how to do this, please log into the Beefree SDK Console and submit a support ticket asking for your usage history.

Custom S3 Bucket is a Beefree application configuration feature that allows you to easily connect your own Amazon Web Services S3 bucket to your Beefree application.

By leveraging this feature, you will be able to store and manage your customers’ assets without having to build a new File System Provider, but rather by providing a compliant folder structure and filling out a simple form.

How are images stored?

Our default file system provider uses two first level folders to manage assets:

• Images folder – It defines where the user’s images will be stored.

• Thumbnails folder – Is used by our API to store the thumbnails of the uploaded images.

These folders can be root folders or can be part of a more complex directory structure.

A few notes and recommendations:

• These folders should not be parents/children between themselves.

• Their name is restricted by AWS standard naming restrictions.

• For performance reasons, you should use a dedicated bucket and place these folders in the root.

Shared Assets

As an additional configuration option, you can provide shared files to your users, something that we do in the free version of the Beefree editor at beefree.io. These images are shown to all your customers as read-only assets.

The most common use case is providing sample images for the user’s first experience with the editor. Other use cases include providing application-specific images or documents that must not be deleted by the user.

To use this option you need to set-up two additional folders:

• Shared images folder – This is the folder that your users will browse through the file manager.

• Shared thumbnails folder – While the user images thumbnails are created when the images are uploaded, there is no automatic thumbnail creation for shared images. You must provide your own thumbnails using these settings:

  • 200px as max. width/height (this guarantee a correct preview in the file manager)

  • Name: original_image_name.ext_thumb.png (so the thumbnail for cat.jpg must be cat.jpg_thumb.png)

  • PNG: use only PNG as image format

S3 configuration

This section discusses how you can configure your own custom S3 bucket within the Developer Console, and also provides an example JSON of the Permission policy.

Configure Access keys in the Developer Console

Prior to configuring your custom S3 bucket, ensure you configure Access keys in the Developer Console.

Take the following steps to configure Access keys in the Developer Console:

1. Log in to the Developer Console.

2. Navigate to the application you'd like to configure a custom S3 bucket for.

3. Click the Details button for that application.

4. Navigate to Application configuration and click View more.

   You will be redirected to Storage options.

5. Toggle on Configure your own S3 storage system to enable the option.

6. Complete the required fields.*

7. Click the Test S3 settings button.

*The following image shows an example of the required fields within the Developer Console for configuring your own S3 bucket:

Configure Access keys policy in AWS

The following JSON is of the Permissions policy assigned to the AWS user.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "CustomBucket01",
            "Effect": "Allow",
            "Action": "s3:ListBucket",
            "Resource": "arn:aws:s3:::the-bucket-name"
        },
        {
            "Sid": "CustomBucket02",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::the-bucket-name/content-path/*"
        }
    ]
}

Configure bucket permissions

File URL Generation Based on "Custom URL" Parameter

The URLs for accessing files in your S3 bucket vary depending on whether the "Custom URL" field is set in the Developer Console:

• If "Custom URL" is empty: URLs will follow this format:

  Copy

  https://<bucket-name>.s3.<region>.amazonaws.com/path/to/file.png

• If "Custom URL" is set (e.g., https://my-cdn/): URLs will be generated like this:

  Copy

  <custom-url>/path/to/file.png

Important Configuration Notes

1. Public Access:

   • For the generated URLs to work, the bucket’s permissions should allow public access to the files.

2. Using a CDN as "Custom URL":

   • If you’re using a CDN (e.g., CloudFront) in the "Custom URL" field, you can restrict the bucket's access to only the CDN. In this case, the bucket itself doesn't need to be publicly accessible, as access is controlled through the CDN.

Ensure that bucket permissions are configured appropriately based on the type of URL being generated.

Enabling the Move File Feature for Your File Manager

You can enable the move icon for files within the File manager. This move icon allows your end users to move their files between folders, locations, and so on within the File manger. They can access the move icon directly on the file within the File manager. The move icon is a folder with an arrow pointing right inside it. End users click this icon to initiate the process of relocating the corresponding file to a new destination.

If you are using a Custom AWS S3 Bucket, take the following steps to enable this feature for your File manager.

How to Enable the Move File Feature

Take the following steps to enable the Move icon for your end users:

1. Log in to the Developer Console.

2. Navigate to the application you'd like to activate it for.

3. Click on the Details button.

4. Select the View more option located under Application configuration.

5. Navigate to the Services section.

6. Toggle on the Enable moving files between folders in file manager option.

The Move file option will automatically become available for your end users.

How File Name Conflicts Are Handled

If a file an end user trying to move or copy has the same name as an existing file, the File Manager will show a pop-up asking how to handle the conflict.

The end user will have the following options:

1. Cancel: For this option, nothing will happen, and the operation will be stopped.

2. Keep Both: This option lets them keep both files. The new file will be saved with a slightly different name, adding a number at the end. For example, if the original file is called "pizza.jpg," the new one will be named "pizza_1.jpg."

3. Replace: Selecting this will replace the old file with the new one, meaning the existing file will be overwritten.

These options help them decide what to do when file names clash, ensuring they have control over how their files are managed.

Using a Custom AWS S3 Bucket

To implement the new Move File feature in your application, follow these steps to change your file path from the old format to the new format. This change is important because it allows the host application to enable the Move File feature within the File Manager without breaking old URLs. Here's how to make the transition:

1. Understand the Changes: The file paths will change from /your-path/UID/user-path/filename.jpg to /your-path/new-internal-id/random-path/filename.jpg. This new structure decouples the logical path you see in the File Manager from the physical path in the storage, supporting the "move file" feature. For example, you can move the file in the File Manager, and the URL will remain the same.

2. Activate Move Feature: Once you are onboarded, activate the Move Feature inside your SDK Console to utilize the new file paths. Follow the steps outlined in the previous section to complete this process.

Why This Change is Important

• Decoupling Logical and Physical Paths: The new path structure separates the logical path (what you see in the File Manager) from the physical path (where the file is stored). This allows for more flexibility and new opportunities for future features.

• Enable the Move File Feature: By adopting the new path structure, you can use the Move File feature in the File Manager, which allows you to move files without changing their URLs.

Impact on Existing Data

• Existing Paths: Existing paths are not affected. The task done was to collect paths in the new database and keep files where they are.

• Newly Uploaded Files: New uploaded files will be stored using the new path structure.

About the New Path

• Logical and Physical Path Separation: The new path structure decouples the logical path you see in the File Manager from the physical path in the storage. This supports the "move file" feature, allowing you to move files in the File Manager without changing their URLs.

• Changes: The key difference between the two paths is that the new path uses a random part to enhance security and reduce predictability, making it harder for unauthorized users to guess the URLs of stored files.

By following these steps, you can ensure a smooth transition to the new file paths and take full advantage of the Move File feature in your application.

Filling out the form to connect your AWS S3 bucket

Once you have set up a compliant folder structure, you can use the form in the Beefree SDK Console to connect your application. It’s one of the available server-side configurations for your Beefree application (Application details > Open configuration > Storage options).

This is a description of the form fields and what information you will need to provide in each of them:

Note: If you change the custom URL, the new URL is immediately used for all images.

Example using single folders in the bucket root:

Example using single nested folders:

Testing your settings

The button will become active once all required fields have been correctly filled out. It allows you to test your settings before saving the updated configuration. We recommend that you do so before saving any changes.

Preparing thumbnails

If you’ve just linked your custom bucket, you may find that you need to create your own thumbnails. Thankfully, this is an easy process.

For starters, the thumbnails in the File Manager are PNG files that are resized to 200×200 px.

Here is an example of thumbnail generation with image magick:

# convert one file
convert image1.jpg -resize 200x200 image1.jpg_thumb.png

# resize many files (WARNING this command overwrite files)
mogrify -resize 200x200  myimages/*jpg

# convert many files
mogrify -format png      myimages/*jpg

As a quick example, we’ll be using this custom bucket configuration:

• bucket_name : my-custom-bucket

• path_images : /path/to/images/

• path_thumbnails : /path/to/thumbnails/

…And starting the editor with this UID:

• uid : my-uid

When uploading image1.jpg in root dir, this key will be created in the custom bucket: s3://my-custom-bucket/path/to/images/my-uid/image1.jpg. Following that, a thumbnail will be generated with name image1.jpg_thumb.png with key: s3://my-custom-bucket/path/to/thumbnails/my-uid/image1.jpg_thumb.png.

And one more example:

When uploading image2.jpg in mydir inside the root dir, this key is created in the custom bucket: s3://my-custom-bucket/path/to/images/my-uid/mydir/image2.jpg. Similarly to above, a thumbnail will be generated with name image2.jpg_thumb.png with key: s3://my-custom-bucket/path/to/thumbnails/my-uid/mydir/image2.jpg_thumb.png.

Moving from the default S3 bucket

If your Beefree application is currently using the default S3 bucket, you wish to switch to your own bucket, and you have files that you want to transfer between the two, please please log into the Beefree SDK Console and submit a support ticket.

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 a Beefree SDK application to perform actions with files outside of the Beefree SDK system, connecting your file system to the Beefree SDK 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

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 the event of a successful response, the API returns a “success” status code (ex. 200 OK) and a JSON object such as the following:

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

In the event an unexpected error occurred during request processing (i.e. missing mandatory request data), the API returns an “error” status code and a JSON object such as the following:

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

In the event a request fails, the API returns the error codes described in the Error codes section.

Authentication

Authentication is managed using Basic Authentication type. The Beefree SDK 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

Ensure you save the username, password, and base URL in the Configuration section of the Beefree SDK Console.

Move Files in the File Manager

You can enable the move icon for files within the File manager. This move icon allows your end users to move their files between folders, locations, and so on within the File manger. They can access the move icon directly on the file within the File manager. The move icon is a folder with an arrow pointing right inside it. End users click this icon to initiate the process of relocating the corresponding file to a new destination.

Complete the following tasks to enable the move files feature for your custom FSP:

• Add a can-move field in the extra object in the listing directory content response. Reference the Listing Directory Content section for steps on how to complete this.

• Modify the listing response to limit its content when the request includes the x-bee-fsp-flags: move header. Reference the Listing for Move Dialog section for steps on how to complete this.

• Implement a PATCH method for file URLs with conflict_strategy management. Reference the Implement PATCH Method section for steps on how to complete this.

File System operations

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

Metadata

In this section, we define the following types of metadata:

• Common meta

• File-specific meta

• Directory-specific meta

Common Meta

The following table lists the fields, descriptions, types and examples for the FSP API response common meta.

File-specific Meta

The following table lists the fields, descriptions, notes and examples for the FSP API response file-specific meta.

Directory specific Meta

The following table lists the fields, descriptions, notes and examples for the FSP API response directory-specific meta.

Listing Directories

Description: Use this to list the directories within the File manager.

Request

The following code shows an example request for listing directories.

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

Response

The following code shows an example response for listing directories.

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

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

Description: This response tells the user interface (UI) whether or not to show the move icon for files within the File manager.

Display the Move Icon

The can-move property controls whether or not the move button is visible within the user interface (UI).

Take the following steps to display the move icon for file within the File manager:

1. In the response of the listing endpoint, add a new field named can-move within the extra object for each file item.

2. The can-move field has a boolean value indicating whether the file can be moved. You can set this value to true or false.

Request

The following code shows an example request for listing directory content.

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

Response

The following code snippet shows an example of the can-move property set to true.

{
    "name": "image1.jpg",
    "path": "/image1.jpg",
    "last-modified": 1703065836532,
    "permissions": "rw",
    "mime-type": "image/jpeg",
    "size": 184149,
    "public-url": "https://myfsp.com/path/to/image1.jpg",
    "thumbnail": "https://myfsp.com/path/to/image1.jpg_thumb.png",
    "extra": {
        "can-move": true
    }
}

Response Metadata

The following table shows the response metadata and its corresponding type and description.

Listing for Move Dialog

Description: When the move button is pressed, the "move dialog" appears and the usual listing URL is called.

The following image shows an example of the move dialog. This dialog appears after the end user clicks on the move icon for a file. In the image, you can see that the move dialog includes a list of directories for the end user to select from in order to relocate the file.

The following code shows an example of the GET request that occurs when the move icon is pressed within the File manager and the "move dialog" appears. This GET request includes the x-bee-fsp-flags: move header, which is responsible for this behavior.

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

The move dialog only shows folders. The GET request will return the full response, including the folders and the files. However, the response will only show items with "mime-type": "application/directory" . The File System Provider recognizes this call by the x-bee-fsp-flags: move header.

For the move dialog to work effectively, it is important that you limit the size of the response. Ensure that the response to this request only contains folders and not any files.

Create a new directory

Description: Use this when creating a new directory within the File manager.

Request

The following code shows an example request for creating a new directory.

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

Response

The following code shows an example response for creating a new directory.

{
    "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": {}, // if null, please use empty object
        }
    }
}

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

Description: You can only delete empty directories. Use this to delete a directory when it is empty.

Request

The following code shows an example request for deleting a directory.

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

Response

The following code shows an example response for deleting a directory.

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

Uploading a file

Description: Use this method when uploading a file to the File manager.

Request

The following code shows an example request for uploading a file.

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",
  "conflict_strategy": "keep"
}

Response

The following code shows an example response for uploading a file.

{
    "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": {}, // if null, please use empty object
        }
    }
}

Managing a File Name Conflict

Handling Upload Conflicts

If an upload has a name conflict with an existing file in the target folder, the FSP must decide how to manage this conflict:

1. Return an Error: Notify the user about the conflict and do not proceed with the upload.

2. Ask the User: Prompt the user for instructions on how to handle the conflict.

3. Overwrite File: Replace the existing file with the new upload.

4. Rename and Complete: Complete the upload using a different name, usually by appending a suffix. Ensure the metadata is consistent with the newly created file.

Ask the user what to do: The FSP can prompt the user for action only if the conflict_strategy field is set to ask. In this scenario, the FSP must return a 3400 error code, instructing the Builder to display a dialog to the user.

Example response:

{
  "code": 3400,
  "message": "Resource Already Present"
}

When the user clicks the keep or replace buttons, a new upload request is sent to the FSP with the conflict_strategy field set to either keep or replace.

If there's a filename conflict, the FSP should return a 3401 error code. This instructs the Builder to show a toast notification to the user and prompt them with a dialog.

Upload Operation Notes

Uploads are proxied by Beefree’s resource APIs, which enforce the maximum file size configured by the Console. Uploads from various sources are handled as follows:

• Image Editor: POST to /editor_images/{filename}. Filename is a UUID.

• Page Builder Favicons: POST to /favicon_images/{filename}.

• Stage: POST to /editor_images/{filename}.

Deleting a file

Description: Use this to delete a file within the File manager.

Request

The following code shows an example request for deleting a file.

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

Response

The following code shows an example response for deleting a file.

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

Implement PATCH Method

Description: When the move icon is clicked in the File manager, the File System Provider (FSP) will receive this call. It is a PATCH on the URL of the file to move.

The final step in activating the move feature within your File manager is to configure a conflict resolution strategy. This strategy is triggered when there is a file conflict within the File manager.

An example of a conflict is when you are moving a file from one folder to another, but the destination folder has an existing file with the same name as the file being moved to that folder. For example, you want to move a pizza.jpg file to a folder that already contains a pizza.jpg file. In this scenario, there is a conflict because both files cannot have the same name.

The PATCH Method enables you set a conflict_strategy that resolves scenarios like these when they occur.

The following code shows an example of this method.

PATCH /mydir/file-to-move.jpg
Authorization: Basic 5AMPL3
X-BEE-ClientId: BeeFree
X-BEE-Uid: 1111-2222-333-444
Content-Type: application/json

{
 "new_path": "/my/other/dir/",
 "conflict_strategy": ""
}

Move Response in Case of Success

The following response is the same as the upload method. This is the response you will see in the event that a file was successfully moved to a new location.

{
 "status": "success",
 "data": {
 "meta": {
 ...
 }
 }
}

Move Response in Case of Name Conflict

This is the response you will see in the event that a file was not successfully moved to a new location, and an error occurred.

{
 "code": 3400,
 "message": "Resource Already Present"
}

In the event a name conflict occurs, the File manager displays a dialog to the user. You have three options to select from to resolve this conflict using the conflict_strategy which is passed to the FSP.

These three conflict resolution options are the following:

• cancel ( "conflict_strategy": "" ): nothing happens

• keep both ( "conflict_strategy": "keep" ): move the file, in order to keep both files our implementation appends a suffix to the new one. For example, the pizza.jpg file will become pizza_1.jpg ( _2 , _3 , ...)

• replace ( "conflict_strategy": "replace" ): move the file, it overwrites the old file with the new one

Status codes and 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 rethumb by Rapid 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).