Shape the JSON your API returns so clients can trust it. Consistent field naming, ISO dates, string IDs, and a predictable shape for both single items and lists.
Clients write code against the shape of your JSON, so consistency is a feature. Decide a few conventions up front and never break them: one naming style for keys (camelCase is common in JavaScript APIs), dates as ISO-8601 strings (the universal "2026-01-04T09:30:00Z" format) so any timezone can read them, and IDs as strings even when they look like numbers — that avoids rounding bugs with very large numbers and lets you switch to UUIDs later without breaking clients.
// Good: consistent keys, ISO date, string id, no surprises.
{
"id": "42",
"fullName": "Ada Lovelace",
"isActive": true,
"createdAt": "2026-01-04T09:30:00Z"
}
// Avoid mixing styles within one API:
{
"ID": 42, // number id, capitalised key
"full_name": "Ada", // snake_case here, camelCase elsewhere
"created": "04/01/2026" // ambiguous date — is that Jan or Apr?
}A request for one thing returns that thing; a request for a collection returns an array, usually wrapped in an object so you have room to add metadata (like paging info) later without breaking clients. Wrapping a list in an object is the safer default — if you return a bare top-level array, you can never add fields next to it.
// One item: return the object directly.
// GET /users/42
{ "id": "42", "name": "Ada" }
// A list: wrap the array so there is room to grow.
// GET /users
{
"data": [
{ "id": "42", "name": "Ada" },
{ "id": "43", "name": "Alan" }
],
"page": { "total": 2, "limit": 20, "offset": 0 }
}
// Returning a bare [ ... ] works, but boxes you in:
// you can never add "page" beside it without breaking everyone.