I'm aware of some of the popular Hypermedia formats such as HAL, UBER, and Collection+JSON and I do see the value in these however if I'm looking to simply add a suggested URI in the case of an error response for an existing HTTP based API what would be a reasonable way of doing so? I would rather not just make something up myself that has no semblance of standards but on the other hand I'm not looking at overruling the API either that the time. Additionally in skimming over the details of some popular Hypermedia formats I don't see any examples specifically suggesting how to present relative links related to error cases.
An example use case I would like to support is something along the lines of a response to a POST to a URL of the format /documents/vehical-listing where the listing was missing an owner property, I would like to point the consumer to a URL such as /vehical-owners so that they would know where to POST a owner information before attempting to POST vehical-listing which requires a registered owner to be referenced.
I believe what you are looking for is called http-problem. It is a format for returning error information that is going through the process of being standardized. Akamai currently use it and I know a number of other developers who are adding support for it.
Here is the example from the spec,
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en
{
"type": "https://example.com/probs/out-of-credit",
"title": "You do not have enough credit.",
"detail": "Your current balance is 30, but that costs 50.",
"instance": "/account/12345/msgs/abc",
"balance": 30,
"accounts": ["/account/12345",
"/account/67890"]
}
The "balance" and "account" properties are arbitrary extensions specific to the example API. You are allowed to add your own extensions. This would allow you to add an extension property that contains a URL that points to the vehicle-owners resource.