Skip to content
Status

OpenAPI Hub

Paths in OpenAPI best practices

Paths Object in OpenAPI

The paths object is a map of Path Item Objects that describes the available paths and operations for the API.

Each path is a relative path to the servers defined in the Servers object, either at the document, path, or operation level. For example, if a server is defined as https://speakeasy.bar/api and a path is defined as /drinks, the full URL to the path would be https://speakeasy.bar/api/drinks, where the path is appended to the server URL.

Example:

paths:
  /drinks:
    get: ... # operation definition
  /drink:
    get: ... # operation definition
    put: ... # operation definition
    post: ... # operation definition
    delete: ... # operation definition
Field
/{path}
Description
A relative path to an individual endpoint, where the path must begin with a /.
Required
x-*
Description
Any number of extension fields can be added to the paths object that can be used by tooling and vendors.
Required

Path Item Object in OpenAPI

A Path Item Object describes the operations available on a single path. This is generally a map of HTTP methods to Operation Objects that describe the operations available.

It is possible to override the Servers defined at the document level for a specific path by providing a list of Server Objects at the path level.

It is also possible to provide a list of Parameters that are common to all operations defined on the path.

Example:

paths:
  /drinks:
    summary: Various operations for browsing and searching drinks
    description:
    servers: # Override the servers defined at the document level and apply to all operations defined on this path
      - url: https://drinks.speakeasy.bar
        description: The drinks server
    parameters: # Define a list of parameters that are common to all operations defined on this path
      - name: type
        in: query
        schema:
          type: string
          enum:
            - cocktail
            - mocktail
            - spirit
            - beer
            - wine
            - cider
    get: ... # operation definition

Or:

paths:
  /drinks:
    $ref: "#/components/pathItems/drinks" # Reference a Path Item Object defined in the Components Object allowing for reuse in different paths
components:
  pathItems:
    drinks:
      servers:
        - url: https://drinks.speakeasy.bar
          description: The drinks server
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum:
              - cocktail
              - mocktail
              - spirit
              - beer
              - wine
              - cider
      get: ... # operation definition
Field
$ref
Type
String
Description
Allows for referencing a Path Item Object defined in the Components Object under the pathItems field. If used, no other fields should be set.
Required
summary
Type
String
Description
A short summary of what the path item represents. This may contain CommonMark syntax to provide a rich description.
Required
description
Type
String
Description
A description of the path item. This may contain CommonMark syntax to provide a rich description.
Required
servers
Description
A list of Server Objects that override the servers defined at the document level. Applies to all operations defined on this path.
Required
parameters
Description
A list of Parameter Objects that are common to all operations defined on this path.
Required
get
Description
An operation associated with the GET HTTP method.
Required
put
Description
An operation associated with the PUT HTTP method.
Required
post
Description
An operation associated with the POST HTTP method.
Required
delete
Description
An operation associated with the DELETE HTTP method.
Required
options
Description
An operation associated with the OPTIONS HTTP method.
Required
head
Description
An operation associated with the HEAD HTTP method.
Required
patch
Description
An operation associated with the PATCH HTTP method.
Required
trace
Description
An operation associated with the TRACE HTTP method.
Required
query
Description
An operation associated with the QUERY HTTP method. Safe and idempotent, like GET, but allows a request body for complex queries. Available in OpenAPI v3.2.0+.
Required
additionalOperations
Type
Map[String, Operation Object]
Description
A map of non-standard HTTP methods to Operation Objects, enabling documentation of custom methods beyond those defined by the specification. Available in OpenAPI v3.2.0+.
Required
x-*
Description
Any number of extension fields can be added to the Path Item Object that can be used by tooling and vendors.
Required

The order of fields above is recommended but is not significant to the order in which the endpoints should be used.

OpenAPI 3.2 path features

OpenAPI 3.2.0 introduces several new capabilities for path items.

The QUERY HTTP method

The QUERY method is a safe, idempotent HTTP method that allows clients to send query criteria in the request body rather than encoding complex parameters in the URL. This is useful for operations that require structured or lengthy query parameters that exceed practical URL length limits.

paths:
  /drinks:
    query:
      operationId: searchDrinks
      summary: Search for drinks with complex criteria
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ingredients:
                  type: array
                  items:
                    type: string
                minRating:
                  type: number
      responses:
        "200":
          description: A list of matching drinks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"

Additional operations

The additionalOperations field allows defining non-standard HTTP methods as Operation Objects. This is useful for APIs that use custom HTTP methods beyond the standard set.

paths:
  /drinks/{drinkId}:
    additionalOperations:
      BREW:
        operationId: brewDrink
        summary: Brew a specific drink
        parameters:
          - name: drinkId
            in: path
            required: true
            schema:
              type: string
        responses:
          "200":
            description: Drink brewed successfully

The querystring field

OpenAPI 3.2.0 also introduces the querystring field on Operation Objects, which allows defining all query parameters as a single Schema Object instead of listing individual parameters with in: query. This simplifies the definition of operations with many query parameters or complex query structures.

paths:
  /drinks:
    get:
      operationId: listDrinks
      summary: List available drinks
      querystring:
        type: object
        properties:
          type:
            type: string
            enum: [cocktail, mocktail, spirit, beer, wine, cider]
          limit:
            type: integer
            default: 20
          offset:
            type: integer
            default: 0
      responses:
        "200":
          description: A list of drinks