Breaking changes to beta sharing endpoints

[UPDATE December 11, 2015] The following breaking changes are now available in the SDKs.

We’re making some improvements to the sharing features currently in beta. Specifically, we’re introducing paging support, and a new shared folder membership endpoint. We’ve also made some changes to how member errors are reported, as well as some of the fields included in SharedFolderMetadata. These changes will not be backwards compatible, but will allow for better scalability and ease of use.

These updates are in our HTTP API, and our SDKs: Swift, Python, .NET, and Java.

New: List folders paging

Clients will no longer need to worry about slow response times and heavy responses for large sets of shared folders or shared folder members. These endpoints now support paging:

  • sharing/list_folders
  • sharing/list_folder_members

When querying the endpoints, responses will contain an optional cursor field that, when present, indicates there are more results to fetch from the server. Remaining results are available in the corresponding /continue endpoints. These endpoints accept a cursor, and return the next batch of results:

  • sharing/list_folders/continue
  • sharing/list_folder_members/continue

Breaking change to /list_folders

It is important that callers of sharing/list_folders update their logic to properly handle the optional cursor in listing responses, otherwise clients may only be processing partial results.

struct ListFoldersResult
    entries List(SharedFolderMetadata)
    cursor String?

New: Membership endpoint

In order to properly support paging across shared folder members, membership will be available through two new endpoints that support paging:

  • sharing/list_folder_members
  • sharing/list_folder_members/continue

Additionally, the members field in our shared folder membership responses will be renamed to users to be more consistent with the naming of other fields:

{
    "users": [
        {
            "access_type": {
                ".tag": "owner"
            }, 
            "user": {
                "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc", 
                "same_team": false
            }
        }
    ],
    "groups": [],
    "invitees": [],
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}

Breaking changes to /get_folder_metadata

To accommodate the new shared folder membership endpoint, the following breaking changes will be made to the sharing/get_folder_metadata endpoint:

  • Membership will no longer be returned as part of the response. Use the new shared folder membership endpoint to list members of a shared folder.
  • The include_membership request parameter will no longer be accepted.
  • BasicSharedFolderMetadata and FullSharedFolderMetadata response structures will be consolidated into a single response structure, SharedFolderMetadata.
  • The id response field will be renamed to shared_folder_id to be consistent with the rest of the beta sharing endpoints.

Below is an example of the new response structure:

{
    "access_type": {
        ".tag": "owner"
    }, 
    "shared_folder_id": "dbsfid:BCcDKIi3BO5uA9Kzv1v7I9MBJiqoXZXx7Fo", 
    "is_team_folder": false, 
    "name": "example", 
    "path_lower": "/example", 
    "policy": {
        "acl_update_policy": {
            ".tag": "editors"
        }, 
        "member_policy": {
            ".tag": "anyone"
        }, 
        "shared_link_policy": {
            ".tag": "anyone"
        }
    }
}

Renamed: Member errors

A few minor breaking changes will be made to some of our error structures and endpoint arguments:

  • All not_member error tags will be renamed to not_a_member
  • SharedFolderMemberError will be reused for common errors across:
    • sharing/update_folder_member
    • sharing/remove_folder_member

not_a_member Errors

We’ve renamed all not_member errors to not_a_member to be consistent across the beta sharing endpoints:

Old

SharedFolderAccessError.not_member
TransferFolderError.new_owner_not_member

New

SharedFolderAccessError.not_a_member
TransferFolderError.new_owner_not_a_member

Common Member Selector Errors

Some API routes allow performing an action on a target shared folder member using a member selector. These routes shared common error conditions for bad member selectors, but are not using a common, shared error structure. We will update the routes to use a common error format for errors when specifying a target member, the SharedFolderMemberError error type:

union SharedFolderMemberError
    invalid_dropbox_id
    not_a_member

Only two routes are affected:

sharing/remove_folder_member:
The asynchronous sharing/remove_folder_member route will have two of its error tags removed since they are redundant with the error tags already specified for asynchronous job failures (see JobError).

sharing/update_folder_member:
The sharing/update_folder_member route will have two of its error tags replaced with the common SharedFolderMemberError error type:

{
    "error_summary": "member_error/not_a_member/...",
    "error": {
        ".tag": "member_error",
        "member_error": {
            ".tag": "not_a_member"
        }
    }
}