Skip to content

API

Jump to bottom
pavel edited this page Dec 3, 2016 · 55 revisions

Rich Filemanager was designed to make possible a flexible integration with any of server-side programming language via connectors. Each connector should implement methods of this API, described below. You can find some connectors already implemented, but since many changes have been done recently, PHP & ASHX connectors are the only actual connectors currently. All API methods implement JSON API standards, follow http://jsonapi.org/ for details.

Connector Location

The entry point is a script at the following location which can respond to HTTP GET requests by returning an appropriate JSON response object:

[path to FileManager]/connectors/[language extension]/filemanager.[language extension]

Rich Filemanager currently includes connectors for PHP, MVC, JSP, lasso, ASP, ASHX, PL and CFM in the following locations:

PHP: .../connectors/php/filemanager.php
ASP.NET MVC Framework .../connectors/mvc/FilemanagerController.cs
JSP: .../connectors/jsp/filemanager.jsp
lasso: .../connectors/lasso/filemanager.lasso
ASP: .../connectors/asp/filemanager.asp
ASHX: .../connectors/ashx/filemanager.asp
PL: .../connectors/pl/filemanager.pl
CFM: .../connectors/cfm/filemanager.cfm

As long as a script exists at this location to respond to requests, you may split up the code (external libraries, configuration files, etc.) however you see fit.

Response structure

The response for each API method should implement JSON API Document Structure. The following snippet is a top level of the response structure.

{
    "data": "(resource data object OR array of resource objects)"
}

Most of API methods are supposed to provide data for files and/or folders within a response, which are represented as an Resource Object (hereinafter referred to "object"). File and folder objects are slightly different. Look at the following examples.

Example of FILE resource data object:

{
    "id": "/images/logo.png",
    "type": "file",
    "attributes": {
        "name": "logo.png",
        "extension": "png",
        "path": "/rfm/userfiles/images/logo.png",
        "protected": 0,
        "created": "18 Aug 2016 17:09",
        "modified": "20 Aug 2016 19:21",
        "timestamp": 1471713699,
        "height": 1024,
        "width": 768,
        "size": "162314"
    }
}

Example of FOLDER resource data object:

{
    "id": "/images/",
    "type": "folder",
    "attributes": {
        "name": "images",
        "path": "/rfm/userfiles/images/",
        "protected": 0,
        "created": "02 Sep 2016 10:42",
        "modified": "19 Oct 2016 00:24",
        "timestamp": 1476829464
    }
}

The keys are as follows:

Parameter Type Description
id string File/folder path relative to the user storage folder, which is "userfiles" by default.
type string Type of the object to return. There are three types at the moment: ("file", "folder", "summary").
attributes object Represents list of attributes specific to the particular response object "type".
attributes.name string Object's name without path.
attributes.extension string Object's extension (file specific).
attributes.path string Object's path relative to the document root folder. Used for building absolute path to preview images and media files. Note that connector path will be used instead of absolute path if "path" is empty.
attributes.protected integer Indicates if object has any read/write restrictions. If not, set to 0. Else set to 1.
attributes.created string Object's creation date, if available. Else empty string.
attributes.modified string Object's modification date, if available. Else empty string.
attributes.timestamp integer Object's modification timestamp, if available. Else empty string.
attributes.height integer If an image, the height in pixels. Else 0.
attributes.width integer If an image, the width in pixels. Else 0.
attributes.size string Object's size in bytes.
attributes.capabilities array (optional) List of allowed actions for the particular object. See capabilities option in Filemanager configuration file for details.

Important: The id and attributes.path parameters of FOLDER object should end with trailing slash.

Errors handling

Response for errors should implement JSON API Errors http://jsonapi.org/format/#errors The following example would be an appropriate response for common server error:

{
    "errors": [
        {
            "id": "server",
            "code": "500",
            "title": "Server error."
        }
    ]
}

METHODS

All requests from Rich Filemanager include a "mode" parameter that indicates which method should be invoked. Additional parameters will provide other information required to fulfill the request. Your script should include support for the following methods/functions.

##GET initiate

Initial request to connector.

Intended to provide the application with safe server-side data, such as shared configuration etc. Due to security reasons never share any credentials and other secured data. Provide only safe / public data.

Method - GET

Parameter Description
mode Contains "initiate" value.

Endpoint example:

GET [path to connector]?mode=initiate

Request example:

{
  "mode": "initiate"
}

Response object contains the following parameters.

