Should hydra:returns and hydra:statusCodes be removed to avoid tight coupling?

[lanthaler]

There are concerns that hydra:returns and hydra:statusCodes promote tight coupling and automatic code generation. An option to avoid that, would be to simply remove them. The disadvantage of doing so would be that it becomes impossible to generate human-readable documentations similar to the ones of current Web APIs.

On Tuesday, February 04, 2014 2:11 AM, Ryan J. McDonough wrote:

On Feb 3, 2014, at 3:19 PM, Markus Lanthaler wrote:

I think the biggest problem is how this stuff is documented and the fact
that people won't read it :-) It's not a contract. It's a hint. Clients have
to interpret the response in any case. Some will be more tolerant, some will
break when they don't get back what they expected. That's similar to how
people often run into troubles when parts of a website get redesigned and
"nothing works anymore" because it looks different or they have to take
different paths.

What I was trying to get at with the profile link header is that if the data
model is expressed up front and there’s sufficient documentation about what
the types mean, a client can create a number of handlers that could react to
different responses. If the model is good enough, the client could react
better to responses that they didn’t expect at build time.

Some developers will read documentation and create code generators that the
illiterate ones will use. It is here that I feel Hydra will get into trouble.

I have troubles extracting something actionable from your mails. Would
removing returns/statusCodes address your concerns?

Absolutely!

If so, what does it really change?

It'll force developers to look at at what’s coming back in the response
headers rather than what’s defined in the Hyrda description. One is a hint and
the other is fact (i.e. what the server is sending back). By removing returns
and status, you are now forcing developers to look in the right place: the
HTTP response headers.

I have development teams messing things up on a fairly frequent basic with
WADL and Swagger (seeing a pattern here? :) ) due to the fact that they are
expecting the server to return exactly what is specified in the descriptor and
not taking into account they may have to deal with both a forward and reverse
proxy in the mix.

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?

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.

IMO it will be just a matter of time till someone else mints
a URL for these things in order to, again, be able to transform a Hydra
description into a nicely formatted HTML documentation.

Sure, and that’s fine. AAA principle working at it’s finest! At least no one
can point to Hydra Core and blame it for suggesting fixed response types :)

[RubenVerborgh]

You can never stop automated code generation. I think Hydra's goal should be to make (dynamic) API consumption as easy as possible. There seem several legitimate uses for status code info.
If it is used for code generation, there's nothing we can or need to do.

[lanthaler]

PROPOSAL: Keep them as they are important for a number of use cases but make it clearer that they should be interpreted at runtime.

[asbjornu]

Related to #88.

[alien-mcl]

Closed with PR #175