6

According to https://labs.omniti.com/labs/jsend,

  • Fail: When an API call is rejected due to invalid data or call conditions
  • Error: When an API call fails due to an error on the server

Can this be interpreted as 4xx errors (such as a 404) should always return a Fail, but 5xx errors always correspond to a Error?

chintogtokh
  • 803
  • 1
  • 10
  • 25
  • Later on it says "it is advised that server-side developers use both: provide a JSend response body, and whatever HTTP header(s) are most appropriate to the corresponding body."...so if you think those errors are most appropriate to those situations (and broadly I'd agree with you) then go ahead. – ADyson Nov 08 '18 at 08:44

1 Answers1

7

This is a great question and I'll answer it with a concrete example from my own experience. In an API for one of my projects, I allow the upload of an Excel spreadsheet, which is processed and the resulting JSON is stored on the server.

If there is an error saving the data to disk, then I would respond with a JSend "error" along with the appropriate error message since the data should have been able to be saved.

If, on the other hand, the data in one of the rows is not valid (maybe an incorrect data type or a range error), then I know the exact row (or rows) of the spreadsheet that were incorrect. In this case, a "fail" response is appropriate as the data property of the JSend response will contain a list of all rows (the row number and the error message) for each unprocessable row.

In the case of an "error" response, I wouldn't have that ability as I would be limited to a single message property. But with the "fail" response, I have the data property available where I can respond with a fine-grained list of issues.

So, while there was no error, the data itself was not correct and the user should go back and look at their spreadsheet and fix the issues identified by the data property in the "fail" response.

Thinking of this in terms of HTTP errors, although an interesting exercise, doesn't always result in an exact mapping (4xx = fail, 5xx = error). It's more about what you want to communicate to the client: something bad happened that shouldn't have happened ("error") or the server is working fine but your data isn't quite up to standards ("fail").

Finally, whether you want to also use HTTP errors is entirely up to you. You could always respond with a 200 and let JSend do the talking. But that's a slightly different (and somewhat religious) discussion. :-)

I hope that helps.

Frank Hellwig
  • 208
  • 3
  • 9
  • 1
    I find this answer confusing: You say: "Thinking of this in terms of HTTP errors, although an interesting exercise, doesn't always result in an exact mapping (4xx = fail, 5xx = error)." In your example you respond `fail` when there is a problem with the spreadsheet and `error` if e.g. it can't be saved to disk even if ok. Isn't that exactly 4xx: "Client_errors" vs. 5xx: "Server errors"? Do you have an example where `fail` should be HTTP error code 5xx or where `error` should be 4xx? – Peter V. Mørch May 12 '20 at 20:38
  • 1
    Peter, you make a valid point. Where I struggle (almost a year after I wrote this), is with the JSend specification making `fail` being "bad-data oriented" and the `message` key is neither required nor optional. I can imagine a `PUT` request with a timestamp inconsistency between the client and the server (based on HTTP headers, and *not* on client data) resulting in a 409 (Conflict) response. Clearly, there is nothing wrong with the data per se and a JSend `error` response with a `code` of 409 and a `message` of "Entity on server is more recent than request data." is entirely appropriate. – Frank Hellwig May 14 '20 at 17:56
  • 2
    In my personal opinion using JSend for a REST API, the root problem is JSend's dismissal of HTTP headers as an integral part of a REST API. JSend's `status` field is redundant, as this information is already in in the `Status` HTTP Header (they're even called the same thing). "The spec is meant to be as small, constrained, and generally-applicable as possible. As such, it has to be somewhat self-contained." - But REST should embrace HTTP headers and verbs, not pretend they don't exist. – Peter V. Mørch May 15 '20 at 13:30
  • 1
    Indeed. These days, I find myself using HTTP status codes and a simple object with a `message` property on error. This way, there is zero friction with axios or related libraries. JSend seems to try to solve a problem that really was never there. – Frank Hellwig May 17 '20 at 17:41
  • I know this is a bit strange but if you think of it like that maybe it will be understandable (if you (Client) Fail to give me the right data I will give you (Server) an Error ) Servers always give an error, Client always Fail to give right data. Right @FrankHellwig – Tarek.Eladly Apr 25 '21 at 07:52
  • @Tarek.Eladly Exactly. I like your logic. By that thinking, even a 404 is technically a "fail" vs an "error" as the client failed to provide a valid URL. So yes, you (the client) failed to provide a valid location. Cool. – Frank Hellwig Apr 26 '21 at 21:31