URIs

Path parameter names

If a property in the response schema for an operation reflects the same value provided in the final path parameter containing an identifier (or other unique resource handle), that property and that parameter MUST use the same name.

For example, if the operation to retrieve a farm resource from its identifier returns:

{
  "id": "0d45edaa-456f-48f2-abff-c01fd6b7530f",
  "name": "Moo-Cow Milk Farm"
}

Then the OpenAPI path parameter for the farm's identifier MUST be named "id":

GET /farms/{id}

Conversely, a path parameter MUST NOT have the same name as a top-level property in the operation's response body that represents a different value. Additionally, a path parameter MUST NOT have the same name as any top-level property in the operation's request body.

The path parameters used to identify a resource and any of its parent resources MUST use consistent names across the resource type's standard operations for creating, retrieving, mutating, deleting, and listing resources of that type.

For example, if /farms/{farm_id}/barns/{id} is used to retrieve, mutate, or delete a barn, the path used to list or create barns MUST be /farms/{farm_id}/barns and not /farms/{id}/barns.

As in the example above, and where otherwise sufficient, the singular form of the prior path segment SHOULD be used to disambiguate a parent resource's identifier from its child's identifier. For example, /farms/{farm_id}/barns/{barn_id}/cows/{id} SHOULD be used instead of /farms/{farm_id}/barns/{farm_barn_id}/cows/{id}.

Example

The following example demonstrates how parameters can be defined in an OpenAPI definition to maximize reuse.

paths:
  '/farms/{id}':
    parameters:
    - $ref: '#/components/parameters/FarmId'
    get:
      operationId: get_farm
      ...
    patch:
      operationId: update_farm
      ...
  '/farms/{farm_id}/barns':
    parameters:
    - $ref: '#/components/parameters/FarmIdQualified'
    get:
      operationId: list_farm_barns
      ...
    post:
      operationId: create_farm_barn
      ...
  '/farms/{farm_id}/barns/{id}':
    parameters:
    - $ref: '#/components/parameters/FarmIdQualified'
    - $ref: '#/components/parameters/FarmBarnId'
    get:
      operationId: get_farm_barn
      ...
    patch:
      operationId: update_farm_barn
      ...
components:
  parameters:
    FarmId:
      name: id
      in: path
      required: true
      description: The identifier for a farm
      schema:
        $ref: '#/components/schemas/Identifier'
    FarmIdQualified:
      name: farm_id
      in: path
      required: true
      description: The identifier for a farm
      schema:
        $ref: '#/components/schemas/Identifier'
    FarmBarnId:
      name: id
      in: path
      required: true
      description: The identifier for a barn on a farm
      schema:
        $ref: '#/components/schemas/Identifier'
  schemas:
    Identifier:
      type: string
      format: identifier
      pattern: '^[-0-9a-z]+$'

Contraints

Each query parameter supported for an operation MUST have a documented and enforced maximum length and the sum of all query parameter maximum lengths (along with the names and control characters & and = for each parameter) for a single operation SHOULD be less than 7000 bytes^[3].

Unrecognized and invalid parameters

To prevent dangerous client bugs and backward-compatibility hazards, unrecognized query parameters SHOULD and invalid parameter values MUST result in a 400 status code and appropriate error response model.

Case insensitivity

Query parameter names SHOULD NOT be case-normalized to support case insensitivity; a parameter that does not match the case of a defined parameter but otherwise matches its name SHOULD be treated as any other extraneous input^[4].

However, parameter name case normalization MAY be supported for backward compatibility with existing clients.

Parameter duplication

Requests that provide a query string with duplicate single-value^[5] query parameters of the same name and differing values^[6] MUST result in a 400 status and appropriate error response model. For backward compatibility with existing clients, query strings containing duplicate query parameters of the same name and with the same value MAY be supported ^[7].

If a service supports parameter name case insensitivity, parameter names MUST be normalized prior to validating uniqueness.

Support for array input in query parameters SHOULD use comma-separated values within a single parameter (for example, foo=1,2,3) instead of duplicated^[8] parameters ( foo=1&foo=2&foo=3).