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

On 02/05/2014 04:13 AM, Ryan J. McDonough wrote:
>> On Tuesday, February 04, 2014 2:11 AM, Ryan J. McDonough wrote:
>>> On Feb 3, 2014, at 3:19 PM, Markus Lanthaler wrote:
>>>> On Friday, January 31, 2014 4:50 PM, Ryan J. McDonough wrote:
>> [...]
>>> Look at some of the comments on the old Facebook API. You have people
>>> whining because they expected a 200 (Ok) and get an image but instead
>>> they got a 303 or 302 instead and they're all perplexed. A good number
>>> of devs will take the documentation as fact rather than look at what's
>>> coming back in the response. Intermediaries on the other hand will
>>> never look at your documentation and will always look at the headers
>>> and message body. Some would argue that the client is also an
>>> intermediary.
>> Hmm.. that's a very good point. So in your opinion no additional information
>> about the returned status codes is necessary? Not even at the API level? For
>> example, to make it clear that if the quota limit is hit a "402 Payment
>> Required" is returned instead of a "429 Too Many Requests”?
I think if hydra is supposed to serve as a vocab for documenting and 
defining APIs at run time
then it is essential to have the possibility to specify HTTP status 
codes along with a textual description
(think about the doc generator use case already discussed on the list).
Rationale: The meaning of HTTP status codes is commonly narrowed or 
redefined in
today's APIs -- which I consider natural due to the weak semantics they 
offer.
Also it allows to provide an overview which of the variety of codes are 
used.
Maybe the idea of splitting the aspects documentation and run-time 
description is the way to go.

I think the 'returns' is a complete analogon to returns so the same 
solution should be applied.

Received on Wednesday, 5 February 2014 09:52:13 UTC