8. Field Naming Consistency

Inconsistent field names across your API force every client to maintain a bespoke mapping layer. Picking a single convention and applying it everywhere removes that friction entirely.

Choose snake_case

snake_case is the most widely adopted convention for JSON APIs, particularly in server-side ecosystems (Ruby on Rails, Laravel, Python). It is easy to read and requires no transformation when mapped to database column names:

{
    "id": 1,
    "first_name": "Jane",
    "last_name": "Smith",
    "email_address": "[email protected]",
    "created_at": "2026-01-15T10:30:00Z"
}

Why Consistency Matters

An API that mixes conventions — firstName in one endpoint, last_name in another, EmailAddress somewhere else — forces client developers to check the documentation for every single field. This increases integration time, raises the chance of bugs, and erodes confidence in the API.

Pick one convention and enforce it:

• JSON response bodies — use the chosen casing for all keys.
• Query parameters — use the same casing (e.g. ?sort=created_at, not ?sort=createdAt).
• Error detail keys — the field names in validation error responses must match the field names in the request and response payloads.

When You Must Support Multiple Conventions

If your API serves clients in ecosystems that strongly prefer camelCase (JavaScript front ends, for example), consider returning both or offering a header/parameter that switches the response casing. This is a deliberate, documented choice — not a fallback for an inconsistent API.