Document how "errors" can be given an identifier and be reused in responses

[lanthaler]

Errors or possible statuses in general can be given an identifier that can then be directly reused in responses. According to RubenVerborgh this should be documented in the spec:

But doesn't really help anyway. Clients won't do anything with the description.

That might not be entirely true as you could give that specific status an identifier and then return it as is as response:

  {
    "@context": "http://www.w3.org/ns/hydra/context.jsonld",
    "@id": "http://example.com/api/errors/180984",
    "@type": "Status",
    "title": "Too Many Requests",
    "description": "A maximum of 500 requests per hour and user is allowed."
   }

I like that very much. So much that I would actually recommend in the spec that the status is given an identifier, that it's not just a blank node. That way, it can be annotated easily later on.

[lanthaler]

This is related to #27

[lanthaler]

PROPOSAL: Document it in the spec. With the new design proposed in ISSUE #27 it is much easier to describe.

[lanthaler]

Call for consensus: http://lists.w3.org/Archives/Public/public-hydra/2014Jul/0081.html

[lanthaler]

RESOLVED: Document in the specification how errors or (possible/potential) statuses in general can be given an identifier (a IRI) that can then be directly reused in responses. This allows clients to recognize particular states/errors and, in some cases, automatically recover.

[asbjornu]

How does this relate to application/problem+json? Wouldn't it be wise to at least use the same properties and perhaps reference it as the recommended format for all error responses in the API?

[dret]

for the record: problem reports now have RFC status: http://tools.ietf.org/html/rfc7807

[alien-mcl]

Would it be OK to start a separate issue related to application/problem+json and close this one that is already resolved?

[asbjornu]

I'd prefer if a new issue was opened before this one is closed, but otherwise that's fine by me.

[tpluscode]

This is "resolved" but I don't see it included in the spec. Hence we cannot close this issue.

For problem+json, please go ahead and create a new issue @asbjornu

[alien-mcl]

True - there is a section 5.3 of the spec that mentions hydra:Status, but it doesn't say anything about reusable identifiers. Unless the fragment below counts:

A server may also return a Status directly in a response. When doing so, it often makes sense to subclass the Status to make its semantics more explicit. Hydra defines just one such subclass, namely the Error class. This provides an extensible framework to communicate error details to a client.

Subclass would probably end up with a separate URL that could be reused and dereferenced