REST Lens

Category: URI Design

Description

URI path segments should use only lowercase letters to ensure consistency, readability, and avoid case-sensitivity issues across different systems.

What It Checks

This rule validates that all path segments in URIs contain only lowercase letters. It checks:

All static path segments (e.g., /users, /api, /products)
Multi-word segments (recommending kebab-case like /user-profiles)
Excludes path parameters (e.g., {userId}, {orderId})

The rule identifies any uppercase letters in non-parameter path segments and recommends converting them to lowercase.

Why It Matters

Using lowercase letters in URIs provides several important benefits:

Case-sensitivity concerns: URIs are case-sensitive according to RFC 3986, so /Users and /users are different endpoints, which can cause confusion
Consistency: Lowercase-only URIs ensure uniform naming across the entire API, making it easier for developers to remember and use
Cross-platform compatibility: Some systems and servers treat URIs as case-insensitive, leading to unexpected behavior with mixed-case URIs
Readability: Lowercase URIs with hyphens (kebab-case) are easier to read and type than camelCase or PascalCase alternatives

Examples

Good ✅

paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: Array of users

  /user-profiles:
    get:
      summary: Get user profiles

  /api/orders/{orderId}:
    get:
      summary: Get a specific order

  /products/{productId}/reviews:
    get:
      summary: Get product reviews

  /account-settings:
    get:
      summary: Get account settings

Bad ❌

paths:
  /Users:  # Should be /users
    get:
      summary: List all users

  /userProfiles:  # Should be /user-profiles
    get:
      summary: Get user profiles

  /API/Orders/{orderId}:  # Should be /api/orders/{orderId}
    get:
      summary: Get orders

  /products/{productId}/Reviews:  # Should be /reviews
    get:
      summary: Get product reviews

  /AccountSettings:  # Should be /account-settings
    get:
      summary: Get account settings

Exceptions

The rule allows uppercase letters in these cases:

Path parameters: {userId}, {OrderId} (though lowercase is still recommended)
Query parameters: Not evaluated by this rule

Configuration

This rule has no configuration options. It is either enabled or disabled.

How to Fix

Convert all path segments to lowercase:

# Before
/Users → /users
/API → /api
/Orders → /orders

Use kebab-case for multi-word segments:

# Before
/userProfiles → /user-profiles
/AccountSettings → /account-settings
/productCategories → /product-categories

Ensure consistency across your entire API:
- Review all endpoints and apply lowercase consistently
- Update documentation to reflect the lowercase convention
- If changing existing endpoints, consider versioning or deprecation strategies

Example transformation:

# Before
paths:
  /API/Users/{userId}/OrderHistory:
    get:
      summary: Get user order history

# After
paths:
  /api/users/{userId}/order-history:
    get:
      summary: Get user order history

Related Rules

Rule 26: Hyphens vs Underscores - Use hyphens for word separation
Rule 1: Plural Collections - URI naming conventions for collections
Rule 12: No File Extensions - Clean URI design patterns

Lowercase Letters