added cookie parameter #655
Conversation
| * Path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. | ||
| * Query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. | ||
| * Header - Custom headers that are expected as part of the request. | ||
| * Body - The payload that's appended to the HTTP request. Since there can only be one payload, there can only be *one* body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation. | ||
| * Form - Used to describe the payload of an HTTP request when either `application/x-www-form-urlencoded`, `multipart/form-data` or both are used as the content type of the request (in the OpenAPI Specification's definition, the [`consumes`](#operationConsumes) property of an operation). This is the only parameter type that can be used to send files, thus supporting the `file` type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4): | ||
| * `application/x-www-form-urlencoded` - Similar to the format of Query parameters but as a payload. For example, `foo=1&bar=swagger` - both `foo` and `bar` are form parameters. This is normally used for simple parameters that are being transferred. | ||
| * `multipart/form-data` - each parameter takes a section in the payload with an internal header. For example, for the header `Content-Disposition: form-data; name="submit-name"` the name of the parameter is `submit-name`. This type of form parameters is more commonly used for file transfers. | ||
|
|
||
| * Cookie - Used to pass a specific cookie value to the API. Cookies are passed specifically through the `Set-Cookie: {name}={value}` syntax. |
There was a problem hiding this comment.
Hmm, no. Set-Cookie: is used by the server, the client sends Cookie:.
Cookie - Used to pass a specific cookie value to the API. Cookies are passed in an HTTP
Cookieheader, using the{name}={value}syntax as defined by RFC 6265.
There was a problem hiding this comment.
my bad, i will fix this
|
There is architecturally no difference between headers and cookies, except for the name and a more rigid serialization scheme |
|
@OAI/tdc please accept or reject, if we choose to accept, I will add response cookie definitions and global cookie definitions to the PR. |
|
[Documenting some of the @OAI/tdc debate on this topic…] At face value, this change seems to make complete sense. However, it cuts to the heart of an important issue — the spec exists so that tooling can leverage it. The wider the spectrum of APIs that OAS can describe, the heavier the burden on tooling authors. Without going into the pros/cons of using cookies in API design, cookies are easy to work with in web browser clients, but they're less easy to deal with in just about everything else. By supporting cookies, we increase the surface area of OSS projects and commercial offerings that may wish to be OpenAPI certified (assuming that such a program exists in the future). The issue of cookies will set a precedence. Cookies are great for the web but arguably less appropriate to modern APIs. Should the OpenAPI Specification aspire to be more descriptive, or should OpenAPI aspire to make difficult choices to keep OAS more actionable? |
|
Having done some research on the subject, there are two sides to it. For most APIs, this is not a recommended approach. However, there are a number of use cases where browser-integrated apps provide a much better DX, at little risk, from utilizing cookies. We have documented a number of significant commercial offerings (Atlassian, Wordpress, etc) where cookies have been used successfully. IMO OpenAPI should not be overly opinionated from an API design perspective. The freedom to make design choices that are appropriate to your use cases is the defining freedom which has made APIs great. Adding too many constraints simply excludes APIs which fall somewhat out of the norm...the result is poorly documented/automated APIs, or other spec formats taking advantage by adding the functionality. 👍 |
|
I agree with @jasonh-n-austin on this one. We shouldn't force design or best practices on anyone. And there are many APIs out there using cookies as some form of the contract and that's OpenAPI's purpose is to describe said contract. |
|
The spec is and will probably be opinionated on API design to some extent. The reason it's opinionated, to me, is normally not because of good/bad API practices but rather what it means for tooling support. Another reason the spec may seem opinionated (but it's not) is the case of simplicity over functionality. For the latter, I don't see added complexity so it's fine. For the former, I'm not sure what kind complexity it will introduce to tooling, if at all. As such, I'm going to abstain here. What I'm concerned about is the serialization of cookies. How exactly are those going to be described? Just type string? Or are people going to expect a way to enumerate 'fields'? For completeness, I think it's important to include an example here of what it's going to look like. |
This simply adds the
cookieparameter type, which addresses the following:#15, #161, #301
There are a number of issues in other projects which are addressed with this fix as well.
In a follow-up issue, a response of type
cookiewill be added