JSON RCP Specifcations: v1.2

Overview

The Xdrive JSON Interface handles JSON requests sent via HTTP. Method calls are exposed via a Web Services gateway using the JavaScript Object Notation format for message exchange.

References

JavaScript Object Notation (JSON): http://www.json.org

Method Naming

Method names exposed via the interface are kept simple and human-readable. They are always lowercase and do not use underscore to separate words. We try to keep the method names to single words where possible.

Example: /json/v1.1/getquota

Versioning

As the Xdrive JSON Interface grows, new methods will be added and existing methods may be changed, deprecated or removed entirely. In order to provide a consistent interface for existing and future 3rd party applications to be developed against, we will version the interface.

Gateway Invocation

The Xdrive JSON Interface is accessed via the URI:
http://plus.xdrive.com/json/version/method

/json/ is the Servlet gateway, all JSON messages must go through the gateway in order to be processed.
version is the version of the interface you wish to use.
method is the method name you wish to call.

A single call to the interface would consist of a POSTed request parameter named 'data'. The value of that parameter should be the JSON encoded message being sent to the server. After the server has handled the message appropriately, a response will be returned to the client encoded in JSON.

Note that I/O methods (upload, download, etc) support multi-part requests and responses. To support standard browser invocation of these I/O methods (where the resulting action is a transfer of binary data), supplemental methods are provided to query the status of a transfer in progress and to convey exceptions suppressed to prevent interruption of the data transfer stream.

Data Types

The Xdrive JSON Interface passes back and forth serialized objects representing key data types of the application. These simple Transfer Objects (TO's) represent individual server-side objects or composites of related primitives. At no time are any primitive data types passed back and/or forth across the Xdrive JSON Interface as discrete arguments or parameters.

Each data transfer object allows certain fields to be populated for request input and certain fields to be read for response output.

Exceptions

If a request causes an exception to be raised (JSON format validation, method argument validation, user error or system error), that exception will be returned as part of the response to the request message.

Note that our system defaults to 'more success' instead of 'more failure'. That is, if a given request is operating on more than one object (e.g. moving several files from one folder to another), the response will have both the exceptions that occurred AND the successful result of the operation.

Exceptions encountered during an I/O method will only return as part of the response when they prevent the entire operation from occurring. Intermediate exceptions that only affect a part of the overall operation (e.g. a single missing file when downloading a whole folder) will be conveyed via the supplemental status method.

Request

Different types of request formats will be supported to allow different clients (Web browser, Desktop Clients, Flex/Flash Applications, etc.) to post requests to the JSON Gateway.
The following information will be read and processed from the request:

URL:
- protocol [required]
  Only /json is currently supported.
- version number [required]
  /v1.2
- method name [optional]
  /file.getlisting
URL Parameters: [optional]
- recoveryToken for cookie-less authentication.
- jsessionid for cookie-less authentication.
- callback for wrapping the JSON output text in parentheses and a callback method
- language this is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us). If not passed in, the language will be extracted from HTTP header Accept-Language and if that is not available will default to en-us. Only language supported at the moment is en-us.
HTTP Headers: [optional]
- Accept
  Only application/json supported. Otherwise, the response's Content-Type defaults to text/plain.
- Accept-Encoding
  Only gzip supported. See GZIP Encoding for more information.
- Accept-Language
  Only en-us supported at the moment.
- Content-Encoding
  Only gzip supported. See GZIP Encoding for more information.
- Content-Type
  - none for GET requests
  - text/plain
  - application/x-www-form-urlencoded
  - application/json
  - application/zip for a part in io.zipupload.
  - application/octet-stream for part(s) in io.upload or io.write which contain data.
  - multipart/mixed for request chaining.
  - multipart/form-data for basic uploads, io.formupload, from a browser.
- Range
  bytes
Cookies: [optional]
- JSESSIONID
- XDRecTok (Represents a token that will allow the user's session to be remade if he/she bounces servers. When logging in the user is granted a secure session, but subsequent non-secure calls receive a new non-secure session that is no longer authenticated. The value of the XDRecTok is used in this case to rebuild the user's session.)
JSON Messages:
- If Content-Type is application/x-www-form-urlencoded or method is GET, the message will be encoded in the body or URL: data=%7Bjson7D%
- Otherwise: {json}
Data Streams:
- Uploads

IMPORTANT: Anything sent as part of the JSON Message will override any HTTP information.

Request Types

GET

Support for multiple Request/Piping: NO

API Versions: 1.1, 1.2

GET /json/v1.2/file.getlisting?data=%7B%22srcFile%22%3A%7B%22type%22%
3A%22FileObject%22%2C%22id%22%3A%22xdr%3AXFS-123456789%22%7D%7D

application/x-www-form-urlencoded

Support for multiple Requests/Piping: NO

API Versions: 1.1, 1.2

POST /json/v1.2/file.getlisting HTTP/1.1
Content-type: application/x-www-form-urlencoded

    data=%7Bjson7D%=

multipart/form-data

Support for multiple Requests/Piping: NO

API Versions: 1.1, 1.2

Version 1.1 style

POST /json/v1.1/io.upload?data=%7B%22destFolder%22%
3A%7B%22type%22%3A%22FileObject%22%2C%22id%22%3A%22xdr
%3AXFS-123456789%22%7D%7D HTTP/1.1
Content-Type: multipart/form-data; boundary=----------**boundary**
------------**boundary**
Content-Disposition: form-data; name="file1"; filename="image.jpg"
Content-Type: image/jpeg

    {bytes}
------------**boundary**
Content-Disposition: form-data; name="file2"; filename="image2.jpg"
Content-Type: image/jpeg

    {bytes}
------------**boundary**--

Version 1.2 style

POST /json/v1.2/io.formupload HTTP/1.1
Content-Type: multipart/form-data; boundary=----------**boundary**
------------**boundary**
Content-Disposition: form-data; name="data"

    {"destFolder":{"type":"FileObject","id":"xdr:XFS-123456789"}}
------------**boundary**
Content-Disposition: form-data; name="file1"; filename="image.jpg"
Content-Type: image/jpeg

    {bytes}
------------**boundary**
Content-Disposition: form-data; name="file2"; filename="image2.jpg"
Content-Type: image/jpeg

    {bytes}
------------**boundary**--

application/json

Support for multiple Requests/Piping: NO

API Version: 1.2

POST /json/v1.2/file.getlisting HTTP/1.1
Content-type: application/json 

    {json}

multipart/mixed

Multipart requests are used to enable multiple requests/piping and data streaming.
Support for multiple Requests/Piping: YES

API Version: 1.2

POST /json/v1.2/ HTTP/1.1
Content-Type: multipart/mixed; boundary=----------**boundary**
------------**boundary**
Content-Type: application/json

    {json} [e.g. io.write]
------------**boundary**
Content-Type: application/octet-stream

    {bytes}
------------**boundary**--

JSON Request Format

    {"method": String,
     "id": int || String, 
     "global": boolean,
     "options": {...},
     "params":  {...}}

method [optional]: Method to be invoked. The method could be also specified in the URL.
id [optional]: Used to match a response to a request. If present, it will be included in the response.
global [optional]: Used to identify the part that sets global fields.
options [optional]: Key/value pairs for command processing options.
params [optional]: Method arguments. All parameters are typed. No primitives are allowed. They are not ordered.

Response

The following information will be sent in the response:

HTTP Headers: [optional]
- Accept-Ranges
  bytes only for single file downloads (io.download*io.thumbnail*, and io.view).
- Cache-Control
  no-cache="set-cookie"
- Content-Encoding
  Only gzip supported. See GZIP Encoding for more information.
- Content-Type
- Content-Range
  bytes start-end/total or null only for single file downloads (io.download*io.thumbnail*, and io.view).
- X-Part
  For Multipart responses.
- X-Status-Code
  For Multipart responses with multi-status.
