Getting started with Syncplicity REST APIs: Part 4

Welcome to Part 4 of my “Getting Started” guide for the Syncplicity REST APIs. If you’re reading this, then you should have already read and attempted to implement the preceding documents in this series:

1. Getting started with the Syncplicity REST APIs: Part 1
2. Getting started with Syncplicity REST APIs: Part 2
3. Getting started with The Syncplicity REST APIs: Part 3

The information below builds upon the information provided in the documents above, so please refer to them before attempting the below!

Downloading a file

To download a file from Syncplicity, you need to perform these steps:

1. Authenticate
2. Collect the metadata required to download the file
3. Download the file

As usual, there are some details to be aware of in these three steps.

Authenticate

As documented in the previous guides, you first need to be authenticated to collect the metadata and download the file. Everything you need to know about getting the Authorization Tokens can be found in Part 1 and Part 2 of this guide.

When making the download API call, the required Headers are:

• AppKey
  • The App Key of your API application.
    • “AppKey: WdVTG3ak9CS717BTgZiLZNxYAFTW2sfW”
  • Authorization
    • The security token that represents the user who is performing this action.
      • “Authorization: Bearer U2FsdGWkX1/KR9Hm3nuwyJssqB6aXcscoSSzxQi4QGjx3GJV3SGt/w52PJb2VC1/ygOZiuSmf7D4MVbeOfStEeHFGXdrBojOEmAtC1ulDK92Ui8SWzCtXJpJ/g035tFoXzGTrVSSFu6xYuKfPxhEzv1qvFER/LeF3UoovZONmb0Nvt726jpsdrEUNc2bXBQGbO0fhTLHwamgdtxtpaSr9zDjE2/Vqsm/dc3qw6sErqisvr6KkUeVXvlcDJLzJwTJmenO6xIJcFzWXOlGVqfdGJNkHBzrsz1K4G6bn3il07fDamJqLPfvMWmMmx7HGWKbEjWFYhG4Yr4HTNjI6zS2LbJiCyBhLqEznoH1hpfhePW2ye8zM4cRelBZ0WqylpO5Jz3zrU21zN+RUF56XOBZaEF2S49YwgcdfwvW/TmWIYhE8BTw6htprH0UUe3rKOfi12N/3uPFEedVzjlmZjD3OK7AkWuZYqUMtKsIBsfq3cYGeMr26wXtRx7DTwtynsyV+xyglkcVcuK8KVjUI1V3BxV7onmc2nNGAeN58jU/Utt98EqOEcJE0oeG+vA/6qF1IZlV85KyDEEPCM6/rL6XhQUd17cSUFH0wvStBQe8om/CAVXgAF1Wy/IvugCj0L/3zVF4wpRhoMj+4/H5jGJ4QDyVrjzGEoBFz1fDdpNTlG/e+W1pY/m5jwoNah7kiGULuWWg2s3zkMJpLqQZUuCkvQkdIxjsg/QoDYlBE0WHBmKIRz+zJLhZ6zqxYwhyowd6HG3/k96PTqXp0jMUr7xRj9nh7YRRZv5iKe6FvTq7ZQ5uEtwktUwTSw==”
    • User-Agent
      • An arbitrary description of your application.
        • “User-Agent: Claudio Client”

If any of the above Headers are missing, the download will fail with authentication errors.

You should have collected the above items by following the steps outlined in the prior parts of this guide.

Metadata required for the file download

The download URL for any file held within Syncplicity is constructed like this: https://storagevault_url/retrieveFile.php?vToken=syncpointid–latestversionid

As you can see, there are only three pieces of metadata (in GREEN above) that need to be provided:

1. storagevault_url
   • This is the URL that points to the Syncplicity StorageVault where the file is located. For example, the URL for the Syncplicity US Cloud is syncplicity.comwhereas an on-premise StorageVault URL might be syncp.mycompany.com instead. Bear in mind that this URL could also include the port number if the default TLS/SSL port (443) isn’t being used. For example: syncp.mycompany.com:9443
2. syncpointid
   • This is the ID of the syncpoint that the file resides in.
3. latestversionid
   • This is the version ID of the file so that, if it has prior versions, you can download the exact version that you need.

As you can see, no filename is passed in the URL so the only way to download a file is to know the metadata.

Here is how to collect the metadata:

syncpointid

• Make an API call to https://api.syncplicity.com/syncpoint/syncpoints.svc/to get a list of your syncpoints.
  • Refer to the documentation at Syncplicity Developers | API Documentationor in Getting Started With The Syncplicity REST APIs: Part 2.
  • In the API response, you’ll want to parse out the following items:
    • Id– this is the ID of the syncpoint, e.g. 5698124
    • Name– this is the name of syncpoint and corresponds with the top-level folder name, e.g. “Claudio’s API Files”
    • RootFolderId– this is the ID of the top-level folder within the syncpoint, e.g. 264841158
    • StorageEndpointId– this is the ID of the StorageVault that contains this syncpoint and the files within it, e.g. “11111111-1111-1111-1111-111111111111”

The Id returned above is the syncopated that you need.  Compare the Name values for the syncpoint folder that you want to look in and capture the corresponding Id value.

latestversionid

• Using the results collected above, make an API call to https://api.syncplicity.com/sync/folder_files.svc/syncpointid/folder/folderid/files?include=activeto get a list of files.
  • Refer to the documentation at Syncplicity Developers | API Documentation
  • Use the Idfrom above as the syncpointid and the RootFolderId as the folderid in the above API URL.
  • In the API response, you’ll want to parse out the following items:
    • Filename– obviously, the name of the file, e.g. “SomeFile.docx”
    • LatestVersionId– the ID of the latest version of this file, e.g. 999211663

The LatestVersionId is what you need to download this file. Compare the Filename value for the name of the file that you want to download and capture the corresponding LatestVersionId value.

storagevault_url

• Make an API call to https://api.syncplicity.com/storage/storageendpoints.svc/
  • Refer to the documentation at Syncplicity Developers | API Documentation
  • In the API response, you’ll want to parse out the following items:
    • Id– the ID of the StorageVault, e.g. “11111111-1111-1111-1111-111111111111”
    • Url– the URL of this StorageVault, e.g. “https://data.syncplicity.com”

The Urls.Url value is the URL that you need to make the download API request to. Compare the Id value with the StorageEndpointId value that you retrieved earlier (when you looked up the syncpoints) so that you get the corresponding URL for the syncpoint that you are targeting.

File download

Now that you have all the metadata that you need to perform a file download. Refer to the Syncplicity Dev Page for more information.

The Syncplicity service running on the StorageVault Connectors expects the following:

• A GET Action
  • This should be self-explanatory.
• Authentication Headers
  • Refer to the “Authenticate” section at the top of this article.
• A URL that indicates which file to download
  • The format of the URL is: https://storagevault_url/retrieveFile.php?vToken=syncpointid–latestversionid
  • Use the metadata values collected above to populate this URL.
  • NOTE: there is a hyphen ( – ) placed between the syncpointidand the latestversionid.

A successful API call will return a “200” HTTP response and the file contents will stream down for you to save.