Client Server API 2.0

Client-Server API 2.0

API version: 2.0

General description

Client - JavaScript application which runs in the client's browser.

Connector - application which runs on the server (server-side). Connector executes commands initiated by the client and returns result to the client.

Volume - One of the root folders (can be just one or multiple). Each volume mounted using driver (class) which implements logic of data storage (local filesystem, remote filesystem, database, etc.). If volume is not available for reading, but available for writing, then it will be mounted as "drop box". If volume is neither readable nor writable, then it will not be mounted.

Default volume - First volume available for reading.

The initiator of the connection is always the client, there is no long polling between client and server.
Client and connector work over HTTP(S) protocol and use JSON format for data exchange.
Connector must always return correct header Content-Type: application/json, except for file and upload commands.
Client passes commands to connector using HTTP GET or POST methods.
Connector always expects cmd argument (name of the command) from client, example: http://localhost/connector.php?cmd=open.

Name of commands on the client side doesn't always match with the connector side:

client commands reload, back, forward, home - implemented in connector using open command
client command open calls connector's open command for directory and file command for a file (if URL option is missing in client options)
client command cut, copy, paste - implemented in connector using copy
client commands which change the look of the file manager and display detailed info do not require a request to the connector.

File paths (hashes)

For executing most of the commands, passing files path is required to determine which files/directories to act upon.
Paths are NEVER passed in clear text format. Passing paths in clear text format will lead to unwanted disclosure of information and can stop client side from working at all.
All paths between client and connector are passed in encrypted format called hash.

Old 1.0 API used MD5 for encryption - it made connector more complicated and caused problems with performance, so it's not recommended to use it anymore.

New 2.x PHP connector uses the following algorithm to create hash from file path:

remove root path from file path
encrypt resulting path so it could be later decrypted (not implemented yet, but stub is present)
encode already encrypted path using base64 with replacement +/= -> -_.
remove trailing dots
add prefix - unique volume id (must start with [a-z])
resulting string must be valid HTML id attribute (that is why base64 is used).

Using this algorithm even without encryption, client cannot get real file paths on the server only relative to root paths. This hash algorithm is recommended but you can use your own implementation so long as it matches these 2 rules:

hash must be valid for storage in the id attribute of an HTML tag
hash must be reversible by connector

Errors

In case of a fatal error (unable to give client correct information), the connector must return a JSON response with error key. error value can be of type string or array.

Error messages are passed as keys, which will be translated by the client. List of available keys can be found in /js/i18n/elfinder.en.js starting with err.

Examples:

{"error" : ["errConf", "errJSON"]} // "Invalid backend configuration. PHP JSON module not installed"

{"error" : "Invalid backend configuration"}

{"error" : ["errLocked", "Some_folder"]} // 'Folder "Some_folder" can’t be opened because you don’t have permission to see its contents.'

In case if command not found return:

{"error" : "errUnknownCmd"} // "Unknown command"

If some required parameter is missing:

{"error" : ["errCmdParams", "command_name"]} // "Invalid parameters for command "command_name"."

Any other data sent with error parameter will be ignored on client side.

Information about file/directory

In most cases the connector returns information about files and/or directories. Info about each file/directory is represented as an object with parameters. This is called the object format.

Example:

{
    "name"   : "Images",             // (String) name of file/dir. Required
    "hash"   : "l0_SW1hZ2Vz",        // (String) hash of current file/dir path, first symbol must be letter, symbols before _underline_ - volume id, Required. 
    "phash"  : "l0_Lw",              // (String) hash of parent directory. Required except roots dirs.
    "mime"   : "directory",          // (String) mime type. Required.
    "ts"     : 1334163643,           // (Number) file modification time in unix timestamp. Required.
    "date"   : "30 Jan 2010 14:25",  // (String) last modification time (mime). Depricated but yet supported. Use ts instead.
    "size"   : 12345,                // (Number) file size in bytes
    "dirs"   : 1,                    // (Number) Only for directories. Marks if directory has child directories inside it. 0 (or not set) - no, 1 - yes. Do not need to calculate amount.
    "read"   : 1,                    // (Number) is readable
    "write"  : 1,                    // (Number) is writable
    "locked" : 0,                    // (Number) is file locked. If locked that object cannot be deleted,  renamed or moved
    "tmb"    : 'bac0d45b625f8d4633435ffbd52ca495.png' // (String) Only for images. Thumbnail file name, if file do not have thumbnail yet, but it can be generated than it must have value "1"
    "alias"  : "files/images",       // (String) For symlinks only. Symlink target path.
    "thash"  : "l1_c2NhbnMy",        // (String) For symlinks only. Symlink target hash.
    "dim"    : "640x480"             // (String) For images - file dimensions. Optionally.
    "volumeid" : "l1_"               // (String) Volume id. For root dir only.
}

