Skip to content

Spec Update 05/11/2026 #84

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
AndreyVMarkelov wants to merge 1 commit into from
Closed

Spec Update 05/11/2026 #84

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 61 additions & 16 deletions account.stone
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,19 @@
namespace account

import account_id
import common

#
# Route set_profile_photo
#
route get_photo (AccountPhotoGetArg, AccountPhotoGetResult, AccountPhotoGetError)
"This lovely endpoint gets the account photo of a given user."

attrs
allow_app_folder_app = true
auth = "user"
host = "content"
scope = "account_info.read"
select_admin_mode = "whole_team"
style = "download"


union PhotoSourceArg
base64_data String
Expand All @@ -13,6 +22,17 @@ union PhotoSourceArg
example default
base64_data = "SW1hZ2UgZGF0YSBpbiBiYXNlNjQtZW5jb2RlZCBieXRlcy4gTm90IGEgdmFsaWQgZXhhbXBsZS4="

union SetProfilePhotoError
file_type_error
"File cannot be set as profile photo."
file_size_error
"File cannot exceed 10 MB."
dimension_error
"Image must be larger than 128 x 128."
thumbnail_error
"Image could not be thumbnailed."
transient_error
"Temporary infrastructure failure, please retry."

struct SetProfilePhotoArg
photo PhotoSourceArg
Expand All @@ -21,29 +41,54 @@ struct SetProfilePhotoArg
example default
photo = default


struct SetProfilePhotoResult
profile_photo_url String
"URL for the photo representing the user, if one is set."

example default
profile_photo_url = "https://dl-web.dropbox.com/account_photo/get/dbaphid%3AAAHWGmIXV3sUuOmBfTz0wPsiqHUpBWvv3ZA?vers=1556069330102&size=128x128"

struct AccountPhotoGetArg
dbx_account_id String
"Encoded ID of the user. Must start either with 'dbid:' or 'dbaphid:'."
size String
"A string representing the size of the photo."
circle_crop Boolean
"True if the photo should be cropped and false otherwise."
expect_account_photo Boolean
"True if we expect account photo to exist."

union SetProfilePhotoError
file_type_error
"File cannot be set as profile photo."
file_size_error
"File cannot exceed 10 MB."
dimension_error
"Image must be larger than 128 x 128."
thumbnail_error
"Image could not be thumbnailed."
transient_error
"Temporary infrastructure failure, please retry."
example default
dbx_account_id = "dbid:s0meEnc0ded1d"
size = "16x16"
circle_crop = false
expect_account_photo = true

union ThumbnailError
permanent_failure
"Indicates permanent infrastructural failure."
temporary_failure
"Indicates temporary infrastructural failure."

union AccountPhotoGetError
thumbnail_error ThumbnailError
"Indicates infrastructural failure."
account_photo_missing
"Account photo is missing (but we did not expect it to exist)."
expected_account_photo_missing
"Account photo was expected to exist, but it's missing."

route set_profile_photo(SetProfilePhotoArg, SetProfilePhotoResult, SetProfilePhotoError)
struct AccountPhotoGetResult
content_type String
"The data returned by get_photo."

example default
content_type = "image/jpeg"

route set_profile_photo (SetProfilePhotoArg, SetProfilePhotoResult, SetProfilePhotoError)
"Sets a user's profile photo."

attrs
auth = "user"
scope = "account_info.write"

6 changes: 6 additions & 0 deletions account_id.stone
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
namespace account_id

annotation_type ContainsDbidAnnotation
"Annotation type should be applied to Response object fields which contain account id"

authorize_caller Boolean = true
39 changes: 5 additions & 34 deletions async.stone
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,15 @@
namespace async

#
# Types for writing asynchronous API methods.
#
# There are two calls for each asynchronous method:
# 1. A "Launch" method that (optionally) launches the asynchronous job
# 2. A "Polling" method that polls for the status of the job that was launched by the first call.
#
# The following definitions are prefixed by "Launch" or "Poll", according to their intended use.

import common

alias AsyncJobId = String(min_length=1)


#
# Launch
#

union_closed LaunchResultBase
"Result returned by methods that launch an asynchronous job.

A method who may either launch an asynchronous job, or complete the request
synchronously, can use this union by extending it, and adding a 'complete' field
with the type of the synchronous response.

See :type:`LaunchEmptyResult` for an example."

async_job_id AsyncJobId
"This response indicates that the processing is asynchronous.
The string is an id that can be used to obtain the status of the asynchronous job."
Expand All @@ -36,63 +20,50 @@ union_closed LaunchResultBase
union_closed LaunchEmptyResult extends LaunchResultBase
"Result returned by methods that may either launch an asynchronous job or complete synchronously.
Upon synchronous completion of the job, no additional information is returned."

complete
"The job finished synchronously and successfully."

example complete
complete = null

example async_job_id
async_job_id = "34g93hh34h04y384084"

#
# Poll
#

struct PollArg
"Arguments for methods that poll the status of an asynchronous job."

async_job_id AsyncJobId
"Id of the asynchronous job.
This is the value of a response returned from the method that launched the job."

example default
async_job_id = "34g93hh34h04y384084"