Parameter Type Description
id string Contains "/" value.
type string Contains "initiate" value.
attributes object Represents list of attributes specific to the particular response object "type".
attributes.config object Configuration options to override ones at the client-side. Only the options which are common for both the client-side and the server-side will be overridden.

Response example:

{
    "data": {
        "id": "/",
        "type": "initiate",
        "attributes": {
            "config": {
                "options": {
                    "culture": "ru",
                    "...": "..."
                },
                "security": {
                    "allowFolderDownload": true,
                    "...": "..."
                },
                "upload": {
                    "chunkSize": 10000000,
                    "...": "..."
                }
            }
        }
    }
}

##GET getfile

Provides data for a single file.

Method - GET

Parameter Description
mode Contains "getfile" value.
path File relative path to retrieve data object for it.

Endpoint example:

GET [path to connector]?mode=getfile&path=/images/logo.png

Request example:

{
  "mode": "getfile",
  "path": "/images/logo.png"
}

Response example:

{
    "data": {
        "id": "/images/logo.png",
        "type": "file",
        "attributes": {
            "name": "logo.png",
            "extension": "png",
            "path": "/rfm/userfiles/images/logo.png",
            "protected": 0,
            "created": "18 Aug 2016 17:09",
            "modified": "20 Aug 2016 19:21",
            "timestamp": 1471713699,
            "height": 128,
            "width": 128,
            "size": "15664"
        }
    }
}

##GET getfolder

Provides list of file and folder objects contained in a given directory.

Method - GET

Parameter Description
mode Contains "getfolder" value.
path Folder relative path to read its contents.
type (optional) Can be specified to restrict returned contents, for example to show only image files in a file system tree.

Endpoint example:

GET [path to connector]?mode=getfolder&path=/&type=images

Request example:

{
  "mode": "getfolder",
  "path": "/",
  "type": "images"
}

Response example:

{
    "data": [
        {
            "id": "/logo.png",
            "type": "file",
            "attributes": {
                "name": "logo.png",
                "extension": "png",
                "path": "/rfm/userfiles/logo.png",
                "protected": 0,
                "created": "18 Aug 2016 17:09",
                "modified": "20 Aug 2016 19:21",
                "timestamp": 1471713699,
                "height": 128,
                "width": 128,
                "size": "15664"
            }
        },
        {
            "id": "/audio.mp3",
            "type": "file",
            "attributes": {
                "name": "audio.mp3",
                "extension": "mp3",
                "path": "/rfm/userfiles/audio.mp3",
                "protected": 1,
                "created": "18 Aug 2016 17:09",
                "modified": "20 Aug 2016 19:21",
                "timestamp": 1462441126,
                "height": 0,
                "width": 0,
                "size": "4387104"
            }
        },
        {
            "id": "/images/",
            "type": "folder",
            "attributes": {
                "name": "images",
                "path": "/rfm/userfiles/images/",
                "protected": 0,
                "created": "02 Sep 2016 10:42",
                "modified": "19 Oct 2016 00:24",
                "timestamp": 1476829464
            }
        }
    ]
}

##GET addfolder

Creates a new directory on the server within the given path.

Method - GET

Parameter Description
mode Contains "addfolder" value.
path Folder relative path to create new folder inside.
name Name of a new folder.

Endpoint example:

GET [path to connector]?mode=addfolder&path=/&name=new_folder

Request example:

{
  "mode": "addfolder",
  "path": "/",
  "name": "new_folder"
}

Response example (created folder object):

{
    "data": {
        "id": "/new_folder/",
        "type": "folder",
        "attributes": {
            "name": "new_folder",
            "path": "/rfm/userfiles/new_folder/",
            "protected": 0,
            "created": "23 Oct 2016 17:11",
            "modified": "23 Oct 2016 17:11",
            "timestamp": 1477235480
        }
    }
}

##POST upload

Uploads a new file to the given folder.

Method - POST

Parameter Description
mode Contains "upload" value.
path Folder relative path to upload a new file.

Upload form in the Rich Filemanager passes an uploaded file. The name of the form element is defined by upload.paramName option in Filemanager configuration file ("files[]" by default). The following example assumes that user uploads file named "logo.png"

Endpoint example:

POST [path to connector]

Request example:

{
  "mode": "upload",
  "path": "/images/"
}

Response example (uploaded file object):

