Working with Date and Times in the RESTful API

Date and Time Fields

To ensure that users are able to easily and consistently work with dates across all TeamDynamix applications, dates submitted through the Web API are handled using Coordinated Universal Time (UTC) standards.

Format of Date/Time Fields

When submitting date and datetime fields through the Web API, values should match ISO 8601 standards. This means that values submitted for date and datetime fields should generally match the following format:

The following table describes what part of the date and time is represented in the above datetime format string.

A time value can be offset from the standard UTC value using a Time Offset. This either follows the time value as the character 'Z', indicating that the time is in UTC, or is set to the UTC time offset in the format ±[hh]:[mm] or ±[hh][mm]. The offset may or may not include a colon separating the hour and minute segment. A full list of UTC time offsets for each time zone can be found here.

Times returned from the Web API will always be in UTC, however when submitting new values for a datetime field, you may either use the UTC value or provide a UTC offset.

Date Only Fields

Although full datetime values are accepted for all date and datetime fields in the Web API, there are instances in which only date values are used. To ensure that these values are set properly when performing operations through the Web API, any date only fields should be set with a time value of 00:00:00. Additionally, a time zone offset should be used to ensure that the date selected is not offset incorrectly while being saved, leading to display problems in different time zones.

Date only fields returned from the server will have their time value set relative to the server it is being sent from. Care should be taken to ensure that these values are being treated properly when retrieving data through the Web API.

Date and Date/Time Custom Attributes

Custom Attributes that are configured as date and date/time fields can be modified similarly to other standard dates (with some exceptions for date-only fields, detailed below). All above formatting rules and specifications apply when setting custom attribute values through the Web API.

Custom Attributes configured as date only fields can be modified in two ways. While standard date/time formatting as described above will correctly set these custom attributes, you will still have to deal with time zone offsets as needed to set the values properly. To avoid this, date only custom attributes support a simpler date only format, which allows for users to omit the time and time-zone offset portion entirely. For example, the value 2018-09-19 will set a custom attribute's value to today's date.

Example Date/Time Fields

As an example, suppose a user needs to submit the current date and time as a value to a field. The following table displays how one might format the current date and time in a number of acceptable ways that the Web API can recognize.