Skip to content

Instantly share code, notes, and snippets.

@voluntas

voluntas/dropbox_api_v2.rst

Last active December 14, 2021 06:38
Show Gist options
  • Save voluntas/fe9394ce56ef4a305aa14168c09a3991 to your computer and use it in GitHub Desktop.
Save voluntas/fe9394ce56ef4a305aa14168c09a3991 to your computer and use it in GitHub Desktop.
Download ZIP
Dropbox API v2 仕様まとめ
Raw
dropbox_api_v2.rst

Dropbox API v2 仕様まとめ

日時:2016-12-10
作:@voluntas
バージョン:0.1.1
url:https://voluntas.github.io/

概要

使う人のためのまとめではなく、 API 設計に興味がある人向けのまとめなので注意すること

Dropbox の API が v1 から v2 になったタイミングで、REST API を完全に捨てた。

method が POST のみになった。GET で利用される query string を一切使わなくなった。

HTTP - Developers - Dropbox

この仕様を自分なりの視点でまとめておく。

資料

HTTP - Developers - Dropbox

認証

普通の OAuth を利用している。

エンドポイント

RPC エンドポイント

api.dropboxapi.com にて提供している

コンテンツアップロードエンドポイント

content.dropboxapi.com を利用して Dropbox-API-Arg ヘッダーを利用して JSON を送る

コンテンツダウンロードエンドポイント

content.dropboxapi.com を利用して Dropbox-API-Arg ヘッダーを利用して JSON を送り、JSON の受信は Dropbox-API-Result ヘッダーを利用する。

日付フォーマット

ISO 8601 の UTC のみに統一している。

ISO 8601 - Wikipedia

グルーピング

サブドメイン

一番気になるのが URL (PATH) だろう。

Dropbox はサブドメインを含めて URL にしており、 content.dropboxapi.com と api.dropboxapi.com の二種類を用意している。

content.dropboxapi.com を利用している API を上げてみる。以下に挙げたの以外は全て api.dropboxapi.com を利用している。

ヘッダー

ファイルのアップロード時に JSON も含めてアップロードしたい時があるが、その場合 Dropbox API v2 では Dropbox-API-Arg という HTTP ヘッダーに JSON をまるっと指定することで解決している。

ちなみに RFC 的にはヘッダー一つの長さに制限はない。ただ、HTTP サーバが勝手に設定している制限がある。ほとんどの場合は任意で変更できる。

Dropbox-API-Arg

download や取得系は PATH を指定するのに使っている、別に Body でもいいのでは？と思ったりしないでも無いが、 content のサブドメインを利用している場合はヘッダーベースとしているようだ

アップロードはバイナリと分けるのが面倒なのでヘッダーにいれている。

Dropbox-API-Result

content.dropboxapi.com の download 時の戻りの JSON は全て Dropbox-API-Result というヘッダーに含まれてくる。

エラー

  • 400
    • インプットパラメーターが間違っている場合は、レスポンスの BODY は JSON ではなくて plaintext で戻ってくる
  • 401
    • OAuth のトークン期限が切れた場合や、そのアクセストークンが revoke された場合に利用される。
    • これが返ってきたらアクセストークン取りに行く必要がある
  • 409
    • HTTP 的にはコンフリクト
    • エンドポイントの仕様エラー、 JSON フォーマットでのエラーが返ってくる
    • Content-Type をみて Body のフォーマット形式を確認できる
  • 429
  • 5xx
    • Dropbox のサーバがおかしいので、このエラーが返ってきた場合は status.dropbox.com を確認する

409 時の JSON に含まれるエラー

409 の時に JSON がエラーに返ってきた場合トップレベルに以下の 3 つのエラーが入る

  • error
  • error_summary
  • user_message
    • オプション
{
    "error_summary": "no_account/...",
    "error": {
        ".tag": "no_account"
    }
}

URL グルーピング

  • auth
  • files
  • paper
  • sharing
  • users

5 個にわかれ、この後ろで判断する。

auth

files

基本的に PATH copy のように 1 つ、ベースでの情報の取得に続いて何か次のアクションを取る場合のみ続きがある

sharing

users

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment