Syncplicity

Getting started with Syncplicity REST APIs: Part 2

Syncplicity REST APIs: Part 2

You may have read part 1 of my series, “Getting started with Syncplicity REST APIs” and now want to try some real API calls. Well, you’ve come to the right place!

Syncplicity REST APIs: Part 2

I’m sure you want to start uploading and downloading files (using the Content APIs) but let’s walk before we try to run by first using the Provisioning APIs. These Provisioning APIs let you manipulate Users, Groups, Policies and other administration type tasks, and are easier to get started with than the Content APIs.

There are many examples on the Developer Portal but I’ll use the “Get Users” API for this example.

Get Users

Looking at the documentation, you can see that the URL to use for this is:

https://api.syncplicity.com/provisioning/company_users.svc/company/{companyID}/users

It seems easy, but the {companyID} isn’t a simple text string, like “Axway,” but rather the hidden unique ID that is embedded in your OAuth token. Luckily, getting this is already documented in Getting Started With The Syncplicity REST APIs, so we can start building our code.

I’m a BASH and cURL guy, so here’s some shell script for you to play with…

First, let’s set some variables for our Key, Secret and user Token:

appkey=”YOUR APP KEY HERE”
appsecret=”YOUR APP SECRET HERE”
usersyncapptoken=”YOUR ADMIN USER APP TOKEN HERE”

To use your Key and Secret, you need to base64 encode them first, with a colon separator:

oauthbasic=$(echo -n “${appkey}:${appsecret}” | base64)

Now we can make the cURL call to login with the above credentials:

