RE: StatusCodeDescription vs. Status (ISSUE-32)

On Monday, March 03, 2014 10:02 PM, Thomas Hoppe wrote:
> >>> 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.
> > Cool! I've created ISSUE-39 to keep track of this:
> >
> >    https://github.com/HydraCG/Specifications/issues/39
> >
> 
> I think this matches what we discussed in [1] already in the context of
> API documentation.

Yeah, you are right Thomas. Sorry for not recognizing that back then. On the
other hand, it's always good to reach the same point from different starting
points.


> The tenor was to "combining returns with the Status description" and I
> specifically stressed the fact that we can re-use such status code
> descriptions.
> 
> [1] http://lists.w3.org/Archives/Public/public-hydra/2014Feb/0102.html

I'm still a bit on the fence whether "returns" on a "Status" makes much
sense. For errors, it doesn't really as we could simply return the Status
itself:

  {
    "@id": "/errors/234890",
    "title": "Too many requests",
    "description": "The max. number of 10 requests/s has been exceeded."
  }

For the normal outcome, "returns" may be helpful but it looks a bit weird to
wrap that in a Status:

  {
    ...,
    "possibleStatus": {
      "title": "Comment successfully created",
      "returns": "Comment"
    }
  }

... but maybe I'm the only one finding that a bit strange!?


--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 4 March 2014 15:25:44 UTC