Developers judge an API in the first thirty seconds, and the endpoint names do most of the talking. Bad names do not just look sloppy — they cause real integration bugs when developers guess wrong about what a path does. These are the mistakes that keep showing up in API reviews.
Mistake 1: Verbs in the path
/getUsers, /createOrder, /deleteAccount — the HTTP method already is the verb. Paths should name resources (nouns); methods name actions. Mixing them creates ambiguity: does POST /createOrder differ from POST /orders? Nobody knows, so everybody guesses.
Fix: GET /users, POST /orders, DELETE /accounts/{id}. One resource, one path, four methods. Our REST naming conventions guide covers the full pattern.
Mistake 2: Plural flip-flopping
/users here, /order there, /productList somewhere else. Inconsistent plurals force developers to memorize each endpoint instead of predicting them. Pick plural nouns for collections — /users, /orders, /products — and never deviate. The endpoint name generator defaults to plural collections for exactly this reason.
Mistake 3: Cryptic abbreviations
/usrPrfUpd, /txnHist, /custAddr — abbreviations save a few characters and cost every new developer an hour of archaeology. Worse, abbreviations collide: does "txn" mean transaction or transmission? Spell it out: /user-profile, /transaction-history. URLs are cheap; confusion is expensive.
Mistake 4: Leaking internals
/api/v2/php/get_users.php, /internal/db/orders_table — paths that expose your stack, your database schema, or your file layout. Beyond looking amateur, they hand attackers a map of your internals and lock you into implementation details you will want to change. Name the resource, not the machinery.
Mistake 5: Inconsistent casing and separators
/userProfile, /user-profile, and /user_profile in the same API. Pick one style — kebab-case is the most URL-friendly — and enforce it with a linter, because humans will not enforce it by willpower. See the endpoint examples for consistent patterns.
Mistake 6: Actions disguised as resources
Some operations genuinely are actions: password resets, publishing, approvals. The mistake is inventing a fake resource for them (/doPublish) instead of using the accepted patterns: either a sub-resource (POST /articles/{id}/publish) or a dedicated action endpoint (POST /password-resets). Actions are fine — disguised actions are not.
Mistake 7: Versioning by vibes
/api/usersV2, /v2.1/users, /users?version=3 — three versioning schemes in one API. Choose one versioning strategy (path versioning like /v2/users is the most common) and document it in your nesting and versioning guide. Inconsistency here breaks client code.
Bad vs good at a glance
| Mistake | Bad | Good |
|---|---|---|
| Verb in path | GET /getUsers | GET /users |
| Singular/plural mix | /user + /orders | /users + /orders |
| Abbreviation | /txnHist | /transaction-history |
| Leaky internals | /get_users.php | /users |
| Casing chaos | /userProfile + /user_profile | /user-profile everywhere |
Key takeaway: endpoint names are a user interface. Nouns for resources, verbs for HTTP methods, one consistent style — and developers will guess right on the first try.
Enforce it with linting, not willpower
Naming conventions decay without automation. Add endpoint linting to CI with a tool like Spectral and an OpenAPI ruleset: no verbs in paths, consistent pluralization, kebab-case only, no file extensions. The linter catches GET /getUsers in the pull request, where fixing it costs minutes — instead of in production, where fixing it costs a migration. Start with warnings on existing endpoints and errors on new ones; grandfather the old paths with a deprecation plan rather than demanding a big-bang rename. Conventions that are not enforced are suggestions, and suggestions do not survive deadlines.
Write the conventions down
None of the above sticks without a written API style guide. Keep it short — one page covering resource naming, pluralization, casing, versioning, and error formats — and link it from your contributing docs and pull request template. New endpoints get reviewed against it; old ones get fixed when touched. A style guide turns naming from personal taste into team law, which is the only way conventions survive contact with deadlines. The REST naming conventions guide is a solid starting point to adapt into your own. For the product-level naming strategy that sits behind those endpoints, see our guide on public vs internal API naming.
FAQ
Should I use singular or plural resource names?
Plural for collections (/users) is the dominant convention and what most developers expect. Whichever you choose, the real rule is consistency.
Are verbs ever acceptable in paths?
For true actions that are not CRUD — search, publish, approve — yes, as sub-resources (/articles/{id}/publish). For CRUD, never; the HTTP method is the verb.
How deep should nesting go?
Rarely more than two levels (/orders/{id}/items). Deeper nesting becomes unreadable; flatten with query parameters or top-level resources instead.
Should endpoints include the file extension?
No. /users.json leaks implementation and complicates content negotiation — use the Accept header for format selection.
How do I fix naming mistakes in a live API?
Introduce the corrected paths alongside the old ones, document the old ones as deprecated with a sunset date, and monitor usage before removal. Never rename in place.