タイプと形式

以下のセクションでは、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としても設定できます。

ヘッダーの値では、特に記載のない限り、大文字と小文字が区別されることがほとんどです。

デフォルトでは、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`	いいえ	マーカーベースのページ割りをサポートするエンドポイントに対して、返すことができる前のページのマーカーを指定します。

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形式で返されます。

タイプと形式

タイプと形式

リクエスト

ヘッダー

GZip圧縮

日付と時刻

レスポンス

ヘッダー

リソース

コレクション

リクエストID

大きな数値