JSON RCP Specifcations: v1.1

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

RPC Specifics

Remote Procedure Calls will be supported over HTTP/HTTPS. Xdrive JSON API Clients must:

• honor HTTP cookies
• honor HTTP header/pragma, including:
  • No-Cache
  • Content-Range
  • Byte-Ranges
  • Transfer-Encoding (i.e., chunking)
  • User-Agent (different user agents may get different treatement)
  • Accept-Encoding (i.e., gzip)
  • Content-Encoding (i.e., gzip)
  • Keep-Alive
• honor HTTP statuses, including the following specific situations:
  • 200 (OK): JSON Request was processed. This may still mean you have an exception.
  • 301 (Moved Permanently): This URL is no longer correct. Please use the new one from now on.
  • 307 (Temporary Redirect): This URL is directing you to re-submit the request to another URL, but continue to first submit the request to the orginal URL next time.
  • 400 (Bad Request): This request was not processable by the JSON gateway.
  • 401 (Unauthorized): This request didn't include proper authorization. For example, the request my not have included a valid session token.
  • 404 (Not Found): This was to a bad URL, there is no active gateway at this URL.
  • 405 (Method Not Allowed): The client is attempting an HTTP request that is not valid, i.e., making a HEAD request against a login processor.
  • 406 (Not Acceptable): The client is requesting a response type that the gateway cannot respond to.
  • 410 (Gone): This gateway or handler is gone. For example, the requested gateway version has been depricated.
  • 510 (Not Implemented): The requested gateway is not implemented. For example, a request was for a version of the gateway that has not yet been launched.
  • 503 (Service Not Available): The requested gateway is temporarly down.

Method Naming

Method names exposed via the interface are kept simple and human-readable. They are always lowercase and do not use underscore to seperate 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 consistant interface for existing and future 3rd party applications to be developed against, we will version the interface. At this time, only *v1.1* of the interface is available.

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 supressed 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 primatives. At no time are any primative data types passed back and/or forth across the Xdrive JSON Interface as discrete arguments or parameters.

Each data tranfer 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 occured 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 occuring. 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.