Timezones in REST APIs — Design Patterns and Standards

Timezone Handling in REST APIs

Designing APIs that handle timezones correctly requires consistent conventions for how timestamps are transmitted and interpreted.

Timestamp Format: Always ISO 8601 with UTC

API responses should use ISO 8601 format with the Z suffix or explicit offset:

{
  "createdAt": "2024-03-15T14:30:00Z",
  "updatedAt": "2024-03-15T14:30:00Z"
}

Never return timestamps in local time without an offset:

// BAD — ambiguous
{ "createdAt": "2024-03-15T14:30:00" }

// BAD — non-standard format
{ "createdAt": "March 15, 2024 2:30 PM EST" }

User Timezone in Requests

There are three common patterns for specifying the user's timezone:

Pattern 1: Query Parameter

GET /api/events?timezone=America/New_York

Pattern 2: Request Header

X-Timezone: America/New_York

Pattern 3: User Profile Setting

// Stored in user profile, applied server-side
{
  "preferences": {
    "timezone": "America/New_York"
  }
}

Returning Both UTC and Local Time

For user-facing APIs, it can be helpful to return both:

{
  "event": {
    "name": "Team Standup",
    "startsAt": "2024-03-15T14:30:00Z",
    "startsAtLocal": "2024-03-15T10:30:00-04:00",
    "timezone": "America/New_York",
    "timezoneAbbreviation": "EDT"
  }
}

Date-Only Fields

When a timestamp represents only a date (no specific time), use the ISO 8601 date format without time or timezone:

{
  "birthday": "1990-05-15",
  "dueDate": "2024-03-31"
}

Scheduling APIs

For scheduling endpoints, accept both a local time and timezone ID:

// POST /api/events
{
  "name": "Weekly Sync",
  "localTime": "10:00",
  "timezone": "America/New_York",
  "recurrence": "RRULE:FREQ=WEEKLY;BYDAY=MO"
}

This lets the server compute the correct UTC time for each occurrence, including across DST boundaries.

Validation

Always validate timezone IDs server-side:

function isValidTimezone(tz) {
  try {
    Intl.DateTimeFormat(undefined, { timeZone: tz });
    return true;
  } catch {
    return false;
  }
}