Getting Started with XDSP JSON v1.2
Overview
When you are done with this short tutorial, you will have completed a client that will:- Authenticate to the XDSP
- Get a folder listing
- Upload a file
- Dowload a file
- Migrate from version 1.1 to 1.2
If you would like to review the previous version of this guide, please go to Getting Started with XDSP JSON v1.1.
The Basics
JSON
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.
Note on the Use of Eval()
Please see the FAQ for an important response on the implications of using eval() to parse JSON data.
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.versionis the version of the interface you wish to use.methodis the method name you wish to call.
Data Types
The Xdrive JSON Interface passes back and forth serialized objects representing key data types of the application. These simple Transfer Objects (TOs) 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 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.
Examples
Authentication
The first step is to make sure you have an Xdrive account. You can get a free 5GB account at www.xdrive.com
We expanded authentication via integration with the OpenAuth API so users can login directly by providing their AOL/AIM credentials (you can use your AOL ®/AIM Screen Name or your email address).
IMPORTANT: This method is now also available for version 1.1 of the API.
- This method is only supported on SSL (https) and as a POST request.
- Method name: member.login
- Parameters:
- user (MemberObject): User to be logged in. The username and password fields cannot be null.
- JSON Request Example: (before encoding)
{"user":
{"type":"MemberObject",
"username":"testuser@xdrive.com",
"password": "testpassword"}
}
POST Example
POST /json/v1.2/member.login HTTP/1.1 Content-Type: application/x-www-form-urlencoded; data=%7B%22user%22%3A%7B%22type%22%3A%22MemberObject%22%2C%22username%22 %3A%22testuser%22%2C%22password%22%3A%22testpassword%22%7D%7D
- Response Output
- user (MemberObject): Populated object with user's information, including rootFolderId.
- jsessionid: A JSESSIONID cookie will be set, but for those clients with no cookie support the jsessionid can be sent in the URL with each request.
- recoveryToken: A XDRecTok cookie will be set, but for those clients with no cookie support the recoveryToken can be sent in the URL with each request along with the jsessionid (MUST be present to be able to use the recovery token for authentication).
- exceptions [ExceptionObject]: Only if the login call fails.
- Response Example
{"results":
{"user":
{"type":"MemberObject",
"username":"testuser@xdrive.com",
"email":"testuser@xdrive.com",
"firstname":"firstname",
"lastname":"lastname",
"rootFolderId":"xdr:XFS-123456789",
"userSeq":123456}
},
"recoveryToken":"xdrectokvalue",
"jsessionid":"jsessionidvalue"}
- Login Failure Response Example
{"exceptions":
[{"type":"ExceptionObject",
"errorMessage":"Your login username or password is incorrect.
Please note that usernames take the form of an e-mail
address for most users, e.g., JohnDoe@aol.com.
Please try logging in again.",
"errorInfo":null,
"errorCode":510}],
"jsessionid":null}
Clients with cookie supportThe member.login method will return session cookies with a successful response. These cookies need to be passed with any requests to sessioned methods. Currently the session cookies include:
- 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.
Clients with NO cookie support
Version 1.2 of the API now supports cookie-less clients. The values of the JSESSIONID and XDRecTok cookies will be included in the JSON response after a successful member.login call.
- jsessionid
- recoveryToken
Note: Include the jsessionid right after the end of the URL and before you attach any parameters. Notice there's a ";" before the jsessionid, which has to be always lower case. This is the format in which Tomcat expects the JSESSIONID. You can include the recoveryToken after the jsessionid as a parameter.
POST /json/v1.2/file.getlisting;jsessionid=jsessionidvalue?recoveryToken=xdrectokvalue &data=%7B%22srcFile%22%3A%7B%22type%22%3A%22FileObject%22%2C%22id%22%3A%22xdr%3A XFS-123456789%22%7D%7D HTTP/1.1
Get a Folder Listing
- Method name: file.getlisting
- Parameters:
- srcFile (FileObject): Folder to get the listing from. If no id is provided, this call defaults to the root folder ("My Xdrive").
- JSON Request Example: (before encoding)
{"srcFile":
{"type":"FileObject",
"id":"xdr:XFS-123456789"}
}
POST Example
POST /json/v1.2/file.getlisting HTTP/1.1
Content-Type: application/x-www-form-urlencoded;
data=%7B%22srcFile%22%3A%7B%22type%22%3A%22FileObject%22
%2C%22id%22%3A%22xdr%3AXFS-123456789%22%7D%7D
GET Example
http://plus.xdrive.com/json/v1.2/file.getlisting?data=%7B%22srcFile%22%3A%7B
%22type%22%3A%22 FileObject%22%2C%22id%22%3A%22xdr%3AXFS-123456789%22%7D%7D
- Response Output
- srcFile (FileObject): Populated folder we got the listing from.
- children [FileObject]: Array of populated children of the srcFile object. If no children available, the call returns an empty array.
- exceptions [ExceptionObject]: Only if folder listing fails.
- jsessionid
- Response Example
{"results":
{"srcFile":
{"type":"FileObject",
"id":"xdr:XFS-123456789",
"parentId":"xdr:XFS-0",
"filename":"/",
"isDir":true,
"isShared":false,
"isMapped":false,
"modifiedTime":1191657698000,
"createTime":1143842914000,
"size":3935149546,
"accessPerm":null,
"aliasTo":null,
"maxQuota":-1,
"version":3493},
"children":
[{"type":"FileObject",
"id":"xdr:XFS-111444777",
"parentId":"xdr:XFS-123456789",
"filename":"file1.jpg",
"isDir":false,
"isShared":false,
"isMapped":false,
"modifiedTime":1190148820000,
"createTime":1190148783000,
"size":3133,
"accessPerm":null,
"aliasTo":null,
"maxQuota":-1,
"version":0},
{...}]},
"jsessionid":"jsessionidvalue"}
- Folder Listing Failure Response Example
{"exceptions":
[{"type":"ExceptionObject",
"errorMessage":"File or folder no longer exists or name is not valid.
Please log out and log in again.
If you continue to experience problems please
go to the "Support"
link for customer support options.",
"errorInfo":
[{"type":"FileObject",
"id":"BAD ID",
"parentId":"xdr:null",
"filename":null,
"isDir":false,
"isMapped":false,
"modifiedTime":-1,
"createTime":-1,
"size":-1,
"accessPerm":null,
"aliasTo":null,
"maxQuota":-1}],
"errorCode":2210}],
"jsessionid":"jsessionidvalue"}
Upload Files
IMPORTANT The version 1.1 io.upload method was renamed to io.formupload since it only works as a form POST.
It also changed the format as follows:
Both the JSON message specifying the destFolder and optionally the statusToken and the files to be uploaded, can be sent in the BODY (in version 1.1 the JSON message had to be sent in the URL as part of the data parameter). The files should be sent in the multi-part message as a standard browser multi-part form POST.
- Method name: io.formupload
- Parameters:
- destFolder (FileObject): Folder where to upload the files.
- statusToken (StatusObject): Represents the status of a data transfer between the members computer and Xdrive. This utility object can be used to query the status of I/O operations (count remaining files, count remaining bytes, convey error messages , etc.) via the io.querystatus method.
- JSON Request Example: (before encoding)
{"destFolder":
{"type":"FileObject",
"id":"xdr:XFS-123456789"},
"statusToken":
{"type":"StatusObject",
"token":"54542165432165"}
}
POST Example
POST /json/v1.2/io.formupload HTTP/1.1
Content-Type: multipart/form-data; boundary=---------------------------160731377214068
-----------------------------160731377214068
Content-Disposition: form-data; name="data"
Content-Type: text/plain
%7B%22destFolder%22%3A%7B%22type%22%3A%22FileObject%22%2C%22id%22%3A%22xdr%3AXFS
-123456789%22%7D%2C
%22statusToken%22%3A%7B%22type%22%3A%22StatusObject%22%2C%22token%22%3A%2254
542165432165%22%7D%7D
-----------------------------160731377214068
Content-Disposition: form-data; name="FILE1"; filename="FILE1.jpg"
Content-Type: image/jpeg
bytes
-----------------------------160731377214068
Content-Disposition: form-data; name="FILE2"; filename="FILE2.jpg"
Content-Type: image/jpeg
bytes
-----------------------------160731377214068--
- Response Output
- uploaded [FileObject]: Populated files that where uploaded.
- parent (FileObject): Populated parent where the files were uploaded to.
- exceptions [ExceptionObject]: If upload fails.
- jsessionid
- Response Example
{"results":
{"parent":
{"type":"FileObject",
"id":"xdr:XFS-123456789",
"parentId":"xdr:XFS-0",
"filename":"/",
"isDir":true,
"isShared":false,
"isMapped":false,
"modifiedTime":1191657698000,
"createTime":1143842914000,
"size":3935149546,
"accessPerm":null,
"aliasTo":null,
"maxQuota":-1,
"version":3493},
"uploaded":
[{"type":"FileObject",
"id":"xdr:XFS-222222222",
"parentId":"xdr:XFS-123456789",
"filename":"FILE1.jpg",
"isDir":false,
"isShared":false,
"isMapped":false,
"modifiedTime":1178646469000,
"createTime":1178646468000,
"size":105542,
"accessPerm":null,
"aliasTo":null,
"maxQuota":-1,
"version":0},
{...}],
"jsessionid":"jsessionidvalue"}
Download Files
- Method name: io.download
- Parameters:
- toDownload (FileObject): File to be downloaded.
- statusToken (StatusObject): Represents the status of a data transfer between the members computer and Xdrive. This utility object can be used to query the status of I/O operations (count remaining files, count remaining bytes, convey error messages , etc.) via the io.querystatus method.
- onlydata (OPTION): Optional - If true, return only bytes. Ifthe download fails, no exceptions will be returned but a HTTP 500 Status Code will be set in the response. If this option is false, a multipart response will be returned. Default: false.
- JSON Request Example: (before encoding)
{"toDownload":
{"type":"FileObject",
"id":"xdr:XFS-777777777"},
"statusToken":
{"type":"StatusObject",
"token":"54542165432165"}
}
Note: The io.download method also takes another optional parameter, "range" for byte range used in block access.
POST Example
POST /json/v1.2/io.download HTTP/1.1
Content-Type: application/x-www-form-urlencoded;
data=%7B%22toDownload%22%3A%7B%22type%22%3A%22FileObject%22%2C%22id%22%3A%22
xdr%3AXFS-777777777%22%7D%2C%22statusToken%22%3A%7B%22type%22%3A%22StatusObject
%22%2C%22token%22%3A%2254542165432165%22%7D%7D
GET Example
http://plus.xdrive.com/json/v1.2/io.download?data=%7B%22toDownload%22%3A%7B %22type%22%3A%22FileObject%22%2C%22id%22%3A%22xdr%3AXFS-777777777%22%7D%2C %22statusToken%22%3A%7B%22type%22%3A%22StatusObject%22%2C%22token% 22%3A%2254542165432165%22%7D%7D
- Response Output
- No JSON is returned, only data. If the option onlydata is false, a JSON message will be returned along with the data (multipart message).
In this version we support multipart requests, so multiple files can be downloaded in one POST request.
- No JSON is returned, only data. If the option onlydata is false, a JSON message will be returned along with the data (multipart message).
- Response Headers
- Content-Length: size of the file or range of the bytes to download
- Accept-Ranges: bytes
- Content-Range: download range (start-end/total size) only if a range was provided
- Content-Disposition: attachment; filename="filename"
- Content-Type: mimetype; name="filename"
To support standard browser invocation of the 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 (io.querystatus) and to convey exceptions supressed to prevent interruption of the data transfer stream.
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.
Version Migration
If you are currently using version 1.1 of the XDSP JSON API, and would like to migrate to the new version, here are a few conversion tips to help you upgrade:
- You can now login via the API using the member.login or member.aollogin methods since we integrated with the OpenAuth API.
- The results from the method invoked in the request are now wrapped in an object called "results". Since new fields were introduced to the response, we thought it would be better to group each part in its own object. The response can contain the following elements: id, results, exceptions, jsessionid, and recoveryToken.
- The request can also contain new elements, so the parameters for the method invocation can be wrapped in an object called "params", although this is not required. You will need to do this if you would like to include options, an id, a global parameter, or the method name in the JSON message.
- The upload method name io.upload was changed to io.formupload since it only works as a form POST.
» Submitted by Developer Network on December 12, 2007 - 8:34am.