Client Server API 2.0

Sergey B (Troex Nevelin) edited this page May 5, 2016 · 64 revisions

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:

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:

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:

mkfile

Create a new blank file.

Arguments:

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

Response:

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.

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

{
    "error" : "Unable to upload files"
}
  1. 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.

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:

archive

Packs directories / files into an archive.

Arguments:

  • cmd : archive
  • type : mime-type for the archive
  • current : hash of the directory that are added to the archive directory / files
  • targets : an array of hashes of the directory / files

Response: Client-Server-API-2.0#open, select - hash of the new archive

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:

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

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.