diff --git a/sections/designRules.md b/sections/designRules.md index 95403e7..f4d8ec1 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -125,6 +125,22 @@ A resource that corresponds to a single conceptual entity is referred to as a [= +
+

Use ISO 8601 for date and time formats

+
+
Statement
+
+

All date and time fields in requests and responses MUST follow [[RFC9557]] and thus be in [[ISO8601]] format (e.g., YYYY-MM-DD for dates, YYYY-MM-DDTHH:mm:ssZ for timestamps). Fields in responses containing timestamps MUST be in UTC (e.g. Z as offset). APIs MUST accept fields with timestamps with any time offset in requests and servers SHOULD normalize to (and store in) UTC.

+

If the time portion is not relevant, only the date portion (e.g., YYYY-MM-DD) SHOULD be accepted, stored, and returned.

+
+
Rationale
+
+

Implementing ISO 8601 in UTC removes ambiguity in date handling between systems and timezones.

+

Inserting a default or irrelevant time can lead to interpretation errors in international contexts. A publish date of 2025-07-24T00:00:00Z could for instance be rendered as July 23 in Ireland. A default time of 23:59 would in turn cause date confusion east of Greenwich.

+
+
+
+ ## HTTP methods Although the REST architectural style does not impose a specific protocol, REST APIs are typically implemented using HTTP [[rfc9110]].