{
    "data": {
        "id": "/logo.png",
        "type": "file",
        "attributes": {
            "name": "logo.png",
            "extension": "png",
            "path": "/rfm/userfiles/images/logo.png",
            "protected": 0,
            "created": "23 Oct 2016 17:19",
            "modified": "23 Oct 2016 17:19",
            "timestamp": 1477235998,
            "height": 128,
            "width": 128,
            "size": "15664"
        }
    }
}

##GET rename

Renames an existed file or folder.

Method - GET

Parameter Description
mode Contains "rename" value.
old Relative path of the source file/folder to rename.
new New name for the file/folder after the renaming.

Endpoint example:

GET [path to connector]?mode=rename&old=/images/logo.png&new=icon.png

Request example:

{
  "mode": "rename",
  "old": "/images/logo.png",
  "new": "icon.png"
}

Response example (renamed object):

{
    "data": {
        "id": "/images/icon.png",
        "type": "file",
        "attributes": {
            "name": "icon.png",
            "extension": "png",
            "path": "/rfm/userfiles/images/icon.png",
            "protected": 0,
            "created": "23 Oct 2016 17:19",
            "modified": "23 Oct 2016 17:19",
            "timestamp": 1477235998,
            "height": 128,
            "width": 128,
            "size": "15664"
        }
    }
}

##GET move

Moves file or folder to specified directory.

Method - GET

Parameter Description
mode Contains "move" value.
old Relative path of the source file/folder.
new Relative path of the target folder to move.

MOVE FILE:

Endpoint example:

[path to connector]?mode=move&old=/images/logo.png&new=/images/target/

Request example:

{
  "mode": "move",
  "old": "/images/logo.png",
  "new": "/images/target/"
}

Response example (moved object):

{
    "data": {
        "id": "/images/target/logo.png",
        "type": "file",
        "attributes": {
            "name": "logo.png",
            "extension": "png",
            "path": "/rfm/userfiles/images/target/logo.png",
            "protected": 0,
            "created": "29 Feb 2016 11:11",
            "modified": "29 Feb 2016 11:11",
            "timestamp": 1456740663,
            "height": 128,
            "width": 128,
            "size": "15664"
        }
    }
}

MOVE FOLDER - no filename in "old" request parameter:

Endpoint example:

[path to connector]?mode=move&old=/images/&new=/shared/

Request example:

{
  "mode": "move",
  "old": "/images/",
  "new": "/shared/"
}

Response example (moved object):

{
    "data": {
        "id": "/shared/",
        "type": "folder",
        "attributes": {
            "name": "shared",
            "path": "/rfm/userfiles/shared/",
            "protected": 0,
            "created": "23 Oct 2016 18:46",
            "modified": "23 Oct 2016 18:46",
            "timestamp": 1477241218
        }
    }
}

##POST replace

Overwrites a specific file with a new uploaded one. The new file should have the same extension the original has.

Method - POST

Parameter Description
mode Contains "replace" value.
path Relative path of the source file to replace.

Endpoint example:

POST [path to connector]

Request example:

{
  "mode": "replace",
  "path": "/file_to_replace.txt"
}

Response example (replaced file):

{
    "data": {
        "id": "/file_to_replace.txt",
        "type": "file",
        "attributes": {
            "name": "file_to_replace.txt",
            "extension": "txt",
            "path": "/rfm/userfiles/file_to_replace.txt",
            "protected": 0,
            "created": "23 Oct 2016 21:27",
            "modified": "23 Oct 2016 21:27",
            "timestamp": 1477250830,
            "height": 0,
            "width": 0,
            "size": "34363"
        }
    }
}

##GET editfile

Edit a specific file contents online (extensions are specified in configuration file).

Note the "content" attribute in the response, which contains requested file contents. All special characters in the file contents should be converted to HTML entities.

Method - GET

Parameter Description
mode Contains "editfile" value.
path Relative path to the editable file.

Endpoint example:

GET [path to connector]?mode=editfile&path=/editable.txt

Request example:

{
  "mode": "editfile",
  "path": "/editable.txt"
}

Response example (file to edit):

{
    "data": {
        "id": "/editable.txt",
        "type": "file",
        "attributes": {
            "name": "/editable.txt",
            "extension": "txt",
            "path": "/rfm/userfiles/editable.txt",
            "protected": 0,
            "created": "23 Oct 2016 21:37",
            "modified": "23 Oct 2016 21:52",
            "timestamp": 1477252324,
            "height": 0,
            "width": 0,
            "size": "56",
            "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
        }
    }
}

##POST savefile

Overwrites the content of the specific file to the "content" request parameter value.

