メインコンテンツへスキップ
以下のセクションでは、Box API内で使用される可能性があるタイプと形式に関する基本的なコンセプトについて説明します。

​
リクエスト

Box APIは、リクエスト本文でJSONを使用します。このルールには注目すべき例外がいくつかあります。
  • POST /oauth2/tokenはアクセストークンのリクエストに使用され、OAuth 2.0の仕様に従って、コンテンツタイプapplication/x-www-form-urlencodedで送信される本文を受け入れます。
  • POST /files/contentエンドポイントなど、バイナリデータをアップロードするのに使用されるほとんどのAPIでは、コンテンツタイプがmultipart/form-dataのフォームデータとしてデータが送信されることを予期します。
必須ではありませんが、content-type: application/jsonのように、送信されるデータのコンテンツタイプを定義するヘッダーを各APIリクエストで渡すことを強くお勧めします。

​
ヘッダー

HTTP仕様に従い、Box APIのすべてのリクエストヘッダー名では大文字と小文字が区別されないため、小文字、大文字、または両方を組み合わせた形で指定できます。つまり、コンテンツタイプヘッダーは、CONTENT-TYPE: application/json、content-type: application/json、content-type: application/json、または多少変わったcOnTeNt-TyPe: application/jsonとしても設定できます。 ヘッダーの値では、特に記載のない限り、大文字と小文字が区別されることがほとんどです。

​
GZip圧縮

デフォルトでは、Boxから送信されるデータは圧縮されません。帯域幅とレスポンス時間を改善するには、Accept-Encoding: gzip, deflateリクエストヘッダーを含めることでAPIレスポンスを圧縮できます。

​
日付と時刻

Box APIはRFC 3339タイムスタンプをサポートします。リクエスト内の日付の形式を設定するには、2013-04-17T09:12:36-00:00のように時刻をUTCに変換する方法をお勧めします。 タイムスタンプが特定の日に丸められる場合は、時刻部分を省略できます。この場合、2013-04-17T13:35:01+00:00は2013-04-17になります。タイムスタンプがミリ秒までサポートする場合、予期されるリクエストの形式は2013-04-17T09:12:36.123-00:00のようになります。 企業のタイムゾーンは経時的に変化するため、タイムゾーンはファイルやフォルダによって異なる場合があります。一般的な例は、夏時間です。標準時に作成された項目のタイムゾーンは、夏時間中に作成された項目とは異なります。このため、APIから返された日付を処理するには、RFC3339準拠の日時パーサーを使用することが重要です。 タイムスタンプは、Unixエポック (1970年1月1日) の00:00:00 UTCの開始後の日付に制限されます。

​
レスポンス

一般的に、Box APIはレスポンス本文でJSONを返します。このルールにも注目すべき例外がいくつかあります。
  • 項目を削除するAPIでは、HTTPステータスコード204 No Contentとともに空の本文が返されます。
  • バイナリデータのリクエストに使用されるAPIでは、バイナリデータが添付されたステータスコード200 OKが返されるか、202 Acceptedが返されるか、またはステータスコード302 Foundとともに実際のバイナリファイルを指すlocationヘッダーのみ (本文なし) が返されます。
content-typeレスポンスヘッダーを使用すると、APIで返されるコンテンツのタイプがわかります。さらに、各APIエンドポイントのレスポンスタイプについては、APIリファレンスドキュメントで説明されています。

​
ヘッダー

HTTP仕様に従い、Box APIのすべてのレスポンスヘッダー名では、大文字と小文字が区別されないため、今後変更される可能性があります。 つまり、APIでは、CONTENT-TYPE: application/json、content-type: application/json、またはcontent-type: application/jsonというコンテンツタイプヘッダーが付いたレスポンスが返される可能性があります。リクエスト時にアプリケーションによってヘッダー名を標準の文字に変換された後、標準化されたそのヘッダーのセットを使用してヘッダーの値を検索できるのが理想的です。 ヘッダーの値では、特に記載のない限り、必ず大文字と小文字が区別されます。

​
リソース

1つしかリソースが返されない標準的なAPIレスポンスのほとんどは、次の形式に従っています。 
{
  "id": "12345",
  "type": "folder",
  ...
}
これらのリソースはすべて、常に1つのIDとリソースのタイプを返します。

​
コレクション

APIレスポンスで複数の項目が返される場合は、コレクションが返されます。これらのコレクションの正確な形式はエンドポイントごとに変わる場合がありますが、一般的には以下の形式になります。 
{
  "total_count": 5000,
  "limit": 1000,
  "offset": 2000,
  "order": [
    {
      "by": "type",
      "direction": "ASC"
    }
  ],
  "entries": [
    {
      "id": 12345,
      "etag": 1,
      "type": "file",
      "sequence_id": 3,
      "name": "Contract.pdf"
    }
  ]
}
フィールド必須かどうか?
entriesはいコレクション内のエントリのリスト
total_countいいえリクエスト可能なコレクション内の合計数。このページの結果数よりも大きくてもかまいません。
limitいいえオフセットベースのページネーションをサポートするエンドポイントに対して、返される結果の数の制限を指定します。
offsetいいえオフセットベースのページネーションをサポートするエンドポイントに対して、返される結果のオフセットを指定します。
orderいいえ並べ替えをサポートするエンドポイントに対して、結果が返される順番を指定します。
next_markerいいえマーカーベースのページネーションをサポートするエンドポイントに対して、返すことができる次のページのマーカーを指定します。
prev_markerいいえマーカーベースのページネーションをサポートするエンドポイントに対して、返すことができる前のページのマーカーを指定します。

​
リクエストID

APIコールがエラーで返されると、BoxのAPIからrequest_idフィールドを含むエラーオブジェクトが返されます。 
{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "message": "Method Not Allowed",
  "request_id": "abcdef123456"
}
特定のエラーについてサポートに連絡する場合は、サポートチームがリクエストをすぐに見つけられるよう、request_idを含むAPIレスポンス全体を提供してください。
ほとんどのAPIコールでは、box-request-idレスポンスヘッダーも返されます。このヘッダーの値を、エラーレスポンスの本文に含まれるrequest_id値と混同しないでください。

​
大きな数値

場合によっては、APIでフィールドに対して極端に大きな数値が返されることがあります。たとえば、フォルダのサイズがテラバイト級のデータまで大きくなった場合、結果として、フォルダのsizeフィールドが、非常に大きな数値になっている可能性があります。 このような場合は、これらの数値は1.2318237429383e+31などのIEEE754形式で返されます。