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

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 describe how clients provide input to API operations through four locations: path (URL segment), query (after ?), header, and cookie.

What You'll Learn

• Parameter locations and when to use each
• Parameter validation with schemas
• Required vs optional parameters

Why It Matters

Correct parameter definitions ensure client requests are valid and your API behaves predictably. They also generate accurate documentation and client validation code.

Parameter Types

Code Examples

parameters:
  - name: userId
    in: path
    required: true
    description: ID of the user
    schema:
      type: integer
      minimum: 1

  - name: page
    in: query
    required: false
    schema:
      type: integer
      default: 1
      minimum: 1

  - name: sort
    in: query
    schema:
      type: string
      enum: [name, date, status]

  - name: X-Request-ID
    in: header
    required: false
    schema:
      type: string
      format: uuid
    description: Request correlation ID

  - name: session
    in: cookie
    required: true
    schema:
      type: string

# Validating parameters against OpenAPI spec
from openapi_core import create_spec
from openapi_core.validation.request.validators import RequestValidator

spec = create_spec(spec_dict)
validator = RequestValidator(spec)

# Validates that request parameters match spec
result = validator.validate(request)
if result.errors:
    for error in result.errors:
        print(f"Parameter error: {error}")

Common Mistakes

1. Missing Required Path Parameters

Parameters defined in the path pattern must have required: true.

2. Not Specifying Parameter Types

Without schema types, clients don't know whether to send strings or numbers.

3. Using Wrong in Location

Putting resource IDs in query instead of path violates REST conventions.

4. No Default Values for Optional Parameters

Document defaults so clients know what to expect when they omit parameters.

5. Inconsistent Naming Across Parameters

Use consistent naming patterns (camelCase, snake_case) across all parameters.

Practice Questions

1. What are the four parameter locations in OpenAPI?
2. Why must path parameters have required: true?
3. How do you set a default value for a query parameter?
4. When would you use a header parameter over a query parameter?
5. How do you restrict a parameter to specific values?

Answers:

1. path, query, header, cookie.
2. Because path parameters are always required to reach the endpoint.
3. Set default in the schema definition.
4. For metadata like authentication tokens, request IDs, or content negotiation.
5. Use the enum constraint in the schema.

Challenge: Design the parameters for a search API endpoint including a query string, page number, page size, sort field, sort direction, and optional filters.

FAQ