ISO 8601 API Developer Guide: REST, GraphQL, and JSON

Why ISO 8601 is the API Standard

Before ISO 8601 became universally adopted, APIs often used custom string formats or Unix Timestamps. While Unix timestamps are efficient, they lack human readability, which hampers the Developer Experience (DX) when debugging JSON payloads.

Using ISO 8601 in REST APIs

In RESTful design, resources should expose dates as ISO 8601 strings (specifically following the RFC 3339 profile). This ensures that standard parsers across Java, Python, Go, and JavaScript can natively deserialize the data.

When using query parameters (e.g., ?start_date=2026-06-04T12:00:00+05:30), remember to URL-encode the plus sign to %2B to avoid it being interpreted as a space.

GraphQL and Custom Date Scalars

GraphQL's type system does not include a native Date type. Developers must define a custom scalar, commonly named DateTime, which maps to an ISO 8601 string in the JSON response.

scalar DateTime

type User {
  id: ID!
  createdAt: DateTime!
}

JSON Data Serialization

JSON natively supports strings, numbers, booleans, arrays, and objects, but not dates. Therefore, calling JSON.stringify() on a JavaScript Date object automatically invokes the toISOString() method, outputting a standard ISO 8601 string.

Backend Systems Integration

Regardless of what timezone the server runs in, APIs should always communicate in UTC. Ensure your backend ORMs (like Prisma, Hibernate, or Entity Framework) are configured to store times in UTC and emit them with the 'Z' suffix.

Validation Examples

Validating incoming payloads is critical to prevent database errors. You can use regex or schema validation libraries (like Zod or Joi) to ensure clients are sending valid ISO strings.

import { z } from "zod";

const UserSchema = z.object({
  name: z.string(),
  birthDate: z.string().datetime() // Validates ISO 8601 (RFC 3339)
});

Frequently Asked Questions