Core HTTP layer for the Dropbox API v2.
Builds authenticated Req requests and normalizes responses. RPC-style
endpoints go through post/3, while content endpoints (file bytes) go
through upload_request/5 and download_request/5.
Requests are authenticated by the client's Magpie.Auth.TokenProvider: a
request step asks it for an access token, and when Dropbox answers 401 expired_access_token a response step refreshes the token and replays the
request once.
The Dropbox endpoints can be overridden (rarely needed) via:
config :magpie,
base_url: "https://api.dropboxapi.com/2",
upload_url: "https://content.dropboxapi.com/2/",
notify_url: "https://notify.dropboxapi.com/2",
oauth_authorize_url: "https://www.dropbox.com/oauth2/authorize",
oauth_token_url: "https://api.dropboxapi.com/oauth2/token"Extra options merged into every request (e.g. plug: {Req.Test, Magpie}
for testing) can be set with config :magpie, req_options: [...].
Selected read-only file routes — downloads, metadata, temporary links, listings, revisions and search — retry transient failures by default. Tune the maximum attempts, log level, or delay controller with:
config :magpie,
retry: [max_retries: 3, log_level: :warning]Setting retry: false disables automatic retries. A :delay integer or
one-arity function overrides Retry-After/exponential backoff. Mutation
routes are never retried automatically, regardless of this setting.
Use Magpie.Client.new/2 or Magpie.Client.with_options/2 to override
configuration per client, and request: [...] on Storage calls to override
it per operation. See the configuration guide for
precedence, execution budgets and diagnostic fields.
Summary
Functions
Base URL for RPC endpoints.
Download a content endpoint directly to destination without accumulating
the response body in memory.
Base URL for the notification endpoints.
URL where users authorize the app (OAuth 2 authorization endpoint).
OAuth 2 token endpoint — note it lives outside the /2 base URL.
Send an RPC request to a Dropbox endpoint, JSON-encoding body when given.
Same as post_url/4, but leaves out the Authorization header — Dropbox
answers 400 on its noauth routes when the request carries one. opts is
merged into the Req request, e.g. receive_timeout: for a blocking call.
Same as post/3 but against an explicit base URL (used by content endpoints
that speak JSON, such as /files/get_thumbnail_batch).
Upload data (iodata or enumerable) as the raw request body.
Used by content endpoints that take bytes directly instead of a local file.
Upload the file at local path file as the raw request body.
The file is streamed, so large files are not loaded into memory at once.
Base URL for content (upload/download) endpoints.
Types
@type response() :: {:ok, term()} | {:error, Magpie.Error.t()}
@type response_download() :: {:ok, %{body: binary(), headers: list() | map()}} | {:error, Magpie.Error.t()}
Functions
Base URL for RPC endpoints.
@spec download_file_request(struct(), binary(), binary(), term(), map(), Path.t()) :: {:ok, %{path: Path.t(), headers: list() | map()}} | {:error, Magpie.Error.t() | File.posix()}
Download a content endpoint directly to destination without accumulating
the response body in memory.
The response is first written to a temporary sibling file and only moved to
destination after Dropbox returns a successful response. Existing files
are therefore left untouched when Dropbox returns an API error.
@spec download_response(Req.Response.t()) :: response_download()
Base URL for the notification endpoints.
Dropbox serves /files/list_folder/longpoll from its own host, and rejects
the request when it carries an Authorization header.
URL where users authorize the app (OAuth 2 authorization endpoint).
OAuth 2 token endpoint — note it lives outside the /2 base URL.
Send an RPC request to a Dropbox endpoint, JSON-encoding body when given.
Same as post_url/4, but leaves out the Authorization header — Dropbox
answers 400 on its noauth routes when the request carries one. opts is
merged into the Req request, e.g. receive_timeout: for a blocking call.
Same as post/3 but against an explicit base URL (used by content endpoints
that speak JSON, such as /files/get_thumbnail_batch).
@spec process_response(Req.Response.t()) :: response()
Upload data (iodata or enumerable) as the raw request body.
Used by content endpoints that take bytes directly instead of a local file.
Upload the file at local path file as the raw request body.
The file is streamed, so large files are not loaded into memory at once.
Base URL for content (upload/download) endpoints.