Syncplicity

Getting started with Syncplicity REST APIs: Part 3

Syncplicity REST APIs part 3

Welcome to part 3 of my “Getting Started” guide for the Syncplicity REST APIs.

You will have most likely read and attempted to implement the preceding documents in this series:

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

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

Uploading a File

To upload a file into Syncplicity, you need to perform these steps:

  1. Authenticate
  2. Collect the metadata required to upload the file
  3. Upload the file

This sounds easy, but there are some details to be aware of…

Authenticate

Uploading a file via HTTP should be easy, but Syncplicity implements a lot of security. Luckily everything you need to know about getting the Authorization Tokens can be found in Part 1 and 2 of these guides.

When making the API call, the required Headers are:

  • Content Range
    • This specifies the range of bytes that will be uploaded. Syncplicity supports “chunking” but this is a topic for a later time. For now, you can specify the entire file by using the following nomenclature:
      • “Content-Range: 0-*/*”
  • 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 upload will fail with authentication errors.

Metadata Required for the File Upload

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

  • A POST Action
    • This should be self-explanatory but I’m highlighting it as it’s easy to forget. If you’re using a PUT, the upload won’t work.
  • Form Data
    • The POST action uses Form Data to upload the file and requires the following Form Fields:
      • A stream of the file data
        • fileData=<bytes of the actual file>
        • filename=name_of_file.txt
        • transfer-encoding=binary
        • type=application/octet-stream
      • The hash of the file
        • sha256=f6ab2afa86202facc379cff353c3eefbecb6494658c91024637fccdda5f7ced6
      • A valid session token
        • sessionKey=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==

      • Notice that this is identical to the token being used in the Header above.
      • The ID number of the Syncpoint being uploaded into
        • virtualFolderId=4584419
      • (OPTIONAL) the creation time of the file
        • creationTimeUtc=2016-11-14T16:27:52Z
        • If this field isn’t provided, then the current time will be used. If you want to retain the file’s original timestamp, then make sure you use this field!
      • (OPTIONAL) the last modification time of the file
        • lastWriteTimeUtc=2016-11-14T16:27:52Z
        • If this field isn’t provided, then the current time will be used. If you want to retain the file’s last modified timestamp, then make sure you use this field!
      • A tag to denote that this is the last part of the file
        • fileDone=
        • This is always set to “empty” or “nothing” to denote that this is the last part of the file.
        • It can be used to denote a partial “chunk” of a file, but this is a topic for a later time.
      • A URL/URI that indicates where to place the file
        • The Form Data (above) indicates which Syncpointto target for the upload, but we can also pass a relative path so that the file can be uploaded into a subfolder contained within the Syncpoint.
        • To upload into the top-level Syncpoint folder, use:
          • https://data.syncplicity.com/saveFile.php?filepath=txt
        • To upload into sub-folder within the Syncpoint, use:
          • https://data.syncplicity.com/saveFile.php?filepath=FolderA/Subfolder2/name_of_file.txt

So, using the required information above, you can see that before you can upload a file, you first need to gather the following information:

  • The ID of the target Syncpoint
    • See Getting Started With The Syncplicity REST APIs – Part 2 for how to get this.
  • The hash of the file
    • Use your awesome coding skills to get this.
  • (Optional) The creation and last modified timestamps of the original file
    • Only required if you want to preserve the current timestamps.
    • The timestamps need to be formatted in a specific format (UTC).
  • The sub-folder path that the file is to be placed into
    • Bear in mind that the top-level folder, for example, “Documents,” does NOT need to be specifiedas it is explicitly specified by the Syncpoint ID.
    • The path should denote the sub-folder below the Syncpoint that is being targeted.

Once you have all the above, you can perform the file upload.

CURL Example

Here is an example of curl performing an upload:

curl -vvvvv -sS -X POST -H “Content-Range: 0-/ -H “AppKey: c48107e6-f97a-436e-9b2b-2508e9f50da0” -H “Authorization: Bearer 8L9HDKPKUkE0sb05JDm5GQHw9VV6uBguHPUsR0MZjgtC1xKu3uDSUK” -H “User-Agent: Claudio Client” -F “fileData=@/path/to/NewPDFDocument1234.pdf;filename=NewPDFDocument1234.pdf;transfer-encoding=binary;type=application/octet-stream” -F “sha256=a0fafb4fbee451cc7df0857ef0769e04d3e1aa803ca0684f851085c7a8435c53” -F “sessionKey=Bearer 8L9HDKPKUkE0sb05JDm5GQHw9VV6uBguHPUsR0MZjgtC1xKu3uDSUK” -F “virtualFolderId=10080607” -F “creationTimeUtc=” -F “lastWriteTimeUtc=” -F “fileDone=” https://data.syncplicity.com/saveFile.php?filepath=/cases/NewPDFDocument1234.pdf

Highlighted in green are the parts collected above.

Watch Out!

Don’t forget that this is still an HTTP operation, so make sure you “escape,” or substitute, any special characters in the URL/URI being used to POST to. Read more about this at Percent-encoding – Wikipedia.

This does not need to be applied to any JSON or Form Data, just to the URL/URI, which happens to contain the subfolder path and file name.

Read more about additional APIs with Syncplicity.