Unix Timestamp in APIs: Best Practices for REST & GraphQL Developers

When building modern APIs, handling time correctly is critical. Whether you're designing REST endpoints or GraphQL schemas, timestamps play a key role in data consistency, caching, security, and performance.

In this guide, we will explore how to use Unix timestamps effectively in APIs, including design patterns, real-world examples, and best practices followed by scalable systems.

To quickly test and convert timestamps while building APIs, use this tool: https://www.mydevtoolhub.com/tools/unix-timestamp-converter

Why APIs Prefer Unix Timestamps

APIs often use Unix timestamps because:

• They are lightweight (numbers instead of strings)
• Easy to parse across languages
• Faster for comparisons
• Avoid timezone confusion

Example API response:

{
  "id": "user_123",
  "createdAt": 1700000000
}

REST API Design with Unix Timestamp

Basic Example

GET /api/users/123

Response:

{
  "id": "123",
  "createdAt": 1700000000,
  "updatedAt": 1700000500
}

GraphQL Schema Example

In GraphQL, timestamps are usually defined as integers.

type User {
  id: ID!
  createdAt: Int!
  updatedAt: Int!
}

When to Use Unix Timestamp in APIs

1. Internal APIs

Best for microservices communication.

2. High-Performance Systems

Reduces payload size and parsing time.

3. Logging & Analytics APIs

Ensures consistent time tracking.

When NOT to Use Unix Timestamp

Sometimes ISO 8601 is better:

1. Public APIs

External developers prefer readable formats.

2. UI-Focused APIs

Frontend teams may want ready-to-display values.

Hybrid API Strategy (Recommended)

The best approach is to provide both formats.

Example:

{
  "createdAt": 1700000000,
  "createdAtISO": "2023-11-14T12:00:00Z"
}

Benefits:

• Developers get flexibility
• No extra conversion needed

Handling Timezones in APIs

Rule: Always Use UTC

Unix timestamps are inherently UTC, so:

• Store in UTC
• Send in UTC
• Convert only on frontend

Pagination Using Timestamps

Timestamps are perfect for cursor-based pagination.

Example:

GET /api/posts?after=1700000000

Backend Query:

db.posts.find({
  createdAt: { $gt: 1700000000 }
}).limit(10);

Caching Strategies

Timestamps help in cache validation.

Example:

If-Modified-Since: 1700000000

Security Use Cases

Token Expiry

const expiry = now + 3600;

Replay Attack Prevention

Use timestamps to validate request freshness.

Versioning APIs with Timestamps

You can track resource versions using timestamps.

{
  "version": 1700000000
}

Common Mistakes

1. Sending Milliseconds Instead of Seconds

// Wrong
Date.now()

// Correct
Math.floor(Date.now() / 1000)

2. Not Documenting Format

Always specify:

• Unit (seconds or milliseconds)
• Timezone (UTC)

3. Mixing Formats

Avoid inconsistency in API responses.

Best Practices Checklist

• Use seconds (10-digit timestamps)
• Always use UTC
• Document timestamp format clearly
• Consider hybrid approach
• Validate input timestamps

Debugging API Timestamp Issues

If your API returns incorrect time:

• Check timezone conversions
• Verify units (ms vs sec)
• Compare server and client time

Use this tool for quick debugging:

https://www.mydevtoolhub.com/tools/unix-timestamp-converter

Real-World API Example (Node.js)

app.get('/api/posts', async (req, res) => {
  const posts = await db.collection('posts').find().toArray();

  const formatted = posts.map(post => ({
    ...post,
    createdAtISO: new Date(post.createdAt * 1000).toISOString()
  }));

  res.json(formatted);
});

Performance Benefits

Unix timestamps improve:

• Query speed
• Sorting efficiency
• Payload size

This is critical for large-scale APIs.

FAQs

Should APIs return timestamps or ISO dates?

Best practice: return both.

Are timestamps faster in APIs?

Yes, they are faster to parse and compare.

Can GraphQL handle timestamps?

Yes, as integers or custom scalars.

What about timezone handling?

Always use UTC in APIs.

Conclusion

Unix timestamps are a powerful tool for API design. They offer speed, simplicity, and consistency across systems. However, combining them with ISO 8601 can provide the best developer experience.

By following the best practices outlined in this guide, you can build scalable, reliable, and developer-friendly APIs.

To simplify timestamp handling and debugging, use:

https://www.mydevtoolhub.com/tools/unix-timestamp-converter

Start optimizing your APIs today with proper timestamp strategies.