Back to NiceJSON
NiceJSON Blog/ JSON API Design Best Practices: Naming, Dates, Errors, and Pagination

JSON API Design Best Practices: Naming, Dates, Errors, and Pagination

Practical conventions for designing clean, consistent JSON APIs: key naming, date formats, null handling, error responses, pagination, and versioning.

3 min read
  • json
  • api
  • best-practices

Consistency beats cleverness

A JSON API is a contract. The best ones are boring and predictable. Decide on conventions once and apply them everywhere.

Key naming

Pick one style and never mix:

StyleExampleCommon in
camelCasefirstNameJavaScript, most web APIs
snake_casefirst_namePython, Ruby, many REST APIs

Use descriptive, singular names for fields and plural names for arrays, for example user and orders.

Dates and times

Use ISO 8601 strings in UTC:

{ "createdAt": "2026-11-04T10:30:00Z" }

Avoid locale formats like 11/04/2026 (ambiguous) and bare timestamps unless you document the unit.

Numbers and money

  • Use strings or integer minor units (cents) for money to avoid floating point errors.
  • Treat large identifiers as strings. JavaScript numbers lose precision above 2^53.
{ "id": "9007199254740993", "amountCents": 1999, "currency": "USD" }

Null versus missing

Decide what each means and document it. A common rule: a missing key means "unchanged" in a PATCH request, while null means "clear this value". Keep response shapes stable by always including documented fields.

Consistent envelope

A predictable top-level structure helps clients:

{
  "data": [
    { "id": "1", "name": "Ada" },
    { "id": "2", "name": "Grace" }
  ],
  "meta": { "page": 1, "pageSize": 2, "total": 40 }
}

Error responses

Return a machine-readable code, a human-readable message, and the HTTP status that matches:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Email is not valid.",
    "details": [{ "field": "email", "issue": "format" }]
  }
}

Never leak stack traces or internal paths.

Pagination

Offset pagination (page and pageSize) is simple. Cursor pagination scales better for large or frequently changing collections and avoids skipped or duplicated items.

Versioning

Include a version in the URL (/v1/users) or a header, and avoid breaking changes inside a version: adding fields is safe, removing or renaming them is not.

Keep payloads lean

  • Return only the fields clients need, or support field selection.
  • Avoid deep nesting beyond three or four levels.
  • Use gzip or Brotli compression instead of hand-minifying.

Verify your output

Before shipping, paste a real response into NiceJSON to confirm it is valid and reads clearly. Readable structure is a sign of a well-designed API.