Parameters & Request Body · API styles — interview questions

In an OpenAPI 3.x document, what are the four values of a parameter's in field, and how do they differ?

juniormust knowfreq 70%

answer

Four places a value can travel
One of them is templated into the URL
Three header names are always ignored
Identity is the name plus location pair
One location cannot be optional

basics

~20 s

OpenAPI parameter objects declare inputs outside the body using in: path, query, header, or cookie. A parameter is identified by name plus in. Path parameters must set required: true and must match a template variable in the path string.

solid answer

~50 s

A Parameter Object in OpenAPI 3.x declares one input that is not the request body. The in field says where it travels: path (a {} template variable in the path key), query (after the ?), header (a request header), or cookie (a name inside the Cookie header). Each parameter needs a name, an in, and normally a schema. Parameters are uniquely identified by the name + in pair, so id in path and id in query can coexist. Path parameters are special: every template variable in the path key must have a matching parameter with in: path and required: true — the spec forbids an optional path parameter. Query, header and cookie parameters default to required: false. Parameters declared on the Path Item apply to every operation under it; an operation-level parameter with the same name + in overrides that inherited one.

A Parameter Object in OpenAPI 3.x declares one input that is not the request body. The `in` field says where it travels: `path` (a `{}` template variable in the path key), `query` (after the `?`), `header` (a request header), or `cookie` (a name inside the `Cookie` header). Each parameter needs a `name`, an `in`, and normally a `schema`. Parameters are uniquely identified by the `name` + `in` pair, so `id` in path and `id` in query can coexist. Path parameters are special: every template variable in the path key must have a matching parameter with `in: path` and `required: true` — the spec forbids an optional path parameter. Query, header and cookie parameters default to `required: false`. Parameters declared on the Path Item apply to every operation under it; an operation-level parameter with the same `name` + `in` overrides that inherited one.

code

yaml · 27 lines

yaml

paths:
  /tenants/{tenantId}/orders:
    parameters:
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
    get:
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
        - name: X-Request-Id
          in: header
          schema:
            type: string
            format: uuid
        - name: session
          in: cookie
          schema:
            type: string
      responses:
        '200':
          description: Orders

go deeper

for a junior

Be ready to name the four in values and write a small path item with a path parameter and a query parameter, remembering required: true on the path one.

for a middle

Explain that identity is name plus in, how path-item parameters merge with operation-level ones, and why Accept, Content-Type and Authorization header parameters are ignored.

for a senior

Show judgment about where inputs belong: hoisting shared path parameters, keeping credentials in security schemes rather than parameters, and knowing which mistakes break generated clients.

for a principal

Own the house rules — which parameters are declared once in components.parameters versus inline, and how the document stays the single source of truth as many teams add operations.

What a Parameter Object is

In OpenAPI 3.x, everything a client sends is described in one of two ways: as a Parameter Object or as the requestBody. Parameter Objects cover the inputs that ride along outside the message body — pieces of the URL, request headers, and cookies. Each Parameter Object is a small record with at minimum a name, an in, and a description of its value (usually schema).

The four locations

in accepts exactly four values, and no others:

path — the value is substituted into a {variable} placeholder in the path key, e.g. /orders/{orderId}.
query — the value appears in the query string after ?, e.g. /orders?status=open.
header — the value is sent as a request header, e.g. X-Request-Id.
cookie — the value is one name/value pair inside the Cookie request header.

Path parameters have extra rules

Path templating is a two-sided contract. If the path key contains {orderId}, there must be a parameter with name: orderId, in: path, and required: true. The spec states that for in: path the required field is REQUIRED and its value MUST be true — there is no such thing as an optional path segment in OpenAPI. If you want the segment to be optional, that is a different path, declared separately (/orders and /orders/{orderId}). Conversely, declaring in: path for a name that appears in no template variable is invalid, and linters flag it.

Query, header and cookie parameters

These default to required: false, so a parameter that a client must always send needs required: true written out. Query parameters are the common case for filters, sorting keys and paging cursors. Header parameters describe custom request headers — but three names are explicitly excluded: if in: header and the name is Accept, Content-Type, or Authorization, the parameter definition SHALL be ignored, because those three are already described elsewhere in the document (content negotiation is expressed by the content maps, and authentication by security schemes). Cookie parameters describe one cookie by name; you do not describe the raw Cookie header itself.

Identity, inheritance and overriding

