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

On 02/05/2014 02:01 PM, Ryan J. McDonough wrote:
>
> On Feb 5, 2014, at 4:51 AM, Thomas Hoppe <thomas.hoppe@n-fuse.de 
> <mailto: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.

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.

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

I also agree with the "happy path problem".
If we decide to make hydra capable of describing things like the Github 
example AND being able to describe multiple outcomes of an operation I 
think we need something like the concept of an 'outcome':

   "supportedOperations": [
     {
       "@type": "CreateResourceOperation",
       "title": "Creates a new comment",
       "method": "POST",
       "expects": "http://api.example.com/doc/#Comment",
       "outcome": [
         {
           "statusCode": 201,
           "returns": "http://api.example.com/doc/#Comment"
         },
         {
           "statusCode": 400,
           "returns": "http://www.w3.org/ns/hydra/core#Error",
           "title": "Bad Request",
           "description": "You've sent invalid JSON"
         }
       ]
     }
   ]

With this multiple outcomes (good and bad) could be defined and each has
a status code tied to returned type. For re-use it might also make sense
to reference a hydra:StatusCodeDescription.

Received on Thursday, 6 February 2014 10:25:51 UTC