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

On Wednesday, February 05, 2014 4:13 AM, Ryan J. McDonough wrote:
> On Feb 4, 2014, at 10:39 AM, Markus Lanthaler wrote:
> 
> > OK, this is the second thread. This one is trying to find an answer
> > to the following question:
> >
> >  "Should hydra:returns and hydra:statusCodes be removed to avoid
> >  tight coupling?" - ISSUE-32
> >
> 
> Yes.

OK, great. That's now something very concrete we can work on.


> > 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"?
> 
> Ah, so it seems we have constraints and consequences but not so much
> return types? This is really interesting but I still don't think
> returns is the right solution for something like this. Perfect example

We should try to clearly separate "returns" and "statusCodes" and the two
place where they might occur: an Operation or an ApiDocumentation. The
question here was about "statusCodes". Do they add value? Is it enough if
they are described on the API level (similar to how we describe the
supported classes there)? Or do they introduce too much coupling?

Adding Thomas' reply:

<snip>
  On Wednesday, February 05, 2014 10:52 AM, Thomas Hoppe wrote:
  > 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.
</snip>

as it summarizes it quite nicely. After the discussions, I'm personally not
so sure anymore whether we really need this stuff for operations but, just
as Thomas, I think they do provide some value at the API level. I also see
the potential misuse that you are probably concerned about. Furthermore, I
agree with Thomas that they do not provide that much value at runtime as, at
least currently, they do not carry any additional machine-readable
information. We just enumerate some of the possible status codes and
describe when they might occur in natural language. As such, I think it
would indeed be another candidate to be moved to a separate "documentation"
vocabulary.



> of this is the Yahoo YQL service and it's service limits:
> 
> http://developer.yahoo.com/yql/
> 
> Being able to express these limits in Hydra would be incredibly
> powerful. But this is a great use case and we should gather more of
> these as they'll help drive requirements. What do you think about
> capturing these in the GitHub Issues?

We should definitely do that. Feel free to add as many issues as you want
(this applies to everyone in the group) but please inform the group that you
did so that we can keep most of the discussions on the list. Ryan, could you
add these?


[...]

> > OK. As you know, there are many vocabularies out there. For ecommerce,
e.g.,
> > there are Schema.org and GoodRelations. Now I think it is necessary to
> > somehow document what kind of types the client should be prepared to
handle.
> > Similar to how you would need to ensure that your client understands the
set
> > of media types used in a specific API. This doesn't have to be described
at
> > the operation level though. We have "supportedClasses" on
"ApiDocumentation"
> > and could leverage that instead.
> >
> > What do you think about that? Do you find that equally problematic? If
so,
> > where would you start if you were to program a client? Would you crawl
the
> > API? By trial and error?
> 
> I actually quite like that. It goes inline with my suggestion of using
> Link headers with the profile relation in order to determine what is in
> the JSON-LD response. But in order to react to that, I'd need to know
> something about the API's capabilities first. Personally, I'd be
> looking for ApiDocumentation first and see what data models it
> references and what classes it supports. What you describe works for
> me.

Exactly. Without such an enumeration you would be left alone and it would be
very difficult to prepare your client for the API. It may still fail at
times because it finds a class it doesn't understand but at least you have
something to get started.


[...]

> > OK, that's a start. What about statusCodes at the ApiDocumentation
> > level? Would you remove them as well?
> 
> I would, yes.

OK so, going back to our previous example, how would you prepare your client
to the fact that a quota limit violation is signaled with a "402 Payment
Required" instead of a "429 Too Many Requests"?

Would you just wait till that happens and debug it then? This might be
tricky as it may take a long time for this to occur.


> > I don't know how much you are into Semantic Web stuff in general,
> 
> A fair amount. I did quite a bit in my time at Nokia, but it's been a
> while so I'm a little rusty now.
> 
> > but how do
> > you feel about rdfs:range in this context? In a sense it is very
> > close to hydra:returns
> >
> >  :discussesWith rdf:type hydra:Link ;
> >                 rdfs:range schema:Person .
> >
> >  </people/markus> rdf:type schema:Person ;
> >                   :discussesWith </people/ryan> .
> 
> Oooh, interesting!
> 
> My mental model starts to go into the whole identity vs. location
> debate and I now see where Kingsley was going by requesting Turtle :) I
> guess the thing that changes for me is that I've never considered
> rdfs:range in the context of HTTP responses. In past, I've had to deal
> with URIs that were either URNs, tel URIs, and other non-HTTP URIs and
> never considered how the protocol reacts to dereferencing these URIs.
> In the tel: case, I didn't want inadvertently call people :)