File manager initialization

Client sends request with open command, init parameter.

Example: http://localhost/connector.php?cmd=open&init=1

Command list

open - open directory and initializes data when no directory is defined (first iteration)
file - output file contents to the browser (download/preview)
tree - return child directories
parents - return parent directories and its subdirectory childs
ls - list files in directory
tmb - create thumbnails for selected files
size - return size for selected files or total folder(s) size
dim - return image dimensions
mkdir - create directory
mkfile - create text file
rm - delete files/directories
rename - rename file
duplicate - create copy of file
paste - copy or move files
upload - upload file
get - output plain/text file contents (preview)
put - save text file content
archive - create archive
extract - extract archive
search - search for files
info - return info for files. (used by client "places" ui)
resize - modify image file (resize/crop/rotate)
netmount - mount network volume during user session. Only ftp now supported.

Command description

open

Returns information about requested directory and its content, optionally can return directory tree as files, and options for the current volume.

Arguments:

init : (true|false|not set), optional parameter. If true indicates that this request is an initialization request and its response must include the value api (number or string >= 2) and should include the options object, but will still work without it. Also, this option affects the processing of parameter target hash value. If init == true and target is not set or that directory doesn't exist, then the data connector must return the root directory of the default volume. Otherwise it must return error "File not found".
target : (string) Hash of directory to open. Required if init == false or init is not set
tree : (true|false), optional. If true, response must contain subfolders trees of roots directories.

Response:

api : (Number) The version number of the protocol, must be >= 2, ATTENTION - return api ONLY for init request!
cwd : (Object) Current Working Directory - information about the current directory. Information about File/Directory
files : (Array) array of objects - files and directories in current directory. If parameter tree == true, then added to the folder of the directory tree to a given depth. The order of files is not important. Note you must include the top-level volume objects here as well (i.e. cwd is repeated here, in addition to other volumes) Information about File/Directory
netDrivers : (Array) Network protocols list which can be mounted on the fly (using netmount command). Now only ftp supported.
Optional
uplMaxSize : (String) Allowed upload max size. For example "32M"
options : (Object) Further information about the folder and its volume

{
 options : {
   "path"          : "files/folder42",                                 // (String) Current folder path
   "url"           : "http://localhost/elfinder/files/folder42/",      // (String) Current folder URL
   "tmbURL"        : "http://localhost/elfinder/files/folder42/.tmb/", // (String) Thumbnails folder URL
   "separator"     : "/",                                              // (String) Разделитель пути для текущего тома
   "disabled"      : [],                                               // (Array) List of commands not allowed (disabled) on this volume
   "copyOverwrite" : 1,                                                // (Number) Whether or not to overwrite files with the same name on the current volume
   "archivers"     : {                                                 // (Object) Archive settings
     "create"  : [
       0 : "application/x-tar",
       1 : "application/x-gzip"
     ],                                                   // (Array)  List of the mime type of archives which can be created
     "extract" : [
       0 : "application/x-tar",
       1 : "application/x-gzip"
     ]                                                    // (Array)  List of the mime types that can be extracted / unpacked
   }
 }
}

debug : (Object) Debug information, if you specify the corresponding connector option.

{
  "debug":{
    "connector":"php",                     // (String) Connector type
    "phpver"   : "5.3.6",                  // (String) php version
    "time"     : 0.0749430656433,          // (Number) Execution time
    "memory"   : "3348Kb / 2507Kb / 128M", // (String) Used / Free / Available Memory
    "volumes"  : [                         // (Array)  Debugging by volume
      {
        "id"         : "l1_",              // (String) ID of the Volume
        "driver"     : "localfilesystem",  // (String) Driver type (class name)
        "mimeDetect" : "internal",         // (String) Method for determining mime type
        "imgLib"     : "gd"                // (String) Library for working with images
      }

    ],
    "mountErrors" : [                      // (Array) List of errors for not mounted volumes
      0 : "Root folder has not read and write permissions."
    ]
  }
}

