REST Lens

Category: URI Design

Description

URI paths should not contain HTTP method names (GET, POST, PUT, DELETE, PATCH). Operations should be conveyed through HTTP methods, not in the URI.

What It Checks

This rule detects HTTP method names appearing in URI path segments:

Checks for: get, post, put, delete, patch (case-insensitive)
Validates all non-parameter path segments
Flags URIs that encode the operation in the path

Why It Matters

Including HTTP methods in URIs violates REST principles:

Redundancy: HTTP methods already convey the operation
Poor REST design: URIs should identify resources, not actions
Inflexibility: Makes it harder to add new operations
Inconsistency: Mixes resource-based and action-based design

HTTP methods were designed specifically to represent operations on resources. Using them in URIs duplicates this information and creates confusion.

Examples

Good ✅

paths:
  /users/{userId}:
    get:
      summary: Retrieve a user
    delete:
      summary: Delete a user
    put:
      summary: Update a user

  /orders/{orderId}:
    get:
      summary: Get order details
    delete:
      summary: Cancel order

Why this works: The HTTP method indicates the operation; the URI identifies the resource.

Bad ❌

paths:
  /users/{userId}/get:  # ❌ 'get' in path
    get:
      summary: Retrieve a user

  /users/{userId}/delete:  # ❌ 'delete' in path
    get:  # Also using wrong HTTP method!
      summary: Delete a user

  /users/getAll:  # ❌ 'get' in path
    get:
      summary: List all users

  /orders/post:  # ❌ 'post' in path
    post:
      summary: Create order

Common Violations

1. Operation Suffix Pattern

# Bad
/users/getUsers
/products/deleteProduct
/orders/updateOrder

# Good
/users (GET)
/products/{id} (DELETE)
/orders/{id} (PUT)

2. Mixed REST and RPC Style

# Bad - mixing styles
/users (GET)
/users/create (POST)  # ❌ inconsistent
/users/{id}/update (PUT)  # ❌ inconsistent

# Good - pure REST
/users (GET, POST)
/users/{id} (GET, PUT, DELETE)

3. Action-Based Endpoints

# Bad
GET /users/{id}/getProfile
POST /users/{id}/deleteAccount

# Good
GET /users/{id}/profile
DELETE /users/{id}

Configuration

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

Exceptions

Controller-style actions that aren't CRUD operations are acceptable:

# Acceptable - these aren't HTTP methods
/users/{id}/activate
/orders/{id}/cancel
/documents/{id}/publish

How to Fix

Remove method names from URIs:

# Before
GET /users/getAllUsers

# After
GET /users

Use appropriate HTTP methods:

# Before
GET /users/{id}/delete

# After
DELETE /users/{id}

For complex actions, use resource-oriented design:

# Before
POST /orders/{id}/cancelOrder

# After
DELETE /orders/{id}
# OR if you need to preserve history:
PATCH /orders/{id}  # with status: "cancelled"

Related Rules

Rule 1: Plural Collections - Resource naming
Rule 7: POST for Create - Proper method usage
Rule 5: GET/POST Tunneling - Method misuse prevention

CRUDy URIs