Lesson 9 / 25

Field Naming Conventions

Pick one field-naming convention, add units to names and prefix booleans so payloads stay clear and consistent.

camelCase or snake_case — just be consistent

JSON APIs commonly use camelCase (matches JavaScript) or snake_case (matches many backend languages and SQL columns). Either works; mixing both in the same payload is what confuses clients.

Be explicit about units and types

Name fields so their meaning is obvious: priceCents not price, durationSec not duration. It prevents a whole class of unit-mismatch bugs on the client.

Booleans read as questions

Prefix booleans so they read naturally: isActive, hasShipped, canCancel — rather than ambiguous nouns like active or shipped which could be a status string instead.

Quick check: What's the main risk of a top-level API response being a bare JSON array like `[ {...}, {...} ]`?

You can't add metadata (pagination, totals) later without a breaking change
It's slower to parse than an object
JSON doesn't officially support arrays at the top level
It cannot contain nested objects

Answer

You can't add metadata (pagination, totals) later without a breaking change — Once clients expect an array, you can't wrap it in an object to add fields like `meta` or `total` without breaking every existing consumer.