REST Lens

Category: Query Parameters

Description

GET requests should support a fields query parameter to enable partial responses, allowing clients to request only specific fields they need.

What It Checks

This rule validates that GET operations include a query parameter named fields for partial response support. It checks:

All GET operations across your API
The presence of a query parameter named exactly fields
The parameter type is array or object (to support multiple field specifications)
Only GET methods are evaluated (other HTTP methods are skipped)

Why It Matters

Supporting a fields query parameter enables partial responses, which provides significant benefits:

Bandwidth Optimization: Clients receive only the data they need, reducing payload size and network usage
Performance: Smaller responses lead to faster transmission times and reduced parsing overhead
Flexibility: Clients can tailor responses to their specific use cases without requiring multiple specialized endpoints
Mobile-Friendly: Particularly important for mobile clients with limited bandwidth or processing power

Examples

Good ✅

paths:
  /users:
    get:
      summary: List all users
      parameters:
        - name: fields
          in: query
          description: Comma-separated list of fields to return
          required: false
          schema:
            type: array
            items:
              type: string
          example: ["id", "name", "email"]
      responses:
        '200':
          description: List of users with requested fields

  /products/{productId}:
    get:
      summary: Get product details
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
        - name: fields
          in: query
          description: Fields to include in response
          schema:
            type: object
            properties:
              include:
                type: array
                items:
                  type: string
      responses:
        '200':
          description: Product with selected fields

  /orders:
    get:
      summary: List orders
      parameters:
        - name: fields
          in: query
          schema:
            type: array
            items:
              type: string
              enum: ["id", "total", "status", "items", "customer"]
      responses:
        '200':
          description: Orders with requested fields

Bad ❌

paths:
  /users:
    get:
      summary: List all users
      # No fields parameter - always returns full user object
      responses:
        '200':
          description: List of users

  /products/{productId}:
    get:
      summary: Get product details
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
        # Missing fields parameter
      responses:
        '200':
          description: Full product object

  /orders:
    get:
      summary: List orders
      parameters:
        - name: select
          in: query
          # Wrong parameter name (should be 'fields')
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Orders

  /invoices:
    get:
      summary: List invoices
      parameters:
        - name: fields
          in: query
          schema:
            type: string  # Wrong type - should be array or object
      responses:
        '200':
          description: Invoices

Configuration

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

Implementation Patterns

Array-Based (Simple)

parameters:
  - name: fields
    in: query
    description: Comma-separated list of fields to return
    schema:
      type: array
      items:
        type: string
    example: ["id", "name", "email"]

Usage: GET /users?fields=id,name,email

Object-Based (Advanced)

parameters:
  - name: fields
    in: query
    description: Field selection object
    schema:
      type: object
      properties:
        include:
          type: array
          items:
            type: string
        exclude:
          type: array
          items:
            type: string

Usage: GET /users?fields[include]=id,name&fields[exclude]=password

How to Fix

Add the fields parameter to all GET operations:

# Before
/users:
  get:
    summary: List users
    responses:
      '200':
        description: Users

# After
/users:
  get:
    summary: List users
    parameters:
      - name: fields
        in: query
        schema:
          type: array
          items:
            type: string
    responses:
      '200':
        description: Users

Use array or object type (not string):

# Correct
schema:
  type: array
  items:
    type: string

# Or
schema:
  type: object

Document expected field names in the description or using enums:

parameters:
  - name: fields
    in: query
    description: "Available fields: id, name, email, createdAt, updatedAt"
    schema:
      type: array
      items:
        type: string
        enum: ["id", "name", "email", "createdAt", "updatedAt"]

Implement server-side field filtering to actually return partial responses:

// Example implementation
app.get('/users', (req, res) => {
  const fields = req.query.fields || [];
  const users = getAllUsers();

  if (fields.length > 0) {
    const filteredUsers = users.map(user =>
      fields.reduce((obj, field) => {
        if (user.hasOwnProperty(field)) {
          obj[field] = user[field];
        }
        return obj;
      }, {})
    );
    return res.json(filteredUsers);
  }

  return res.json(users);
});

Related Rules

Rule 24: Query Pagination GET - Supports pagination for collection responses
Rule 25: Query Sorting GET - Enables sorting of collection results
Rule 16: Response Schema - Ensures proper response schema definitions for partial responses

Best Practices

Consistent naming: Always use fields as the parameter name across your API
Whitelist fields: Validate requested fields against a whitelist to prevent exposing sensitive data
Default behavior: When fields is not provided, return a sensible default (usually all non-sensitive fields)
Nested fields: Consider supporting dot notation for nested fields (e.g., user.profile.name)
Documentation: Clearly document which fields are available for selection
Security: Never allow filtering to expose fields that should be protected (e.g., passwords, tokens)

Query Fields GET