REST Lens

Category: HTTP Headers

Description

GET operations for specific resources (those with path parameters) should include an ETag header in their responses to support caching and conditional requests.

What It Checks

This rule examines GET operations that:

Have path parameters (indicating a specific resource, not a collection)
Have a 200 response defined
Verifies the response includes an ETag header

Why It Matters

ETag headers enable:

Efficient Caching: Clients can validate cached responses
Conditional Requests: Use If-None-Match for efficient updates
Bandwidth Savings: 304 responses avoid re-transferring unchanged data
Optimistic Concurrency: Use If-Match for safe updates

Examples

Good

paths:
  /users/{id}:
    get:
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
      responses:
        '200':
          description: User details
          headers:
            ETag:
              schema:
                type: string
              description: Entity tag for caching
          content:
            application/json:
              schema:
                type: object

Bad

paths:
  /users/{id}:
    get:
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
      responses:
        '200':
          description: User details
          # Missing ETag header
          content:
            application/json:
              schema:
                type: object

Exceptions

Collection endpoints (GET /users) - typically use different caching strategies
Non-GET operations
Resources that change too frequently for ETags to be useful

Configuration

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

Related Rules

Rule 20: Caching Headers - Cache-Control headers
Rule 58: Last-Modified - Last modification timestamp
Rule 60: Conditional PUT - Conditional request support
Rule 17: 412 Precondition Failed - Precondition failures

ETag Headers