More breaking changes to beta sharing endpoints

We are making breaking changes to the beta sharing endpoints, which will take effect as of February 24th, 2016:

1. Reorganizing some error structures
   
   
2. Changing the format of shared folder IDs

These changes help make error handling more intuitive and provide a better migration path for apps still using v1 endpoints.

We’re improving and reorganizing the error structures for the beta sharing endpoints. For apps handling errors, changes will not be backwards compatible, but they will make error handling more intuitive in the future, especially as more features are added.

Errors returned by sharing/check_job_status will be grouped by route, to make it clear what type of asynchronous job failed and to allow for route-specific errors. This change will allow different asynchronous routes to raise different errors, without affecting the error types allowed by sharing/check_job_status.

JobError will include the following error tags:

• unshare_folder_error for sharing/unshare_folder jobs
  
  
• remove_folder_member_error for sharing/remove_folder_member jobsOld

Old

JobError.access_error
JobError.member_error

New

JobError.remove_folder_member_error
JobError.unshare_folder_error

Here’s what sharing/check_job_status will return if sharing/unshare_folder_error fails with the not_a_member error:

{
  ".tag": "failed",
  "failed:": {
    ".tag": "unshare_folder_error",
    "unshare_folder_error": {
    ".tag": "access_error",
    "access_error": {
      ".tag": "not_a_member"
      }
    }
  }
}

We’re taking the error tags no_permission and team_folder out of SharedFolderAccessError, and moving them to error unions associated directly with specific sharing endpoints.

We’re doing this because SharedFolderAccessError should mean that the user cannot access the shared folder. We use no_permission to mean that the user cannot perform a particular operation on a shared folder, but the user may actually be able to access the shared folder. Similarly, team_folder means that a particular operation is not applicable for team folders, not that the user cannot access this folder.

Old

union SharedFolderAccessError
  invalid_id
  not_a_member
  no_permission
  email_unverified
  team_folder
  unmounted

New

union SharedFolderAccessError
  invalid_id
  not_a_member
  email_unverified
  unmounted

We have added no_permission and team_folder to the error types of applicable routes. For example, AddFolderMemberError and UnshareFolderError now include no_permission and team_folder.

The following routes are affected:

• sharing/add_folder_member

• sharing/mount_folder
• sharing/relinquish_folder_membership
• sharing/remove_folder_member
• sharing/transfer_folder
• sharing/unmount_folder
• sharing/unshare_folder
• sharing/update_folder_member
• sharing/update_folder_policy

The following routes raise SharedFolderAccessError directly, but they are not affected because no_permission and team_folder do not apply.

• sharing/get_folder_metadata
• sharing/list_folder_members
• sharing/list_folder_members/continue

We are changing the tags shared_folder_id and parent_shared_folder_id in the API response from an encoding string( dbsfid:BCcDKIi3BO5uA9Kzv1v7I9MBJiqoXZXx7Fo) to a raw id string( 123456). This is equivalent to the id returned in API v1.

The following routes are affected as they return shared_folder_id or parent_shared_folder_id:

• /files/copy
• /files/create_folders
• /files/delete
• /files/download
• /files/get_metadata
• /files/get_preview
• /files/get_thumbnail
• /files/list_folders
• /files/list_folders/continue
• /files/move
• /files/restore
• /files/search
• /files/upload
• /files/upload_session/finish
• /sharing/check_share_job_status
• /sharing/get_folder_metadata
• /sharing/list_folders
• /sharing/list_folders/continue
• /sharing/mount_folder
• /sharing/share_folder
• /sharing/update_folder_policy

To facilitate migration, the following endpoints will accept both encoded and raw shared folder ID:

• /sharing/add_folder_member
• /sharing/get_folder_metadata
• /sharing/list_folder_members
• /sharing/mount_folder
• /sharing/relinquish_folder_membership
• /sharing/remove_folder_member
• /sharing/transfer_folder
• /sharing/unmount_folder
• /sharing/unshare_folder
• /sharing/update_folder_member
• /sharing/update_folder_policy

We will monitor usage of encoded shared folder IDs and disable support once usage has stopped.

If your app stores encoded shared folder IDs, you should migrate to the raw IDs by calling /sharing/get_folder_metadata with the encoded IDs to retrieve the raw ID for each stored folder.

We are introducing a new pair of endpoints, /sharing/list_mountable_folders and /sharing/list_mountable_folders/continue, which return a list of shared folders that more closely matches the shared folders shown on dropbox.com/share. These new endpoints should be preferred over the current /sharing/list_folders[/continue] pair, which will remain in beta.