Cookies: [optional]
- JSESSIONID
- XDRecTok (represents a token that will allow the user's session to be remade if he/she bounces servers.)
JSON Messages
Data streams:
- Downloads

JSON Response Format

    callback(
    {"id": int || String,
     "results": {...}, 
     "exceptions": [...],
     "jsessionid": String,
     "recoveryToken": String}
    )

id [optional]: Used to match a response to a request. Present if an id was given in the request.
results: Results of processing the request. Always present if the request was successful (even if partially) unless the quiet option was set to true in the request.
exceptions [optional]: Array of errors containing information on any failure, including error message, error code and error info.
jsessionid: User's session. It is set in a cookie but also returned only after the user logs in to support cookie-less sessions.
recoveryToken: This is a token that will allow the user's session to be remade if he/she bounces servers. It is set in a cookie but also returned only after the user logs in to support cookie-less sessions.
callback [optional]: If a callback method is specified in the request, the response will be wrapped around the callback function name and parenthesis.

Callbacks allow users to make requests in client-side JavaScript without the use of proxies on the server side. Because JSON output is native JavaScript, you do not have to eval the returned object in the callback function, you have immediate access to the response object elements.
Simply place your request inside a < script > tag in your document and the JavaScript callback function that will access the response object:

< script type="text/javascript">
    function processListing(response) {
        var rootId = response.results.srcFile.id;
    }
< /script>

< script 
 type="text/javascript" 
 src="http://plus.xdrive.com/json/v1.2/file.getlisting?callback=processListing">

Options

Options can be given with a request to change the behavior of the request or response independent of the method result.

Options Format

{"options": {"optionname": value}}

All options names are lower-case. All options values are primitives.

Options Available to all handlers:

failonerror [default: false]: If true, abort the entire request if a part fails. Otherwise, continue processing the request when an error occurs.
quiet [default: false]: If true, do not send back a response. Exceptions will be sent.
sparse [default: false]: If true, do not send the fully populated object in the response.
quota [default: false]: If true, include the quota in the response.
onlydata [default: false, except for downloads]: If true, do not send back a response or exceptions, just data. If the call fails, a 500 status code will be set in the response.

Multiple Requests

Multiple method invocations can be sent using a single HTTP POST. Multiple requests will be implemented using multipart requests.

Multiple Requests Format

POST /json/v1.2/ HTTP/1.1
Content-Type: multipart/mixed; boundary=----------**boundary**
------------**boundary**
Content-Type: application/json 

    {"global": true,
     "options": {...},
     "params":  {...}}
------------**boundary**
Content-Type: application/json

    {"method": "io.write",
     "id": 000000, 
     "options": {...},
     "params":  {...}}
------------**boundary**
Content-Type: application/octet-stream

    {bytes}
------------**boundary**--

Global Request Part

In multipart requests, the first part can be used for setting global arguments (options, params, etc.) These global arguments will apply to all the subsequent requests in the multipart message. Global arguments can be overridden by specifying items in each method call.

POST /json/v1.2/ HTTP/1.1
Content-Type: multipart/mixed; boundary=----------**boundary**
------------**boundary**
Content-Type: application/json

    {"options": {"failonerror": false},
     "params": {...}
     "global": true}
------------**boundary**
Content-Type: application/json

    {"method": "methodname",
     "options": {"failonerror": true}} [method options, override global]
------------**boundary**--

Multiple Responses

The response could be single or multipart, depending on the number of responses that need to be sent back after processing the request. If the response is multipart, there has to be a way to match a response part to a request part, since the total number of parts is not always the same. Since the id is not required, another way of identifying the parts needs to be introduced.

For this purpose, the X-Part HTTP Header will be set in each part in the response. Request/Response parts start counting at 1. Any bytes sent in the request/response are considered to be the same part as the JSON message preceding it.

The HTTP response status code will also be sent in the response. If the response is multipart and the status codes in all the parts do not match, a 207 Multi-Status WebDAV HTTP status code will be sent and the X-Status-Code HTTP Header will be set for each part.

Multiple Response Format

POST /json/v1.2/ HTTP/1.1
Content-Type: multipart/mixed; boundary=----------**boundary**
------------**boundary**
Content-Type: application/json [part 1]

    {"options": {...},
     "global": true}
------------**boundary**
Content-Type: application/json [part 2]

    {"method": "io.open",
     "options": {...}
     "params": {...}}
------------**boundary**
Content-Type: application/json [part 3]

    {"method": "io.write",
     "id": 0000,
     "params": {...}}
------------**boundary**
Content-Type: application/octet-stream [part 3]

    {bytes}
------------**boundary**
Content-Type: application/json [part 4]

    {"method": "io.close",
     "params": {...}}
------------**boundary**--


207 MULTI-STATUS HTTP/1.1
Content-Type: multipart/mixed; boundary=----------**boundary**
------------**boundary**
[Response to io.open]
Content-Type: application/json
X-Status-Code: 200 OK
X-Part: 2

    {"results": {...}, "exceptions": [...]}
------------**boundary**
[Response to io.write]
Content-Type: application/json
X-Status-Code: 200 OK
X-Part: 3

    {"id": 0000, "results": {...}, "exceptions": [...]}
------------**boundary**
[Response to io.close]
Content-Type: application/json
X-Status-Code: 500 INTERNAL SERVER ERROR
X-Part: 4
------------**boundary**--

Request Piping

Coming Soon...
Request piping allows for the output of one command to be used as input of another command. Both commands must be chained in the same HTTP request. Command ids are required when piping request. The command id will be used to identify the command from which the output should be obtained.

GZIP Encoding

The json interface will now support GZIP Encoding.

GZIP in Requests

Non-Multipart
If the request has the Content-Encoding: gzip HTTP header set, the request body will be unzipped before being parsed.
Multipart
&nsbp;If the whole request has the Content-Encoding: gzip HTTP header set, the request body will be unzipped before being parsed.
If a single part in the request has the Content-Encoding: gzip HTTP header set, the part body will be unzipped before being parsed/reading data.
You should NOT mix zipping of single parts and zipping of the entire body at the same time.

GZIP in responses

Non-Multipart
If the request contained an Accept-Encoding: gzip HTTP header, we may choose to gzip the entire response body.
Multipart
&nsbp;We will not gzip the entire response body for multipart responses.
If the request was not multipart and contained an Accept-Encoding: gzip HTTP header, we may choose to gzip individual parts of the response.
If the request was multipart, and a single part contained an Accept-Encoding: gzip HTTP header, we may choose to gzip the corresponding response part.

Topic Centers

Overview

References

Method Naming

Versioning

Gateway Invocation

Data Types

Exceptions

Request

Request Types

JSON Request Format

Response

JSON Response Format

Options

Options Format

Multiple Requests

Multiple Requests Format

Global Request Part

Multiple Responses

Multiple Response Format

Request Piping

GZIP Encoding

GZIP in Requests

GZIP in responses