Should I return arrays at the top level?

Prefer an object envelope. It lets you add metadata (paging, version) later without a breaking change.

Snake_case or camelCase?

Either is fine. Consistency matters more than the choice.

JSON best practices for APIs

Naming, nullability, dates, errors, and pagination — pragmatic conventions for production APIs.

February 2, 2025·9 min read

Naming

Pick one casing and stick to it. camelCase is most common in JavaScript-facing APIs; snake_case in many Ruby/Python APIs. Document it.

Nullability

Decide whether absence and null are distinct. Either always include the key (null when empty) or never include it. Don't mix.

Dates

Always ISO 8601 with timezone: "2025-04-21T09:00:00Z". Never raw epoch unless the field name screams it.

Big numbers & money

Send IDs and money as strings. JavaScript's Number loses precision above 2^53; floats can't represent 0.1 exactly.

Errors

Use a consistent envelope: { "error": { "code": "invalid_email", "message": "..." } }. Include a stable code clients can branch on; reserve message for humans.

Pagination

Cursor pagination scales better than offset. Return nextCursor in the response so clients don't compute it.

Versioning

Version in the URL (/v1/...) or via a header. Don't break field semantics inside the same version.