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}.

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 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}.

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:

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).