microsoft / microsoft/api-guidelines

Add guidance about how to handle unrecognized query params, well-known but unsupported headers, & unrecognized fields in a request body

Open
#348 1 comment 0 reactions 1 assignee View on GitHub

@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:

  1. 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?
  2. 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?
  3. Unrecognized fields in a request body, i.e. Should they be ignored or should they result in an error?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.