5 ms·
The error messages could be better yet. The example uses a different code per issue, for instance: "user/email_required". Most integrators will build their UI
by pokoleo 5y ago
The error messages could be better yet.
The example uses a different code per issue, for instance: "user/email_required". Most integrators will build their UI to highlight the input fields that contain an error. Making them parse the `code` field (or special-case each possible code) is pretty toilsome.
// from blog post
{
"code": "user/email_required",
"message": "The parameter [email] is required."
}
Make it parseable:
// improved
{
"message": "An email is required.",
"error": "missing_parameter",
"parameter": "user.email"
}
In addition, I:
* rewrote `message` to be an acceptable error message displayed to (non-technical) end-users
* moved message to be the first field: some developer tools will truncate the JSON response body when presenting it in the stack trace.
---
As an added bonus, structured data allows you to analyze `error` frequencies and improve frontend validation or write better error messages: https://twitter.com/VicVijayakumar/status/1495092161821429761 https://twitter.com/VicVijayakumar/status/149509216182142976...
- smoyer 5y agoIt also doesn't hurt to repeat the HTTP status code in the JSON body - when you receive a response, the status code and entity body are coupled but even if the server logs the status code, they're often decoupled in the logging system - having both in one log entry is way easier!
- moltar 5y agoAgreed. But rather than reinvent, let’s just use JSON API standard? https://jsonapi.org/format/ https://jsonapi.org/format/ (Scroll to the very bottom)
- pokoleo 5y agoThe article is about REST API design, not JSON APIs! It’s a whole different ballpark.
- pan69 5y agoIt might be to formal for your use-case, but there is a standard defined for error responses in RFC 7807: https://datatracker.ietf.org/doc/html/rfc7807 https://datatracker.ietf.org/doc/html/rfc7807
- aeontech 5y agoWow, I had never seen an API with errors at this level of detail… I feel lucky when they at least use sane status codes instead of always giving back 200 and a maybe-json-maybe-plaintext-maybe-empty body… I’d love to hear from anyone who has encountered APIs in the wild that actually implement this standard!
- JimDabell 5y agoI use Problem Details in most APIs I build. It’s as simple to generate a Problem Detail as it is to generate ad-hoc errors, but you can re-use code.
- abdusco 5y agoASP.NET Core uses ProblemDetails ~~by default~~. https://docs.microsoft.com/en-us/aspnet/core/web-api/handle-errors?view=aspnetcore-6.0#produce-a-problemdetails-payload-for-exceptions https://docs.microsoft.com/en-us/aspnet/core/web-api/handle-... https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.mvc.problemdetails?view=aspnetcore-6.0 https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnet...
- amjd 5y agoI used to work at Akamai and Problem Details is used in most of their APIs. It might have something to do with the fact that one of the RFC authors (Mark Nottingham / @mnot on HN) worked there for a while.
- morelisp 5y agoI've used both Problem Details and JSONAPI errors[0] which are basically the same idea (and I've used them plenty outside of JSONAPI-proper APIs). In both cases if you have a decent error-handling middleware there should be not much difference than outputting any other kind of errors. One thing to keep in mind re. "maybe-json-maybe-plaintext-maybe-empty" responses is that the more complex your errors, the more likely the error handling encounters an error. If you're trying to send back some JSON or XML but it fails it's usually better to at least shove out a line of plain text and hope it reaches a human than to mask the real error with a second fallback in the "right format" but with unhelpful fixed content. [0] https://jsonapi.org/format/#error-objects https://jsonapi.org/format/#error-objects
- hinkley 5y agoLocalization has entered the chat. You need codes because the field isn't going to be 'email' for much longer than it takes for your management to realize that people outside of the US also have wallets.
- aidos 5y agoNo doubt they exist, but I’ve never seen an api that localised identifiers.
- codys 5y agoField ids are not (necessarily, especially when doing localization) something shown in the UI. The point made by the original commenter is that a field in the error should refer directly to which field has an issue. It does, via an id that happens to be "email". It's still up to the clients to decide how to represent that to the user, but they're given a distinct field rather than needing to infer which field an error code refers to. (While the comment I replied to can be read differently, I assume we all know that changing actual field names (in APIs) depending on localization is nuts)
- chaz6 5y agoMy view is that apis should simply return a number when an error occurs. The vendor should supply a list of error codes to its consumers, translated into as many languages as necessary. The developers who are consuming the api can then determine how best to present the error to its end users. A set of error numbers is tied to the version of the api that is being consumed so there should be no surprises.
- Step888 5y agoIn other words, if a set of people don't understand the message, make sure that no one understands the message (not even the people that normally just press the Google Translate button). Is that what you're saying? Or did I misunderstand you?
- b-pagis 5y agoSuch simple approach is limited only to errors without arguments. For more complex use cases, where we would want an error message to indicate that field value was too long and in addition provide maximum field length, we would need to introduce new field in the error response. While it is solvable by adding this information to client application side. It would create a situation where the logic is duplicated in two places (backend and client application)... Also if we would want better UX, then we would need to display all errors at the same time in the form that is incorrectly filled. This would require changing error structure to return array of errors and it potentially create a breaking change in the API or would result in confusing structure that supports both, legacy and new format... Some years ago, I wrote an article sharing the ideas on how REST API error structuring could be done depending on the complexity of application or service: https://link.medium.com/ObW78jhDkob https://link.medium.com/ObW78jhDkob
- pokoleo 5y agoInteresting! Do you find that returning an array of errors works in practice? Most validation I’ve seen looks like: raise error if foo raise other_error if bar This pattern turns into one exception per response, and some foresight in architecting exceptions would be needed
- iudqnolq 5y agoThe Phoenix framework does this for forms. It requires a whole system built around a type called a Changeset that describes input parameters, their validity, and how to modify a struct to reflect the valid changes. In practice this ends up tightly coupled to the database layer for simplity.
- pokoleo 5y agoDoes "tightly coupled with the database" work, in practice?
- bongobingo1 5y ago
- rbluethl 5y agoHey thanks for your input. These are great additions!