Ensure consistency with headers

Some Box APIs support headers used to ensure consistency between your application and Box.

etag、if-match、およびif-none-match

APIを介してリクエスト可能なファイルシステムの項目 (ファイルまたはフォルダ) の多くは、項目のetag値を返します。

たとえば、ファイルリソースはJSONレスポンスでetagを返します。

curl https://api.box.com/2.0/files/12345 \
    -H "authorization: Bearer ACCESS_TOKEN"

{
  "id": 12345,
  "etag": 1,
  "type": "file",
  "sequence_id": 3,
  "name": "Contract.pdf",
  ...
}

このetagをif-matchまたはif-none-matchヘッダーの値として使用できるのは、etag値が受信されてからリソースが変更されていないことを確認するためか、または変更されていない項目を不必要にダウンロードしないようにするためです。

たとえば、同じファイルを取得するのはそのファイルが変更された場合のみにするには、if-none-matchヘッダーでetag値を渡します。

curl https://api.box.com/2.0/files/12345 \
    -H "authorization: Bearer ACCESS_TOKEN" \
    -H "if-none-match: 1"

ファイルが変更されていない場合、このAPIコールでは空のレスポンスが返されます。

一貫性のある変更の確保

if-matchヘッダーを使用すると、アプリケーションは、最後に調べた項目がその後別のアプリケーションまたはユーザーによって変更が加えられても、項目が変更されないようにすることができます。これにより、2つのアプリケーションまたは2人のユーザーが項目を同時に変更しても変更が失われることはありません。

このヘッダーは、以下のエンドポイントでサポートされます。

これらのAPIコールのレスポンスは、項目が存在するかどうか、およびetag値が最新バージョンと一致するかどうかによって異なります。

リクエストによる不要なダウンロードの防止

if-none-matchヘッダーを使用すると、アプリケーションは、最後に調べてから変更されていない項目の情報がダウンロードされないようにすることができます。これにより、不要な情報がダウンロードされなくなるため、アプリケーションの速度が向上し、帯域幅が節約されます。

これらのAPIコールのレスポンスは、項目が存在するかどうか、およびetag値が最新バージョンと一致するかどうかによって異なります。