-
Notifications
You must be signed in to change notification settings - Fork 890
Closed
Labels
Description
Before I write up a PR for this, I want to see if there's interest. The idea is to identify particular error cases described by the spec with a URI, which would live at the href
property in the returned error object. This would have a few advantages, as I see it:
- It would allow clients to distinguish between multiple errors that return the same status code. For example, a 403 Forbidden can occur on a request to replace a to-many relationship either because full replacement isn't allowed, in which case the client might be able to reformat its request successfully, or because the client simply isn't authorized to patch the resource, in which case it should give up. The same ambiguity can occur for a POST with a client-generated id, that is: the 403 could be coming because of a general authorization error, which the client can't do anything about, or because client-generated ids are unsupported, which it may be able to adjust to. As I alluded to in Media type negotiation cleanup #673, there will also likely be different-but-same-status-code errors around extension negotiation that it would be valuable for clients to be able to distinguish as well. For example, the difference between extension negotiation not being supported at all vs. a particular combination of extensions not being supported.
- It would be a usability win, in that each error uri could actually be dereferenceable to a page at jsonapi.org that has a human-readable description of the error and suggestions for fixing it. Angular does this for its errors and its incredibly helpful.
To get the full benefits of (1) for clients, I think this would ideally be a MUST for 1.0 (at least for certain errors), since it doesn't impose any real implementation burden on servers. That said, these URIs could be added as a SHOULD post 1.0, with almost the same value.