file

Output file into browser. This command applies to download and preview actions.

Arguments:

cmd : file
target : file's hash,
download : Send headers to force download file instead of opening it in the browser.

May need to set Content-Disposition, Content-Location and Content-Transfer-Encoding. Content-Disposition should have 'inline' for preview action or 'attachments' for download.

tree

Return folder's subfolders.

Arguments:

cmd : tree
target : folder's hash

Response:

tree : (Array) Folders list. Information about File/Directory

parents

Returns all parent folders and its subfolders on required (in connector options) deep. This command is invoked when a directory is reloaded in the client. Data provided by 'parents' command should enable the correct drawing of tree hierarchy directories.

Arguments:

cmd : parents
target : folder's hash,

Response:

tree : (Array) Folders list. Information about File/Directory

Example:

With the present hierarchy

/root1
  /dir1
    /dir11
      /dir111            
    /dir12
      /dir121
  /dir2
    /dir22
    /dir23
      /dir231
/root2

Should 'dir111' be reloaded, 'parents' data should return:

'dir111' parent directories
for each parent directory, its subdirectories (no more depth is needed)
should multiroot nodes be implemented, its root nodes (and optionally children)

This way, client-side component will render the following reloaded hierarchy

/root1
  /dir1
    /dir11
      /dir111      
    /dir12
  /dir2
/root2

ls

Return a list of file names in the target directory. arguments:

cmd : ls
target : hash of directory,

Response:

list : (Array) Files list.

mkdir

Create a new directory.

Arguments:

cmd : mkdir
target : hash of target directory,
name : New directory name

Response:

added : (Array) Array with a single object - a new directory. Information about File/Directory

mkfile

Create a new blank file.

Arguments:

cmd : mkfile
target : hash of target directory,
name : New file name

Response:

added : (Array) Array with a single object - a new file. Information about File/Directory

rename

Renaming a directory/file

Arguemnts:

cmd : rename
target : hash directory/file renaming
name : New name of the directory/file

Response:

added : (Array) array of file and directory objects renamed. Information about File/Directory
removed : (Array) array of file and directory 'hashes' that were successfully remoevd

upload

Process file upload requests. Client may request the upload of multiple files at once.

Arguments (HTTP POST):

cmd : upload
target : hash of the directory to upload to
upload[] : array of multipart files to upload

Response: An array of successfully uploaded files if success, an error otherwise.

added : (Array) of files that were successfully uploaded. Information about File/Directory

If the files could not be loaded, return the following:


{
    "error" : "Unable to upload files"
}

If at least one file has been uploaded, the response is Client-Server-API-2.0 # open and * select *. If not all files are uploaded, failures will be put in * error * and * errorData *:


{
    // open
    "select"    : [ "8d331825ebfbe1ddae14d314bf81a712" ], // (Array)  An array of hashes of the loaded paths
    "error"     : "Some files was not uploaded",          // (String) If not all files have been uploaded
    "errorData" : {                                       // (Object) Info about the files that could not be uploaded
        "some-file.exe" : "Not allowed file type"         // (String) "filename": "error"
    }
}

ping

Utility command needed to fix a bug when uploading files from Safari. http://www.webmasterworld.com/macintosh_webmaster/3300569.htm

Arguments:

cmd : ping

Response: sends a blank response with the header @Connection: close@

paste

Copies or moves a directory / files

Arguments:

cmd : paste
src : hash of the directory from which the files will be copied / moved (the source)
dst : hash of the directory to which the files will be copied / moved (the destination)
targets : An array of hashes for the files to be copied / moved
cut : 1 if the files are moved, missing if the files are copied

Response:

If the copy / move is successful:

added : (Array) array of file and directory objects pasted. Information about File/Directory
removed : (Array) array of file and directory 'hashes' that were successfully deleted

