API JSON best practices

A JSON API is easiest to use when every endpoint follows the same conventions, so a developer who has learned one endpoint can predict how the rest behave. The conventions below are widely used and avoid the most common sources of client bugs. What matters most is choosing a convention and applying it everywhere.

1) Pick one naming style for keys

Use either camelCase (createdAt, common in JavaScript ecosystems) or snake_case (created_at, common in Python and Ruby APIs) and never mix them. Mixed styles force clients to remember each field individually.

Also:

• Use plural nouns for collections (items, orders) and singular names for single values.
• Prefix booleans so their meaning is obvious: isActive, hasChildren, canEdit.
• Avoid abbreviations that aren't universal: quantity beats qty.

2) Be deliberate about null vs a missing field

These mean different things, and clients often treat them differently:

• "middleName": null means the field exists and has no value.
• A missing middleName key can mean "not set", "not requested" or "not available in this version".

Choose a rule and document it. A common approach is to always include every field defined for a resource, using null for empty values, so the response shape is predictable. For partial updates (PATCH), missing means "leave unchanged" and null means "clear the value".

3) Use standard formats for common types

• Dates and times: ISO 8601 strings in UTC, such as "2026-03-15T14:30:00Z". Avoid Unix timestamps whose unit (seconds or milliseconds?) clients must guess, and avoid locale formats like 03/04/2026.
• Money: an integer number of minor units plus a currency, such as {"amount": 1999, "currency": "USD"}, or a decimal string like "19.99". Floating-point numbers can't represent many decimal values exactly.
• Large integers: JavaScript loses precision above 2^53 − 1 (9,007,199,254,740,991). Send 64-bit IDs, such as database or snowflake IDs, as strings.
• Identifiers: opaque strings, such as UUIDs, are easier to evolve than sequential integers and don't reveal how many records you have; see What is a UUID.
• Enums: stable lowercase or uppercase strings ("pending", "shipped"), never integers whose meaning lives in documentation.

4) Paginate every list

Any endpoint that returns a list will eventually return too much. Paginate from the start:

json
{
  "items": [
    {"id": "o_101", "status": "shipped"},
    {"id": "o_102", "status": "pending"}
  ],
  "nextCursor": "eyJpZCI6Im9fMTAyIn0",
  "hasMore": true
}

Cursor-based pagination stays correct when records are added or removed between requests. Offset-based pagination (?page=3&limit=50) is simpler but can skip or repeat items while data changes. Always cap limit on the server.

Wrapping lists in an object rather than returning a bare array also lets you add nextCursor, totals or other metadata later without breaking clients.

5) Use one error shape everywhere

Return the correct HTTP status code and the same error envelope from every endpoint, with a stable machine-readable code. See API error JSON payload patterns for examples.

6) Version without breaking clients

• Additive changes are safe: new optional fields, new endpoints and new enum values (if clients are told to ignore unknown values).
• Breaking changes need a new version: removing or renaming fields, changing types, or changing what a field means.
• Version with a URL prefix (/v2/orders) or a header, and keep old versions running long enough for clients to migrate.
• Tell clients to ignore unknown fields. That single rule makes most additive changes painless.

7) Keep responses lean and predictable

• Don't return internal fields such as password hashes, internal flags or database implementation details.
• Prefer consistent nesting. For example, always return a related object as {"customer": {"id": ...}} rather than sometimes an ID and sometimes an object.
• Send Content-Type: application/json; charset=utf-8 and compress responses with gzip or Brotli.

8) Validate both directions

Validate incoming request bodies against a schema and reject invalid input with a clear error. Validating your own responses in tests catches accidental breaking changes. See JSON Schema basics.

Try it

Send requests to your API with curl or your API testing tool, and paste responses into the JSON Formatter to check naming, null handling and date formats across endpoints. Comparing responses from two versions is a quick way to spot accidental breaking changes.