microsoft
Add guidance about how to handle unrecognized query params, well-known but unsupported headers, & unrecognized fields in a request body
Regarding header parameters, the guidelines say:
DO NOT fail a request that contains an unrecognized header. Headers may be added by API gateways or middleware and this must be tolerated.
Regarding query parameters, the guidelines say:
DO return an error if the client specifies any parameter not supported by the service.
However, this last sentence is not mentioned in a generic context but specifically in the context of the query parameters used to query collections (e.g. filter, orderBy, etc.).
💡 It would be great to have explicit guidance about how services should handle the following:
- Unrecognized query parameters, i.e., Does the guidance above extrapolate to any unsupported query parameter or does it not? Is it a problem that adding arbitrary query parameters to a URL is a common (albeit hacky) way to circumvent caches?
- Well-known but unsupported header parameters, e.g.,
If-Match,If-None-Match, etc. If a client specifies them but the service does not support them, should this result in an error so as to not return a misleading response? Or does the guidance above about ignoring unrecognized headers still applies? - Unrecognized fields in a request body, i.e. Should they be ignored or should they result in an error?
All good questions! We'll try to get these clarified in the next round of guidelines updates.
