Topic Centers

Getting Started with XDSP JSON v1.1

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
  • Download a file
If you have any questions, check out the API Documentation and Demo Client.

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.

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 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.

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 http://www.xdrive.com
  • Log in through Xdrive (http://plus.xdrive.com) with your Xdrive Username or AOL/AIM Screen Name and password. This will set the required SNS and Xdrive cookies to maintain your session.
If you are going to make the JSON calls in the same browser window where you logged in, you can start using the API since you already have a session. Otherwise, you need to include your JSESSIONID in the url with each request to maintain your session.

Find your JSESSIONID Cookie from your browser and attach it to every JSON call.

POST Example 
  POST /json/v1.1/file.getlisting;jsessionid=A5D6568B12D80E0200C29DD68141C73F.
xdr-mtc13.websys.aol.com_6002 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.1/file.getlisting;jsessionid=A5D6568B12D80E0200C29DD68141C73F.
  xdr-mtc13.websys.aol.com_6002?data=%7B%22srcFile%22%3A%7B%22type%22%3A%22FileObject%22
  %2C%22id%22%3A%22xdr%3AXFS-123456789%22%7D%7D
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.
XDSP JSON API v1.2 will support more authentication options, including AOL authentication using SNS tickets, etc.

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.1/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.1/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 
  {"srcFile":
             {"type":"FileObject",
              "id":"xdr:XFS-123456789",
              "parentId":"xdr:XFS-0",
              "filename":"/",
              "isDir":true,
              "isShared":false,
              "isMapped":false,                       
              "modifiedTime":1179196431000,
              "createTime":1143842914000,
              "aliasTo":"xdr:null",
              "accessPerm":null,
              "maxQuota":-1,
              "size":17725711},
   "children":
              [{"type":"FileObject",
                "id":"xdr:XFS-222222222",
                "parentId":"xdr:XFS-123456789",
                "filename":"Winter.jpg",
                "isDir":false,
                "isShared":false,
                "isMapped":false,
                "modifiedTime":1178646469000,
                "createTime":1178646468000,
                "aliasTo":"xdr:null",
                "accessPerm":null,
                "maxQuota":-1,
                "size":105542},
               {...}],
   "jsessionid":"77B8EEA5C0EE5C22FA551735D22A4CB9.xdr-mtc13.websys.aol.com_6002"
  }
  • 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,
                                "isShared":false,
                                "isMapped":false,
                                "modifiedTime":-1,
                                "createTime":-1,
                                "aliasTo":"xdr:null",
                                "accessPerm":null,
                                "maxQuota":-1,
                                "size":-1}],                      
                  "errorCode":2210}],
   "jsessionid":null}

Upload Files

  • Method name: io.upload
  • 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.).

  • JSON Request Example: (before encoding) 
  {"destFolder":
                {"type":"FileObject",
                 "id":"xdr:XFS-123456789"},
   "statusToken":
                 {"type":"StatusObject",
                  "token":"54542165432165"}
  }
POST Example 
  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%2C%22statusToken%22%3A%7B%22type%22%3A%22StatusObject%22%2C%22token%22%
3A%2254542165432165%22%7D%7D HTTP/1.1

  Content-Type: multipart/form-data; boundary=---------------------------160731377214068
  -----------------------------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 
  {"parent":
            {"type":"FileObject",
             "id":"xdr:XFS-123456789",
             "parentId":"xdr:XFS-0",
             "filename":"/",
             "isDir":true,
             "isShared":false,
             "isMapped":false,                       
             "modifiedTime":1179196431000,
             "createTime":1143842914000,
             "aliasTo":"xdr:null",
             "accessPerm":null,
             "maxQuota":-1,
             "size":17725711},
   "uploaded":
              [{"type":"FileObject",
                "id":"xdr:XFS-222222222",
                "parentId":"xdr:XFS-123456789",
                "filename":"FILE1.jpg",
                "isDir":false,
                "isShared":false,
                "isMapped":false,
                "modifiedTime":1178646469000,
                "createTime":1178646468000,
                "aliasTo":"xdr:null",
                "accessPerm":null,
                "maxQuota":-1,
                "size":105542},
               {...}],
   "jsessionid":"77B8EEA5C0EE5C22FA551735D22A4CB9.xdr-mtc13.websys.aol.com_6002"
  }

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.).

  • 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.1/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.1/io.download?datadata=%7B%22toDownload%22%3A
%7B%22type%22%3A%22FileObject%22%2C%22
  id%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 response. Only bytes.

  • 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) or null
    • 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.
Submitted by Developer Network on June 11, 2007 - 4:27pm.

 

Login | AOL.com | About Us | Site Map | Help
Contact Us | AOL Terms of Service | AOL Privacy Policy
© 2008 AOL LLC. All Rights Reserved.