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