My Apps

    Ensure Consistency

    Ensure Consistency

    A few of the Box APIs support special headers to ensure consistency between your application and Box.

    Etag, If-Match, and If-None-Match

    Many of the file system items (files or folders) that can be requested via the API return an etag value for the item.

    For example, a file resource returns an etag in the JSON response.

    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",
      ...
    }

    This etag can be used as the value of a If-Match or If-None-Match header to either ensure a resource hasn't changed since the etag value was received, or to prevent unnecessary downloads for items that haven't changed.

    For example, to fetch the same file only if it has changed, pass in the etag value in a If-None-Match header.

    curl https://api.box.com/2.0/files/12345 \
      -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "If-None-Match: 1"

    This API call would result in an empty response if the file had not changed.

    Ensure consistent changes

    The If-Match header allows your application to ensure that no changes are made to items when another application or a user has made changes to the item since your application last inspected it. This helps ensure that changes aren't lost when two applications or users are changing items at the same time.

    The following endpoints support this header.

    If-Match capable endpoints
    POST /files/:id/contentUpload a new file version
    PUT /files/:idUpdate a file's information
    DELETE /files/:idDelete a file
    PUT /folders/:idUpdate a folder's information
    DELETE /folders/:idDelete a folder
    PUT /web_links/:idUpdate a web link's information
    DELETE /web_links/:idDelete a web link

    The response of these APIs calls depends on the existence of the item, and whether the etag value matches the most recent version.

    Item found?Etag match?HTTP Status
    YesYes200
    YesNo412
    NoYes412
    NoNo404

    Moving items

    The If-Match header can not be used to prevent moving of files, folders, or web links. Instead, Box will always ensure that the latest item is moved to the new location.

    Prevent unnecessary request downloads

    The If-None-Match header allows your application to ensure that no information is downloaded for items that have not changed since your application last inspected it. This helps ensure no unnecessary information is downloaded, speeding up your application and saving on bandwidth.

    If-None-Match capable endpoints
    GET /files/:idGet a file's information
    GET /folders/:idGet a folder's information
    GET /web_links/:idGet a web link's information
    GET /shared_itemsGet a shared item's information

    The response of these APIs calls depends on the existence of the item, and whether the etag value matches the most recent version.

    Item found?Etag match?HTTP Status
    YesYes304
    YesNo200
    NoYes404
    NoNo404