123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548 |
- namespace sharing
- import common
- import files
- import users
- alias Id = files.Id
- alias Path = files.Path
- alias Rev = files.Rev
- alias TeamInfo = users.Team
- alias ReadPath = files.ReadPath
- #
- # Link Metadata definitions and route
- #
- struct GetSharedLinkMetadataArg
- url String
- "URL of the shared link."
- path Path?
- "If the shared link is to a folder, this parameter can be used to retrieve the metadata for
- a specific file or sub-folder in this folder. A relative path should be used."
- link_password String?
- "If the shared link has a password, this parameter can be used."
- example default
- url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
- path = "/Prime_Numbers.txt"
- union_closed RequestedVisibility
- "The access permission that can be requested by the caller for the shared link.
- Note that the final resolved visibility of the shared link takes into account other aspects,
- such as team and shared folder settings.
- Check the :type:`ResolvedVisibility` for more info on the possible resolved visibility values
- of shared links. "
- public
- "Anyone who has received the link can access it. No login required."
- team_only
- "Only members of the same team can
- access the link. Login is required."
- password
- "A link-specific password is required to access the
- link. Login is not required."
- union ResolvedVisibility extends RequestedVisibility
- "The actual access permissions values of shared links after taking into account user
- preferences and the team and shared folder settings.
- Check the :type:`RequestedVisibility` for more info on the possible visibility values
- that can be set by the shared link's owner. "
- team_and_password
- "Only members of the same team who
- have the link-specific password can access the link. Login is required."
- shared_folder_only
- "Only members of the shared folder containing the linked file
- can access the link. Login is required."
- union SharedLinkAccessFailureReason
- login_required
- "User is not logged in."
- email_verify_required
- "User's email is not verified."
- password_required
- "The link is password protected."
- team_only
- "Access is allowed for team members only."
- owner_only
- "Access is allowed for the shared link's owner only."
- struct LinkPermissions
- resolved_visibility ResolvedVisibility?
- "The current visibility of the link after considering the shared links policies of the
- the team (in case the link's owner is part of a team) and the shared folder (in case the
- linked file is part of a shared folder). This field is shown only if the caller has access
- to this info (the link's owner always has access to this data)."
- requested_visibility RequestedVisibility?
- "The shared link's requested visibility. This can be overridden by the team and shared
- folder policies. The final visibility, after considering these policies, can be found in
- :field:`resolved_visibility`. This is shown only if the caller is the link's
- owner."
- can_revoke Boolean
- "Whether the caller can revoke the shared link"
- revoke_failure_reason SharedLinkAccessFailureReason?
- "The failure reason for revoking the link. This field will only be present if the
- :field:`can_revoke` is :val:`false`."
- example default
- resolved_visibility = public
- can_revoke = false
- revoke_failure_reason = owner_only
- struct TeamMemberInfo
- "Information about a team member."
- team_info TeamInfo
- "Information about the member's team"
- display_name String
- "The display name of the user."
- member_id String?
- "ID of user as a member of a team. This field will only be present if the member is in the
- same team as current user."
- example default
- team_info = default
- display_name = "Roger Rabbit"
- member_id = "dbmid:abcd1234"
- struct SharedLinkMetadata
- "The metadata of a shared link "
- union
- file FileLinkMetadata
- folder FolderLinkMetadata
- url String
- "URL of the shared link."
- id Id?
- "A unique identifier for the linked file."
- name String
- "The linked file name (including extension).
- This never contains a slash."
- expires common.DropboxTimestamp?
- "Expiration time, if set. By default the link won't expire."
- path_lower String?
- "The lowercased full path in the user's Dropbox. This always starts with a slash.
- This field will only be present only if the linked file is in the authenticated user's
- dropbox."
- link_permissions LinkPermissions
- "The link's access permissions."
- team_member_info TeamMemberInfo?
- "The team membership information of the link's owner. This field will only be present
- if the link's owner is a team member."
- content_owner_team_info TeamInfo?
- "The team information of the content's owner. This field will only be present if
- the content's owner is a team member and the content's owner team is different from the
- link's owner team."
- example default
- file = default
- example folder_link_metadata
- folder = default
- struct FileLinkMetadata extends SharedLinkMetadata
- "The metadata of a file shared link "
- client_modified common.DropboxTimestamp
- "The modification time set by the desktop client
- when the file was added to Dropbox. Since this time is not verified
- (the Dropbox server stores whatever the desktop client sends up), this
- should only be used for display purposes (such as sorting) and not,
- for example, to determine if a file has changed or not."
- server_modified common.DropboxTimestamp
- "The last time the file was modified on Dropbox."
- rev Rev
- "A unique identifier for the current revision of a file. This field is
- the same rev as elsewhere in the API and can be used to detect changes
- and avoid conflicts."
- size UInt64
- "The file size in bytes."
- example default
- url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
- id = "id:a4ayc_80_OEAAAAAAAAAXw"
- name = "Prime_Numbers.txt"
- path_lower = "/homework/math/prime_numbers.txt"
- link_permissions = default
- team_member_info = default
- client_modified = "2015-05-12T15:50:38Z"
- server_modified = "2015-05-12T15:50:38Z"
- rev = "a1c10ce0dd78"
- size = 7212
- struct FolderLinkMetadata extends SharedLinkMetadata
- "The metadata of a folder shared link "
- example default
- url = "https://www.dropbox.com/sh/s6fvw6ol7rmqo1x/AAAgWRSbjmYDvPpDB30Sykjfa?dl=0"
- id = "id:a4ayc_80_OEAAAAAAAAAXw"
- name = "Math"
- path_lower = "/homework/math"
- team_member_info = default
- link_permissions = default
- union SharedLinkError
- shared_link_not_found
- "The shared link wasn't found."
- shared_link_access_denied
- "The caller is not allowed to access this shared link."
- unsupported_link_type
- "This type of link is not supported."
- route get_shared_link_metadata(GetSharedLinkMetadataArg, SharedLinkMetadata, SharedLinkError)
- "Get the shared link's metadata."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- #
- # List Shared links definitions and route
- #
- struct ListSharedLinksArg
- path ReadPath?
- "See :route:`list_shared_links` description."
- cursor String?
- "The cursor returned by your last call to :route:`list_shared_links`."
- direct_only Boolean?
- "See :route:`list_shared_links` description."
- example default
- "List all links"
- cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
- example path
- path = "/Homework/Math"
- example id
- path = "id:a4ayc_80_OEAAAAAAAAAYa"
- example rev
- path = "rev:a1c10ce0dd78"
- example id_no_parent_links
- path = "id:a4ayc_80_OEAAAAAAAAAYa"
- direct_only = true
- struct ListSharedLinksResult
- links List(SharedLinkMetadata)
- "Shared links applicable to the path argument."
- has_more Boolean
- "Is true if there are additional shared links that have not been returned
- yet. Pass the cursor into :route:`list_shared_links` to retrieve them."
- cursor String?
- "Pass the cursor into :route:`list_shared_links` to obtain the additional links. Cursor is
- returned only if no path is given."
- example default
- links = [default]
- cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
- has_more = true
- union ListSharedLinksError
- path files.LookupError
- reset
- "Indicates that the cursor has been invalidated. Call
- :route:`list_shared_links` to obtain a new cursor."
- route list_shared_links(ListSharedLinksArg, ListSharedLinksResult, ListSharedLinksError)
- "List shared links of this user.
- If no path is given, returns a list of all shared links for the current user.
- If a non-empty path is given, returns a list of all shared links
- that allow access to the given path - direct links to the given path and links to parent folders
- of the given path. Links to parent folders can be suppressed by setting
- direct_only to true."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- #
- # Modify shared link settings definitions and route
- #
- struct SharedLinkSettings
- requested_visibility RequestedVisibility?
- "The requested access for this shared link."
- link_password String?
- "If :field:`requested_visibility` is :field:`RequestedVisibility.password` this is needed
- to specify the password to access the link. "
- expires common.DropboxTimestamp?
- "Expiration time of the shared link. By default the link won't expire."
- example default
- requested_visibility = public
- struct ModifySharedLinkSettingsArgs
- url String
- "URL of the shared link to change its settings"
- settings SharedLinkSettings
- "Set of settings for the shared link."
- remove_expiration Boolean = false
- "If set to true, removes the expiration of the shared link."
- example default
- url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
- settings = default
- union_closed SharedLinkSettingsError
- invalid_settings
- "The given settings are invalid
- (for example, all attributes of the :type:`SharedLinkSettings` are empty,
- the requested visibility is :field:`RequestedVisibility.password` but the
- :field:`SharedLinkSettings.link_password` is missing, :field:`SharedLinkSettings.expires`
- is set to the past, etc.)"
- not_authorized
- "User is not allowed to modify the settings of this link. Note that basic
- users can only set :field:`RequestedVisibility.public`
- as the :field:`SharedLinkSettings.requested_visibility` and cannot
- set :field:`SharedLinkSettings.expires`"
- union ModifySharedLinkSettingsError extends SharedLinkError
- settings_error SharedLinkSettingsError
- "There is an error with the given settings"
- email_not_verified
- "The caller's email should be verified"
- route modify_shared_link_settings(ModifySharedLinkSettingsArgs, SharedLinkMetadata, ModifySharedLinkSettingsError)
- "Modify the shared link's settings.
- If the requested visibility conflict with the shared links policy of the team or the
- shared folder (in case the linked file is part of a shared folder) then the
- :field:`LinkPermissions.resolved_visibility` of the returned :type:`SharedLinkMetadata` will
- reflect the actual visibility of the shared link and the
- :field:`LinkPermissions.requested_visibility` will reflect the requested visibility."
- attrs
- owner = "adminx"
- allow_app_folder_app = true
- #
- # Create shared link with settings definitions and route
- #
- struct CreateSharedLinkWithSettingsArg
- path ReadPath
- "The path to be shared by the shared link"
- settings SharedLinkSettings?
- "The requested settings for the newly created shared link"
- example default
- path = "/Prime_Numbers.txt"
- settings = default
- union_closed CreateSharedLinkWithSettingsError
- path files.LookupError
- email_not_verified
- "User's email should be verified"
- shared_link_already_exists
- "The shared link already exists"
- settings_error SharedLinkSettingsError
- "There is an error with the given settings"
- access_denied
- "Access to the requested path is forbidden"
- route create_shared_link_with_settings(CreateSharedLinkWithSettingsArg, SharedLinkMetadata, CreateSharedLinkWithSettingsError)
- "Create a shared link with custom settings.
- If no settings are given then the default visibility is :field:`RequestedVisibility.public`
- (The resolved visibility, though, may depend on other aspects such as team and shared folder
- settings). "
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- #
- # Revoke shared link
- #
- struct RevokeSharedLinkArg
- url String
- "URL of the shared link."
- example default
- url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
- union RevokeSharedLinkError extends SharedLinkError
- shared_link_malformed
- "Shared link is malformed."
- route revoke_shared_link(RevokeSharedLinkArg, Void, RevokeSharedLinkError)
- "Revoke a shared link.
- Note that even after revoking a shared link to a file, the file may be accessible if there are
- shared links leading to any of the file parent folders. To list all shared links that enable
- access to a specific file, you can use the :route:`list_shared_links` with the file as the
- :field:`ListSharedLinksArg.path` argument. "
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- #
- # NSLR endpoints
- #
- union GetSharedLinkFileError extends SharedLinkError
- shared_link_is_directory
- "Directories cannot be retrieved by this endpoint."
- alias GetSharedLinkFileArg = GetSharedLinkMetadataArg
- route get_shared_link_file(GetSharedLinkFileArg, SharedLinkMetadata, GetSharedLinkFileError)
- "Download the shared link's file from a user's Dropbox."
- attrs
- host="content"
- style="download"
- owner = "sharing"
- allow_app_folder_app = true
- #
- # Depracated endpoints
- #
- union Visibility
- "Who can access a shared link.
- The most open visibility is :field:`public`.
- The default depends on many aspects, such as team and user
- preferences and shared folder settings."
- public
- "Anyone who has received the link can access it. No login required."
- team_only
- "Only members of the same team can
- access the link. Login is required."
- password
- "A link-specific password is required to access the
- link. Login is not required."
- team_and_password
- "Only members of the same team who
- have the link-specific password can access the link."
- shared_folder_only
- "Only members of the shared folder containing the linked file
- can access the link. Login is required."
- struct LinkMetadata
- "Metadata for a shared link. This can be either a
- :type:`PathLinkMetadata` or :type:`CollectionLinkMetadata`."
- union
- path PathLinkMetadata
- collection CollectionLinkMetadata
- url String
- "URL of the shared link."
- visibility Visibility
- "Who can access the link."
- expires common.DropboxTimestamp?
- "Expiration time, if set. By default the link won't expire."
- struct PathLinkMetadata extends LinkMetadata
- "Metadata for a path-based shared link."
- path String
- "Path in user's Dropbox."
- example default
- url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
- path = "/Homework/Math/Prime_Numbers.txt"
- expires = null
- visibility = public
- struct CollectionLinkMetadata extends LinkMetadata
- "Metadata for a collection-based shared link."
- example default
- url = "https://www.dropbox.com/sh/s6fvw6ol7rmqo1x/AAAgWRSbjmYDvPpDB30Sykjfa?dl=0"
- expires = null
- visibility = public
- struct GetSharedLinksArg
- path String?
- "See :route:`get_shared_links` description."
- example default
- "Get all links, including collection links"
- path = ""
- example math_homework_links
- "Get links giving access to /Homework/Math"
- path = "/Homework/Math"
- struct GetSharedLinksResult
- links List(LinkMetadata)
- "Shared links applicable to the path argument."
- union GetSharedLinksError
- path files.MalformedPathError
- route get_shared_links(GetSharedLinksArg, GetSharedLinksResult, GetSharedLinksError) deprecated by list_shared_links
- "Returns a list of :type:`LinkMetadata` objects for this user,
- including collection links.
- If no path is given, returns a list of all shared links for the current
- user, including collection links.
- If a non-empty path is given, returns a list of all shared links
- that allow access to the given path. Collection links are never
- returned in this case.
- Note that the url field in the response is never the shortened URL."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
- union_closed PendingUploadMode
- "Flag to indicate pending upload default (for linking to not-yet-existing paths)."
- file
- "Assume pending uploads are files."
- folder
- "Assume pending uploads are folders."
- struct CreateSharedLinkArg
- path String
- "The path to share."
- short_url Boolean = false
- "Whether to return a shortened URL."
- pending_upload PendingUploadMode?
- "If it's okay to share a path that does not yet exist, set this to
- either :field:`PendingUploadMode.file` or :field:`PendingUploadMode.folder`
- to indicate whether to assume it's a file or folder."
- example default
- path = "/Homework/Math/Prime_Numbers.txt"
- union CreateSharedLinkError
- path files.LookupError
- route create_shared_link(CreateSharedLinkArg, PathLinkMetadata, CreateSharedLinkError) deprecated by create_shared_link_with_settings
- "Create a shared link.
- If a shared link already exists for the given path, that link is returned.
- Note that in the returned :type:`PathLinkMetadata`, the
- :field:`PathLinkMetadata.url` field is the shortened URL if
- :field:`CreateSharedLinkArg.short_url` argument is set to :val:`true`.
- Previously, it was technically possible to break a shared link by moving or
- renaming the corresponding file or folder. In the future, this will no
- longer be the case, so your app shouldn't rely on this behavior. Instead, if
- your app needs to revoke a shared link, use :route:`revoke_shared_link`."
- attrs
- owner = "sharing"
- allow_app_folder_app = true
|