A parameter is uniquely identified by the combination of name and in. Two entries with the same name but different in are two different parameters and both are legal; two entries with the same name and the same in in the same list are invalid.

Parameters may be declared in two places: on the Path Item Object, where they apply to every operation under that path, and on the Operation Object, where they apply only to that operation. The operation-level list does not replace the inherited list wholesale — the two are merged, and an operation-level entry with the same name + in replaces the inherited one. This is how you hoist a shared {tenantId} path parameter to the path item once instead of repeating it on get, put and delete.

Other fields worth knowing

description — human documentation; renderers show it next to the field.
deprecated — a boolean flag; generators typically emit a deprecation annotation.
example / examples — sample values (examples is a map of named Example Objects; the two are mutually exclusive).
allowEmptyValue — query only, and the specification itself discourages its use; treat it as legacy.
style / explode / allowReserved — how a non-trivial value is serialized into the URL.
content — an alternative to schema for values whose serialization needs a media type; the map must contain exactly one entry.

schema and content are mutually exclusive: a parameter uses one or the other, never both.

Where teams get this wrong

The frequent mistakes are: forgetting required: true on a path parameter (many validators reject the document outright); declaring Authorization as a header parameter instead of a security scheme, which makes generated clients grow a raw string argument nobody wires up; repeating the same path parameter on every operation rather than on the path item; and inventing a fifth in value such as body or formData, which were Swagger 2.0 concepts replaced in 3.x by requestBody.

## What a Parameter Object is In OpenAPI 3.x, everything a client sends is described in one of two ways: as a **Parameter Object** or as the **requestBody**. Parameter Objects cover the inputs that ride along outside the message body — pieces of the URL, request headers, and cookies. Each Parameter Object is a small record with at minimum a `name`, an `in`, and a description of its value (usually `schema`). ## The four locations `in` accepts exactly four values, and no others: - **`path`** — the value is substituted into a `{variable}` placeholder in the path key, e.g. `/orders/{orderId}`. - **`query`** — the value appears in the query string after `?`, e.g. `/orders?status=open`. - **`header`** — the value is sent as a request header, e.g. `X-Request-Id`. - **`cookie`** — the value is one name/value pair inside the `Cookie` request header. ## Path parameters have extra rules Path templating is a two-sided contract. If the path key contains `{orderId}`, there must be a parameter with `name: orderId`, `in: path`, and `required: true`. The spec states that for `in: path` the `required` field is REQUIRED and its value MUST be `true` — there is no such thing as an optional path segment in OpenAPI. If you want the segment to be optional, that is a different path, declared separately (`/orders` and `/orders/{orderId}`). Conversely, declaring `in: path` for a name that appears in no template variable is invalid, and linters flag it. ## Query, header and cookie parameters These default to `required: false`, so a parameter that a client must always send needs `required: true` written out. Query parameters are the common case for filters, sorting keys and paging cursors. Header parameters describe custom request headers — but three names are explicitly excluded: if `in: header` and the name is `Accept`, `Content-Type`, or `Authorization`, the parameter definition SHALL be ignored, because those three are already described elsewhere in the document (content negotiation is expressed by the `content` maps, and authentication by security schemes). Cookie parameters describe one cookie by name; you do not describe the raw `Cookie` header itself. ## Identity, inheritance and overriding A parameter is uniquely identified by the combination of `name` and `in`. Two entries with the same `name` but different `in` are two different parameters and both are legal; two entries with the same `name` and the same `in` in the same list are invalid. Parameters may be declared in two places: on the **Path Item Object**, where they apply to every operation under that path, and on the **Operation Object**, where they apply only to that operation. The operation-level list does not replace the inherited list wholesale — the two are merged, and an operation-level entry with the same `name` + `in` replaces the inherited one. This is how you hoist a shared `{tenantId}` path parameter to the path item once instead of repeating it on `get`, `put` and `delete`. ## Other fields worth knowing - `description` — human documentation; renderers show it next to the field. - `deprecated` — a boolean flag; generators typically emit a deprecation annotation. - `example` / `examples` — sample values (`examples` is a map of named Example Objects; the two are mutually exclusive). - `allowEmptyValue` — query only, and the specification itself discourages its use; treat it as legacy. - `style` / `explode` / `allowReserved` — how a non-trivial value is serialized into the URL. - `content` — an alternative to `schema` for values whose serialization needs a media type; the map must contain exactly one entry. `schema` and `content` are mutually exclusive: a parameter uses one or the other, never both. ## Where teams get this wrong The frequent mistakes are: forgetting `required: true` on a path parameter (many validators reject the document outright); declaring `Authorization` as a header parameter instead of a security scheme, which makes generated clients grow a raw string argument nobody wires up; repeating the same path parameter on every operation rather than on the path item; and inventing a fifth `in` value such as `body` or `formData`, which were Swagger 2.0 concepts replaced in 3.x by `requestBody`.

