Designing JSON Representations — REST APIs in Depth

Consistency beats any single convention. Pick one field casing (snake_case or camelCase) for the whole API. Use ISO-8601/RFC 3339 timestamps in UTC (2026-10-10T09:12:44Z), money as minor units plus currency (or decimal strings), strings for 64-bit IDs (JavaScript loses precision above 2^53), and string enums that clients treat as open (unknown values must not crash them). Decide how you represent absence: omit vs null, and document it. Avoid response envelopes for single resources; for collections, a small wrapper (items, next_cursor) is useful.

Field type conventions

Data	Recommended	Why
Timestamps	"2026-10-10T09:12:44Z"	Unambiguous, sortable, timezone-safe
Dates only	"2026-10-10"	No fake midnight/timezone
Money	{"amount": 1299, "currency": "EUR"}	No float rounding
IDs	"ord_01J9ZK…" (string)	No JS precision loss; opaque
Enums	"status": "shipped"	Readable; clients tolerate new values
Booleans	"is_active": true	Not "Y"/"N" or 0/1
Durations	"PT15M" or seconds as integer	Explicit unit

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "ord_01J9ZK6R3B",
  "status": "paid",
  "customer_id": "cus_19",
  "total": {"amount": 2400, "currency": "EUR"},
  "created_at": "2026-10-10T09:12:44Z",
  "shipping_address": null,
  "items": [{"sku": "MUG-01", "quantity": 2, "unit_price": {"amount": 1200, "currency": "EUR"}}]
}

Common pitfalls

Floats for money.
Local times without offsets.
Numeric IDs above 2^53 parsed by JavaScript clients.

Key points

One casing convention
UTC RFC 3339 timestamps, minor-unit money, string IDs
Open enums; documented null semantics

Further reading: Zalando RESTful API Guidelines: JSON

Practice questions

Why should 64-bit IDs be sent as strings in JSON?

Answer

JavaScript numbers are IEEE-754 doubles and lose precision above 2^53, so large IDs get silently corrupted in browsers and Node unless sent as strings.

What does it mean to treat enums as 'open'?

Answer

Clients must handle unknown enum values gracefully (e.g., show 'other'), so the server can add new values without breaking existing clients.