Sharing API updates: error models and folder IDs change
On February 24, 2016, the beta sharing endpoints will see breaking changes in two areas: error structures are being reorganized and shared folder IDs are returning in a new format. Both changes are aimed at making error handling more straightforward and giving apps still on v1 endpoints a cleaner migration path.
Fine-grained errors for async job checks
Errors from sharing/check_job_status will now be grouped by route. Previously, a failure from any asynchronous operation surfaced through a generic error type, which made it hard to tell which operation had failed. Returning errors grouped by route lets different async routes raise their own route-specific errors without polluting the space of errors allowed by sharing/check_job_status.
Under the new scheme, JobError carries the following error tags:
unshare_folder_errorforsharing/unshare_folderjobsremove_folder_member_errorforsharing/remove_folder_memberjobs
The old versus new shapes of the error:
Old
JobError.access_error
JobError.member_errorNew
JobError.remove_folder_member_error
JobError.unshare_folder_errorFor example, if an unshare_folder job fails with the not_a_member error, sharing/check_job_status will return:
{
".tag": "failed",
"failed:": {
".tag": "unshare_folder_error",
"unshare_folder_error": {
".tag": "access_error",
"access_error": {
".tag": "not_a_member"
}
}
}
}SharedFolderAccessError narrowed to genuine access failures
Two tags are leaving SharedFolderAccessError: no_permission and team_folder. They move to the error unions associated with the specific sharing routes where they actually apply.
The rationale: SharedFolderAccessError is supposed to indicate that the user cannot access the shared folder at all. no_permission is used when a user can access the folder but cannot perform a given operation on it. Similarly, team_folder indicates that an operation does not apply to team folders — not that the folder itself is inaccessible.
Old
union SharedFolderAccessError
invalid_id
not_a_member
no_permission
email_unverified
team_folder
unmountedNew
union SharedFolderAccessError
invalid_id
not_a_member
email_unverified
unmountedRoutes that can raise the moved-in tags now include them directly. For example, AddFolderMemberError and UnshareFolderError include both no_permission and team_folder.
Affected routes:
sharing/add_folder_membersharing/mount_foldersharing/relinquish_folder_membershipsharing/remove_folder_membersharing/transfer_foldersharing/unmount_foldersharing/unshare_foldersharing/update_folder_membersharing/update_folder_policy
Three routes raise SharedFolderAccessError directly but are unaffected because neither no_permission nor team_folder applies to them:
sharing/get_folder_metadatasharing/list_folder_memberssharing/list_folder_members/continue
Raw shared folder IDs
The shared_folder_id and parent_shared_folder_id fields in API responses switch from an encoding string format (like dbsfid:BCcDKIi3BO5uA9Kzv1v7I9MBJiqoXZXx7Fo) to a raw ID string (like 123456). The raw format matches what v1 returns.
Routes affected by the ID change are those that 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
Until the migration is complete, these endpoints will accept both encoded and raw shared folder IDs on input:
/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
Encoded ID usage will be monitored, and support will be disabled once it drops off. If your app stores encoded shared folder IDs, migrate by calling /sharing/get_folder_metadata with the encoded IDs to fetch the raw ID for every stored folder.
Prefereable folder listing endpoint
A new set of endpoints — /sharing/list_mountable_folders and /sharing/list_mountable_folders/continue — now returns shared folders as shown on dropbox.com/share. These new endpoints should be preferred over /sharing/list_folders[/continue], which remains in beta.
