One Vocabulary: Naming and Consistency

The same concept spelled three ways — userId in one response, user_id in another, owner in a third; created as epoch seconds here, createdAt as an ISO string there, creation_date as YYYY-MM-DD somewhere else — is not a cosmetic problem. Every consumer writes a mapping layer to normalize it, every SDK generator produces three accessor styles, and every new integrator has to read every endpoint because none can be predicted from the last. The tax is paid on every integration, and it never goes away because fixing it later is a breaking change (Backward Compatibility: The Real Rules).

It arrives without anyone deciding. Team A ships the first endpoints in camelCase because their framework defaults to it; Team B copies a snake_case example from a partner API; a contractor adds epoch timestamps because the database stored them that way. No decision was wrong in isolation; the absence of a shared decision produced the mess. Consistency is therefore an organizational artifact — a written vocabulary and a mechanism that enforces it — not a matter of individual care (API Ownership and the Catalog decides who holds the pen).

The payoff of consistency is that the API becomes learnable by induction. A consumer who knows that lists return { data, next_cursor }, errors return { code, message, request_id, errors[] }, ids look like type_xxxx, and timestamps are RFC 3339 UTC, can write correct code against an endpoint they have never read. That is the sense in which consistency is documentation: it lets the docs say less, and it makes the Documentation Is Part of the Contract that remains describe *what* each operation does rather than re-explaining *how* every field is spelled.

A style guide is the vocabulary written down: one page, versioned, owned, with the decisions above and the reasoning behind each. The reasoning matters more than the choice — snake_case vs camelCase is a coin flip, but "because our SDK generator and our largest consumer use it" survives the next reorganization. The guide also records the exceptions and why they exist (legacy /v1/reports uses epoch timestamps; migrating in Q4), which stops the exception from being copied as a pattern.

A guide nobody enforces is a wish. Enforcement is mechanical: a linter over the OpenAPI: Describing the Contract, Not Designing It description (or whatever schema the API is described in) that fails the build on a non-conforming field name, a missing envelope, a timestamp typed as integer, an error response that is not the shared shape. Spectral-style rulesets exist for this; a custom script over the schema is a day's work. The linter runs in CI on every schema change and in the API review, and its rules *are* the style guide in executable form — this is one of the concrete arguments for Schema-First vs Code-First.

The review process closes the loop. Every new endpoint is reviewed against the guide by someone outside the authoring team; the review asks the induction question — "could a consumer of our other endpoints guess this one?" — and treats a "no" as a defect. The Review Lab's linter findings ("inconsistent id format", "list without envelope") are the same checks, run against a design before it ships.

The hardest consistency is temporal. The style guide exists so that the endpoint added in year three matches the one shipped in year one, when the original team is gone. That is why the guide, the linter and the review are a system: the guide holds the decisions, the linter enforces the checkable ones, and the review catches the rest. Any one of them alone decays.

When the vocabulary must change — an id format that has to grow, a timestamp precision that has to increase — the change follows API Migration: Running the Change End to End: both forms accepted on input for a window, one form emitted, telemetry on who still sends the old form, then removal. A vocabulary change is by definition API-wide, which makes it the most expensive kind of breaking change and the strongest reason to get the vocabulary right before the second endpoint ships.

Consistency is not uniformity of *semantics*. Two operations that genuinely differ should look different — a command-style POST /orders/{id}/ship next to resource-style CRUD is fine when Resource or Action? justified it, and The "REST Purity" Anti-Pattern warns against flattening real differences for the sake of visual sameness. The rule is that *the same thing* is spelled the same way; different things are allowed, and encouraged, to look different.