Skip to main content

​
What is Box doing and why is Box performing this upgrade?

Box is upgrading to a new metadata storage system that provides a number of benefits for Box customers, including the ability to use the Metadata Query API to find files and folders on the basis of metadata using an SQL-like query. This update also enables Box to deliver a higher quality of service, and add metadata capabilities that previously were not possible.

​
What is changing?

As part of this transition, the API will behave in a more consistent manner. You can expect to see three classes of change:
  1. Metadata date (datetime) field changes - These changes should not require action if the implementation conforms to the RFC3339 timestamp specification as indicated in Box’s developer documentation.
  2. Error code changes - These changes may require action if you are handling specific metadata-related error codes which are returned in the response body.
  3. Metadata instance version number change - This change should not require action as it simply clarifies implicit behavior and should not be used by client logic.

​
Where to get support

If you notice anything unusual with metadata operations in your Sandbox environment following this change, please contact Product Support with a description of the problem and supporting evidence.

​
Detailed change information

​
Metadata date (datetime) field changes

  1. Previously, if you specified a datetime value in a metadata field that included a time zone offset, then on subsequent operations (such as a GET request) Box may either have returned the datetime value exactly as specified (including the time zone offset) or may have returned the datetime value normalized to Zulu time (UTC). Now, Box always returns the datetime value in a metadata field normalized to Zulu time.
     
    Before: 2020-02-20T13:00:00.000Z OR  2020-02-20T12:00:00.000-01:00
    After: 2020-02-20T13:00:00.000Z
  2. Previously, Box returned metadata datetime values with 0 to 3 digits of sub-second precision. Now, Box always returns metadata datetime values with millisecond precision.
     
    Before:  2020-02-20T12:00:00Z OR  2020-02-20T12:00:00.000 Z  
    After:  2020-02-20T12:00:00.000Z
  3. Previously, when using the “test” operator, Box compared datetime values using the literal string value. Now, Box compares date-times using their UNIX timestamp, in milliseconds (milliseconds since epoch). Before: 2020-01-21T19:20:00.123-08:00 is not equivalent to 2020-01-22T03:20:00.123Z
    After: 2020-01-21T19:20:00.123-08:00 is equivalent to 2020-01-22T03:20:00.123Z
What should I do about this? If your application implements RFC3339-compliant datetime parsing, then no action is necessary as these are all valid RFC3339 formats. If your application does not implement RFC3339-compliant datetime parsing, you should update it to do so. Note that the Box SDKs support RFC3339-compliant parsing, so applications using an up-to-date version of a Box SDK for such operations should require no change.

​
Error code changes

To be more consistent with the typical Box API dialect and to minimize confusing and non-actionable errors, Box is updating multiple metadata-related error codes and error messages returned in an API response. Note that HTTP status codes remain unchanged. For example Before: HTTP Status Code: 404| Error Code: instance_tuple_not_found
After: HTTP Status Code: 404' | Error Code: not_found` A full list of all error code changes is available. What should I do about this? If you are handling specific error codes instead of the more generic HTTP Status codes, you may need to update your application logic to handle the new error code values.

​
Metadata instance version number changes

Previously, an implicit behavior incremented the version number associated with a metadata instance if a field on the parent template was deleted, or if an enum option within a field on the parent template was deleted. Now, these changes do not increment the version number of a metadata instance. Note that Box does not support reverting to or reading values from prior versions of a metadata instance now, nor will it with this change.