Parameters in OpenAPI — Path, Query, Header, and Cookie
In this tutorial, you will learn about Parameters in OpenAPI. We cover key concepts, practical examples, and best practices to help you master this topic.
OpenAPI parameters define input values for API operations through path segments, query strings, HTTP headers, or cookies, each with schemas, validation, Serialization style, and documentation.
In this tutorial, you will learn all parameter locations, how to define schemas and validation, serialization styles for arrays and objects, and best practices for reusable parameters.
What You'll Learn
You will learn the four parameter locations, how to define parameter schemas with validation constraints, serialization styles for complex parameters, and how to make parameters reusable via components.
Why It Matters
Parameters are how clients customize every API request. Well-defined parameters enable auto-generated client code with type safety, validation, and clear documentation. Poorly defined parameters lead to integration bugs.
flowchart LR A[Parameters] --> B[Path] A --> C[Query] A --> D[Header] A --> E[Cookie] B:::current classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px
Path Parameters
Path parameters are embedded in the URL path. They are required and identify a specific resource.
/users/{userId}/documents/{documentId}:
get:
parameters:
- name: userId
in: path
required: true
description: Unique identifier of the user
schema:
type: integer
minimum: 1
example: 42
- name: documentId
in: path
required: true
description: Unique identifier of the document
schema:
type: string
format: uuid
example: "550e8400-e29b-41d4-a716-446655440000"
Query Parameters
Query parameters appear after the question mark in the URL. They are typically optional and used for filtering, sorting, and pagination.
/users:
get:
parameters:
- name: page
in: query
description: Page number (1-indexed)
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
description: Number of items per page
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: sort
in: query
description: Sort field and direction
schema:
type: string
pattern: "^[a-z_]+:(asc|desc)$"
example: "created_at:desc"
- name: search
in: query
description: Full-text search term
schema:
type: string
minLength: 2
- name: role
in: query
description: Filter by role
schema:
type: string
enum: [admin, member, viewer]
Header Parameters
Header parameters are sent in HTTP request headers.
/users:
get:
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: Requested API version
schema:
type: string
pattern: "^20[0-9]{2}-[0-9]{2}-[0-9]{2}$"
example: "2026-06-28"
- name: Accept-Language
in: header
description: Preferred response language
schema:
type: string
default: "en-US"
Cookie Parameters
Cookie parameters are sent in the Cookie header.
/users/me:
get:
parameters:
- name: session_token
in: cookie
description: Session authentication token
schema:
type: string
example: "sess_eyJhbGciOiJIUzI1NiJ9"
Parameter Serialization Styles
OpenAPI defines how complex parameters are serialized:
# Array query parameter
- name: tags
in: query
schema:
type: array
items:
type: string
style: form
explode: true
# ?tags=python&tags=api&tags=docs
- name: tags
in: query
style: form
explode: false
# ?tags=python,api,docs
- name: filter
in: query
schema:
type: object
properties:
field:
type: string
operator:
type: string
value:
type: string
style: deepObject
explode: true
# ?filter[field]=age&filter[operator]=gte&filter[value]=18
Reusable Parameters
Define common parameters in components:
components:
parameters:
pageParam:
name: page
in: query
description: Page number
schema:
type: integer
minimum: 1
default: 1
example: 1
limitParam:
name: limit
in: query
description: Items per page
schema:
type: integer
minimum: 1
maximum: 100
default: 20
example: 20
Common Mistakes
Path parameter required: false — Path parameters are always required. Setting required: false is invalid. Remove the field or set it to true.
No description — Skipping parameter descriptions. Every parameter needs a description that explains what it does.
Missing default values — Not providing defaults for optional parameters. Developers need to know what they get without the parameter.
No examples — Not showing example values. Examples are the fastest way for developers to understand parameter format.
Wrong serialization style — Not considering how arrays and objects are serialized. Clients may send parameters in unexpected formats.
Practice Questions
- What are the four parameter locations?
- Why are path parameters always required?
- How do you define array query parameters?
- What is the difference between form and deepObject style?
- How do you make parameters reusable?
Challenge
Design a comprehensive parameter set for a search API. Include query parameters for text search, filters (multiple fields with operators), pagination (cursor-based), sorting (multiple fields), fields selection, embedding, and locale. Define reusable pagination and sorting parameters in components.
FAQ
Mini Project
Create a parameter library for an e-commerce API. Define reusable parameters for pagination (page, limit, cursor), sorting (sort, direction), filtering (category, priceMin, priceMax, inStock, rating), search (query, fields), and identification (productId, categoryId, orderId). Include schemas, defaults, examples, and descriptions.
What's Next
In the next lesson, you will learn how to define request bodies in OpenAPI.
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro