タイプと形式

ガイドAPI呼び出しタイプと形式

タイプと形式

以下のセクションでは、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/jsoncontent-type: application/jsoncontent-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:002013-04-17になります。タイムスタンプがミリ秒までサポートする場合、予期されるリクエストの形式は2013-04-17T09:12:36.123-00:00のようになります。

リクエストを発行する際、タイムゾーンが省略され、時刻が指定されていると、太平洋標準時のタイムゾーンが想定されます。応答では、タイムゾーンが会社の設定に基づいています。これは、管理者が設定したデフォルトのユーザー設定になります。管理対象ユーザーが自分のアカウント設定でタイムゾーンを変更した場合でも、APIによって返されるタイムゾーンには影響しないことに注意してください。

企業のタイムゾーンは経時的に変化するため、タイムゾーンはファイルやフォルダによって異なる場合があります。一般的な例は、夏時間です。標準時に作成された項目のタイムゾーンは、夏時間中に作成された項目とは異なります。このため、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/jsoncontent-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": "http://developers.box.com/docs/#errors",
  "message": "Method Not Allowed",
  "request_id": "abcdef123456"
}

特定のエラーについてサポートに連絡する場合は、サポートチームがリクエストをすぐに見つけられるよう、request_idを含むAPI応答全体を提供してください。

ほとんどのAPI呼び出しでは、box-request-id応答ヘッダーも返されます。このヘッダーの値を、エラー応答の本文に含まれるrequest_id値と混同しないでください。

大きな数値

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

このような場合は、これらの数値は1.2318237429383e+31などのIEEE754形式で返されます。