Re: StatusCodeDescription vs. Status (ISSUE-32)

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

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.

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

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.

Best,

Ruben

Received on Monday, 10 February 2014 10:38:22 UTC