{
    "added": [{
        "mime": "text\/plain",
        "ts": 1380910690,
        "read": 1,
        "write": 1,
        "size": 51,
        "hash": "l2_dW50aXRsZWQgZm9sZGVyL1JlYWQgVGhpcyBjb3B5IDEudHh0",
        "name": "Read This copy 1.txt",
        "phash": "l2_dW50aXRsZWQgZm9sZGVy"
    }],
    "removed": ["l2_UmVhZCBUaGlzIGNvcHkgMS50eHQ"]
}

Caution * The command should stop copying at the first error. Is not allowed to overwrite files / directories with the same name.

rm

Recursively removes files and directories.

Arguments:

cmd : rm
targets : (Array) array of file and directory hashes to delete

Response:

removed : (Array) array of file and directory 'hashes' that were successfully deleted

duplicate

Creates a copy of the directory / file. Copy name is generated as follows: basedir_name_filecopy+serialnumber.extension (if any)

Arguments:

cmd : duplicate
current : hash of the directory in which to create a duplicate
target : hash of the directory / file that is being duplicated

Response: Client-Server-API-2.0#open (if you copy a directory, then open back up with a directory tree), select - hash for the path of the duplicate.

get

Returns the context of a plain/text file (preview)

Arguments:

cmd : read
current : hash of the directory where the file is stored
target : hash of the file

Response:

content - text file contents (raw string)


{
    "content": "Hello world!" // (String) contents of the text file 
}

put

Stores text in a file.

Arguments (passed in via HTTP POST):

cmd : edit
target : hash of the file
content : new contents of the file

Response: An array of successfully uploaded files if success, an error otherwise.

changed : (Array) of files that were successfully uploaded. Information about File/Directory

extract

Unpacks an archive.

Arguments:

cmd : extract
current : hash of the directory where the file is located
target : hash of the archive file

Response: Information about File/Directory

search

Return a list of files and folders list, that match the search string. arguments:

cmd : search
q : search string,

Response:

files : (Array) array of objects - files and folders list, that match the search string. Information about File/Directory

tmb

Background command. Creates thumbnails for images that do not have them. Number of thumbnails created at a time is specified in the Connector_Configuration_RU option tmbAtOnce. Default is 5.

Arguments:

cmd : tmb
current : hash path to the directory in which to create thumbnails

Response:


{
    "current": "b4473c8c08d1d499ecd7112f3398f125", // (String) hash path to a directory, in which the thumbnails were created
    "images" : {                                   // (Object)
        "a696323d7fd86513754004ba8bc12967":        // (String) has of the file path
            "http://localhost:8001/~troex/git/elfinder/files/.tmb/a696323d7fd86513754004ba8bc12967.png"
                                                   // (String) Thumbnail URL
    }, 
    "tmb": true  // (Boolean) returns true if there are still pictures that don't have thumbnails.
                 // Otherwise, returns false.
}

info

Returns information about places nodes

Arguments:

cmd : info
targets[] : array of hashed paths of the nodes

Response:

files: (Array of data) places directories info data Information about File/Directory

size

Returns the size of a directory or file.

Arguments:

cmd : size
targets[] : hash paths of the nodes

Response:

size: The total size for all the supplied targets.

dim

Returns the dimensions of an image/video

Arguments:

cmd : dim
target : hash path of the node

Response:

dim: The dimensions of the media in the format {width}x{height} (e.g. "640x480").

resize

Change the size of an image.

Arguments:

cmd : resize
current : hash of the directory where the file is located
target : has of the image path
width : new image width
height : new image height

Response: Information about File/Directory, select - hash of the image path

To be able to resize the image, cdc record file must be specified and resize dim. resize must be in true dim and contain a line with dimensions of height and width (like "600x400"). If specified without resize dim resize the dialog will not work correctly.

netmount

Mount network volume during user session.

Arguments:

protocol : network protocol. Now only ftp supports. Required.
host : host name. Required.
path : root folder path.
port : port.
user : user name. Required.
pass : password. Required.
alias : mount point name. For future usage. Now not used on client side.
options : additional options for driver. For future usage. Now not used on client side.

-- back to command list

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Client Server API 2.0

Client-Server API 2.0

General description

File paths (hashes)

Errors

Information about file/directory

File manager initialization

Command list

Command description

open

file

tree

parents

ls

mkdir

mkfile

rename

upload

ping

paste

rm

duplicate

get

put

extract

search

archive

tmb

info

size

dim

resize

netmount

Clone this wiki locally