Representing dates in an API is a common but often not well thought out functionality. Microsoft’s guidelines for representing dates in API’s is here  . We need to be very cognizant of representing dates, intervals, and periods in the API Payload. There are two generally accepted date formats for API’s.The two date formats are

ISO 8601 format

The ISO 8601 standard is an International Standard for the representation of dates and times. This format contains date, time, and the offset from UTC, as well as the T character that designates the start of the time, for example, 2007-04-05T12:30:22-02:00. The pattern for this date and time format is YYYY-MM-DDThh:mm:ss.sTZD. It is recommended to use the ISO-8601 format for representing the date and time in your RESTful web APIs.

The formats for an ISO8601 date are as follows:

  • Year: YYYY (2018)
  • Year and month: YYYY-MM (2018-04)
  • Complete date: YYYY-MM-DD (2018-04-25)
  • Complete date plus hours and minutes: YYYY-MM-DDThh:mmTZD (2018-04-25T18:00+01:00)
  • Complete date plus hours, minutes, and seconds: YYYY-MM-DDThh:mm:ssTZD (2018-04-25T18:00:30+01:00)
  • Complete date plus hours, minutes, seconds, and a decimal fraction of a second: YYYY-MM-DDThh:mm:ss.sTZD (2018-04-25T18:00:30.45+01:00)

The letters used in the above format are:

  • YYYY: Four-digit year
  • MM: Two-digit month (01 = January, and so on)
  • DD: Two-digit day of month (01 through 31)
  • hh: Two digits of hour (00 through 23, a.m./p.m. NOT allowed)
  • mm: Two digits of minute (00 through 59)
  • ss: Two digits of second (00 through 59)
  • s: One or more digits representing a decimal fraction of a second
  • TZD: Time zone designator (Z or +hh:mm or -hh:mm)

It offers an unambiguous way of making comparisons between two dates simpler. The date and time values are organized from the most to the least significant components: year, month (or week), day, hour, minute, second, and fraction of second. All values are numbers with leading zeros to ensure that the correct number of digits are used. Hours are given in 24-hour time. In strict ISO 8601 format, a T is required between the date and the time. The time zone designator is required for all dates that are not UTC.

The time zone designator is required for all dates that are not UTC. The time zone designator is optional for dates that are UTC. The time zone designator can be either expressed using the ±hh:mm format or using the “Z” format (UTC - Coordinated Universal Time). Z stands for Zulu time. Zulu Time Zone is 0 hours ahead of Greenwich Mean Time So 12:00 PM in Z is 12:00 PM in GMT and 5:30 PM in India.

UTC Epoch format

Epoch or Unix time is defined as the number of seconds since midnight (UTC) on 1st January 1970. The value of epoch is the amount of seconds since the timestamp, minus the amount of leap seconds since then. A 10-digit value indicates it is in seconds, while a 13-digit value is indicative of a millisecond value. An example of an epoch time format is 1524715312 which converts to the ISO 8601 format of 2018-04-26T04:01:52Z

This Wikipedia entry explains a little about the origins of Unix time and the chosen epoch. The definition of Unix time and the epoch date went through a couple of changes before stabilizing on what it is now. Early versions of Unix measured system time in 1/60 s intervals. This meant that a 32-bit unsigned integer could only represent a span of time less than 829 days. For this reason, the time represented by the number 0 (called the epoch) had to be set in the very recent past. As this was in the early 1970s, the epoch was set to 1971-1-1. Later, the system time was changed to increment every second, which increased the span of time that could be represented by a 32-bit unsigned integer to around 136 years. As it was no longer so important to squeeze every second out of the counter, the epoch was rounded down to the nearest decade, thus becoming 1970-1-1. One must assume that this was considered a bit neater than 1971-1-1.

Note that a 32-bit signed integer using 1970-1-1 as its epoch can represent dates up to 2038-1-19, on which date it will wrap around to 1901-12-13. Take a look here to understand the Year 2038 problem. Unix time is not particularly readable and certainly does not make it easy for people to interact with the service - either for exploratory or debug purposes. There are a number of online converters to convert epoch time into human readable formats. The most popular is this one .

Conclusion

ISO-8601 is a portable, readable datetime format designed with data interchange in mind. It’s supported by most languages either natively or through a third-party library. The ISO 8601 standard has been developed for clear communication of date and time information across countries, applications, and platforms. It is a standard that is used by the World Wide Web Consortium (W3C) and is supported by the ISO and other organizations. It fits in well with designing API’s that can be used globally across different time zones, consumed by different languages, and used by different platforms.