Re: ISSUE-32: Should hydra:returns and hydra:statusCodes be removed to avoid tight coupling?

>> But this is exactly the type of thing I want to avoid by excluding returns and statusCodes. There’s a big difference from including a response body that details why you got a 400 (Bad Request) vs. redefining what 400 means. An HTTP 400 response is already well defined but it’s up to the response body to explain why you got this. Your vocabulary should be capable of describing the reason for thing, not redefining the semantics of 400. Even worse, we have people inventing their own status codes like Facebook used to their old API [1]. This is clearly something that would have been better handled with a 400 response code and a response body detailing what went wrong.
> 
> I 100% agree with you, I just meant this is what people did and maybe will do in the future.
> The question is whether we want to be able to describe this in a vocab for offline documentation.

Note that this discussion might also be the result of terminology,
as I remarked in the thread that concerns renaming of statusCode and statusCodes [1][2].

What we currently call a hydra:StatusCodeDescription is conceptually a hydra:Status:

    {
      "@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."
    }

So all this says is: there exists a status in which the user has exceeded the 500 requests/hour limit.
You could additionally say that this Status will be associated with the code 429:

      "statusCode": 429,

This statusCode bit might be unnecessary; this is just HTTP semantics.
But I think the bit of describing a Status is interesting.
Saying what could happen, regardless of protocol semantics. That seems reasonable to do.

So let's not throw out the baby with the bath water;
it's not because we don't want to explain HTTP status codes
that we don't want to explain possible statuses resources can be in.

Best,

Ruben

[1] http://lists.w3.org/Archives/Public/public-hydra/2014Feb/0061.html
[2] https://github.com/HydraCG/Specifications/issues/27

Received on Thursday, 6 February 2014 13:20:19 UTC