Date Formats in REST APIs and JSON

Date Formats in APIs and JSON

Choosing the right date format for your API is a critical design decision that affects interoperability, timezone handling, and developer experience. This guide covers the most common approaches and their trade-offs.

The Three Main Approaches

1. ISO 8601 / RFC 3339 String

{
  "created_at": "2026-02-28T14:30:00Z",
  "updated_at": "2026-02-28T14:30:00+09:00"
}

2. Unix Timestamp (Integer)

{
  "created_at": 1772236800,
  "updated_at": 1772236800000
}

3. Custom String Format

{
  "created_at": "02/28/2026 2:30 PM"
}

Recommendation: ISO 8601 / RFC 3339

The overwhelming industry consensus is to use ISO 8601 (specifically RFC 3339, which is a profile of ISO 8601):

"2026-02-28T14:30:00Z"

Reasons:

1. Human-readable — developers can inspect payloads visually
2. Timezone-aware — the offset is part of the string
3. Widely supported — every language has built-in parsing
4. Sortable — lexicographic sorting = chronological sorting
5. Industry standard — used by GitHub, Stripe, Twilio, AWS

When to Use Unix Timestamps

Unix timestamps make sense for:

• JWT claims — exp, iat, nbf are defined as Unix seconds
• High-frequency data — financial tickers, IoT sensor data
• Simple comparison — numeric comparison is faster than string parsing
• Existing systems — databases storing timestamps as integers

API Design Best Practices

1. Always include timezone info — never send "2026-02-28T14:30:00" without offset or Z
2. Use UTC for storage — convert to local time only on the client
3. Document your format — specify ISO 8601/RFC 3339 in your API docs
4. Be consistent — use the same format for all date fields
5. Use seconds precision by default — add milliseconds only if needed
6. Accept multiple formats on input — be liberal in what you accept
7. Consider pagination — cursor-based pagination with timestamps needs precision

Framework Defaults

Framework	Default Format
Rails	ISO 8601 (2026-02-28T14:30:00.000Z)
Django REST	ISO 8601 (2026-02-28T14:30:00Z)
Spring Boot	ISO 8601 (2026-02-28T14:30:00+09:00)
Express/Node	Date.toISOString() (2026-02-28T14:30:00.000Z)
Go (encoding/json)	RFC 3339 (2026-02-28T14:30:00Z)
ASP.NET	ISO 8601 (2026-02-28T14:30:00+09:00)