CODEWITHSUNDEEP
serializationopenapi
Balázs Édes
Balázs Édes

Reputation: 13807

OpenAPI cookie parameter serialization

I'm trying to implement spec-compliant parameter serialization for OpenAPI cookie parameters.

My only source for this is the docs: https://swagger.io/docs/specification/serialization/#cookie

In the description I'm seeing this line:

An optional explode keyword controls the array and object serialization

However the table below only defines array and object serialization, when explode is false.

What does this mean?:

I hope an OpenAPI expert can shed some light on this, thank you!

Upvotes: 1

Views: 370

Answers (1)

Helen
Helen

Reputation: 97847

Cookie serialization is defined but unfortunately not well thought out, as a result some forms of it don't make much sense. One of the specification authors admits that they "never really thought anyone would go through the trouble of describing objects in cookies in an exploded way".

In a nutshell, cookie serialization follows the same rules as query parameters with style: form.

When using explode: true:

  • A cookie parameter named param with the array value [3, 4, 5] would be sent as:

    Cookie: param=3&param=4&param=5

  • A cookie parameter named param with the object value {"foo": "test", "bar": 5} would be sent as:

    Cookie: foo=test&bar=5

    Note that the parameter name (param) is lost in this case.


As you may notice, both methods deviate from the standard Cookie header format which expects semicolon-separated name=value pairs:

Cookie: [cookie-name]=[cookie-value]; [cookie-name]=[cookie-value];...

In other words, OpenAPI's exploded form of cookies is not quite compatible with cookie parsers. For example, an OpenAPI-formatted exploded array cookie Cookie: param=3&param=4&param=5 would be parsed by a cookie parser as param = 3&param=4&param=5 - which is not what an API developer would expect.


The problems with cookie serialization are being discussed here:
Default 'explode' for cookie parameters?
Feel free to provide your implementer's feedback.

Upvotes: 1

Related Questions