Inconsistent API Naming and Conventions

Inconsistent API naming is when conventions vary across an API: some fields are camelCase and others snake_case, some collections are singular and others plural, dates come in different formats, and errors have different shapes per endpoint. The API has no coherent design language.

Why It Happens

APIs grow incrementally, often by different teams or over years, with no shared style guide. Each developer applies their own habits. Endpoints get bolted on under deadline pressure without anyone owning consistency. When there is no machine-readable spec or linting, drift accumulates silently until the surface is a patchwork.

Why It Hurts

Consumers must learn each endpoint's quirks individually rather than generalizing from a pattern, raising the learning curve and integration time. Inconsistency breeds bugs: a client that assumes userId everywhere trips over an endpoint that returns user_id. Error handling becomes error-prone when every endpoint reports failures differently, so clients can't write one robust handler. Code generation and tooling work poorly against an irregular surface. The cumulative effect is friction and lost developer goodwill, which for a product API translates to lost adoption.

Warning Signs

• Mixed casing styles across fields and parameters.
• Some collection endpoints are singular, others plural.
• Multiple date/time formats appear across responses.
• Each endpoint returns errors in a different structure.

Better Alternatives

Adopt an API style guide that fixes casing, pluralization, resource naming, pagination, filtering, and a single error format (such as RFC 9457 Problem Details). Describe the API with a machine-readable specification like OpenAPI so it can be reviewed and linted. Use consistent resource-naming conventions — plural nouns for collections, standard HTTP semantics for actions. Enforce the guide automatically in CI with a linter (for example, Spectral).

How to Refactor Out of It

Write or adopt a style guide and capture the current API in an OpenAPI spec to see the inconsistencies clearly. Apply the guide to all new endpoints immediately. For existing inconsistencies on a live API, fix forward under versioning rather than breaking clients — standardize within the next version while keeping the old contract until deprecated. Add automated linting to block new violations. Consistency compounds: once the API speaks one language, every new endpoint becomes predictable and self-documenting.