Why is a header parameter named Authorization ignored by OpenAPI tooling?
The specification says a header parameter named `Accept`, `Content-Type` or `Authorization` SHALL be ignored, because those are described by other parts of the document: content negotiation by the `content` maps on request bodies and responses, and credentials by security schemes. Declaring `Authorization` as a parameter is usually a Swagger 2.0 habit; move it to `components.securitySchemes` and reference it from `security`.
If a parameter is declared on the path item and again on the operation, which one wins?
They merge, and the operation-level entry wins for any parameter with the same `name` and `in` pair. That lets you declare a shared path parameter once on the path item and still narrow, say, its description or example for a single operation. Parameters the operation does not redeclare are inherited unchanged; there is no way to delete an inherited parameter.
Can a path parameter be optional in OpenAPI 3.x?
No. For `in: path` the `required` field is mandatory and its value must be `true`. If a segment is genuinely optional, that is two different resources and you declare two path keys — for example `/orders` and `/orders/{orderId}` — each with its own operations. Trying to express optionality inside one templated path produces a document most validators reject.

saying these in an interview costs you the question

Says body or formData is a valid in value
Leaves required off a path parameter
Declares Authorization as a header parameter
Thinks operation parameters replace the whole inherited list
Uses both schema and content on one parameter

context

open as a page

In OpenAPI, when do you use requestBody instead of a parameter, and what does its content map key on?

middlemust knowfreq 65%

basics

~20 s

In OpenAPI 3.x anything sent in the HTTP message body is a requestBody, never a parameter. Its content map is keyed by media type, each entry carrying its own schema and examples. requestBody defaults to required: false, so a mandatory payload must say so explicitly.

open as a page

In OpenAPI, how do the style and explode keywords change how an array query parameter appears in the URL?

middlemust knowfreq 60%

basics

~20 s

OpenAPI's style picks the serialization rule and explode says whether each array item gets its own key. Query parameters default to style: form with explode: true, giving tags=a&tags=b; explode: false gives tags=a,b. spaceDelimited and pipeDelimited use spaces or pipes instead.

open as a page

In an OpenAPI document, how do you describe a multipart/form-data upload and what does encoding control?

seniorshould knowfreq 42%

basics

~20 s

Declare a requestBody with a multipart/form-data content entry whose schema is an object: each property becomes one part. The encoding map then overrides a part's Content-Type and adds part headers, since OpenAPI otherwise infers the part type from the property's schema.

open as a page

In OpenAPI, how do you describe an object-valued query parameter, and when is deepObject the wrong choice?

seniorshould knowfreq 40%

basics

~20 s

OpenAPI offers three ways: style form with explode true, which flattens the object into top-level keys; style deepObject, which produces bracketed keys like filter[status]=open; and a content-typed parameter carrying the value as JSON. deepObject fails for nested objects and arrays.

open as a page

§explore

▾roadmaps that cover this12

§questions

In an OpenAPI 3.x document, what are the four values of a parameter's in field, and how do they differ?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~3 min

What a Parameter Object is

The four locations

Path parameters have extra rules

Query, header and cookie parameters

Identity, inheritance and overriding

Other fields worth knowing

Where teams get this wrong

▾common follow-ups3 questions

▾red flags5 flags

§ context

▾related questions4 questions

▾related topics3 topics

In OpenAPI, when do you use requestBody instead of a parameter, and what does its content map key on?

basics

In OpenAPI, how do the style and explode keywords change how an array query parameter appears in the URL?

basics

In an OpenAPI document, how do you describe a multipart/form-data upload and what does encoding control?

basics

In OpenAPI, how do you describe an object-valued query parameter, and when is deepObject the wrong choice?

basics

What a Parameter Object is

The four locations

Path parameters have extra rules

Query, header and cookie parameters

Identity, inheritance and overriding

Other fields worth knowing

Where teams get this wrong

explore

questions

answer

go deeper

context