OpenAPI Parameters — Path, Query, Header, and Cookie Definitions

In this tutorial, you will learn about OpenAPI Parameters. We cover key concepts, practical examples, and best practices to help you master this topic.

OpenAPI parameters define input values that API operations receive through path segments, query strings, HTTP headers, or cookies, each with schemas, validation constraints, and descriptions.

In this tutorial, you will learn how to define all four parameter types in OpenAPI, how to set validation constraints, how to make parameters reusable, and best practices for parameter documentation.

What You'll Learn

You will learn the four parameter locations (path, query, header, cookie), how to define parameter schemas with validation, how to make parameters reusable via components, and how to document parameter behavior clearly.

Why It Matters

Parameters are how clients customize every API request. Poorly defined parameters lead to confusing documentation, invalid requests, and integration bugs. Well-defined parameters enable auto-generated client code with type safety and validation.

Real-World Use

DodaTech APIs define all pagination parameters as reusable components. The page, limit, and sort parameters are defined once in a shared file and referenced by every list endpoint, ensuring consistent pagination behavior across all services.

flowchart LR
  A[Parameter Definition] --> B[Path]
  A --> C[Query]
  A --> D[Header]
  A --> E[Cookie]
  B --> F[Request Building]
  C --> F
  D --> F
  E --> F
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Parameter Locations

Path Parameters

Path parameters are embedded in the URL path. They are required and typically identify a specific resource.

/users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        - name: userId
          in: path
          required: true
          description: Unique identifier of the user
          schema:
            type: integer
            minimum: 1
          example: 42

Query Parameters

Query parameters appear in the URL after the question mark. They are optional and used for filtering, sorting, and pagination.

/users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 1
        - name: limit
          in: query
          description: Number of items per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          example: 20
        - name: search
          in: query
          description: Search term for filtering users
          schema:
            type: string
            minLength: 2
            maxLength: 100
          example: "alice"
        - name: role
          in: query
          description: Filter by user role
          schema:
            type: string
            enum: [admin, member, viewer]
          example: "admin"

Header Parameters

Header parameters are sent in the HTTP request headers.

/users:
    get:
      summary: List users
      parameters:
        - name: X-Request-ID
          in: header
          description: Unique request identifier for tracing
          schema:
            type: string
            format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        - name: X-API-Version
          in: header
          description: API version to use
          schema:
            type: string
            pattern: "^v[0-9]+$"
          example: "v2"

Cookie Parameters

Cookie parameters are sent in the Cookie header.

/users/me:
    get:
      summary: Get current user
      parameters:
        - name: session_token
          in: cookie
          description: Session authentication token
          schema:
            type: string
          example: "sess_abc123def456"

Reusable Parameters

Define common parameters in components and reference them.

components:
  parameters:
    pageParam:
      name: page
      in: query
      description: Page number for pagination
      schema:
        type: integer
        minimum: 1
        default: 1
      example: 1
    limitParam:
      name: limit
      in: query
      description: Number of items per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      example: 20
    userIdPath:
      name: userId
      in: path
      required: true
      description: Unique identifier of the user
      schema:
        type: integer
      example: 42

Referencing reusable parameters:

/users:
    get:
      parameters:
        - $ref: "#/components/parameters/pageParam"
        - $ref: "#/components/parameters/limitParam"
  /users/{userId}:
    get:
      parameters:
        - $ref: "#/components/parameters/userIdPath"

Parameter Serialization

OpenAPI defines how parameters are serialized. The style and explode fields control serialization.

# Array parameter serialization
parameters:
  - name: tags
    in: query
    description: Filter by tags
    schema:
      type: array
      items:
        type: string
    style: form
    explode: true
    example: ["python", "api", "docs"]

# Results in: ?tags=python&tags=api&tags=docs
# With explode: false: ?tags=python,api,docs

# Object parameter serialization
parameters:
  - name: filter
    in: query
    description: Complex filter object
    schema:
      type: object
      properties:
        field:
          type: string
        operator:
          type: string
        value:
          type: string
    style: deepObject
    explode: true

# Results in: ?filter[field]=age&filter[operator]=gte&filter[value]=18

Parameter Deprecation

Mark parameters as deprecated to signal they will be removed.

parameters:
  - name: api_version
    in: query
    description: Legacy version parameter (use Accept header instead)
    schema:
      type: string
    deprecated: true

Common Mistakes

1. Missing path parameter definitions — Using {paramName} in the path but forgetting to define paramName in the parameters section. Every path variable needs a parameter with in: path and required: true.

2. Not setting required for path parameters — Path parameters are always required. Setting required: false on a path parameter is invalid.

3. No default values — Not specifying default values for optional query parameters. Clients should know what they get if they omit a parameter.

4. Inconsistent parameter naming — Using user_id in some endpoints and userId in others. Follow a consistent naming convention across all endpoints.

5. No examples — Omitting the example field. Examples show developers the expected format and valid values.

Practice Questions

1. What are the four parameter locations in OpenAPI?
2. Why are path parameters always required?
3. How do you define reusable parameters that multiple endpoints share?
4. What is the difference between form and deepObject parameter styles?
5. How do you mark a parameter as deprecated?

Challenge

Design the parameter definitions for a products API with the following requirements: path parameter for product ID, query parameters for search, category filter, price range min/max, sort field and direction, pagination (page, limit), header parameters for API version and request ID, and cookie parameter for session. Make pagination parameters reusable.

FAQ

Mini Project

Create a parameter component library for a blog API. Define reusable parameters for pagination (page, limit, sort, direction), filtering (status, authorId, categoryId, search, dateFrom, dateTo), and identification (postId, commentId, userId). Include appropriate schemas, defaults, and examples for each.

What's Next

In the next lesson, you will learn how to define request bodies in OpenAPI, including content types, schema references, and required body documentation.