Types and formats

The following sections explain some basic concepts about the types and formats that can be encountered within the Box APIs.

Requests

The Box APIs use JSON in the requests bodies. There are a few notable exceptions to this rule:

• The POST /oauth2/token is used to request access tokens and as per the OAuth 2.0 specification it accepts the body to be sent with a content type of application/x-www-form-urlencoded.
• Most of the APIs that are used to upload binary data, like the POST /files/content endpoint, expect data to be sent as form data with a content type of multipart/form-data.

Headers

As per the HTTP specification, all request header names in the Box API are case-insensitive and can be provided in lowercase, uppercase, or any mixed case form. In other words, the content type header can be set as CONTENT-TYPE: application/json, content-type: application/json, content-type: application/json or even the slightly absurd cOnTeNt-TyPe: application/json.

Header values are mostly case sensitive unless stated otherwise.

GZip compression

By default data sent from Box is not compressed. To improve bandwidth and response times it's possible to compress the API responses by including a Accept-Encoding: gzip, deflate request header.

Date and times

The Box APIs support RFC 3339 timestamps. The preferred way to format a date in a request is to convert the time to UTC, for example 2013-04-17T09:12:36-00:00.

In those cases where timestamps are rounded to a given day, the time component can be omitted. In this case, 2013-04-17T13:35:01+00:00 would become 2013-04-17. In those cases where timestamps support millisecond precision the expected request format should be as followed 2013-04-17T09:12:36.123-00:00.

The timezone can differ between different files and folders because an enterprise's timezone can change over time. A common example is daylight saving time. Items created during standard time would have a different timezone than items created during daylight saving time. For this reason it's important to use a RFC3339-compliant date-time parser to handle dates returned by the API.

Timestamps are restricted to dates after the start of the Unix epoch, 00:00:00 UTC on January 1, 1970.

Responses

The Box APIs generally returns JSON in the response body. There are a few notable exceptions to this rule as well.

• APIs that delete items return an empty body with a 204 No Content HTTP status code.
• APIs used to request binary data either return a 200 OK status code with the binary data attached, or a 202 Accepted, or 302 Found status code with no body and a location header pointing to the actual binary file.

Headers

As per the HTTP specification, all response header names in the Box API are case-insensitive and could change over time.

This means that the API might return responses with a content type header of CONTENT-TYPE: application/json, content-type: application/json or content-type: application/json. Ideally your application should convert header names to a standard case upon request and then use that standardized set of headers to look up values of the headers.

Header values are always case sensitive unless stated otherwise.

Resources

Most standard API responses where only one resource is returned follow the following format.

{
  "id": "12345",
  "type": "folder",
  ...
}

Every one of these resources will always return an ID and the type of the resource.

Collections

Where an API response returns multiple items a collection is returned. Although the exact format of these collections can change from endpoint to endpoint they generally are formatted as follows.

{
  "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"
    }
  ]
}

Request IDs

When your API call returns in an error, our API will return an error object with a request_id field.

{
  "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"
}

When reaching out to support about specific error, please provide the full API response including the request_id to help our support team to quickly find your request.

Large numbers

In some cases the API can return extremely large numbers for a field. For example, a folder's size might have grown to many terabytes of data and as a result the size field of the folder might have grown to a very large number.

In these cases these numbers are returned in IEEE754 format for example 1.2318237429383e+31.