API

RichFilemanager 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. The actual connectors are: PHP, Java, ASHX, ASP & Python 3 Flask. 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 and POST requests by returning an appropriate JSON response object:

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

RichFilemanager currently includes entry scripts for PHP, MVC, ASP, ASHX and Node.js connectors in the following locations:

PHP: .../connectors/php/filemanager.php
ASHX: .../connectors/ashx/filemanager.ashx
Node.js: .../connectors/nodejs/filemanager.js
ASP.NET MVC: .../connectors/asp/FileManagerController.cs

Python 3 Flask connector has no entry script, see details.

JAVA connector suggests to use JitPack.

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",
        "path": "/rfm/userfiles/images/logo.png",
        "readable": 1,
        "writable": 1,
        "created": 1471713699,
        "modified": 1471713699,
        "height": 1024,
        "width": 768,
        "size": 162314
    }
}

Example of FOLDER resource data object:

{
    "id": "/images/",
    "type": "folder",
    "attributes": {
        "name": "images",
        "path": "/rfm/userfiles/images/",
        "readable": 1,
        "writable": 1,
        "created": 1476829464,
        "modified": 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.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.readable	integer	Indicates if object has read permissions. If not, set to 0. Else set to 1.
attributes.writable	integer	Indicates if object has write permissions. If not, set to 0. Else set to 1.
attributes.created	integer	Object's creation Unix Timestamp, if available (seconds). Else null.
attributes.modified	integer	Object's modification Unix Timestamp, if available (seconds). Else null.
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	integer	Object's size in bytes.
attributes.capabilities	array	(optional) List of allowed actions for the particular object. See `capabilities` option in Configuration options 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": "DIRECTORY_ALREADY_EXISTS",
            "meta": {
                "arguments": [
                    "/path/to/directory"
                ]
            }
        }
    ]
}

When fire an error you have to add the following HTTP headers to the response (PHP example):

    header('Content-Type: application/json');
    header('HTTP/1.1 500 Internal Server Error');

METHODS

All requests from RichFilemanager 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 affect the client-side.

Response example:

{
    "data": {
        "id": "/",
        "type": "initiate",
        "attributes": {
            "config": {
                "security": {
                    "readOnly": true,
                    "extensions": {
                        "policy": "ALLOW_LIST",
                        "ignoreCase": true,
                        "restrictions": [
                            "jpg",
                            "jpe",
                            "jpeg",
                            "gif",
                            "png"
                        ]
                    }
                },
                "upload": {
                    "fileSizeLimit": 16000000
                }
            }
        }
    }
}

GET getinfo

Provides data for a single file or folder.

Method - GET

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

Endpoint example:

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

Request example:

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

Response example:

{
    "data": {
        "id": "/images/logo.png",
        "type": "file",
        "attributes": {
            "name": "logo.png",
            "path": "/rfm/userfiles/images/logo.png",
            "readable": 1,
            "writable": 1,
            "created": 1471713699,
            "modified": 1471713699,
            "height": 128,
            "width": 128,
            "size": 15664
        }
    }
}

GET readfolder

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

Method - GET

Parameter	Description
mode	Contains "readfolder" value.
path	Folder relative path to read its contents.

Endpoint example:

GET [path to connector]?mode=readfolder&path=/

Request example:

{
  "mode": "readfolder",
  "path": "/"
}

Response example:

{
    "data": [
        {
            "id": "/logo.png",
            "type": "file",
            "attributes": {
                "name": "logo.png",
                "path": "/rfm/userfiles/logo.png",
                "readable": 1,
                "writable": 1,
                "created": 1471713699,
                "modified": 1471713699,
                "height": 128,
                "width": 128,
                "size": 15664
            }
        },
        {
            "id": "/audio.mp3",
            "type": "file",
            "attributes": {
                "name": "audio.mp3",
                "path": "/rfm/userfiles/audio.mp3",
                "readable": 0,
                "writable": 0,
                "created": 1462441126,
                "modified": 1462441126,
                "height": 0,
                "width": 0,
                "size": 4387104
            }
        },
        {
            "id": "/images/",
            "type": "folder",
            "attributes": {
                "name": "images",
                "path": "/rfm/userfiles/images/",
                "readable": 1,
                "writable": 1,
                "created": 1476829464,
                "modified": 1476829464
            }
        }
    ]
}

GET seekfolder

Looking for files and folders recursively inside the given path. The comparison should be case insensitive and check if file/folder names start with a given search string.

Method - GET

Parameter	Description
mode	Contains "seekfolder" value.
path	Folder relative path to look for files and folders inside.
string	Search string.

Endpoint example:

GET [path to connector]?mode=seekfolder&path=/&string=

Request example:

{
  "mode": "seekfolder",
  "path": "/",
  "string": "im"
}

According to the example the matching results may be as the following:

/image.png
/IMPROVE.doc
/folder/Impact.txt
/folder/imprint/

Response example:

{
    "data": [
        {
            "id": "/image.png",
            "type": "file",
            "attributes": {
                "name": "image.png",
                "path": "/rfm/userfiles/image.png",
                "readable": 1,
                "writable": 1,
                "created": 1471713699,
                "modified": 1471713699,
                "height": 128,
                "width": 128,
                "size": 15664
            }
        },
        {
            "id": "/IMPROVE.doc",
            "type": "file",
            "attributes": {
                "name": "IMPROVE.doc",
                "path": "/rfm/userfiles/IMPROVE.doc",
                "readable": 1,
                "writable": 1,
                "created": 1462441126,
                "modified": 1462441126,
                "height": 0,
                "width": 0,
                "size": 157032
            }
        },
        {
            "id": "/folder/Impact.txt",
            "type": "file",
            "attributes": {
                "name": "Impact.txt",
                "path": "/rfm/userfiles/folder/Impact.txt",
                "readable": 1,
                "writable": 1,
                "created": 1481320912,
                "modified": 1481320912,
                "height": 0,
                "width": 0,
                "size": 6810
            }
        },
        {
            "id": "/folder/imprint/",
            "type": "folder",
            "attributes": {
                "name": "imprint",
                "path": "/rfm/userfiles/folder/imprint/",
                "readable": 1,
                "writable": 1,
                "created": 1476829464,
                "modified": 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/",
            "readable": 1,
            "writable": 1,
            "created": 1477235480,
            "modified": 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 RichFilemanager passes an uploaded file. The name of the form element is "files[]". 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 (list of uploaded file objects):

{
    "data": [
        {
            "id": "/logo.png",
            "type": "file",
            "attributes": {
                "name": "logo.png",
                "path": "/rfm/userfiles/images/logo.png",
                "readable": 1,
                "writable": 1,
                "created": 1477235998,
                "modified": 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",
            "path": "/rfm/userfiles/images/icon.png",
            "readable": 1,
            "writable": 1,
            "created": 1477235998,
            "modified": 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:

GET [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",
            "path": "/rfm/userfiles/images/target/logo.png",
            "readable": 1,
            "writable": 1,
            "created": 1456740663,
            "modified": 1456740663,
            "height": 128,
            "width": 128,
            "size": 15664
        }
    }
}

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

Endpoint example:

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

Request example:

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

Response example (moved object):

{
    "data": {
        "id": "/shared/images/",
        "type": "folder",
        "attributes": {
            "name": "images",
            "path": "/rfm/userfiles/shared/images/",
            "readable": 1,
            "writable": 1,
            "created": 1477241218,
            "modified": 1477241218
        }
    }
}

GET copy

Copies file or folder to specified directory.

Method - GET

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

COPY FILE:

Endpoint example:

GET [path to connector]?mode=copy&source=/images/logo.png&target=/images/target/

Request example:

{
  "mode": "copy",
  "source": "/images/logo.png",
  "target": "/images/target/"
}

Response example (copied object):

@see Response example of MOVE FILE above.

COPY FOLDER - no filename in "target" request parameter:

Endpoint example:

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

Request example:

{
  "mode": "copy",
  "source": "/images/",
  "target": "/shared/"
}

Response example (copied object):

@see Response example of MOVE FOLDER above.

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	File content (text string) obtained by readfile 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",
            "path": "/rfm/userfiles/editable.txt",
            "readable": 1,
            "writable": 1,
            "created": 1477253443,
            "modified": 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",
            "path": "/rfm/userfiles/images/logo.png",
            "readable": 1,
            "writable": 1,
            "created": 1456740663,
            "modified": 1456740663,
            "height": 128,
            "width": 128,
            "size": 15664
        }
    }
}

GET download

Downloads requested file or folder.

The download process consists of 2 requests:

Ajax GET request. Perform all checks and validation. Should return file/folder object in the response data to proceed.
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",
            "path": "/rfm/userfiles/media/audio.mp3",
            "readable": 1,
            "writable": 1,
            "created": 1462439783,
            "modified": 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|HEAD readfile

Outputs the content of requested file to browser. Intended to:

display file content in preview mode (if file extension is supported by viewers/editors)
read file requested via connector path (not absolute path), for files located outside document root folder or hosted on remote server.

NOTE: ViewerJS file previewer performs a HEAD request right before performing a GET request. Thus HEAD requests should be allowed.

Method - GET and HEAD

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
        }
    }
}

POST extract

Extract files and folders from zip archive.

Note that only the first-level of extracted files and folders are returned in the response. All nested files and folders should be omitted for correct displaying at the client-side.

Method - POST

Parameter	Description
mode	Contains "extract" value.
source	Relative path of the source archive file.
target	Relative path to the target folder to extract into.

Endpoint example:

POST [path to connector]

Request example:

{
  "mode": "extract",
  "source": "/archive.zip",
  "target": "/extracted/"
}

Response example:

{
    "data": [
        {
            "id": "/extracted/empty/",
            "type": "folder",
            "attributes": {
                "name": "empty",
                "path": "/rfm/userfiles/extracted/empty/",
                "readable": 1,
                "writable": 1,
                "created": 1494151071,
                "modified": 1494151071
            }
        },
        {
            "id": "/extracted/audio.mp3",
            "type": "file",
            "attributes": {
                "name": "audio.mp3",
                "path": "/rfm/userfiles/extracted/audio.mp3",
                "readable": 1,
                "writable": 1,
                "created": 1494151071,
                "modified": 1494151071,
                "height": 0,
                "width": 0,
                "size": 9385587
            }
        }
    ]
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API

Connector Location

Response structure

Errors handling

METHODS

GET initiate

GET getinfo

GET readfolder

GET seekfolder

GET addfolder

POST upload

GET rename

GET move

GET copy

POST savefile

GET delete

GET download

GET getimage

GET|HEAD readfile

GET summarize

POST extract

Clone this wiki locally