:-)


> With JSON-LD, ids should be dereferenceable HTTP URIs. Now we're not
> only dealing with what the information means, but also how it reacts to
> being dereferenced via the protocol that URI specifies. I guess the
> biggest difference for me is that rdfs:range doesn't assert that the
> relationship is conditional based on a successful HTTP request. It
> qualifies the relationship, but it doesn't make any assumptions about
> the HTTP request. The Hydra spec currently states that hyrdra:returns
> represents "The information returned by the Web API on success." I
> guess that's the fundamental difference.

Interesting point of view. Will have to think a bit more about this myself. 


[...]

> >> It could also be the wording. If this is just a hint, then perhaps
> >> instead of hydra:returns, which sounds a bit more committed than say
> >> perhaps something more like hyrdra:intimation or perhaps even
> >> hydra:anticipatedResponseType?
> >
> > Well, naming is one of those two difficult things in computer science
:-) I
> > don't think it would change much if we would change its name. Perhaps
the
> > stronger signal would be sent by moving this to a separate vocabulary
which
> > adds a couple of other things to facilitate the generation of
> > natural-language documentations.
> 
> IANACS? Can that be a thing?
> 
> Anyway, I actually do think it could change things. With JSON, you're
> typically not dealing with computer sciencey types form the get go.
> JSON-LD has been a great tool to bridge the gap between those who are
> more comfortable working with structs and tree structures and those who
> grok the RDF stuff. Terms like "returns" is one to one with "returns"
> in most programming languages. Developers who skim the docs, will look
> for familiar things and may make assumptions as to it's function. A
> term like intimation, or even rdfs:range, likely wouldn't suggest that
> this is a hard return type. Just a thought.

Hmmm... The thing I'm still struggling with is how much "familiar" stuff we
can take away from average developers without losing them completely. The
question "what will I get back if I do that" isn't that far-fetched. The
typical approach is to invoke an operation, check the response, if it is
what was expected proceed, otherwise try to recover or fail. Now we don't
tell them anymore what to expect, at least not explicitly. But probably this
also depends a lot on how the tooling is designed.


> >> I'm still not sold on status codes. For the most part, everyone is
> >> going to expect something in the 200 range. There's too many
> >> exceptional codes to deal with in a format like Hydra to be practical.
> >
> > Right, there are many. Maybe its again about finding a compromise. I
don't
> > think we would lose much by expressing these things just at the API
level
> > instead of doing so at the operation level. Of course also this could be
> > moved out of the core vocabulary into a "documentation" vocabulary.
> 
> That sounds reasonable. I mean I get that in some places, you want to
> be able to indicate that when you do "X", you're going to get a 202
> rather than the usual 200, and that's to be expected because this
> operations take longer than you're willing to wait. The way statusCodes
> feels like it suggest that these are the only things you'd have to
> contend with.

By "in some places", do you mean operations? This confuses me a bit as till
now you were saying that it's not needed anywhere. Not even at the API
level. Or are you suggesting in the paragraph above that it is just the
wrong terminology that we are using?


> > I feel we already made quite some progress on these recent
> > discussions and have some concrete options to evaluate:
> >
> >  - remove "returns" from "Operation"?
> >  - remove "statusCodes" from "Operation"?
> >  - remove "statusCodes" from "ApiDocumentation"?
> >  - move all of them to a separate "documentation generation"
> >    vocabulary?
> 
> That'd work.

OK, so maybe just moving them to a separate vocabulary does the trick. But
perhaps we should also use that opportunity to rename them if we find
something short and concise that makes it clear that these are just hints.


> > We should also discuss whether "supportedClasses" on "ApiDocumentation"
> > is enough or perhaps too much :-)
> 
> I do like that quite a bit actually and I don't think that's too much.

Great


> Also, we should capture the use case you mentioned earlier on somewhere
> on the issues list.

You mean the quota limit one? Could you please file an issue. Thanks!



--
Markus Lanthaler
@markuslanthaler

Received on Wednesday, 5 February 2014 22:45:09 UTC