Skip to main content

URL segments use one casing style

ab-000356 · api-design.naming-conventions.url-casing
Severity: highactive

Why it matters

Mixed URL casing — /api/user-profiles alongside /api/order_items — creates ambiguity that breaks DNS case-sensitivity on some servers, confuses API clients that normalize URLs differently, and forces documentation to call out each route individually instead of stating a predictable rule. The iso-25010:2011 maintainability.modifiability impact is direct: developers adding new routes have no clear template to follow and will continue adding to the inconsistency.

Severity rationale

High because URL segment casing inconsistencies can cause routing failures on case-sensitive servers and force every consumer to memorize per-route conventions.

Remediation

Pick one URL casing convention — kebab-case is the REST standard — and rename all routes in a single pass. Update client-side fetch calls and any saved references:

// Before -- mixed casing:
/api/user-profiles
/api/order_items
/api/paymentMethods

// After -- consistent kebab-case:
/api/user-profiles
/api/order-items
/api/payment-methods

If you have external consumers, add redirects from the old paths and announce the change with a deprecation header before removing them.

Detection

  • ID: api-design.naming-conventions.url-casing

  • Severity: high

  • What to look for: Examine all URL path segments across route definitions. Check that all segments use one consistent casing: kebab-case (/api/user-profiles), snake_case (/api/user_profiles), or camelCase (/api/userProfiles). The REST convention is kebab-case, but consistency matters more than which convention is chosen. Look for mixing: /api/user-profiles/recent_orders.

  • Pass criteria: List all URL path segments containing multi-word names. All URL path segments use one consistent casing convention. No mixing of kebab-case and snake_case or camelCase in paths. Must not pass when even a single segment deviates from the dominant convention.

  • Fail criteria: URL segments mix casing conventions (e.g., /api/user-profiles and /api/order_items coexist, or /api/userProfiles and /api/user-settings).

  • Skip (N/A) when: Fewer than 3 API routes exist, or all routes are single-segment (e.g., /api/users, /api/posts -- no multi-word segments to evaluate).

  • Detail on fail: Show the mixed casing (e.g., "Routes mix kebab-case (/api/user-profiles, /api/team-members) with snake_case (/api/order_items, /api/payment_methods). 4 routes use kebab-case, 3 use snake_case."). Max 500 chars.

  • Remediation: Pick one URL casing convention (kebab-case is the REST standard) and rename all routes. Update client-side fetch calls, documentation, and any saved bookmarks.

    // Before -- mixed casing:
/api/user-profiles
/api/order_items
/api/paymentMethods

// After -- consistent kebab-case:
/api/user-profiles
/api/order-items
/api/payment-methods

External references

Taxons

code-quality

History