Re:Reserve the 418 status code
by caseysoftware on Monday August 14, 2017 @11:06AM
(#15009114)
Expressive error messages are great. Calling errors a "success" is wrong.
Check out my slides here for more: https://speakerdeck.com/caseysoftware/12-reasons-your-api-su...
Slides 38-40 are specifically about expressive and useful error messages.
Your slides illustrate a custom response payload which happens to use codes that numerically match HTTP status codes. You also use a response message, I think we actually agree. I'd recommend using a different numerical namespace to avoid any possible confusion about the semantics of those codes. Just because they sound the same to one person reading the spec doesn't mean they will make sense to others.
Re:Reserve the 418 status code
by caseysoftware on Monday August 14, 2017 @11:13AM
(#15009177)
Understood on that point. The response codes are in those payloads purely for illustrative purposes.
>appropriately formatted
If the server is expecting data that it doesn't receive (because the form field was left blank) then can you really consider the request "appropriately formatted"? Is it in any way meaningfully different from the case where the server receives a request on /api/invalid-url/ and doesn't have a corresponding resource on its end?
Error handling is an application level concern, not a transport level concern.
HTTP status codes lack the nuance required to inform the end user about errors in any non-trivial application. I personally enjoy the OP's solution. I've worked on dozens of REST APIs in my life, and I always prefer those that contain a response envelope complete with metadata and error responses.
Pre-emptive edit: When I say error handling is an application level concern, I don't mean "application" from an OSI model perspective, which is narrower in scope than what I'm talking about.