Inconsistent API naming erodes maintainability (ISO-25010:2011 maintainability.modifiability): a mix of kebab-case, camelCase, and plural/singular resource names forces every developer to read each route individually rather than predicting it. Client codebases accumulate one-off special cases for each naming quirk, and search-and-replace migrations become unreliable. When AI generates new routes or a second engineer adds an endpoint, the inconsistency compounds — each addition makes the surface harder to audit and the refactor more expensive.
High because naming fragmentation raises change cost on every future API modification and integration, violating ISO-25010:2011 maintainability.modifiability at the structural level.
Pick one convention — lowercase kebab-case with plural resource names is the REST standard — and rename every route directory or file to match. In Next.js App Router, route names are directory names, so the rename is mechanical:
app/api/v1/users/route.ts
app/api/v1/user-profiles/route.ts
app/api/v1/billing-invoices/route.ts
Update every client-side fetch call in the same commit. Add a one-paragraph convention note to your README or an api-conventions.md file so contributors don't reintroduce drift. Internal-namespace routes (e.g., /api/cron/) are fine as a separate prefix only when that separation is documented.
ID: saas-api-design.api-consistency.consistent-naming
Severity: high
What to look for: Enumerate all API route paths across app/api/, pages/api/, or the server's router. Check whether routes follow a single consistent naming convention. Acceptable conventions: all-kebab-case (/api/user-profiles), all-snake-case (/api/user_profiles), or camelCase (/api/userProfiles) — the point is consistency, not which convention is chosen. Also check: plural vs. singular resource names (should be uniform), consistent nesting depth, and consistent prefix patterns (e.g., /api/v1/ prefix used everywhere or nowhere).
Pass criteria: At least 80% of route paths follow the same naming convention (case style and plural/singular pattern consistent). One or two legacy or edge-case deviations are acceptable. Report even on pass: report the count of routes examined and the dominant convention detected.
Fail criteria: Mix of conventions found across routes with no clear dominant pattern — e.g., some routes use kebab-case and others use camelCase, or some resources are plural and others singular without a rule. Additionally, fail if two or more distinct URL namespace prefixes are used for API routes without documented intent (e.g., /api/v1/ and /api/cron/ coexisting). Internal routes (cron endpoints, health checks) that intentionally use a different namespace must have a comment or naming convention that explains the separation. Undocumented namespace fragmentation is a structural naming inconsistency even if individual route naming within each namespace is consistent.
Skip (N/A) when: Fewer than 2 API routes exist in the project. Signal: only 0 or 1 route handler files detected.
Detail on fail: Name the specific inconsistencies found (e.g., "Routes mix kebab-case (/api/user-profiles) and camelCase (/api/userProfile); resource naming is inconsistent between plural (/api/posts) and singular (/api/user)"). Max 500 chars.
Remediation: Pick one naming convention and apply it uniformly across all routes in app/api/ or pages/api/. The REST convention is lowercase kebab-case with plural resource names:
app/api/v1/users/route.ts
app/api/v1/user-profiles/route.ts
app/api/v1/billing-invoices/route.ts
Once chosen, update all routes and any client-side fetch calls. For Next.js App Router, this means renaming the route directory; for Pages Router, renaming the file. Document the chosen convention in a README or API reference so it's enforced going forward. When using a separate namespace for internal routes (e.g., /api/cron/), add a comment or README section explaining the intentional separation.
Note: Next.js projects frequently mix Server Actions and API Route Handlers for the same resource type (e.g., using a Server Action for creating items but an API route for deleting them). When evaluating naming consistency, note in the detail field if the project uses both patterns for the same domain without a clear architectural boundary.