oauthresult=$(curl -sS -X POST https://api.syncplicity.com/oauth/token -H ‘Authorization: Basic ‘${oauthbasic} -H “Sync-App-Token: ${usersyncapptoken}” -d ‘grant_type=client_credentials’)

This will return something like this:

{
“issued_at”:”1457653432956”,
“scope”:”readwrite read”,
“user_company_id”:”8c1212c9-1e54-4ce1-b9fd-6f826f2582c3”,
“expires_in”:”5099”,
“user_email”:””,
“organization_id”:”0”,
“token_type”:”BearerToken”,
“client_id”:”WdVRG3ak9CS717BTgZiLZMxYAFTW2sfW”,
“access_token”:”OJnEotf5AhWpM3qsumDG3O8YpBIW”,
“organization_name”:”syncplicity”,
“application_id”:”58497e23-b3cb-4f17-a6e7-e25cca808214”
}

 

The two parts we need are highlighted in green. The “access_token” is the Bearer Token that you’ll need to use to authorize your API calls. The “user_company_id” is the unique ID that represents your company’s Syncplicity account. We just need to capture those into variables:

accesstoken=$(echo ${oauthresult} | sed -e ‘s/[{}”]/”/g’ | awk -v RS=’,’ -F: ‘/access_token/ {print $2}’)
companyID=$(echo ${oauthresult} | sed -e ‘s/[{}”]/”/g’ | awk -v RS=’,’ -F: ‘/user_company_id/ {print $2}’)

If the above doesn’t work, because it’s using basic Bash built-in capabilities, then use the ‘jq’ command instead. You may need to install ‘jq’ on your system by going to https://stedolan.github.io/jq/ and following the instructions there.  The ‘jq’ version of the above lines are:

accesstoken=$(echo ${oauthresult} | jq -r ‘.access_token’)
companyID=$(echo ${oauthresult} | jq -r ‘.user_company_id’)

Now we have everything we need to make our API call to list the users so we can invoke cURL like this:

curl -sS -X GET -H “Accept: application/json” -H “Content-Type: application/json” -H “AppKey: ${appkey}” -H “Authorization: Bearer ${accesstoken}” https://api.syncplicity.com/provisioning/company_users.svc/company/${companyID}/users

And the above will return the users in your Syncplicity Enterprise account, like this:

 

[
{
“Active”: true,
“EmailAddress”: “claudio-apidev@moonlife.com”,
“FirstName”: “Claudio”,
“Id,”: “de6f3bc1-87a3-47a2-a5d7-714d24f6bf52”
“LastName”: “Tinnirello,”,
“Roles”: [
1,
2
],
“Status”: 2
},
{
“Active”: true,
“EmailAddress”: “someemail@somewhere.com”,
“FirstName”: “Joe”,
“Id”: “2a960a07-05da-4c3f-86db-1463e0ae265a”
“LastName”: “Anybody,”,
“Roles”: [],
“Status”: 5
}
]

 

Now that you’ve successfully made an API call to Syncplicity, you can move forward with the content-based APIs…

Content APIs

Before you can upload and download files, you must first understand how to access Syncplicity’s folders.  Not all folders are equal! Each folder is referenced by its ID, not its name, and the top-level folder is also referred to as a “Sync Point.”  Users can have multiple Sync Points, in which each Sync Point can contain multiple folders and sub-folders.

Sync Points

Whenever I add a new top-level folder to Syncplicity, it becomes a Sync Point which may or may not be currently syncing to my desktop. For example, if I add the following folders to Syncplicity, then each will be a Sync Point:

  • My Documents
  • My Pictures
  • SomeRandomFolder

In addition, any folders that have been shared with me are also Sync Points. For example:

  • PicsFromPatty
  • FilesFromFred

Folders

Within each Sync Point, there is a “top-level” folder.  This folder has the same name as the Syncpoint but also has a unique Folder ID which is different from its Sync Point ID.

All other sub-folders have unique Folder IDs but, like the top-level folder, they all exist under a specific Sync Point.  A folder’s Folder ID is unique, but multiple folders can have the same Sync Point ID.

For example:

FolderSync Point IDFolder ID
My Documents11111
My Documents/Personal12222
PicsFromPatty21111
PicsFromPatty/CustomerEvents/2016/June/SF29999

 

NOTE: I’m not 100% sure if Folder IDs are unique (no two folders can have the same ID) or if they’re just unique within a Sync Point (folders in different Sync Points can have identical IDs) so don’t assume anything from the above example!

The reason I’m explaining this is that most of the Content API calls require you to specify both the Sync Point ID and the Folder ID that you’re trying to target, so be aware of the differences in the two so that you don’t inadvertently confuse the two.

To start using the Content API to list the files and folders in Syncplicity, you’ll need to start at the top-level folder and traverse down the folder hierarchy from there.  You can get both the Sync Point ID and the top-level Folder ID by using the GET Syncpoints API.

Get Syncpoints

You can use the same code as above to get your OAuth token:

appkey=”YOUR APP KEY HERE”
appsecret=”YOUR APP SECRET HERE”
usersyncapptoken=”YOUR ADMIN USER APP TOKEN HERE”

oauthbasic=$(echo -n “${appkey}:${appsecret}” | base64)

oauthresult=$(curl -sS -X POST https://api.syncplicity.com/oauth/token -H ‘Authorization: Basic ‘${oauthbasic} -H “Sync-App-Token: ${usersyncapptoken}” -d ‘grant_type=client_credentials’)

accesstoken=$(echo ${oauthresult} | sed -e ‘s/[{}”]/”/g’ | awk -v RS=’,’ -F: ‘/^access_token/ {print $2}’)
companyID=$(echo ${oauthresult} | sed -e ‘s/[{}”]/”/g’ | awk -v RS=’,’ -F: ‘/^user_company_id/ {print $2}’)

Now we can invoke cURL like this:

curl -sS -X GET -H “Accept: application/json” -H “Content-Type: application/json” -H “AppKey: ${appkey}” -H “Authorization: Bearer ${accesstoken}” https://api.syncplicity.com/syncpoint/syncpoints.svc/

And the above will return the Sync Points, like this (see bold items for Sync Point ID and top-level Folder ID):

[
{
  “Id”: 3557411,
“Type”: 6,
“Name”: “My Documents,”
  “RootFolderId”: 36744204,
“Mapped”: false,
“DownloadEnabled”: true,
“UploadEnabled”: true,
“Shared”: true,
“Owner”: {
“Id”: “de6f3bc1-88a3-46a2-a5d7-714d24f6bf52”,
“EmailAddress”: “claudio-apidev@moonlife.com”,
“FirstName”: “Claudio”,
“LastName”: “Tinnirello”,
“Company”: {
“Id”: “8c1211c9-1e54-4ce1-b9fd-6f826f2582c3”,
“Name”: “Moonlife”
}
},
“Permission”: 1,
“Mappings”: [],
“Policy”: {
“RemoteWipeSyncpointPolicy”: 1,
“ResharingPolicy”: 3,
“ShareLinkPolicy”: 3,
“ShareLinkPasswordProtectedPolicy”: 1,
“ShareLinkPasswordComplexity”: 1,
“ShareLinkPasswordLength”: 6,
“ShareLinkExpirationPolicy”: 2,
“ShareLinkExpireInDays”: 6,
“StoragePasswordPolicy”: 2,
“StoragePasswordComplexityPolicy”: 2,
“StoragePasswordComplexity”: {
“Options”: 6,
“MinimumLength”: 8
},
“StorageCookiePersistancePolicy”: 2,
“DesktopShareLinkFlowPolicy”: 2,
“SFSCreationPolicy”: 2,
“WopiPolicy”: 2
},
“StorageEndpointId”: “11111111-1111-1111-1111-111111111111”,
“PathToRoot”: “\\”,
“ServiceState”: {
“Status”: 1
},
“SyncpointSize”: 129209968,
“ResharingPermission”: 1,
“NotifyAboutResharing”: false,
“EffectivePermission”: 1,
“EventServerId”: “11111111-1111-1111-1111-111111111111”
}
{
  “Id”: 6187591,
“Type”: 6,
  “Name”: “PicsFromPatty”,
  “RootFolderId”: 131888965,
“Mapped”: false,
“DownloadEnabled”: true,
“UploadEnabled”: true,
“Owner”: {
“Id”: “de6f3bc1-88a3-46a2-a5d7-714d24f6bf52”,
“EmailAddress”: “claudio-apidev@moonlife.com”,
“FirstName”: “Claudio”,
“LastName”: “Tinnirello”,
“Company”: {
“Id”: “8c1211c9-1e54-4ce1-b9fd-6f826f2582c3”,
“Name”: “Moonlife”
}
},
“Permission”: 1,
“Mappings”: [],
“Policy”: {
“RemoteWipeSyncpointPolicy”: 1,
“ResharingPolicy”: 3,
“ShareLinkPolicy”: 3,
“ShareLinkPasswordProtectedPolicy”: 1,
“ShareLinkPasswordComplexity”: 1,
“ShareLinkPasswordLength”: 6,
“ShareLinkExpirationPolicy”: 2,
“ShareLinkExpireInDays”: 6,
“StoragePasswordPolicy”: 2,
“StoragePasswordComplexityPolicy”: 2,
“StoragePasswordComplexity”: {
“Options”: 6,
“MinimumLength”: 8
},
“StorageCookiePersistancePolicy”: 2,
“DesktopShareLinkFlowPolicy”: 2,
“SFSCreationPolicy”: 2,
“WopiPolicy”: 2
},
“StorageEndpointId”: “11111111-1111-1111-1111-111111111111”,
“PathToRoot”: “\\”,
“ServiceState”: {
“Status”: 1
},
“SyncpointSize”: 60208503,
“ResharingPermission”: 1,
“NotifyAboutResharing”: false,
“EffectivePermission”: 1,
“EventServerId”: “11111111-1111-1111-1111-111111111111”
}
]

 

Now that you have the Sync Point IDs, you can make API calls for any folder contained in any of these Sync Points. Feel free to try the “GET all folders from a syncpoint” API call next. You can find the details for that API call at https://developer.syncplicity.com/apis.

Whose Sync Points?

The above API call will return the Sync Points of the user whose API Token you used. Use a different Token and you’ll see different Sync Points which highlights how important it is to never share your user Token with anyone else!

To see another user’s Sync Points, you’ll need to:

  • Be a “Global Administrator” type user with elevated privileges to use the API.
    • See Admin -> User Accounts -> select a Global Administrator role user-> Privileges.
    • Make sure the privilege is set to “Access content on behalf of managed users through API.
    • Use the “As-User” API Header to specify which user you want to act on behalf of.
      Refer to the Content API Guide as this goes beyond the scope of this document.
    • Or you can circumvent these restrictions by using built-in Syncplicity functionality:
      • Ask the other user to “share” their folder with your API account and give you “Editor” rights to it.
        • Now, you can access their Sync Point using your Token as you’ve been given “Editor” rights.

Learn more about introducing additional APIs for Syncplicity.