123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659 |
- namespace sharing
- import common
- import files
- import users
- alias PathOrId = String(pattern="((\/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?", min_length=1)
- alias FileId = String(pattern="id:.*", min_length=1)
- ###########################################
- # Generic route error related definitions #
- ###########################################
- union SharingUserError
- "User account had a problem preventing this action."
- email_unverified
- "The current user must verify the account e-mail address before performing this action."
- union SharingFileAccessError
- "User could not access this file."
- no_permission
- "Current user does not have sufficient privileges to perform the desired action."
- invalid_file
- "File specified was not found."
- is_folder
- "A folder can't be shared this way. Use folder sharing or a shared link instead."
- inside_public_folder
- "A file inside a public folder can't be shared this way. Use a public link instead."
- inside_osx_package
- "A Mac OS X package can't be shared this way. Use a shared link instead."
- union FileErrorResult
- file_not_found_error files.Id
- "File specified by id was not found."
- invalid_file_action_error files.Id
- "User does not have permission to take the specified action on the file."
- permission_denied_error files.Id
- "User does not have permission to access file specified by file.Id."
- #############################################
- # File metadata and permissions definitions #
- #############################################
- union FileAction
- "Sharing actions that may be taken on files."
- disable_viewer_info
- "Disable viewer information on the file."
- edit_contents
- "Change or edit contents of the file."
- enable_viewer_info
- "Enable viewer information on the file."
- invite_viewer
- "Add a member with view permissions."
- invite_viewer_no_comment
- "Add a member with view permissions but no comment permissions."
- unshare
- "Stop sharing this file."
- relinquish_membership
- "Relinquish one's own membership to the file."
- share_link
- "This action is deprecated. Use create_link instead."
- create_link
- "Create a shared link to the file."
- example default
- edit_contents = null
- struct FilePermission
- "Whether the user is allowed to take the sharing action on the file."
- action FileAction
- "The action that the user may wish to take on the file."
- allow Boolean
- "True if the user is allowed to take the action."
- reason PermissionDeniedReason?
- "The reason why the user is denied the permission. Not present if the action
- is allowed."
- example default
- action = edit_contents
- allow = false
- reason = user_not_same_team_as_owner
- struct SharedFileMetadata
- "Properties of the shared file."
- access_type AccessLevel?
- "The current user's access level for this shared file."
- id FileId
- "The ID of the file."
- expected_link_metadata ExpectedSharedContentLinkMetadata?
- "The expected metadata of the link associated for the file when it is first shared.
- Absent if the link already exists. This is for an unreleased feature so it may not be
- returned yet."
- link_metadata SharedContentLinkMetadata?
- "The metadata of the link associated for the file. This is for an unreleased feature so
- it may not be returned yet."
- name String
- "The name of this file."
- owner_team users.Team?
- "The team that owns the file. This field is not present if the file
- is not owned by a team."
- parent_shared_folder_id common.SharedFolderId?
- "The ID of the parent shared folder. This field is present only if the
- file is contained within a shared folder."
- path_display String?
- "The cased path to be used for display purposes only. In rare instances
- the casing will not correctly match the user's filesystem, but this
- behavior will match the path provided in the Core API v1.
- Absent for unmounted files."
- path_lower String?
- "The lower-case full path of this file. Absent for unmounted files."
- permissions List(FilePermission)?
- "The sharing permissions that requesting user has on this file. This
- corresponds to the entries given in :field:`GetFileMetadataBatchArg.actions`
- or :field:`GetFileMetadataArg.actions`."
- policy FolderPolicy
- "Policies governing this shared file."
- preview_url String
- "URL for displaying a web preview of the shared file."
- time_invited common.DropboxTimestamp?
- "Timestamp indicating when the current user was invited to this shared file. If the user was
- not invited to the shared file, the timestamp will indicate when the user was invited to the
- parent shared folder. This value may be absent."
- example default
- policy = default
- permissions = []
- owner_team = default
- preview_url = "https://www.dropbox.com/scl/fi/fir9vjelf"
- path_lower = "/dir/file.txt"
- path_display = "/dir/file.txt"
- name = "file.txt"
- id = "id:3kmLmQFnf1AAAAAAAAAAAw"
- time_invited = "2016-01-20T00:00:00Z"
- access_type = viewer
- union ViewerInfoPolicy
- enabled
- "Viewer information is available on this file."
- disabled
- "Viewer information is disabled on this file."
- ##################################
- # File membership mutation types #
- ##################################
- struct FileMemberActionResult
- "Per-member result for :route:`add_file_member` or :route:`change_file_member_access`."
- member MemberSelector
- "One of specified input members."
- result FileMemberActionIndividualResult
- "The outcome of the action on this member."
- union_closed FileMemberActionIndividualResult
- success AccessLevel?
- "Member was successfully removed from this file. If AccessLevel is given,
- the member still has access via a parent shared folder."
- member_error FileMemberActionError
- "User was not able to perform this action."
- example default
- success = null
- union FileMemberRemoveActionResult
- success MemberAccessLevelResult
- "Member was successfully removed from this file."
- member_error FileMemberActionError
- "User was not able to remove this member."
- union AddFileMemberError
- "Errors for :route:`add_file_member`."
- user_error SharingUserError
- access_error SharingFileAccessError
- rate_limit
- "The user has reached the rate limit for invitations."
- invalid_comment
- "The custom message did not pass comment permissions checks."
- union RemoveFileMemberError
- "Errors for :route:`remove_file_member_2`."
- user_error SharingUserError
- access_error SharingFileAccessError
- no_explicit_access MemberAccessLevelResult
- "This member does not have explicit access to the file and therefore cannot be removed.
- The return value is the access that a user might have to the file from a parent folder."
- union FileMemberActionError
- invalid_member
- "Specified member was not found."
- no_permission
- "User does not have permission to perform this action on this member."
- access_error SharingFileAccessError
- "Specified file was invalid or user does not have access."
- no_explicit_access MemberAccessLevelResult
- "The action cannot be completed because the target member does not have explicit access
- to the file. The return value is the access that the member has to the file from a parent folder."
- #####################
- # Route Definitions #
- #####################
- route add_file_member(AddFileMemberArgs, List(FileMemberActionResult), AddFileMemberError)
- "Adds specified members to a file."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- struct AddFileMemberArgs
- "Arguments for :route:`add_file_member`."
- file PathOrId
- "File to which to add members."
- members List(MemberSelector)
- "Members to add. Note that even an email address is given, this
- may result in a user being directy added to the membership if that
- email is the user's main account email."
- custom_message String?
- "Message to send to added members in their invitation."
- quiet Boolean = false
- "Whether added members should be notified via device notifications of
- their invitation."
- access_level AccessLevel = viewer
- "AccessLevel union object, describing what access level we want to give new members."
- add_message_as_comment Boolean = false
- "If the custom message should be added as a comment on the file."
- example default
- file = "id:3kmLmQFnf1AAAAAAAAAAAw"
- members = [default]
- custom_message = "This is a custom message about ACME.doc"
- quiet = false
- access_level = viewer
- # --
- route change_file_member_access(ChangeFileMemberAccessArgs, FileMemberActionResult, FileMemberActionError) deprecated by update_file_member
- "Identical to update_file_member but with less information returned."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- struct ChangeFileMemberAccessArgs
- "Arguments for :route:`change_file_member_access`."
- file PathOrId
- "File for which we are changing a member's access."
- member MemberSelector
- "The member whose access we are changing."
- access_level AccessLevel
- "The new access level for the member."
- example default
- file = "id:3kmLmQFnf1AAAAAAAAAAAw"
- member = default
- access_level = viewer
- struct UpdateFileMemberArgs extends ChangeFileMemberAccessArgs
- "Arguments for :route:`update_file_member`."
- example default
- file = "id:3kmLmQFnf1AAAAAAAAAAAw"
- member = default
- access_level = viewer
- route update_file_member(UpdateFileMemberArgs, MemberAccessLevelResult, FileMemberActionError)
- "Changes a member's access on a shared file."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- # --
- route get_file_metadata(GetFileMetadataArg, SharedFileMetadata, GetFileMetadataError)
- "Returns shared file metadata."
- attrs
- owner = "sharing"
- api_group = "truelink-alpha"
- allow_app_folder_app = true
- struct GetFileMetadataArg
- "Arguments of :route:`get_file_metadata`."
- file PathOrId
- "The file to query."
- actions List(FileAction)?
- "A list of `FileAction`s corresponding to `FilePermission`s that should appear in the
- response's :field:`SharedFileMetadata.permissions` field describing the actions the
- authenticated user can perform on the file."
- example default
- file = "id:3kmLmQFnf1AAAAAAAAAAAw"
- actions = []
- union GetFileMetadataError
- "Error result for :route:`get_file_metadata`."
- user_error SharingUserError
- access_error SharingFileAccessError
- # --
- route get_file_metadata/batch(GetFileMetadataBatchArg, List(GetFileMetadataBatchResult), SharingUserError)
- "Returns shared file metadata."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- struct GetFileMetadataBatchArg
- "Arguments of :route:`get_file_metadata/batch`."
- files List(PathOrId, max_items=100)
- "The files to query."
- actions List(FileAction)?
- "A list of `FileAction`s corresponding to `FilePermission`s that should appear in the
- response's :field:`SharedFileMetadata.permissions` field describing the actions the
- authenticated user can perform on the file."
- example default
- files = ["id:3kmLmQFnf1AAAAAAAAAAAw","id:VvTaJu2VZzAAAAAAAAAADQ"]
- actions = []
- struct GetFileMetadataBatchResult
- "Per file results of :route:`get_file_metadata/batch`."
- file PathOrId
- "This is the input file identifier corresponding to one of
- :field:`GetFileMetadataBatchArg.files`."
- result GetFileMetadataIndividualResult
- "The result for this particular file."
- example default
- file = "id:3kmLmQFnf1AAAAAAAAAAAw"
- result = default
- example file_error
- file = "id:3kmLmQFnf1AAAAAAAAAAAw"
- result = file_error
- union GetFileMetadataIndividualResult
- metadata SharedFileMetadata
- "The result for this file if it was successful."
- access_error SharingFileAccessError
- "The result for this file if it was an error."
- example default
- metadata = default
- example file_error
- access_error = invalid_file
- # --
- route list_file_members(ListFileMembersArg, SharedFileMembers, ListFileMembersError)
- "Use to obtain the members who have been invited to a file, both inherited
- and uninherited members."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- struct ListFileMembersArg
- "Arguments for :route:`list_file_members`."
- file PathOrId
- "The file for which you want to see members."
- actions List(MemberAction)?
- "The actions for which to return permissions on a member."
- include_inherited Boolean = true
- "Whether to include members who only have access from a parent shared folder."
- limit UInt32(min_value=1, max_value=300) = 100
- "Number of members to return max per query. Defaults to 100 if no limit is specified."
- example default
- file = "id:3kmLmQFnf1AAAAAAAAAAAw"
- struct SharedFileMembers
- "Shared file user, group, and invitee membership.
- Used for the results of :route:`list_file_members` and
- :route:`list_file_members/continue`, and used as part of the results
- for :route:`list_file_members/batch`."
- users List(UserMembershipInfo)
- "The list of user members of the shared file."
- groups List(GroupMembershipInfo)
- "The list of group members of the shared file."
- invitees List(InviteeMembershipInfo)
- "The list of invited members of a file, but have not logged in and
- claimed this."
- cursor String?
- "Present if there are additional shared file members that have not been returned yet. Pass
- the cursor into :route:`list_file_members/continue` to list additional members."
- example default
- users = [default]
- groups = [default]
- invitees = [default]
- union ListFileMembersError
- "Error for :route:`list_file_members`."
- user_error SharingUserError
- access_error SharingFileAccessError
- # --
- route list_file_members/batch(ListFileMembersBatchArg, List(ListFileMembersBatchResult), SharingUserError)
- "Get members of multiple files at once. The arguments
- to this route are more limited, and the limit on query result size per file
- is more strict. To customize the results more, use the individual file
- endpoint.
- Inherited users and groups are not included in the result, and permissions are not
- returned for this endpoint."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- struct ListFileMembersBatchArg
- "Arguments for :route:`list_file_members/batch`."
- files List(PathOrId, max_items=100)
- "Files for which to return members."
- limit UInt32(max_value=20) = 10
- "Number of members to return max per query. Defaults to 10 if no limit is specified."
- example default
- files = ["id:3kmLmQFnf1AAAAAAAAAAAw","id:VvTaJu2VZzAAAAAAAAAADQ"]
- limit = 10
- struct ListFileMembersBatchResult
- "Per-file result for :route:`list_file_members/batch`."
- file PathOrId
- "This is the input file identifier, whether an ID or a path."
- result ListFileMembersIndividualResult
- "The result for this particular file."
- example default
- file = "id:3kmLmQFnf1AAAAAAAAAAAw"
- result = default
- example member_error
- file = "id:3kmLmQFnf1AAAAAAAAAAAw"
- result = file_error
- struct ListFileMembersCountResult
- members SharedFileMembers
- "A list of members on this file."
- member_count UInt32
- "The number of members on this file. This does not include inherited members."
- example default
- members = default
- member_count = 3
- union ListFileMembersIndividualResult
- result ListFileMembersCountResult
- "The results of the query for this file if it was successful."
- access_error SharingFileAccessError
- "The result of the query for this file if it was an error."
- example default
- result = default
- example file_error
- access_error = invalid_file
- # --
- route list_file_members/continue(ListFileMembersContinueArg, SharedFileMembers, ListFileMembersContinueError)
- "Once a cursor has been retrieved from :route:`list_file_members` or
- :route:`list_file_members/batch`, use this to paginate through all shared
- file members."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- struct ListFileMembersContinueArg
- "Arguments for :route:`list_file_members/continue`."
- cursor String
- "The cursor returned by your last call to :route:`list_file_members`,
- :route:`list_file_members/continue`, or :route:`list_file_members/batch`."
- example default
- cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
- union ListFileMembersContinueError
- "Error for :route:`list_file_members/continue`."
- user_error SharingUserError
- access_error SharingFileAccessError
- invalid_cursor
- ":field:`ListFileMembersContinueArg.cursor` is invalid."
- # --
- route list_received_files(ListFilesArg, ListFilesResult, SharingUserError)
- "Returns a list of all files shared with current user.
- Does not include files the user has received via shared folders, and does
- not include unclaimed invitations."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- struct ListFilesArg
- "Arguments for :route:`list_received_files`."
- limit UInt32(min_value=1, max_value=300) = 100
- "Number of files to return max per query. Defaults to 100 if no limit
- is specified."
- actions List(FileAction)?
- "A list of `FileAction`s corresponding to `FilePermission`s that should appear in the
- response's :field:`SharedFileMetadata.permissions` field describing the actions the
- authenticated user can perform on the file."
- example default
- limit = 100
- actions = []
- struct ListFilesResult
- "Success results for :route:`list_received_files`."
- entries List(SharedFileMetadata)
- "Information about the files shared with current user."
- cursor String?
- "Cursor used to obtain additional shared files."
- example default
- entries = [default]
- cursor = "AzJJbGlzdF90eXBdofe9c3RPbGlzdGFyZ3NfYnlfZ2lkMRhcbric7Rdog9cmV2aXNpb24H3Qf6o1fkHxQ"
- # --
- route list_received_files/continue (ListFilesContinueArg, ListFilesResult, ListFilesContinueError)
- "Get more results with a cursor from :route:`list_received_files`."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- struct ListFilesContinueArg
- "Arguments for :route:`list_received_files/continue`."
- cursor String
- "Cursor in :field:`ListFilesResult.cursor`."
- example default
- cursor = "AzJJbGlzdF90eXBdofe9c3RPbGlzdGFyZ3NfYnlfZ2lkMRhcbric7Rdog9emfGRlc2MCRWxpbWl0BGRId"
- union ListFilesContinueError
- "Error results for :route:`list_received_files/continue`."
- user_error SharingUserError
- "User account had a problem."
- invalid_cursor
- ":field:`ListFilesContinueArg.cursor` is invalid."
- # --
- route remove_file_member(RemoveFileMemberArg, FileMemberActionIndividualResult, RemoveFileMemberError) deprecated by remove_file_member_2
- "Identical to remove_file_member_2 but with less information returned."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- route remove_file_member_2(RemoveFileMemberArg, FileMemberRemoveActionResult, RemoveFileMemberError)
- "Removes a specified member from the file."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- struct RemoveFileMemberArg
- "Arguments for :route:`remove_file_member_2`."
- file PathOrId
- "File from which to remove members."
- member MemberSelector
- "Member to remove from this file. Note that even if an email is
- specified, it may result in the removal of a user (not an invitee) if
- the user's main account corresponds to that email address."
- example default
- file = "id:3kmLmQFnf1AAAAAAAAAAAw"
- member = default
- # --
- route relinquish_file_membership(RelinquishFileMembershipArg, Void, RelinquishFileMembershipError)
- "The current user relinquishes their membership in the designated file.
- Note that the current user may still have inherited access to this file
- through the parent folder.
- Apps must have full Dropbox access to use this endpoint."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- struct RelinquishFileMembershipArg
- file PathOrId
- "The path or id for the file."
- example default
- file = "id:3kmLmQFnf1AAAAAAAAAAAw"
- union RelinquishFileMembershipError
- access_error SharingFileAccessError
- group_access
- "The current user has access to the shared file via a group. You can't relinquish
- membership to a file shared via groups."
- no_permission
- "The current user does not have permission to perform this action."
- # --
- route unshare_file(UnshareFileArg, Void, UnshareFileError)
- "Remove all members from this file. Does not remove inherited members."
- attrs
- owner = "sharing"
- api_group = "truelink-alpha"
- allow_app_folder_app = true
- struct UnshareFileArg
- "Arguments for :route:`unshare_file`."
- file PathOrId
- "The file to unshare."
- example default
- file = "id:3kmLmQFnf1AAAAAAAAAAAw"
- union UnshareFileError
- "Error result for :route:`unshare_file`."
- user_error SharingUserError
- access_error SharingFileAccessError
- example default
- user_error = email_unverified
|