Unix Timestamps in API Design: Epoch vs ISO 8601

When building APIs that return dates and times, you face a choice: return a Unix integer like 1700000000 or a string like "2023-11-14T22:13:20Z". Each has clear use cases.

Why APIs use Unix timestamps

Epoch integers are preferred when:

• Performance matters — integers sort and compare faster than strings
• Clients are in multiple timezones — epoch is always UTC, no ambiguity
• Storage is a concern — 4 or 8 bytes vs 24+ bytes for an ISO string
• The value will be used for arithmetic (e.g. calculating durations, expiry)

// Example: JWT expiry uses epoch seconds
{
  "sub": "user_123",
  "iat": 1700000000,
  "exp": 1700086400
}

When ISO 8601 strings are better

ISO 8601 strings are preferred when:

• Human readability matters (logs, debugging, admin interfaces)
• You need to preserve timezone information beyond UTC
• The API is consumed directly by non-developers (spreadsheets, BI tools)

// Example: calendar API returns ISO string
{
  "event": "Team Standup",
  "start": "2026-01-15T09:00:00+07:00",
  "end": "2026-01-15T09:30:00+07:00"
}

Best practice: return both

Many well-designed APIs return the epoch integer as the canonical value and include the ISO string as a convenience field. This gives clients flexibility without ambiguity.

{
  "created_at": 1700000000,
  "created_at_iso": "2023-11-14T22:13:20Z"
}