Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 37 ยท Paths, Schemas and Components

OpenAPI Parameters: Path, Query, Header and Cookie

Describe API inputs with OpenAPI parameters: the four locations, required, schema, style and explode for arrays, content-based parameters and a request builder demo.

A parameter is a piece of input that travels in the URL or the request headers, not in the body. OpenAPI knows exactly four places a parameter can live, and each has its own rules. Describe them well and every generated client builds correct requests without guesswork.

The four locations

in Where it appears Example Required?
path Inside the URL path /pets/42 Always true
query After ? /pets?limit=10 Optional by default
header In an HTTP header X-Request-Id: abc Optional by default
cookie In the Cookie header session=abc Optional by default
YAML
parameters:
  - name: petId
    in: path
    required: true
    description: Pet identifier
    schema: { type: integer, format: int64 }
  - name: status
    in: query
    description: Filter by status
    schema: { type: string, enum: [available, pending, sold], default: available }
  - name: X-Request-Id
    in: header
    schema: { type: string, format: uuid }
  - name: session
    in: cookie
    schema: { type: string }

Fields every parameter has:

  • name (case sensitive; header names are case insensitive in HTTP, but write them in the usual casing).
  • in: one of the four locations.
  • required: must be true for path parameters.
  • schema: the type, constraints and default (see schema objects).
  • description, deprecated, example / examples.

Do not describe the headers Accept, Content-Type and Authorization as parameters. The specification reserves them: use content on requests and responses, and security schemes for credentials.

Arrays and objects in the query string: style and explode

A query parameter may be a list: ?tag=cat&tag=dog or ?tag=cat,dog. The style and explode fields say which.

YAML
- name: tag
  in: query
  schema:
    type: array
    items: { type: string }
  style: form       # default for query
  explode: true     # default for form: tag=cat&tag=dog
style explode Result for tag = [cat, dog]
form true (default) ?tag=cat&tag=dog
form false ?tag=cat,dog
spaceDelimited false ?tag=cat%20dog
pipeDelimited false ?tag=cat|dog
deepObject true ?filter[color]=red (for objects)

The defaults are style: simple for path and header parameters and style: form for query and cookie parameters. For form, explode defaults to true.

Serialization in action

This stand-in turns parameter descriptions and values into a real request line. Notice how style and explode change the query string. It is what a client generator does behind every listPets(...) call.

Python Stand-in: build a request from parameter descriptions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Reusing parameters

When the same parameter appears on many operations, define it once under components.parameters and reference it (covered in components and $ref):

YAML
components:
  parameters:
    LimitParam:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
paths:
  /pets:
    get:
      parameters:
        - $ref: "#/components/parameters/LimitParam"

Complex values: the content form

Instead of schema, a parameter can describe a value with content and a media type. This is how you describe a JSON object passed in a query parameter:

YAML
- name: filter
  in: query
  content:
    application/json:
      schema:
        type: object
        properties:
          color: { type: string }

A parameter must have either schema or content, never both.

Design advice

  • Use path parameters to identify a resource (/pets/{petId}), query parameters to filter, sort and page (?status=sold&limit=20).
  • Put cross-cutting metadata (request id, API version) in headers.
  • Avoid cookie parameters unless you describe a browser-based API; use authorization schemes for credentials.
  • Give every parameter a description, and constraints that match your server's real validation.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which locations can a parameter have?

    OpenAPI defines exactly four parameter locations.
  2. 2. A path parameter must declare which of these?

    Path parameters are part of the URL and are therefore always required.
  3. 3. With the defaults, how is the array [cat, dog] of a query parameter tag sent?

    The default query style is form with explode true, which repeats the name.
  4. 4. Which header should NOT be described as a normal parameter?

    Authorization, Accept and Content-Type are reserved; use security schemes and content instead.
  5. 5. A parameter may have...

    The two are mutually exclusive ways to describe the value.

Summary

  • Parameters live in the path, query, header or cookie; path ones are always required.
  • Each has a name, in, optional required and a schema (or content).
  • style and explode control how arrays and objects are serialized.
  • Do not declare Accept, Content-Type or Authorization as parameters.
  • Share common parameters through components.parameters.

Next: Request bodies and media types