liveBook · Manning

ISO 8601

As explained in The Design of Web APIs, Second Edition

An ISO 8601 date format is a standardized textual representation of calendar dates defined by ISO 8601.

ISO 8601 provides readable, standardized strings for representing dates and times in API data. Compared with numeric timestamps, these strings are easier to inspect in logs and use in test requests. section 8.5.3

Choose the representation and precision that match the data:

  • Use YYYY-MM-DD for a date without time precision, such as 1982-12-20. section 8.5.3
  • Use a date-time string such as 1982-12-20T10:31:00Z when time is needed. T separates the date and time; Z indicates UTC. section 8.5.3
  • An offset can express local time relative to UTC. Prefer UTC unless specific requirements call for another time zone, and include time precision only when necessary. section 8.10 section 8.5.3

A bank transaction time

A transaction at December 20, 1982, 10:31 a.m. can be represented as 1982-12-20T10:31:00Z. The numeric alternative, 409228260, is less immediately interpretable and does not make clear from the value alone whether it represents a date or date-time. section 8.5.3

How The Design of Web APIs, Second Edition covers it

How deep it goes
Defines date and date-time formats, explains their components, and compares time zones and timestamps.
Examples
Compares a bank transaction date-time string with its Unix timestamp and gives date-only and offset examples.
What you can do after
Apply ISO 8601 strings to API dates and times, selecting date-only or date-time precision and an appropriate time zone.
How it connects
Connects date-time strings with JSON Schema, UTC, time-zone offsets, and Unix timestamps.

Also explained in

Compare how 2 books explain ISO 8601 →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of The Design of Web APIs, Second Edition. The section links point to the parts of the book it draws on.