How to disallow unknown query parameter?

[smikulcik]

The operation object allows folks to specify parameters, but how can I express that no unnamed parameters may be accepted?

We've had issues where clients are passing in query parameters thinking that they're accepted when actually they are not.

How do folks feel about introducing something like additionalQueryParameters for parameters?

/foo:
  get:
    parameters:
      limit:
        in: query
      offset:
        in: query
    additionalQueryParameters: false
    ...

Then when folks do GET /foo?start=xxx-xxx-xxx they'll get an error instead of a silent failure.

Other links on the web:

• https://stackoverflow.com/questions/58187233/is-it-possible-to-disallow-unknown-query-parameters-in-an-openapi-v3-spec
• Rejecting unknown query parameters should be optional cdimascio/express-openapi-validator#133
• Should a server ignore unrecognized query parameters OR throw a 400? opengeospatial/ogcapi-features#128
• https://softwareengineering.stackexchange.com/a/311489

[savage-alex]

This is an excellent question!
Inside a schema the additionalProperties defaults to true as it (loosely in 3.0) based on JSON schema which will unless specified accept additional properties.

Re query params it is an interesting question and seems to vary per implementation. As these are explicitly defined and documented a client should be following the API definition to ensure the type, range, format etc of their request matches what the OAS definition aka "contract" prescribes. You would be well within your rights to return a 400 detailing the unsupported parameter in the same way you would report an out of range.

Where it gets a bit nuanced is interpretations of postels law on being conservative what you send and liberal in what you accept. Its not unusual to see APIs that would accept but disregard anything that is not in the definition silently and this is also acceptable.

Is it something you could cover in the descriptions and overall behaviour of your APIs stating your position and in your level of error verboseness?

[hkosova]

Possibly related: #568

[g-t-a-ogle]

This would be a very useful feature to have, as an added help to security. It also helps with the conditions mentioned above, especially where you would consider sending the wrong query variables concerning and you have a large number of paths.

[MikeRalphson]

If we moved to representing all in:query parameters as an object described by a single JSON schema, then we would get this functionality 'for free' with the existing additionalProperties keyword.

[nfroidure]

In my APIs I always default to disallow additional query parameters but I think it would be nice to have this option to explicitly say we do it.

I also made a proposal for the order of the query parameters here: #883

[aagranovExtend]

This would be very useful. I was looking for this just now.

[smikulcik]

So where does this put us today.

@savage-alex you make a good point about what we actually should and shouldn't document in our specifications.

Perhaps we should ask, "when would it be desirable to permit undocumented query parameters?" If we have no good use cases for it, maybe we should by default specify that implementations should reject unknown query parameters in general.

[Virtual-felix]

Did someone found a workaround in the meantime that the feature might be integrated ?
Or there is no way to catch unknown query parameter as an error currently ?

[mikekistler]

Reposting my comments from #3738 here for visibility:

I am wondering how this feature will be used in practice.

I don't think users of the API get any benefit from it. It does not "describe" any useful behavior of the API, unlike additionalProperties which can include a description that explains the meaning of additional properties. It specifies when the operation is required to fail but not when it actually will fail, since undefined query parameters can still cause failures when undefinedQueryParameters is true, the default. So users must be prepared for failures either way.

I suppose this clarifies to implementers how they should treat undefined query parameters, but this assumes that the API description is written by someone other than the team that implements the API, which in my experience is rather rare.

I do understand that, from an API governance perspective, rejecting undefined query parameters is a best practice and failures to do so should be rooted out and corrected. But I don't think adding undefinedQueryParameters helps much on this front -- and could actually hinder it, since it gives implementers an excuse for not following this best practice -- "Well, we didn't document that undefined query parameters must fail, so we don't need to fix our service".

In short, I don't see much practical value in this new keyword and would not recommend it's use in any of the APIs I work with, but if others feel strongly that it is needed I wouldn't oppose it.

[handrews]

I'll note that I've talked to several folks who specifically recommend allowing undefined query parameters due to 3rd-party entities appending them for various purposes (e.g. tracking). There was a brief discussion about it on the APIs You Won't Hate slack recently.

So that's a use case for allowing, and multiple people have spoken up here over the past two years saying that they would use the disallow.

I'm generally very skeptical of one person saying "I wouldn't use this" and making that an argument for not adding something. Particularly when multiple people over time have said they would use it. Why should someone's lack of interest in a feature invalidate the use cases of others? No one is forced ot use the keyword.

[karenetheridge]

If we moved to representing all in:query parameters as an object described by #256 (comment), then we would get this functionality 'for free' with the existing additionalProperties keyword.

This is already possible: with style=form, explode=true, type=object, a single parameter will consume all values in the query string.

This functionality should be documented as an example in the specification, as it is quite useful but not immediately obvious to those unfamiliar with json schema (or those who have written an openapi validator ;) ).

I can see that it may still be useful to have an explicit config for what OP requested, however.