Epoch Timestamps in REST API Design

Epoch Timestamps in API Design

APIs need a consistent, unambiguous way to represent time. The choice between epoch integers and ISO 8601 strings affects client implementation complexity, debugging ease, and data size.

Common Patterns

Epoch seconds (Stripe, Twilio):

{
  "id": "evt_123",
  "created": 1705312200,
  "expires_at": 1705398600
}

ISO 8601 (GitHub, AWS):

{
  "id": "evt_123",
  "created_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-16T09:30:00Z"
}

Milliseconds (Discord, Twitter/X):

{
  "id": "evt_123",
  "timestamp": 1705312200000
}

Choosing a Format

Criterion	Epoch (int)	ISO 8601 (string)
Payload size	Smaller	Larger
Human debugging	Harder	Easier
Timezone clarity	Implicit UTC	Explicit with Z or offset
Client parsing	Trivial	Requires date parser
Arithmetic	Native subtraction	Needs conversion
Documentation	Must specify seconds/ms	Self-documenting

Best Practices

1. Be consistent: Pick one format and use it across all endpoints
2. Document the unit: If using epoch, always state whether it is seconds or milliseconds
3. Use field naming conventions: created_at for ISO 8601, created for epoch
4. Always use UTC: Never return localized timestamps from an API
5. Include timezone info: If using ISO 8601, always include Z or an offset
6. Support both in input: Accept epoch or ISO 8601 in query parameters for flexibility

Versioning Considerations

If you need to change timestamp formats between API versions, provide clear migration guides. Changing from epoch to ISO 8601 (or vice versa) is a breaking change that requires a new API version.