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

+1

-----Original Message-----
From: Dietrich Schulten [mailto:ds@escalon.de] 
Sent: woensdag 23 september 2015 20:45
To: public-hydra@w3.org
Subject: Re: Replace hydra:Error with application/problem+json

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

Received on Thursday, 24 September 2015 17:09:54 UTC