# TODO(kelkabany): Remove `error_msg` since others might want to return it
# differently.
union_closed PollResultBase
"Result returned by methods that poll for the status of an asynchronous job.
Unions that extend this union should add a 'complete' field with a type of
the information returned upon job completion.

See :type:`PollEmptyResult` for an example."

See :type:`PollEmptyResult` for an example"
in_progress
"The asynchronous job is still in progress."


union_closed PollEmptyResult extends PollResultBase
"Result returned by methods that poll for the status of an asynchronous job.
Upon completion of the job, no additional information is returned."

complete
"The asynchronous job has completed successfully."

example complete
complete = null

example in_progress
in_progress = null


union PollError
"Error returned by methods for polling the status of asynchronous job."

invalid_async_job_id
"The job ID is invalid."
internal_error
"Something went wrong with the job on Dropbox's end. You'll need to
verify that the action you were taking succeeded, and if not, try
again. This should happen very rarely."

99 changes: 51 additions & 48 deletions auth.stone
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,8 @@ namespace auth

import common

struct TokenScopeError
required_scope String
"The required scope to access the route."

union AuthError
"Errors occurred during authentication."

invalid_access_token
"The access token is invalid."
invalid_select_user
Expand All @@ -24,39 +19,60 @@ union AuthError
route_access_denied
"The route is not available to public."

route token/revoke(Void, Void, Void)
"Disables the access token used to authenticate the call.
If there is a corresponding refresh token for the access token,
this disables that refresh token, as well as any other access tokens for that refresh token."

attrs
allow_app_folder_app = true

union RateLimitReason
too_many_requests
"You are making too many requests in the past few minutes."
too_many_write_operations
"There are currently too many write operations happening in the user's Dropbox."

union TokenFromOAuth1Error
invalid_oauth1_token_info
"Part or all of the OAuth 1.0 access token info is invalid."
app_id_mismatch
"The authorized app does not match the app associated with the supplied access token."

union AccessError
"Error occurred because the account doesn't have permission to access the resource."
invalid_account_type InvalidAccountTypeError
"Current account type cannot access the resource."
paper_access_denied PaperAccessError
"Current account cannot access Paper."
team_access_denied
"Team doesn't have permission to access."
no_permission NoPermissionError
"Caller does not have permission to access the resource."

union PaperAccessError
paper_disabled
"Paper is disabled."
not_paper_user
"The provided user has not used Paper yet."

union InvalidAccountTypeError
endpoint
"Current account type doesn't have permission to access this route endpoint."
feature
"Current account type doesn't have permission to access this feature."

union NoPermissionError
unauthorized_account_id_usage UnauthorizedAccountIdUsageError
"Current caller does not have permission to access the account information for one or more of the specified account IDs."

struct TokenScopeError
required_scope String
"The required scope to access the route."

struct RateLimitError
"Error occurred because the app is being rate limited."

reason RateLimitReason
"The reason why the app is being rate limited."

retry_after UInt64 = 1
"The number of seconds that the app should wait
before making another request."

#
# OAuth 1.0 token conversion
#

struct TokenFromOAuth1Arg

oauth1_token String(min_length=1)
"The supplied OAuth 1.0 access token."

oauth1_token_secret String(min_length=1)
"The token secret associated with the supplied access token."

Expand All @@ -65,42 +81,29 @@ struct TokenFromOAuth1Arg
oauth1_token_secret = "qomoftv0472git7"

struct TokenFromOAuth1Result

oauth2_token String(min_length=1)
"The OAuth 2.0 token generated from the supplied OAuth 1.0 token."

example default
oauth2_token = "9mCrkS7BIdAAAAAAAAAAHHS0TsSnpYvKQVtKdBnN5IuzhYOGblSgTcHgBFKFMmFn"

union TokenFromOAuth1Error
invalid_oauth1_token_info
"Part or all of the OAuth 1.0 access token info is invalid."
app_id_mismatch
"The authorized app does not match the app associated with the supplied access token."
struct UnauthorizedAccountIdUsageError
unauthorized_account_ids List(String)
"The account IDs that the caller does not have permission to use."

route token/revoke (Void, Void, Void)
"Disables the access token used to authenticate the call.
If there is a corresponding refresh token for the access token,
this disables that refresh token, as well as any other access tokens for that refresh token."

route token/from_oauth1(TokenFromOAuth1Arg, TokenFromOAuth1Result, TokenFromOAuth1Error) deprecated
"Creates an OAuth 2.0 access token from the supplied OAuth 1.0 access token."
attrs
auth = "app"
allow_app_folder_app = true
auth = "user"

union AccessError
"Error occurred because the account doesn't have permission to access the resource."

invalid_account_type InvalidAccountTypeError
"Current account type cannot access the resource."

paper_access_denied PaperAccessError
"Current account cannot access Paper."
route token/from_oauth1 (TokenFromOAuth1Arg, TokenFromOAuth1Result, TokenFromOAuth1Error) deprecated
"Creates an OAuth 2.0 access token from the supplied OAuth 1.0 access token."

union PaperAccessError
paper_disabled
"Paper is disabled."
not_paper_user
"The provided user has not used Paper yet."
attrs
allow_app_folder_app = true
auth = "app"

union InvalidAccountTypeError
endpoint
"Current account type doesn't have permission to access this route endpoint."
feature
"Current account type doesn't have permission to access this feature."
Loading