Update example to be more HTTP-focused

[dret]

The original example in https://www.rfc-editor.org/rfc/rfc7807#section-3 is more about a business problem than about an HTTP problem. It might be helpful to change the example to one that's more specifically about a technical problem. Optionally, we could also mention that different people have different preferences when it comes to if/how business problem should be reflected in HTTP status codes. By choosing an example that's clearly technical in nature, we could better avoid taking sides in that discussion.

[asbjornu]

I'm afraid I have to disagree with a "neutral" stance on whether to represent business problems in HTTP or not. As HTTP is an application protocol, representing the application's state in HTTP is IMHO the correct thing to do.

If anything, I believe it's important that RFC 7807 takes a clear stance on this issue to help nudge this discussion in the right direction, and not re-enforce the view of HTTP merely being a transport protocol.

[dret]

On 2023-03-27 22:02, Asbjørn Ulsberg wrote:

I'm afraid I have to disagree with a "neutral" stance on whether to represent business problems in HTTP or not. As HTTP is an application protocol, representing the application's state in HTTP is IMHO the correct thing to do.

If anything, I believe it's important that RFC 7807 takes a clear stance on this issue to help nudge this discussion in the right direction, and not re-enforce the view of HTTP merely being a transport protocol.

some things are relatively clear: when you send a request with a wrong media type or with payload violating the request schema, you are violating the contract and a 4xx is in order. problem reports can help to be more explicit about what happened.

other things are less clear: if you ask to transfer money but you don't have enough, denying the transfer is not really an "client error", it follows the rules of the contract: you can only transfer money when you have money.

some people like exposing those latter problems in HTTP as well, others don't. one reason is that not all these decisions are binary, and HTTP has no way to natively signal "your request partly succeeded".

one way or the other, there is no reason for the spec to go down this particular rabbit hole, and using an example that's clearly from the binary category (such as validating against a schema) allows us to be explain how the spec works without having to be opinionated about how people design their APIs.

-- Erik Wilde | @.*** | | https://youtube.com/ErikWilde |

[asbjornu]

some people like exposing those latter problems in HTTP as well, others don't.

For those who don't like to expose business problems in HTTP, how would they represent the error of trying to transfer money from an account with insufficient funds? 200 OK?

[dret]

On 2023-03-28 11:05, Asbjørn Ulsberg wrote:

For those who don't like to expose business problems in HTTP, how would they represent the error of trying to transfer money from an account with insufficient funds? |200 OK|?

yup, which i am sure makes you unhappy. but there is some logic to it: you receive a request and responded according to what the business logic defines. that's a successful processing of the request and it's hard to imagine that a user agent would be able to fix anything and retry.

[asbjornu]

you receive a request and responded according to what the business logic defines. that's a successful processing of the request and it's hard to imagine that a user agent would be able to fix anything and retry.

The request was to transfer money, not to have the HTTP body parsed according to its Content-Type and assigned programmatic schema. The request to transfer money failed, therefore the response should indicate that the request failed.

A 200 OK response for a failing request is a clear violation of the HTTP specification, imho.

[mnot]

I agree with @dret here -- this is not the spec to resolve this debate in.

[mnot]

A 200 OK response for a failing request is a clear violation of the HTTP specification, imho.

It depends on how you define fail. When I perform a web search, if there aren't any results, should the results really be a 4xx? What about when a banking transaction fails in an HTML interface?

I was looking at resolving this issue by changing the example completely, but given where we're at in the process, that's not really desireable. So I think the best thing to do here is to keep 403 on the first example, and use 422 on the second one. See commit forthcoming.

[asbjornu]

It depends on how you define fail. When I perform a web search, if there aren't any results, should the results really be a 4xx?

The search resource exists, so a 404 would be wrong, at least. But I would say that the nature of search is to often not return any results and as such, that's not something I would consider an exception and therefore not an error. 200 OK.

What about when a banking transaction fails in an HTML interface?

I'm not sure why the HTML interface is relevant? If the transaction fails, 4xx is the appropriate response code regardless of media type, imho.

I was looking at resolving this issue by changing the example completely, but given where we're at in the process, that's not really desireable. So I think the best thing to do here is to keep 403 on the first example, and use 422 on the second one. See commit forthcoming.

Fair.