RE: StatusCodeDescription vs. Status (ISSUE-32)

On Monday, February 10, 2014 11:38 AM, Ruben Verborgh wrote:
> >  - move "returns" to "Status" (aka StatusCodeDescription)
> >  - rename "statusCodes" to possibleOutcome/possibleStatus
> >    (still allowing it on both ApiDocumentation *and* Operation)
> >
> > I think I like the idea of combining returns with the Status
description;
> > even though it results in more deeply nested structures. The problem I
have
> > with this (terminology) is that overall it doesn't improve the situation
> > much. It still feels to much like a contract instead of highlighting the
> > fact that it is just a hint.
> 
> What makes you feel like that?
> `possibleStatus` very much feels like a hint to me.

Yeah, you are probably right. An shorter alternative could be "mayReturn"
but only if the "returns" is renamed as well (which I'd expect us to do
anyway if we move it into "Status", right?)


> Below my answers:
> 
> > 1) Do we need/want to describe what an operation returns?
> 
> If "returns" means what kind of document we get under normal operation
> (2xx), I'd say yes.

Just to make sure we are on the same: "returns" would be wrapped in a
"Status" and not be directly on the operation, right?


> > 2) Do we need/want to describe the exceptions that might happen?
> 
> Probably not strictly defined ones like 404 and some 5xx codes.
> We might want to define application-specific common exceptions.
> 
> > 3) What do we lose if we don't describe it?
> 
> Good one. For exceptions, we probably lose nothing.
> Exceptions are exceptions. They can happen anyway.
> 
> This one is unnecessary:
> 
> >          {
> > 	   "@id": "bad",
> > 	   "statusCode": 400,
> >            "returns": "http://www.w3.org/ns/hydra/core#Error",
> >            "title": "Bad Request",
> >            "description": "You've sent invalid JSON"
> >          }
> 
> This one might be interesting:
> 
> >    {
> >      "@context": "http://www.w3.org/ns/hydra/context.jsonld",
> >      "@type": "Status",
> >      "title": "Too Many Requests",
> >      "description": "A maximum of 500 requests per hour and user is
> allowed."
> >    }
> 
> 
> 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."
    }


> Better to just go ahead and make those 500 requests.
> Then interpret the error message.
> 
> > 4) What do we gain if we do?
> 
> Depends on the exception.
> The invalid JSON thing? Nothing. It's not like we'd be trying to send
> invalid JSON.
> 
> Rate limiting?
> Nothing really. it's not that we'd make fewer requests if we know we'll
> hit the limit.
> 
> > 5) If we describe it, does it belong in the core vocabulary?
> 
> 1: could be interesting.
> 2: no.

I assume you wrote this under the assumption that those 2 cases would be
expressed differently, right? So you have one property to describe the
*likely, normal result* (at the moment that would be "returns") and another
one to describe additional outcomes that occur only in specific scenarios
("possibleStatus").


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 3 March 2014 16:16:07 UTC