OpenAPI Parameters

Parameters are used to describe inputs to an operation. Parameters can be defined at the path or operation levels. Duplicates are merged at the operation level, overriding those from the path level.

Each parameter in an operation must be uniquely identified by its name and in fields combined.

A parameter in the list can either be a parameter object or a reference to a parameter object defined in the components object under the parameters field.

Parameters can represent various input types, including:

• Path parameters: Variables within the path portion of the URL.
• Query parameters: Appended to the URL after a question mark.
• Headers: Custom HTTP header values sent with the request.
• Cookies: Data sent via HTTP cookies.

This example demonstrates parameters in different locations:

paths:
  /drinks/{type}:
    parameters:
      - name: type
        in: path
        description: The type of drink to filter by.
        required: true
        schema:
          $ref: "#/components/schemas/DrinkType"
      - name: Cache-Control
        in: header
        description: The cache control header.
        required: false
        schema:
          type: string
          enum:
            - no-cache
            - no-store
            - must-revalidate
    get:
      operationId: listDrinks
      summary: Get a list of drinks.
      parameters:
        - name: limit
          in: query
          description: The maximum number of drinks to return.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100

Parameter Object

The order of fields above is recommended for defining fields in the document.

Parameter Serialization

Depending on the parameter’s in, style, and explode fields and schema type, the parameter value will be serialized in different ways. Some combinations of schema type and parameter serialization are not valid and should be avoided.

Use the content field to define complex serialization scenarios, such as converting an object to a JSON string for including in a query parameter in the URL.

Required vs. Optional Parameters

Whether to make parameters required or optional directly impacts an API’s robustness.

When To Make Parameters Required

• If the resource cannot be identified without the parameter:

  # Required path parameter for resource identification
  - name: userId
    in: path
    required: true  # Path parameters must always be required
    description: The unique identifier of the user

• If the operation fundamentally depends on the parameter:

  # Required parameter for essential functionality
  - name: transferAmount
    in: query
    required: true
    description: The amount of money to transfer

• If security or access control depends on the parameter:

  # Required parameter for security context
  - name: tenant-id
    in: header
    required: true
    description: The tenant context for multi-tenant operations

When To Make Parameters Optional

• If a parameter provides filtering, sorting, or presentation options:

  # Optional parameter for filtering
  - name: status
    in: query
    required: false
    description: Filter results by status (returns all statuses if omitted)
    schema:
      type: string
      enum: [active, pending, closed]

• If a parameter modifies but isn’t essential to an operation

  # Optional parameter with sensible default
  - name: format
    in: query
    required: false
    schema:
      type: string
      enum: [json, xml, csv]
      default: json
    description: Response format (defaults to JSON)

Always document default behavior when parameters are omitted to help API users understand what to expect without having to try different combinations.

Backward Compatibility

As an API evolves, it’s important to add parameters without breaking existing clients. Here are some effective strategies to maintain backward compatibility.

1. Add New Parameters as Optional Only

Always make new parameters optional with sensible defaults that maintain the original behavior:

- name: includeDeleted
  in: query
  required: false  
  schema:
    type: boolean
    default: false  # maintains original behavior
  description: Include soft-deleted items in the response

2. Use Feature Flags for Behavioral Changes

When new parameters significantly change behavior, add version flags to opt-in:

- name: version
  in: query
  required: false
  schema:
    type: string
    enum: ["2023-01-01", "2023-07-01", "current"]
    default: "2023-01-01"
  description: API behavior version to use

3. Handle Parameter Deprecation Gracefully

When retiring parameters, first mark them as deprecated while still supporting them:

- name: filter
  in: query
  required: false
  deprecated: true
  description: >
    Filter results (DEPRECATED: Use 'filters' parameter instead, 
    which supports multiple filter criteria)
  schema:
    type: string

4. Documentation and Communication

Always provide clear migration guidance in your parameter descriptions:

- name: filters
  in: query
  required: false
  description: >
    JSON-encoded filter criteria. Replaces the deprecated 'filter'
    parameter. Example: {"status":"active","category":"clothing"}
    
    Migration from 'filter': If you previously used ?filter=status:active,
    the equivalent is now ?filters={"status":"active"}
  schema:
    type: string
    format: json