Re: Replace hydra:Error with application/problem+json

Yes, this is what I have in mind. But I think we should go even futher; use the exact same naming as in application/problem+json as well, since people reading these responses are much more likely to have seen application/problem+json responses before than responses decorated with Hydra. I think we should even rename hydra:Error to hydra:Problem to make the relationship explicit and unambiguous. That is: A hydra:Problem *is* application/problem+json and there should be no doubt about it, even though those reading the JSON on the wire have never heard about Hydra before.



-- 

Asbjørn Ulsberg          -=|=-         asbjorn@ulsberg.no

«He's a loathsome offensive brute, yet I can't look away»

On Wed, Sep 23, 2015 at 8:44 PM, Dietrich Schulten <ds@escalon.de> wrote:

> In my very first posting to the list I asked for a similar thing.
> Essentially I asked to adopt the problem+json attribute semantics into
> Hydra. I think the discussion is still open.
> Back then Markus answered [1]: "What would we need to redefine to
> achieve that? Please also have a look at
> ISSUE-27 [2] and ISSUE-39 [3]."
> [1] https://lists.w3.org/Archives/Public/public-hydra/2014Oct/0065.html
> Markus also noted that one could easily contextualize the json
> attributes of problem+json and map them to Hydra, saying that 'status'
> is hydra:statusCode, 'title' is hydra:title, 'detail' is
> hydra:description and 'instance' could be @id. Still lacks 'type', which
> also has valuable semantics.
> The advantage of adopting problem+json would be that problem+json is
> richer and more precise, and if things work out well, more widely
> understood. It makes a clear distinction what does and does not belong
> into the response, and what exactly the error response is for.
> As it stands now, hydra:Error does not come with such a clarification.
> People might be tempted to define new status codes just for their API or
> redefine existing ones, which I would consider an abuse.
> Proposal:
> - define all problem+json attributes in Hydra (i.e. add 'type')
> - publish a json-ld context 'problem.jsonld' which maps problem+json
> attributes to Hydra
> - say in the spec that the semantics of the hydra attributes is an exact
> match to the problem+json attributes and that hydra:Error should be used
> to explain possible solutions, not to overload existing or define
> API-specific status codes
> - explain the use of the problem.jsonld context
> If we would adopt the problem+json semantics into hydra by publishing a
> problem.jsonld error context file, one could respond:
> HTTP/1.1 403 Forbidden
> Content-Type: application/problem+json
> Link: <http://www.w3.org/ns/hydra/contexts/problem.jsonld>;
> rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"
> Content-Language: en
> {
> "type": "http://example.com/probs/out-of-credit",
> "title": "You do not have enough credit.",
> "status": 403,
> "detail": "Your current balance is 30, but that costs 50.",
> "instance": "http://example.net/account/12345/msgs/abc"
> }
> Where http://www.w3.org/ns/hydra/core/problem.jsonld dereferences to our
> published error context file:
> @context": {
> "@vocab" : "http://www.w3.org/ns/hydra/core#",
> "type": "errorType" <-- yet to be defined in Hydra,
> "status": "statusCode",
> "detail": "description",
> "instance": "@id" <-- see ISSUE-27/ISSUE-39
> }
> If an api decides to use custom attributes:
> HTTP/1.1 403 Forbidden
> Content-Type: application/problem+json
> Link: <http://api.example.com/example.problem.jsonld>;
>   rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"
> Content-Language: en
> {
>   "type": "http://example.com/probs/out-of-credit",
>   "title": "You do not have enough credit.",
>   "status": 403,
>   "detail": "Your current balance is 30, but that costs 50.",
>   "instance": "http://example.net/account/12345/msgs/abc",
>   "balance": 30,
>   "accounts": ["http://example.net/account/12345",
>                "http://example.net/account/67890"]
> }
> Where http://api.example.com/example.problem.jsonld dereferences to:
> "@context": [
>     "http://www.w3.org/ns/hydra/contexts/problem.jsonld",
>     {
>       "balance" : "http://api.example.com#balance",
>       "accounts" : "http://api.example.com#accounts"
>     }
>   ],
> Both Hydra and non-Hydra clients could work with that. We would be good
> web citizens if we promoted the use of commonly understand semantics.
> Am 23.09.2015 um 08:56 schrieb Thomas Hoppe:
>> Hi,
>> 
>> nice idea but in the same way you could argue we should use JSON
>> JSON-Home [1] as API-Documntation (hydra:ApiDocumentation).
> If it happened to fit, why not? I want to make my API understandable by
> many clients.
> One might also argue, the fewer attributes hydra defines and the more
> well-established semantics from the "world of the uniform interface" it
> adopts, the better.
> E.g. why have hydra:nextPage if there is an IANA rel next
> (urn:iana:link-relations:next)?
> Best regards,
> Dietrich