API JSON best practices

Consistent JSON makes APIs easier to use, document, and debug. Here are practices that improve developer experience.

1) Choose a naming convention and stick to it

• camelCase is common in JavaScript ecosystems
• snake_case is common in Python/Ruby ecosystems

Mixing styles inside the same API is a frequent source of bugs.

2) Be intentional with null vs missing

• Missing often means “not applicable” or “not provided”
• null often means “known to be empty”

3) Use stable IDs and explicit types

IDs are commonly strings even if they look numeric (to avoid precision and formatting issues across systems).

4) Pagination should be predictable

Common patterns include:

{
  "items": [/* ... */],
  "nextCursor": "abc123"
}

5) Standardize error shapes

Clients should branch on stable error codes. See: API error payload patterns.

6) Version carefully

• Avoid breaking changes when possible
• If you must break, version explicitly (URL, header, or media type)

Related: JSON Schema basics · Validate JSON