Method - POST

Parameter Description
mode Contains "savefile" value.
path Relative path to the editable file to overwrite its contents.
content Text string initially obtained by editfile method and then edited via editor.

Endpoint example:

POST [path to connector]

Request example:

{
  "mode": "savefile",
  "path": "/editable.txt",
  "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. EDITED."
}

Response example (overwritten file):

{
    "data": {
        "id": "/editable.txt",
        "type": "file",
        "attributes": {
            "name": "/editable.txt",
            "extension": "txt",
            "path": "/rfm/userfiles/editable.txt",
            "protected": 0,
            "created": "23 Oct 2016 21:37",
            "modified": "23 Oct 2016 22:10",
            "timestamp": 1477253443,
            "height": 0,
            "width": 0,
            "size": "64"
        }
    }
}

##GET delete

Deletes an existed file or folder.

Method - GET

Parameter Description
mode Contains "savefile" value.
path Relative path to the file or folder to delete.

Endpoint example:

GET [path to connector]?mode=delete&path=/images/logo.png

Request example:

{
  "mode": "delete",
  "path": "/images/logo.png"
}

Response example:

{
    "data": {
        "id": "/images/logo.png",
        "type": "file",
        "attributes": {
            "name": "logo.png",
            "extension": "png",
            "path": "/rfm/userfiles/images/logo.png",
            "protected": 0,
            "created": "29 Feb 2016 11:11",
            "modified": "29 Feb 2016 11:11",
            "timestamp": 1456740663,
            "height": 128,
            "width": 128,
            "size": "15664"
        }
    }
}

##GET download

Downloads requested file or folder.

The download process consists of 2 requests:

  1. Ajax GET request. Perform all checks and validation. Should return file/folder object in the response data to proceed.
  2. Regular GET request. Response headers should be properly configured to output contents to the browser and start download.

Thus the implementation of download method should differentiate requests by type (ajax/regular) and act accordingly.

Method - GET

Parameter Description
mode Contains "download" value.
path Relative path to the file or folder.

Endpoint example:

GET [path to connector]?mode=download&path=/media/audio.mp3

Request example:

{
  "mode": "download",
  "path": "/media/audio.mp3"
}

Response №1 example:

{
    "data": {
        "id": "/media/audio.mp3",
        "type": "file",
        "attributes": {
            "name": "audio.mp3",
            "extension": "mp3",
            "path": "/rfm/userfiles/media/audio.mp3",
            "protected": 0,
            "created": "05 May 2016 11:16",
            "modified": "05 May 2016 11:16",
            "timestamp": 1462439783,
            "height": 0,
            "width": 0,
            "size": "9385587"
        }
    }
}

Response №2 is a body content of the requested file.

##GET getimage

Outputs the content of image file to browser.

Method - GET

Parameter Description
mode Contains "getimage" value.
path Relative path to the image file.
thumbnail (optional) If specified then server should return contents of image thumbnail, not the original image.

Endpoint example:

GET [path to connector]?mode=getimage&path=/images/logo.png&thumbnail=true

Request example:

{
  "mode": "getimage",
  "path": "/images/logo.png",
  "thumbnail": "true"
}

Response is a body content of the requested image.

##GET readfile

Outputs the content of requested file to browser. Intended to read file requested via connector path (not absolute path), for files located outside document root folder or hosted on remote server.

Method - GET

Parameter Description
mode Contains "readfile" value.
path Relative path to the file.

Endpoint example:

GET [path to connector]?mode=readfile&path=/manual.pdf

Request example:

{
  "mode": "readfile",
  "path": "/manual.pdf"
}

Response is a body content of the requested file.

##GET summarize

Display user storage folder summarize info.

Method - GET

Parameter Description
mode Contains "summarize" value.

Endpoint example:

GET [path to connector]?mode=summarize

Request example:

{
  "mode": "summarize"
}

Response object contains the following parameters.

Parameter Type Description
id string Contains "/" value.
type string Contains "summary" value.
attributes object Represents list of attributes specific to the particular response object "type".
attributes.size integer Total storage size used (in Bytes).
attributes.files integer Total number of files.
attributes.folders integer Total number of folders.
attributes.sizeLimit integer User storage folder size limit (in Bytes).

Response example:

{
    "data": {
        "id": "/",
        "type": "summary",
        "attributes": {
            "size": 1545463665,
            "files": 56,
            "folders": 14,
            "sizeLimit": 2000000000
        }
    }
}
Clone this wiki locally