Overview   •   Protocol

Abstract

Specify messaging protocol for remote file system reading and writing (files metadata and content).

Messaging

Client and server exchange messages in XML format using request-response paradigm. Generic request format is:

<request id="N" type="T">
[request body]
</request>

Where:

  • N — sequence number (generated by client, must be unique in a session scope)
  • T — request type (operation specific, such as "list", "remove" etc.)
  • request body — request type specific XML content

Server respond with XML formatted response message, generic response format is: 

<response id="N" type="T">
[response body]
</response>
Where:

  • N — sequence number, must match request ID
  • T — response type, must be one of
    • ok — request has been processed normally and response body contains processing result
    • error — request processing terminated unexpectedly, response body contains error message and code (client typically display on user GUI):
      <message>Error message</message>
      <code>Error code</code>
      Error message is a human readable string. Error code is a alphanumeric value, see "Error codes" section for known values.
  • response body — request/response type specific XML content

Common

Any date/time information used in XML should be formatted using following pattern:
yyMMddHHmmssZ, for example, 010704120856-0700.
Protocol operates on files, below is a common structure definition for a file object:
<file>
<type>${type}</type>
<path>${path}</path>
<name>${name}</name>
<length>${length}</length>
<created>${created}</created>
<modified>${modified}</modified>
</file>
Where:

  • Type — file type, one of:
    • "f" — file
    • "d" — directory
  • Path — a full path to the file, for example: "/dir/document.txt"
  • Name — a name of the file (title and extension), for example: "document.txt"
  • Length — file length (bytes), valid for files only (not directories)
  • Created — file created timestamp
  • Modified — file last modified timestamp

A "file" element may contain nested "file" elements, this reflects file hierarchy.
There is a special character "/" (slash) used to separate files in the path (file separator).
There is a special root file, which is ancestor for all other files. The root file name matches its path and equal to the file separator ("/"). The root file type is directory, root file is immutable and have no created and modified timestamps.
All the file names and paths are case sensitive.

Protocol

Request type and description

Request example

Response example

get
Get specified file or directory denoted by path.
If file path information is missing, server should return list information about root file.

<request id="1" type="get">
<file>
<path>/mydir/myfile.txt</path>
</file>
</request>

<response id="1" type="ok">

<file>
<type>d</type>
<path>/mydir/myfile.txt</path>
<name>myfile.txt</name>
<created>010704120856-0700</created>
<modified>010704120856-0700</modified>
<length>1234567</length>
</file>

</response>

list
List specified file or directory denoted by path.

If file path information is missing, server should return list information about root file.
If directory being listed, response should contain directory file element with nested file elements, which are direct children of specified directory.
If file listed, response contains single file element (same as "get" request).

<request id="1" type="list">
<file>
<path>/mydir</path>
</file>
</request>

<response id="1" type="ok">

<file>
<type>d</type>
<path>/mydir</path>
<name>mydir</name>
<created>010704120856-0700</created>
<modified>010704120856-0700</modified>

<file>
<type>f</type>
<name>myfile.txt</name>
<length>1234567</length>
<created>010704120856-0700</created>
<modified>010704120856-0700</modified>
</file>

</file>

</response>

mkdir
Create directory denoted by path.
Server should return file information about created directory.

<request id="1" type="mkdir">
<file>
<path>/mydir</path>
</file>
</request>

<response id="1" type="ok">
<file>
<type>d</type>
<path>/mydir</path>
<name>mydir</name>
<created>010704120856-0700</created>
<modified>010704120856-0700</modified>
</file>
</response>

delete
Delete file or directory denoted by path.

<request id="1" type="delete">
<file>
<path>/mydir</path>
</file>
</request>

<response id="1" type="ok">
</response>

move
Move file or directory denoted by source path to a file or directory denoted by target path.
Server should return file information about target file.

<request id="1" type="move">
<source>
<file>
<path>/mydir</path>
</file>
</source>

<target>
<file>
<path>/mydir2</path>
</file>
</target>

</request>

<response id="1" type="ok">
<file>
<type>d</type>
<path>/mydir</path>
<name>mydir</name>
<created>010704120856-0700</created>
<modified>010704120856-0700</modified>
</file>
</response>

upload
Store file content denoted by path on a server.
Client may specify additional parameter, showing whether content should be appended to file (false by default).
The data transfer process is implementation specific.

<request id="1" type="upload">
<file>
<path>/mydir/myfile.txt</path>
</file>
<append>true</append>
</request>

<response id="1" type="ok">
</response>

download
Retrieve file content denoted by path.

Client may specify additional parameters, specifying file content range:

  • offset — file offset (bytes), 0 by default
  • length — content length (bytes), until EOF by default.

The data transfer process is implementation specific.

<request id="1" type="download">
<file>
<path>/mydir/myfile.txt</path>
</file>
<offset>123</ofsset>
<length>456</length>
</request>

<response id="1" type="ok">
</response>

Error codes

This section contains well known error codes for exceptional responses.

Code Description

fileSystem.generalFailure

File system general failure.

fileSystem.fileNotFound

File not found. This is usually thrown by an operation that requires file existence, for example "get" or "download".

fileSystem.fileExists

File exists. This is usually thrown by an operation that assume target file absence, for example "mkdir" or "move".
fileSystem.unauthorized Authoriaztion required

HTTP transport

This section describes HTTP implementation details. All the requests issued by client should be POSTed to predefined HTTP URL. XML request content should be set in parameter named "request". Server should respond with HTTP OK (200) result code (even if response type is "error"), response content type should be "text/xml" and response content should be XML document.

Upload

If upload request accepted, server must send upload URL:
<response id="1" type="ok">
<url>http://host/uploadLink</url>
</response>
Client will issue POST request and send file content as request raw data.

Download

If download request accepted, server must send download URL:
<response id="1" type="ok">
<url>http://host/downloadLink</url>
</response>
Client will issue GET request and treat response content as file data.