Syncplicity

Introducing additional APIs for Syncplicity

Syncplicity API

As many of you know, Syncplicity has rich REST APIs to give access to content, as well as to administrative capabilities. My previous blog on Syncplicity APIs gives a good overview of these and explains how they can be used to provide a rich integration of Syncplicity with other applications.

Syncplicity API

The 2019 Q4 release of the Syncplicity APIs includes several additional APIs to cover other use cases. These APIs provide the capability to:

  • Rename files and folders
  • Search files and folders
  • Support tagging and extensible metadata support
  • Provide Legal Hold
  • Support Syncplicity Rights Management

This blog will take a closer look at this new functionality:

Rename files and folders

The ability to rename files and folders was introduced in the web UI some time back, and this functionality is now also available via the API. The documentation for renaming files and folders in the web UI explains the different possible scenarios, especially concerning the renaming of folders that are synchronized with a PC or Mac.

Now there is one cool feature with this API not available via the web UI: the ability to move files and folders! When renaming a file or folder via the API, one of the input parameters is “FolderId”; which determines the folder in which the renamed object will be placed. By specifying a different folder ID to the current one, you can move the file or folder. Very useful! I’m certain this API will be used as much for moving as for renaming files and folders.

Note: You can only move files and folders within a Syncpoint, not across Syncpoints. There is a reason for this: Syncpoints are mostly top-level folders, and different organizations can own these, stored in different locations, etc.

The APIs for renaming files and folders can be found here:

  • Folder rename API: under “Folders”, then “/sync/folder.svc/{SYNCPOINT_ID}/folder”
  • File rename API: under “Files”, then “/sync/file.svc/{SYNCPOINT_ID}/file”

The API documentation for renaming files and folders is available here.

Search files and folders

If you look at the API docs for the search API, you will be disappointed, it’s not there. The reason for this is that, as for the object moving described above, different Syncpoints can reside in different locations and be owned by different organizations. The index for the search is therefore related to the specific Syncpoint, so to use the search API, you first need to call the “get Syncpoint” API, which will return the search API URL to use. Once you have that, you can call that URL to search either on metadata, or full text.

As with the web UI, you can filter by file size, type, date, owner, tags, etc. If you are using the search API across different Syncpoints, you will need to call the relevant search API for each Syncpoint, then merge the responses. The documentation for searching files and folders in the Developer Portal explains how to best do this.

Tagging and extensible metadata support

Within Syncplicity, files and folders can be tagged with keywords. When used in conjunction with the search, this provides a rich way of finding the exact information you need. For example, if you tag documents with the name of the client or product that they relate to, it makes finding that information via the search very simple. However, you can imagine that trying to tag dozens (or more) of documents or folders manually will be a tedious and error-prone process. Using the API to set or use tags will provide the following advantages:

  • The mass setting of tags based on certain criteria (ownership, folder, full-text search, etc.)
  • Automatic setting of tags when documents are uploaded
  • Easy searching for all content with specific tags

Note that the tagging functionality (like the search functionality) may not be available in your instance of Syncplicity unless you have requested this to be turned on (which you can do by sending a mail to support@syncplicity.com). Read more about categorizing your APIs, tips and tricks.

Review the API documentation for tagging for more information and find the APIs for tagging files and folders here:

  • File tagging APIs: under “Files/Folder Metadata” then “/syncpoint/{SYNCPOINT_ID}/file/{FILE_ID}/tags”
  • Folder tagging APIs: under “Files/Folder Metadata” then “/syncpoint/{SYNCPOINT_ID}/folder/{FOLDER_ID}/tags”

The Syncplicity documentation page explains the different rules for tagging content.

Legal Hold

Organizations may be legally obliged to retain documents for regulatory or other legal reasons. If the legal department suspects that this content may be maliciously or accidentally deleted, it has the possibility of placing a legal hold on the documents, thus preventing their physical deletion. This functionality is available in the web UI for users with an “eDiscovery” role (see the Syncplicity Legal holds page for more info).

This same functionality is now available via the API, with the addition of a new API: “/provisioning/legal_holds.svc/”. This API allows for a GET (to retrieve a list of all current legal holds in the instance), a POST (to create a legal hold for all content for a specific user), and a DELETE (to remove a specific legal hold). This API is destined to be used by companies wanting to incorporate legal holds in Syncplicity within more general applications used to manage the legal access to content. The

Syncplicity Rights Management

Last but not least in the list of API enhancements for this release is the support for Syncplicity Rights Management. Syncplicity Rights Management extends the protection of shared files by determining which actions the recipient can take on the file (print, copy, download, screen capture, etc.), and allowing the sender to revoke access at any time.

As far as the APIs are concerned, this functionality is provided via additional parameters for the shared links API (“/syncpoint/links.svc/”). The POST method (used when creating a shared link) now allows for indicating that Syncplicity Rights Management is to be used (“IsIrmProtected” set to true), and the role for the recipient (“IrmRoleType” set to either 1 (reader) or 2 (editor)). The GET method returns these settings when accessing an existing shared link. For even more information, read our API documentation for using Syncplicity Rights Management.

Updated documentation of Developer Portal

Besides the above, this release contains many additions to the documentation on the Developer Portal, to help developers get to grips with the use of these comprehensive APIs to access Syncplicity programmatically.

If you have questions regarding the use of the API, please post them in the Axway community.

Happy coding against the Syncplicity API!

View the Syncplicity API release notes.