Consistency & Conventions

The individual rules matter less than applying them everywhere. An API that is 90% consistent is more confusing than one that is consistently quirky, because the exceptions are where bugs and support tickets live.

Pick conventions once

Decide these for the whole API and write them down:

Casing of fields — camelCase or snake_case, the same in every response.
Plurals — every collection plural (/articles, /users), no mixing.
IDs — one format (UUID, ULID, or integer) and one field name (id).
Timestamps — ISO 8601 UTC strings (2026-06-24T10:00:00Z), with consistent field names like createdAt/updatedAt.
Money & enums — minor units (integers) for money; documented string enums, not magic numbers.

Collections vs singletons

Most resources are items in a collection (/articles/42). A few are singletons — there is exactly one per context, so there is no ID:

GET   /me              # the authenticated user
GET   /settings        # the account's settings
PATCH /settings        # update them

Singletons skip the collection level on purpose; do not invent a fake ID for them.

A conventions checklist

Collections are plural; items are /collection/{id}.
Lowercase, hyphenated paths; no verbs; no file extensions.
One casing, one ID format, one timestamp format across every resource.
Errors share one shape (covered in Status Codes & Errors).
The same field means the same thing everywhere.