REST Lens

Category: HTTP Methods

Description

POST should not be used for operations that are semantically idempotent. If calling an operation multiple times with the same input produces the same result (no additional side effects after the first call), it should use PUT instead of POST.

What It Checks

This rule analyzes POST operations in the API:

Skips obvious resource creation endpoints (e.g., POST /users with "create" in the summary)
Uses AI to evaluate whether the remaining POST operations are semantically idempotent
Flags operations where PUT would be more appropriate based on their name, path, and description

Why It Matters

Correct HTTP method usage improves:

Predictability: Clients know POST creates new resources and is not safe to retry, while PUT is idempotent and safe to retry
Reliability: Idempotent operations can be safely retried on network failures without causing duplicate side effects
Cacheability: Intermediaries (proxies, CDNs) understand HTTP method semantics and can optimize accordingly
Standards Compliance: REST APIs should respect HTTP method semantics as defined in RFC 9110

Examples

Good

paths:
  /users/{id}/activate:
    put:
      operationId: activateUser
      summary: Activate a user account
      responses:
        "200":
          description: User activated

  /settings:
    put:
      operationId: updateSettings
      summary: Replace application settings
      responses:
        "200":
          description: Settings updated

  /users:
    post:
      operationId: createUser
      summary: Create a new user
      responses:
        "201":
          description: User created

Bad

paths:
  /users/{id}/activate:
    post:
      operationId: activateUser
      summary: Activate a user account
      # Activating is idempotent — calling it twice has no extra effect
      responses:
        "200":
          description: User activated

  /settings:
    post:
      operationId: updateSettings
      summary: Replace application settings
      # Replacing settings is idempotent — same input, same result
      responses:
        "200":
          description: Settings updated

Exceptions

Operations that are intentionally POST for backward compatibility
RPC-style APIs where POST is used as a general-purpose verb
Operations that have non-obvious side effects (e.g., logging, audit trails) that make them non-idempotent

Configuration

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

Related Rules

Rule 5: GET/POST Tunneling - Detect misuse of GET/POST for other operations
Rule 7: POST for Create - POST should create new resources
Rule 83: Toggle Anti-Pattern - POST toggles should be split into PUT + DELETE

Idempotent Design