Lesson 9 / 24

Field Naming Conventions

Picking one casing and sticking to it across the whole API.

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 `[ {...}, {...} ]`?

  • It's slower to parse than an object
  • You can't add metadata (pagination, totals) later without a breaking change
  • JSON doesn't officially support arrays at the top level
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.