I really like the JSON:API spec for it’s clearness regarding MAY and MUST mentions.
However the links member in an Error is not crystal clear.
An error object MAY have the following members:
Does this mean a links member MUST and MUST ONLY contain an about link?
Or MAY it contain an about link and MAY it contain any other links?
Cheers,
Marcel
I think you interpreted the specification exactly correct. To me, the link object in the error response is intended to point to the documentation of the specific application error code in order to explain the context when combined with the source/pointer and source/parameter arguments.
Suppose you have a very complex workflow, like a mortgage application. If you have specific domain (application) validation which goes beyond simply sanitizing the user input, the error link would point to the documentation which explains error code=394294. The client or user/developer could then use these combined fields to present a correction dialogue with only the invalid segments for the user to correct, and resubmit.
If you were to expand this field to a generic container, you would lose the ability to guarantee the interoperability of the fields to create this capability. You could certainly still have it if the situation persisted, but it would greatly complicate the consumer, making errors and interpretation differences far more likely.
I find the description of the links member of the error object confusing as well.
Since the about member refers to information on the specific instance of the error described by the error object, why isn’t a self member used instead? Is an error instance really not a resource as well?