SugarSync API description

Requirements

A valid SugarSync user name, with password.

A valid SugarSync developer access key id with private access key.

Authorization

POST the following XML to https://api.sugarsync.com/authorization.

    <?xml version="1.0" encoding="UTF-8"?>
    <authRequest>
	<username>$username</username>
	<password>$password</password>
	<accessKeyId>$akeyid</accessKeyId>
	<privateAccessKey>$pacckey</privateAccessKey>
    </authRequest>

The result is a small XML data package.

HTTP/1.1 201 Created
Connection: close
Date: Wed, 31 Aug 2011 11:15:57 GMT
Accept-Ranges: bytes
Location: https://api.sugarsync.com/authorization/Oz3odjluQU6n6RCA
Server: Noelios-Restlet-Engine/1.1.5
Content-Type: application/xml; charset=UTF-8
Client-Date: Wed, 31 Aug 2011 11:15:57 GMT
Client-Peer: 74.201.86.35:443
Client-Response-Num: 1
Client-SSL-Cert-Issuer: /C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc./OU=http://certificates.godaddy.com/repository/CN=Go Daddy Secure Certification Authority/serialNumber=07969287
Client-SSL-Cert-Subject: /O=*.sugarsync.com/OU=Domain Control Validated/CN=*.sugarsync.com
Client-SSL-Cipher: AES256-SHA
Client-SSL-Warning: Peer certificate not verified

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<authorization>
  <expiration>2011-08-31T05:15:57.516-07:00</expiration>
  <user>https://api.sugarsync.com/user/123456</user>
</authorization>

Most important is the Location: header of the result:

Location: https://api.sugarsync.com/authorization/Oz3odjluQU6n6RCA

This url (which is much longer than shown here) has to be passed as Authorization: header to all subsequent calls.

Note that it is only of limited validity, e.g., 1 hour.

Requests

When autorization is complete, further requests are common https: get requests. Almost all of them return XML data. For convenience, the XML data is shown here as a Perl structure.

WARNING: When transforming the XML to Perl (e.g., with XML::Simple) be careful about repeating entries. E.g.,

<foo>
 <bar>111</bar>
 <bar>222</bar>
<foo>

will return { foo => [ 111, 222 ] }, but

<foo>
 <bar>111</bar>
<foo>

will return { foo => 111 }

User info

Get https://api.sugarsync.com/user.

Returns:

    {
      'quota' => {
	 'usage' => '94055',
	 'limit' => '6039797760'
      },
      'salt' => 'C2c4DA==',
      'webArchive' => 'https://api.sugarsync.com/folder/:sc:123456:1',
      'publicLinks' => 'https://api.sugarsync.com/user/123456/publicLinks/contents',
      'mobilePhotos' => 'https://api.sugarsync.com/folder/:sc:123456:3',
      'nickname' => 'happyreader',
      'deleted' => 'https://api.sugarsync.com/folder/:sc:123456:9',
      'albums' => 'https://api.sugarsync.com/user/123456/albums/contents',
      'username' => 'happyreader@example.com',
      'receivedShares' => 'https://api.sugarsync.com/user/123456/receivedShares/contents',
      'magicBriefcase' => 'https://api.sugarsync.com/folder/:sc:123456:2',
      'workspaces' => 'https://api.sugarsync.com/user/123456/workspaces/contents',
      'syncfolders' => 'https://api.sugarsync.com/user/123456/folders/contents',
      'recentActivities' => 'https://api.sugarsync.com/user/123456/recentActivities/contents'
    };

receivedShares

Get the receivedShares url from the user info.

Returns:

    {
      'receivedShare' => [
	{
	  'owner' => 'https://api.sugarsync.com/contact/123456/654321',
	  'permissions' => {
	    'readAllowed' => {
	      'enabled' => 'true'
	    },
	    'writeAllowed' => {
	      'enabled' => 'false'
	    }
	  },
	  'timeReceived' => '2011-08-21T06:00:14.000-07:00',
	  'ref' => 'https://api.sugarsync.com/receivedShare/123456/:sc:654321:186_8178842',
	  'sharedFolder' => 'https://api.sugarsync.com/folder/:sc:654321:186_8178842',
	  'displayName' => 'boeken'
	}
      ]
    };

sharedFolder

Returns slightly more detailed data for the shared folder.

    {
      'sharing' => {
	'shareList' => 'https://api.sugarsync.com/sharelist/:sc:654321:186_8178842',
	'readAllowed' => {
	  'enabled' => 'true'
	},
	'writeAllowed' => {
	  'enabled' => 'false'
	},
	'enabled' => 'true'
      },
      'parent' => 'https://api.sugarsync.com/folder/:sc:654321:2',
      'files' => 'https://api.sugarsync.com/folder/:sc:654321:186_8178842/contents?type=file',
      'collections' => 'https://api.sugarsync.com/folder/:sc:654321:186_8178842/contents?type=folder',
      'contents' => 'https://api.sugarsync.com/folder/:sc:654321:186_8178842/contents',
      'dsid' => '/sc/654321/186_8178842',
      'timeCreated' => '2011-08-20T10:41:52.000-07:00',
      'displayName' => 'boeken'
    };

As all folders, the sharedFolder can contain files and collections (subfolders). Retrieving the contents link returns both files and folders:

    {
      'collection' => [
	{
	  'ref' => 'https://api.sugarsync.com/folder/:sc:654321:186_8179242',
	  'contents' => 'https://api.sugarsync.com/folder/:sc:654321:186_8179242/contents',
	  'type' => 'folder',
	  'displayName' => 'AA'
	},
	{
	  'ref' => 'https://api.sugarsync.com/folder/:sc:654321:4497561_97048',
	  'contents' => 'https://api.sugarsync.com/folder/:sc:654321:4497561_97048/contents',
	  'type' => 'folder',
	  'displayName' => 'BB'
	},
      ],
      'file' => {
          'fileData' => 'https://api.sugarsync.com/file/:sc:654321:4497561_327763/data',
          'lastModified' => '2011-08-28T23:03:48.000-07:00',
          'presentOnServer' => 'true',
          'mediaType' => 'application/octet-stream',
          'ref' => 'https://api.sugarsync.com/file/:sc:654321:4497561_327763',
          'size' => '695067',
          'displayName' => 'De woorden van Babel - Andreu Carranza.epub'
      },
      'hasMore' => 'false',
      'end' => '26',
      'start' => '0'
    };

This example shows one file and two collections. Note that files and collections may be returned as scalars instead of ARRAYs if there's only one element. See XML::Simple for details.

Also note the hasMore attribute, that (I assume) indicates whether all data was returned with this call. Likewise, start and end seem to indicate the first and last entry. I haven't found out what to do in case hasMore is true.

Collections

See sharedFolder,

Files

To retrieve file data, use a normal https get.

For a mirror, you might want to set the file times according to the lastModified attribute.

Miscellaneous

When the authorization token expires, you'll get a HTTP 401 Unauthorized result. Renew the token and retry.

Server errors like 503 Server unavailable may occur.