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

I agree with Asbjørn, specially concerning those reading the response on
the wire.

2015-09-25 4:47 GMT-03:00 Asbjørn Ulsberg <asbjornu@gmail.com>:

> 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
>>
>>
>>
>


-- 
Carlos Eduardo Melo