Parameter Serialization

• Explode
• Style
• Path Parameters
  • Simple
  • Label
  • Matrix
• Query Parameters
  • Form
  • Space Delimited
  • Pipe Delimited
  • Deep Object
• Header Parameters
• Cookie Parameters
• Examples and Recommendations
  • General Guide Lines
    • Location
    • Style
  • Optional Boolean
  • Required String
  • List of Strings
  • AnyOf Object or String

Parameters not only define what inputs your API accepts, they also define the format your API expects to receive them in, i.e. how you would like it serialized.

There are two keywords concerning serialization:

Explode #

explode defines whether parameters should be broken into logical components.

It takes a boolean value:

• If true; a parameter with multiple values will be serialized as if each of its values were separate parameters.
  • What separates each parameter is determined by the style.
• If false; a parameter is a single parameter, regardless of how many values it has.

In practice, this means only parameters of type:array or type:object are affected by explode.

• For an array, each value becomes its own parameter.
• For an object, each key-value pair is concatenated into its own parameter as “key=value”.
  • For any style other than form, if the value is an empty string, then it drops the equals and becomes “key”

For a more verbose description of explode, refer to RFC6750’s Variable Expansion.

Its default value depends on the style of serialization:

• explode:true is the default for style:form
• explode:false for anything else.

Style #

style defines how your API expects the parameter to be serialized.

It takes a string value: The options defined depend on the location your parameter is in:

• in:path defaults to simple but can also be label or matrix.
• in:query defaults to form but can also be spaceDelimited, pipeDelimited or deepObject.
• in:header defaults to simple.
• in:cookie defaults to form.

Each style will be explained in more depth per location; examples will make use of the following two parameters.

“pets” which depending on its type has one of the following values:

bool   -> true
int    -> 2
string -> "dog"
array  -> ["cat","dog"]
object -> {"age":2,"type":"dog"}

“hats” which depending on its type has one of the following values:

bool   -> false
int    -> 1,
string -> "fedora"
array  -> ["fedora"]
object -> {"type":"fedora"}

Path Parameters #

For parameters in:path there are three defined values for style:

• simple: defined by RFC6750’s Simple String Expansion.
• label: defined by RFC6750’s Label Expansion with Dot-Prefix.
• matrix: defined by RFC6750’s Path-Style Parameter Expansion.

The defaults in:path are:

• style:simple
• explode:false

Every style in:path follows RFC6750 so the effects of explode are well-defined by RFC6570’s Variable Expansion.

Simple #

style:simple with its default of explode:false, would serialize your parameters like this:

• Single values are unchanged.
• An array with multiple values is concatenated into a comma-delimited list.
• An objecthas its key-value pairs concatenated into comma-delimited pairs, then each pair is concatenated into a comma-delimited list.

If you set explode:true, then the seperator used is also a comma: “,”:

• Single values remain unchanged.
• Surprisingly, an array with multiple values seems unchanged. Though it treated each value as a separate parameter, it still had to separate them with a comma. So it still ends up as a comma-delimited list.
• To understand what happened for an object looking back at the rules on explode we see it concatenates key-value pairs into their own parameters as “key=value”. Then it has to separate each parameter with a comma.

Label #

style:label with its default of explode:false, would serialize your parameters like this:

Everything is the same as style:simple except all parameters were prefixed with “.”.

If you set explode:true, then the seperator used is a period: “.”: