JSON best practices for APIs
Naming conventions, versioning, nullability, payload design and pagination tips for high-quality JSON APIs.
By JSON Formatter Team
Pick one naming convention
Choose camelCase or snake_case and use it everywhere. Mixing them is the single biggest tell of a poorly-maintained API. camelCase is the default for JavaScript ecosystems; snake_case is idiomatic for Python and Ruby.
Prefer null over missing keys
Return "middle_name": null rather than omitting the field. Consumers can now rely on the shape.
Use ISO 8601 for dates
"created_at": "2026-07-01T12:34:56Z". Never Unix epochs, never locale-specific formats.
Version at the URL or header, never in the payload
/v2/orders or Accept: application/vnd.acme.v2+json. Do not embed "version": 2 in each response.
Wrap collections in a container
{"data": [...], "next_cursor": "..."} beats a bare array — you can add pagination or metadata without breaking existing clients.
Keep payloads flat where possible
Deeply nested objects are painful to consume and to diff. Flatten unless the nesting carries real semantics.
Avoid over-fetching
Support field selection (?fields=id,name) or provide focused endpoints for common views.
Document the contract
Publish an OpenAPI spec or JSON Schema. It powers client generation, contract tests and honest documentation.
Test with fuzzed inputs
Validators, formatters and repair tools like ours let you paste real production payloads and immediately see edge cases.