19. Consistency Rules

A well-designed API has a single personality. Every endpoint, every response, every error should feel as though it came from the same place. Consistency rules are the guardrails that make that possible.

What Your Style Guide Must Cover

Agree on and document the following conventions before you write a single endpoint:

Area	Decision to Make
Resource naming	Plural nouns, hyphens between words, lowercase throughout
Field casing	snake_case or camelCase — pick one, apply everywhere
Pagination parameters	Standard names (page, per_page) with documented defaults and maximums
Response envelope	One consistent JSON shape for data, meta, and links
Error envelope	One consistent JSON shape for all errors, including validation details
Datetime format	UTC ISO 8601 with trailing Z
Authentication scheme	Bearer tokens in the Authorization header
Versioning	URL-path versioning (/v1/, /v2/) with a documented deprecation process

Apply It Everywhere

These conventions are not suggestions for new endpoints only. They apply uniformly:

• JSON response bodies must use the agreed field casing.
• Query parameters must use the same casing as response fields.
• Error detail keys must match the field names in requests and responses.
• Pagination parameters must be the same on every list endpoint.

Use It as a Review Checklist

Before any new endpoint ships, run through the style guide as a checklist. During code review, verify that the new code does not diverge from the established conventions. Catching inconsistencies at review time is infinitely cheaper than fixing them after consumers have built integrations around them.

Enforce Where Possible

Automate as much of this as you can. Linters, API-level test suites that validate response shapes against your OpenAPI spec, and CI checks that flag deviations from your conventions will catch drift before it reaches production.