ADE
API Design EssentialsBETA

English

繁體中文

English

繁體中文

Appearance

[ADE-707] Date-time and Time Data ​

Guidance ​

  • All date-time and time values exchanged between clients and servers MUST strictly adhere to the RFC 3339 format. This requirement ensures that the date-time representations are unambiguous, consistent, and interoperable across different systems and platforms.
    • All APIs MUST return date-time and time values in RFC 3339 format in their responses.
    • All APIs that accept date-time and time inputs MUST accept values in RFC 3339 format.
  • APIs MAY use format including microsecond precision when needed.

RFC 3339 Format Overview ​

RFC 3339 is a profile of the ISO 8601 standard for date and time representations. It defines a clear and unambiguous format for date-time values, which includes the following components:

  1. Date: A full-date in the form YYYY-MM-DD
  2. Time: A time of day in the form hh:mm:ss
  3. Time Zone: A time-offset from UTC in the form ±hh:mm or the literal Z for UTC

Example ​

An example of an RFC 3339 date-time string is:

http
2024-07-13T14:23:55Z

This represents July 13, 2024 at 14:23:55 UTC.

Detailed Breakdown ​

  • Date: 2024-07-13
  • Time: 14:23:55
  • Time Zone: Z (UTC)

Optional Fractional Seconds ​

RFC 3339 allows for the optional inclusion of fractional seconds to a precision of up to nanoseconds. An example with milliseconds:

http
2024-07-13T14:23:55.123Z

Time Zone Offsets ​

When specifying a time zone offset, it is crucial to include the offset in hours and minutes:

http
2024-07-13T14:23:55+02:00

This represents July 13, 2024 at 14:23:55 with a two-hour offset ahead of UTC.

Design Rationale ​

Typically, timestamps are used to describe specific times, but they may be in units of seconds or milliseconds, and cannot explicitly indicate time zone information. Additionally, ISO-8601 defines a basic time format, but its regulation of time is relatively loose. Therefore, our standard is to adopt the more stringent RFC 3339.

References ​