-
Notifications
You must be signed in to change notification settings - Fork 251
API
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, only PHP connector is the only actual connector currently. All API methods implement JSON API standards, follow http://jsonapi.org/ for details.
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.
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:
(string) "id" - File/folder path relative to the user storage folder, which is "userfiles" by default.
(string) "type" - Type of the object to return. There are three types at the moment: ("file", "folder", "summary").
(object) "attributes" - Represents list of attributes specific to the particular response object "type".
Most common "attributes":
(string) "name" - Object's name without path.
(string) "extension" - Object's extension (file specific).
(string) "path" - Object's path relative to the [document root folder](https://ru.godaddy.com/help/what-is-my-websites-root-directory-9123). 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.
(integer) "protected" - Indicates if object has any read/write restrictions. If not, set to 0. Else set to 1.
(string) "created" - Object's creation date, if available. Else empty string.
(string) "modified" - Object's modification date, if available. Else empty string.
(integer) "timestamp" - Object's modification timestamp, if available. Else empty string.
(integer) "height": If an image, the height in pixels. Else 0.
(integer) "width" - If an image, the width in pixels. Else 0.
(string) "size" - Object's size in bytes.
Optional:
(array) "capabilities" - List of allowed actions for the particular object. See `capabilities` option in [[Filemanager configuration file]] for details.
Important: The "id" and "path" parameters of FOLDER object should end with trailing slash.
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."
}
]
}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 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 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 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 | Description |
|---|---|
| id | Contains "/" value. |
| type | Contains "summary" value. |
| attributes.size | Total storage size used (in Bytes). |
| attributes.files | Total number of files. |
| attributes.folders | Total number of folders. |
| attributes.sizeLimit | User storage folder size limit (in Bytes). |
Response example:
{
"data": {
"id": "/",
"type": "summary",
"attributes": {
"size": 1545463665,
"files": 56,
"folders": 14,
"sizeLimit": 2000000000
}
}
}##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.
The download method serves the requested file to the user.
Rich Filemanager performs two requests for the download method:
- Ajax GET request to perform all checks and validation. You have to Implementation of this method should differentiate ajax requests
The download will make two requests, the first one will need only a success response if the file exists, the second will contain the force=true query parameter, and this request is when you actually return the file.
Request example:
{
"mode": "download",
"path": "/images/logo.png"
}Response is a body content of the requested file.