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

On Feb 5, 2014, at 4:51 AM, Thomas Hoppe <thomas.hoppe@n-fuse.de> wrote:

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


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.

The other reason I’m digging my heels in on this one is that the “returns” property only covers the happy path. In reality, the returns value is only true in a specific condition and arguably the one most likely to occur. GitHub does a pretty good job of describing when you’ll get certain types of client errors in HTML [2] and we want the Hydra and JSON-LD equivalent. The disconnect for me is that returns and statusCodes suggest that you WILL get these values back rather than acting as a hint and explain under what conditions you might get this back. 

Ryan-

[1]: http://books.google.com/books?id=E2Ye_ZQfEl8C&pg=PA299&lpg=PA299&dq=facebook+600+response+codes&source=bl&ots=PET5YlC6Nw&sig=v1ScQAegTwn86Vm8-MQ_Au2HQEs&hl=en&sa=X&ei=vTPyUou8BIWMyAH02YHQDA&ved=0CDoQ6AEwAQ#v=onepage&q=facebook%20600%20response%20codes&f=false
[2]: http://developer.github.com/v3/#client-errors

+-----------------------------------------------+
    Ryan J. McDonough (a.k.a John Yaya)
    http://damnhandy.com
    http://twitter.com/damnhandy