REST Lens

Category: URI Design

Description

URI path segments should use hyphens (-) as word separators instead of underscores (_) for improved readability and adherence to REST API conventions.

What It Checks

This rule validates that all path segments in URIs use hyphens instead of underscores for multi-word identifiers. It checks:

All path segments in the API specification
Multi-word path components that need word separators
Excludes path parameters (e.g., {user_id} is allowed as it's a variable placeholder)

The rule recursively examines the entire path tree, flagging any non-parameter path segment containing underscore characters.

Why It Matters

Using hyphens over underscores in URIs is a critical best practice for several reasons:

Readability: Hyphens are more visually distinct and easier to read in URLs, especially when underlined in links
SEO considerations: Search engines treat hyphens as word separators but may interpret underscores differently
Industry standard: The vast majority of well-designed REST APIs use hyphens, making this pattern familiar to API consumers
Accessibility: Underscores can be difficult to see or may be hidden by URL underlining in some contexts

Examples

Good ✅

paths:
  /user-profiles:
    get:
      summary: Get all user profiles
      responses:
        '200':
          description: List of user profiles

  /api/v1/customer-orders:
    get:
      summary: Get customer orders

  /products/{productId}/review-history:
    get:
      summary: Get product review history

  /data-exports/{exportId}:
    get:
      summary: Download data export

Bad ❌

paths:
  /user_profiles:  # Should be /user-profiles
    get:
      summary: Get all user profiles

  /api/v1/customer_orders:  # Should be /customer-orders
    get:
      summary: Get customer orders

  /products/{productId}/review_history:  # Should be /review-history
    get:
      summary: Get product review history

  /data_exports/{exportId}:  # Should be /data-exports
    get:
      summary: Download data export

Exceptions

The rule allows underscores in these specific cases:

Path parameters: /{user_id} or /{order_id} (detected automatically by the rule)
Query parameters: Not evaluated by this rule (query parameter naming is separate)

Note: While path parameters with underscores are technically allowed by the rule's implementation, best practice is to use camelCase or hyphens even in parameter names for consistency.

Configuration

This rule has no configuration options. It is either enabled or disabled in your project's rule set.

How to Fix

Identify all path segments with underscores:
- Review your OpenAPI specification for paths containing _
- Focus on non-parameter segments

Replace underscores with hyphens:

# Before
/user_profiles → /user-profiles
/customer_orders → /customer-orders
/review_history → /review-history

# After
/user-profiles
/customer-orders
/review-history

Update all references:
- Ensure client code, documentation, and tests use the new paths
- Implement redirects if needed for backward compatibility
- Update any hardcoded URLs in your application

Consider path parameters:

# Acceptable (though camelCase is preferred)
/users/{user_id}

# Better
/users/{userId}

Verify consistency:
- Run the rule checker to confirm all violations are resolved
- Review your entire API for consistent naming patterns

Related Rules

Rule 1: Plural Collections - Collection naming conventions in URIs
Rule 28: Lowercase Letters - URI casing standards
Rule 75: Consistent Naming Conventions - Overall API naming patterns

Hyphens vs Underscores