Uploading a File into Syncplicity using API

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

1. 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 the API Guide.

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: YOUR_APP_KEY_HERE" 

• Authorization
  • The security token that represents the user who is performing this action.
  • "Authorization: Bearer ACCESS_TOKEN_HERE" 

• User-Agent
  • An arbitrary description of your application.
  • "User-Agent: Syncplicity Client"

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

2. 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 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=f6aafa86202facc379cff353c3eefbecb6494658c91024637fccdda5f7ced6 
  • A valid session token
    • sessionKey=Bearer  YOUR_ACCESS_TOKEN_HERE
    • 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 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 Syncpoint to target for the upload, but we can also pass a relative path so that the file can be uploaded into a sub-foldercontained within the Syncpoint.
  • To upload into the top-level Syncpoint folder, use:
    • https://data.syncplicity.com/saveFile.php?filepath=name_of_file.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 the API Guide for information on 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 specified as 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.

Watch Out

Don't forget that this is still a 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 sub-folder path and file name. For example, spaces need to be replaced with %20.