Best Practices for HTTP Content Negotiation in case of Error Responses?

95 Views Asked by At

I have a discussion, how to implement content negotiation for error cases. I'd like to hear your opinion or experiences to deal with this topic. Please be aware that there might be APIs dealing with RFC-7807, and those who don't.

The main theses to discuss are (only concerning error responses):

  • The Accept-Header names the mime types that the client is able to handle in case of 2xx responses. It can be used also to decide which error response format is rendered (recommended), but this is not required. E.g. if we return a RFC-7807 problem detail, we typically use application/problem+json or application/problem+xml, although the client requested application/pdf.
  • The 406 response code is only for reporting back that the server is not able to create a 2xx response for the requested format(s). It would not be applicable to use when another problem occured, but the server is not able to render the error response in a client-compatible format.
  • In case of RFC-7807, we would mostly derive from the Accept header. If the client requests application/json, and we return application/problem+json, it's the same format, but not the same semantic and therefor has a different scheme in comparison with the 2xx response.
  • In case of errors, the client has to deal with response formats that it is not able to render. To minimize confusion, an OpenAPI spec for the API lists the error response formats that can be returned.
  • If the client sends an Accept-Header of application/problem+xml, it only prefers a special content type in case of error responses, but does not specify one for 2xx responses, so the server would use its preferred (mostly JSON).

What do you think about that?

0

There are 0 best solutions below