Error object or similar

[idlesign]

Hi,

Spec is interesting, despite of lack of recent activity. Thank you.

The draft seems to be missing value object describing errors, which is substantial.
This could not only supply some additional information for HTTP status (link #29), but also help to describe form validation (link #36).

Any suggestions on that?

Offtopic: ionwg.org links are misleading.

[lhazlewood]

@idlesign thanks for the issue - we've been a bit busy on other work, but Ion is definitely a priority.

My biggest concern around errors is ubiquity. For a spec to define an error object/resource/result, it should be ubiquitous, and I'm not sure that is possible across domains and use cases.

Also, it is totally plausible to define a custom error result using Ion today with simple links, descriptions and whatever JSON members you prefer.

One example that illustrates the difficulty here: should an error object contain an integer status code member?

Years ago, I firmly believed that should be the case, but now, after a lot more experience, I believe error codes (beyond a general quantity like what HTTP provides) is a nightmare - error semantics could change ever so slightly over time, or new errors could be introduced over time, or also as likely, an error interpretation should be changed to mean something else because of a bug found in the software which was fixed later (at which point the current error code doesn't make sense anymore).

Worse, error consumers write conditional logic into their code (if (errorCode == 1501) { //do stuff }), and if you need to add, remove or change error codes, now you're introducing backwards incompatible changes that can easily break consuming clients.

Based on this and the many APIs I've seen over the last 5 years, I'm firmly in the camp that error codes are a horrible idea and the ideal solution for them is links (that can be traversed to more information for troubleshooting) and human-readable error descriptions that can be relayed to end-users in software.

That said, there will be plenty of people that still choose to - as I believe - shoot themselves in the foot by using them or are just not aware of these (truly painful) downsides, and will want them anyway. So then what should Ion define?

You can see the difficulty here. Since my experience indicates links and meaningful text are the best way to solve this problem (at scale, which is a spec's concern), Ion already has these concepts and an spec-defined error structure might not be necessary at all.

Does this make sense? Any thoughts? Cheers!

P.S. We acquired https://ionspec.org which should be more intuitive. Please try that URL.

[idlesign]

@lhazlewood

Also, it is totally plausible to define a custom error result using Ion today with simple links, descriptions and whatever JSON members you prefer.

Yes and that arouses my concern: every service would try to invent something different. Which wouldn't be the case if standardized.

One example that illustrates the difficulty here: should an error object contain an integer status code member?

Those seems useful. Codes are usually made backward compatible. If required, codes deprecation is usually handled with API versioning. I don't think that integer is a must for a code, by the way.

Links are ok but emedding error information (including machine-friendly and human readable) seems to be more appropriate in many cases: it's easier to get error in response than make a round-trip to recieve some basic info; it doesn't obligite service to store all errors happened (sometimes such info goes straight to something like Sentry).

Besides links are just a pointers to resources. If such resource format could be formalized it would be great. It'll allow libs (implementing API both for servers and clients) to provide useful generic abstractions for error handling.

Does this make sense? Any thoughts?

Since Ion has a notion of forms, maybe it could help in error response definition.
E.g., response with error could address field names described in form:

{
  ...
  "value": [
    { "name": "username",  "error": "Already taken."},
    { "name": "password", "error": "Not strong enogh." }
  ]
 ...
}

https://ionspec.org works fine, thank you.