REST Lens

Category: URI Design

Description

Collection names in URIs should use plural nouns (e.g., /users, /orders) rather than singular forms.

What It Checks

This rule validates that path segments representing collections (not path parameters or verb endpoints) use plural nouns. It checks:

Path segments that represent collections of resources
Excludes path parameters like {id} or {userId}
Excludes terminal verb segments (e.g., /users/search)

Why It Matters

Using plural nouns for collections provides consistency and clarity:

Consistency: Standardizes how collections are named across your API
Clarity: Makes it immediately obvious that the endpoint returns multiple resources
REST conventions: Follows widely adopted REST API design patterns
Predictability: Developers can predict endpoint naming patterns

Examples

Good ✅

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

  /users/{userId}:
    get:
      summary: Get a specific user

  /orders:
    get:
      summary: List orders

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

Bad ❌

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

  /order:  # Should be /orders
    get:
      summary: List orders

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

Exceptions

The rule allows singular nouns in these cases:

Path parameters: /{userId} (automatically detected)
Terminal verbs: /users/search (when "search" is the last segment and is a verb)
Singleton resources: Resources that naturally represent a single entity (though these should be rare)

Configuration

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

Related Rules

Rule 26: Hyphens vs Underscores - URI naming style
Rule 28: Lowercase Letters - URI casing
Rule 75: Consistent Naming Conventions - Overall naming patterns

Plural Collections