REST Lens

Category: URI Design

Description

URIs should not end with a trailing slash (/) to avoid ambiguity and issues with resource identification and caching.

What It Checks

This rule validates that all path definitions in your OpenAPI specification do not end with a trailing slash. It checks:

All path definitions in the paths object
Every URI pattern regardless of HTTP method
Both collection and individual resource endpoints

A trailing slash at the end of a URI (e.g., /users/ instead of /users) is considered a violation.

Why It Matters

Avoiding trailing slashes is critical for API consistency and reliability:

Ambiguity: /users and /users/ may be treated as different resources by some servers and frameworks, leading to duplicate content issues
Caching: HTTP caching mechanisms may treat URIs with and without trailing slashes as different resources, reducing cache hit rates
Redirects: Many servers automatically redirect trailing slash URIs, adding unnecessary latency and complexity
Standards Compliance: REST API design best practices recommend consistent URI patterns without trailing slashes

Examples

Good ✅

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

  /users/{userId}:
    get:
      summary: Get a specific user
      responses:
        '200':
          description: User details

  /organizations/{orgId}/projects:
    get:
      summary: List organization projects
      responses:
        '200':
          description: Array of projects

  /products/{productId}/reviews/{reviewId}:
    get:
      summary: Get a specific review
      responses:
        '200':
          description: Review details

Bad ❌

paths:
  /users/:  # Trailing slash not allowed
    get:
      summary: List all users

  /users/{userId}/:  # Trailing slash not allowed
    get:
      summary: Get a specific user

  /organizations/{orgId}/projects/:  # Trailing slash not allowed
    get:
      summary: List organization projects

  /products/{productId}/reviews/{reviewId}/:  # Trailing slash not allowed
    get:
      summary: Get a specific review

Configuration

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

Common Violations

Trailing slash on collection endpoints:
- /users/ instead of /users
- /products/ instead of /products
Trailing slash on individual resource endpoints:
- /users/{userId}/ instead of /users/{userId}
- /products/{productId}/reviews/{reviewId}/ instead of /products/{productId}/reviews/{reviewId}
Inconsistent trailing slash usage:
- Some endpoints with trailing slashes, others without
- This creates confusion and unpredictability

How to Fix

Remove trailing slashes from all path definitions:

# Before
/users/
/products/{productId}/
/orders/{orderId}/items/

# After
/users
/products/{productId}
/orders/{orderId}/items

Update your API documentation to reflect the correct paths
If your API is already deployed with trailing slashes:
- Add server-side redirects from trailing slash URIs to non-trailing versions (301 Permanent Redirect)
- Or configure your server to normalize URIs by removing trailing slashes
- Update client applications gradually to use the correct URIs

Configure your API framework/server to handle trailing slashes consistently:

// Express.js example
app.use((req, res, next) => {
  if (req.path !== '/' && req.path.endsWith('/')) {
    const query = req.url.slice(req.path.length);
    res.redirect(301, req.path.slice(0, -1) + query);
  } else {
    next();
  }
});

Related Rules

Rule 1: Plural Collections - URI naming for collections
Rule 28: Lowercase Letters - URI casing conventions
Rule 12: No File Extensions - URI format best practices

Trailing Slash