Connexion: Validate that all query and formData parameters are in spec

[dsem]

I think a case can be made that the validators should fail if a request is made with an extra query or formData parameter that is not in the spec (though I don't think this should apply to header parameters).

I have a commit that implements this change. If it's wanted, how should I contribute it?

[hjacobs]

@dsem IMHO it's not good practice to be too strict here --- unknown params and payload fields should be ignored to support API evolution. See also our RESTful API guidelines: https://zalando.github.io/restful-api-guidelines/compatibility/Compatibility.html

We _MAY_ consider supporting a strict mode which needs to be explicitly enabled...

[jmcs]

If we took this to an extreme we would need to document every single standard HTTP header in the spec. I think it's a good idea to follow Postel's law (within reason).

[dsem]

I have not yet had to support an evolving API so I don't know the pain-points first-hand, but feel this validation would help in a few ways:

• Clients developing against the API would see a clear error message if e.g. they have a typo in their parameter name
• Clients migrating from one version of the API to the next would have explicit messages showing which parameters they use are no longer supported
• The Flask code itself doesn't have to worry about handling parameters that are not defined in the spec. For example, if I have a /search endpoint function and I want to pass all of the API parameters on to my ORM, I can just use **kwargs in the ORM call and not have to worry about a malformed parameter that wasn't defined in the spec messing with the results (though I don't have an explicit example of one that would mess with the results). This makes evolving the API easier as when new fields are added or changed, one just needs to update the Swagger spec and the database schema and not the Flask codebase (which can be nice when prototyping APIs with connexion).

Also, I strongly dislike the comparison to the extreme case. No one is asking for header parameters to be validated in this way so it shouldn't be used as an argument against validating query and form data parameters.

Anyways, in the case that you someday want to enable a strict mode, should I push my commit upstream somewhere or just hold on to it?

[rafaelcaricio]

@dsem If you can make you can create a "flag" to enable strict validation and make sure the strict behaviour only executes when the flag is active, you can send a PR and we will be happy to discuss and accept.

[dsem]

So, I've done some more reading about API design and can see the value in not having strict validation. (sorry to cause such a fuss). Still, I updated the patch and made it optional if anyone finds it useful.

On a side note, I see in the link to Zalando's API standards that your responses are structured in the HAL format. Do you use a Flask module to achieve this and is it compatible with connexion or is it all defined as part of your swagger spec? Also, have you found it to be worthwhile? Do you use curies and if so, do any of your clients actually consume the documentation endpoints provided in the curies, besides twintip? (Feel free to answer as many or as few of those questions as you want).

[hjacobs]

@dsem short answer regarding HAL: I never used it myself and I'm personally not convinced that HATEOAS brings many benefits. Our RESTful API guidelines say "Could: Use HATEOAS", so it's not mandatory (but if you do it then use HAL) http://zalando.github.io/restful-api-guidelines/hyper-media/Hypermedia.html