The 5 laws of API dates and times

The page gives five rules for handling dates and times in APIs. It recommends ISO 8601, accepting any timezone input, storing times in UTC, returning UTC to consumers, and leaving out time values when only a date is needed.

Reading notes

#

• Use ISO 8601 because it sorts naturally, handles timezone offsets, avoids locale ambiguity, and is widely supported by programming languages and libraries.
• Accept any timezone because API users can come from anywhere, and the API should not assume one timezone for everyone.
• Store dates and times in UTC, since UTC is the common reference point and avoids tying data to the company headquarters timezone.
• Return dates and times in UTC so consumers can apply the offset they need and the API team does not have to calculate offsets for every request.
• Do not use time when it is not needed, especially for date-only values like a target completion date, because adding a random time can create interpretation problems across timezones.