Skip to content

Path Parameters in OpenAPI best practices

OpenAPI path parameters

Path parameters are serialized at runtime to the path of the URL, meaning they are generally serialized to a string representation and must adhere to the RFC 3986 specification. Reserved characters are percent-encoded (for example, ? becomes %3F).

By default, path parameters are serialized using style: simple and explode: false, but several different serialization options are available:

  • style: simple - Simple style serialization is the default serialization for path parameters, using commas (,) to separate multiple values. Defined by RFC 6570.
  • style: label - Label-style serialization uses dots (.) to separate multiple values. Defined by RFC 6570.
  • style: matrix - Matrix-style serialization uses semicolons (;) to separate multiple values. Defined by RFC 6570.

Primitive types as path parameters in OpenAPI

Primitive types such as string, number, integer, and boolean are serialized as strings. The style and explode fields generally determine the prefix for the value.

For the examples below, we will use a path parameter named type with a value of cocktail for a path-templated URL of /drinks/{type}.

Primitive Types Serialization

Style
simple
Explode == `true`
/drinks/cocktail
Explode == `false`
/drinks/cocktail
label
Explode == `true`
/drinks/.cocktail
Explode == `false`
/drinks/.cocktail
matrix
Explode == `true`
/drinks/;type=cocktail
Explode == `false`
/drinks/;type=cocktail

Simple arrays as path parameters in OpenAPI

For simple arrays of primitive types such as string, number, integer, and boolean, serialization will vary depending on the style and explode fields.

For the examples below, we will use a path parameter named types with a value of ["gin", "vodka", "rum"] for a path-templated URL of /drinks/{types}.

Simple Arrays Serialization

Style
simple
Explode == `true`
/drinks/gin,vodka,rum
Explode == `false`
/drinks/gin,vodka,rum (default)
label
Explode == `true`
/drinks/.gin.vodka.rum
Explode == `false`
/drinks/.gin,vodka,rum
matrix
Explode == `true`
/drinks/;types=gin;types=vodka;types=rum
Explode == `false`
/drinks/;types=gin,vodka,rum

Simple objects as path parameters in OpenAPI

For simple objects whose fields are primitive types such as string, number, integer, and boolean, serialization will vary depending on the style and explode fields.

For the examples below, we will use a path parameter named filter with a value of {"type": "cocktail", "strength": 5} for a path-templated URL of /drinks/{filter}.

Simple Objects Serialization

Style
simple
Explode == `true`
/drinks/type=cocktail,strength=5
Explode == `false`
/drinks/type,cocktail,strength,5 (default)
label
Explode == `true`
/drinks/.type=cocktail.strength=5
Explode == `false`
/drinks/.type,cocktail,strength,5
matrix
Explode == `true`
/drinks/;type=cocktail;strength=5
Explode == `false`
/drinks/;filter=type,cocktail,strength,5

Complex objects and arrays as path parameters in OpenAPI

For complex objects and arrays, serialization in a path parameter is only possible using content and not any style options.

For example, to serialize using JSON, you can define a parameter in the following way:

parameters:
  - name: filter
    in: path
    content:
      application/json:
        schema:
          type: object
          properties:
            type:
              type: array
              items:
                type: string
            strength:
              type: array
              items:
                type: integer

This configuration would serialize to /drinks/%7B%22type%22%3A%5B%22cocktail%22%2C%22mocktail%22%5D%2C%22strength%22%3A%5B5%2C10%5D%7D, which is the equivalent of /drinks/{"type":["cocktail","mocktail"],"strength":[5,10]} unencoded.

How to override path parameter encoding

By default, the characters :/?#[]@!$&'()*+,;= are encoded when present in the value of a path parameter. To render these characters unencoded in a request URL, use the x-speakeasy-param-encoding-override: allowReserved extension. Read more about parameter encoding in the (docs).