Proposal: Parameters in cookie

[JamesMessinger]

Currently, the only way we can define a cookie parameter is like this:

parameters:
  - name: Cookie
    in: header
    type: string
    required: true

But that just requires a cookie - any cookie - to be present. There's no way to distinguish between third-party cookies (e.g. google analytics, advertising, etc.) and our API's cookies. It would be nice to be able to do this:

parameters:
  - name: myApiCookie
    in: cookie
    type: string
    required: true

[webron]

We actually thought about adding support for cookie parameters, but honestly, I'm not sure how that translates to the request. Would would the HTTP request look like in your example above?

[JamesMessinger]

Here's an example HTTP request:

GET /api/pets
Host: petstore.com
Accept: image/webp,*/*;q=0.8
Cookie: _octo=GH1.1.529510590.1404332311; _ga=GA1.2.37070353.1396286465; _gat=1; favorite_pet=Fido;

Notice that there are several third-party cookies in there, as well as my API cookie (favorite_pet=Fido). I'd like to be able to specify in my Swagger spec that this operation requires the favorite_pet cookie.

parameters:
  - name: favorite_pet
    in: cookie
    type: string
    required: true

[webron]

Okay, thank you for the clarification. I should probably hunt down and see if there's any RFC or other standard that defines it. If you know of anything specific, feel free to share.

[mohsen1]

If we are adding cookies to parameters we should add it to response object too. That would help tooling test responses more accurately

[cemo]

definitely +1

[frozenspider]

+1, we just ran into that issue and was quite surprised by the lack of cookies support

[webron]

Parent: #565.

[jharmn]

Example in the wild of cookie-based auth in Wordpress API http://v2.wp-api.org/guide/authentication/#cookie-authentication
JIRA does cookies as well
https://developer.atlassian.com/jiradev/jira-apis/jira-rest-apis/jira-rest-api-tutorials/jira-rest-api-example-cookie-based-authentication

[ePaul]

Cookies do not fit into the REST model of resources and their manipulation with HTTP operations, as they introduce some kind of session state hold by the client and sent back to the server – instead all needed state should be in the resource representations retrieved and the links in them to other resources (i.e. the hypermedia).

I guess cookies used as authentication are a border case which might be needed sometimes – but there is #15 for that.

[JamesMessinger]

@ePaul - I agree that it's bad practice to use cookies for state or resource representations. But using them for authentication is common practice and should be supported by Swagger, IMHO.

There are two scenarios in which Cookie parameters are needed, both having to do with cookie-based authentication:

1. Documenting auth endpoints
   I should be able to use Swagger to document my authentication endpoints, just like I use it to document the rest of my API endpoints. And since my auth endpoints rely on a specific cookie being set, I need to be able to specify a cookie parameter in Swagger.
2. Indicating that an endpoint requires an auth cookie
   Certain parts of my API may require authentication, and other parts may not. I need to be able to indicate this in Swagger. This could be done via the securityDefinitions object, but that doesn't support cookie-based auth yet either. Cookie parameters would accomplish the same goal though, since the it would allow me to indicate that an endpoint requires a specific cookie to be set.

[gmta]

@ePaul I agree with @BigstickCarpet with his use cases, and would like to add another: if I were to document a third party API using OpenAPI / Swagger, I don't get to choose whether they apply a "pure" REST model or use cookies for authentication, state, etcetera.

Although the use of cookies should not be encouraged, it would be nice to be able to document as much as possible about an API - which would include (to some degree) the underlying HTTP mechanisms available.

[IvanGoncharov]

if I were to document a third party API using OpenAPI / Swagger

@BigstickCarpet @gmta
How widespread this practice?
Is it used in new APIs or it went out of fashion?

I'm very interested in documenting third party APIs, my entire project build around this concept. But at the same time, if we start adding all features available in the wild, core spec became huge and hard to fully implement. And the worse possible case is then developers will start doing partial or "light-weight" implementations. Which exactly story behind CORBA failure. So I think two questions which I asked earlier is the minimal threshold for adding non-standard REST practices in the core spec.

[JamesMessinger]

For public APIs, cookie-based auth doesn't seem to be as common as other options, such as OAuth. But it's used very frequently for enterprise APIs, b2b APIs, and single-sign-on solutions. There are even some popular public APIs that use cookie-based auth, such as the ones that @jasonh-n-austin posted the other day

[webron]

Closed as cookie support was added.