microsoft / microsoft/api-guidelines
Add guidance about how to handle unrecognized query params, well-known but unsupported headers, & unrecognized fields in a request body
@mikekistler is already working on this.
Since May 5, 2022.
- Dominant language
- No language data
- Stars
- 23.3k
- Forks
- 2.7k
- PR merge metrics
- No merged PRs in 30d
Description
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?
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.