Introduction

Choosing the right timestamp format for your API is crucial for interoperability and developer experience. This guide compares the most common formats and their use cases.

ISO 8601 Format

The international standard for date and time representation.

Examples

// Basic format
"2024-01-15T14:30:00Z"

// With timezone offset
"2024-01-15T14:30:00-05:00"

// With milliseconds
"2024-01-15T14:30:00.123Z"

Advantages

• Human-readable
• Includes timezone information
• Widely supported across programming languages
• Self-documenting format

Unix Timestamp

Seconds since January 1, 1970, 00:00:00 UTC.

Examples

// Seconds
1705327800

// Milliseconds (JavaScript style)
1705327800000

Advantages

• Compact representation
• Easy arithmetic operations
• No timezone ambiguity (always UTC)
• Efficient storage and transmission

RFC 3339 Format

A subset of ISO 8601 with stricter rules.

Example

"2024-01-15T14:30:00.123Z"

Recommendations by Use Case

Use Case	Recommended Format	Reason
REST APIs	ISO 8601 / RFC 3339	Human-readable, widely supported
High-frequency data	Unix timestamp	Compact, efficient
Log files	ISO 8601	Human-readable for debugging

Implementation Examples

JavaScript

// Convert Unix timestamp to ISO 8601
const timestamp = 1705327800;
const isoString = new Date(timestamp * 1000).toISOString();

// Parse ISO 8601 to Unix timestamp
const isoString = "2024-01-15T14:30:00Z";
const timestamp = Math.floor(new Date(isoString).getTime() / 1000);

Best Practices

1. Be consistent across your entire API
2. Always include timezone information
3. Document your chosen format clearly
4. Consider providing multiple formats if needed
5. Validate timestamp formats on input