RE: Interesting discussion on Twitter

Hi Darrel,

On Thursday, April 28, 2016 7:23 PM, Darrel Miller wrote:
> Hey folks,
> 
> I’m not sure whether to feel browbeaten into defending my position, or
> honoured that you care what I think. 😊

Definitely the latter. I highly value your opinion and really appreciate it that you took the time to write your thoughts down and share them with us.


[...]

> In my world view, the HTML tag <a> is simply a different serialization
> of a link relation type.  The <a> tag is simply a shortcut for what
> could be,
> 
  > <link rel=”anchor” href =””/>
> 
> I’m not suggesting the above is valid HTML, but it could have been.

Right. Back in the days there were discussions whether <img> is needed along those lines.


> As is shown in the second example of the Hydra spec, links and their
> corresponding types can be represented as
> 
> {
>   "urn:iana:link-relations:stylesheet": { "@id": "http://www.example.com/styles.css" }
> }
> 
> A web browser knows how to process a “stylesheet” link because it
> understands the meaning of that specific link relation type. No
> special vocabulary is needed if you accept that clients need to
> understand the semantics of a Term in order to successfully process
> the document. If the semantics of a particular Term are understood by
> the client then the client will know that it identifies a link
> relation type and the term value is a dereferencable URL.

What Hydra tries to achieve here is to teach machines which properties are links and which aren't. Developers shouldn't need to hardcode into their implementations but it can be discovered at runtime instead.


> My approach requires a client to at least recognize a Term before it
> can process it.

It always depends on what you wanna achieve, right? A crawler certainly shouldn't be required to recognize the term (if by term you mean link relationship type by that). As JSON-LD/RDF isn't a markup language it isn't as straightforward to "mark links up", you either need to reify the links to all make them look similar or you describe which terms represent links.


> Clients generally follow a must ignore policy on
> content they don’t understand.  URLs are no different than strings and
> numbers in this regard for me.  As I understand it, Hydra is providing
> a way for clients to know that something is a link without knowing
> what kind of link it is.

Right. Just as HTML does in the form of the link or anchor tags.


> I tend to avoid trying to do things with
> links I don’t have any understanding of.  If I want a client to handle
> links generically then usually polymorphism can be applied to achieve
> this.

It's interesting that you mention polymorphism here because this is kind of what Hydra is doing.


[...]

> Inline Interaction Metadata
> -----------------------------------
> 
> I think a limited amount of inline metadata can be useful for helping
> clients create HTTP requests.  For example, I think URI Templates are
> very useful.  If there is significantly more metadata required then I
> tend to move that metadata out into its own resource as it tends to
> have a different lifetime than the data it is related to.  Adding
> inline interaction metadata to every affordance seems wasteful and
> redundant to me. One exception that comes to mind is Collection+Json.
> Having an embedded template for creating new items to the list is a
> reasonable compromise.

Hydra allows you to do both for exactly the reasons you mention. Have you seen the demo event API?

    http://bit.ly/hydra-console-event-api

You'll see there's no "inline metadata" (or a *very* limited amount thereof if you consider typings as metadata). The HydraConsole discovers all of this at runtime. For one-off operations, the exactly same vocabulary can be used to describe an ad-hoc operation.


> API Descriptions
> ---------------------
> 
> My comment about the risk of encouraging developers to build tightly
> coupled APIs is a concern that I have for all formats that are
> attempting to be API description languages.  The issues are nicely
> highlighted by this diagram http://www.hydra-
> cg.com/spec/latest/core/vocabulary.png

I struggle to understand how you can both be against inline controls/metadata and machine-readable API descriptions? What's the alternative? A only human-readable documentation? I can't see how that could possibly reduce coupling... apart from standardization in which case the coupling is considered to be fine because the coupling is not tied to a specific implementation. Unfortunately, I don't think standardization is even remotely possible at this level of abstraction.


> Terms like “expects”, “returns”, “statusCodes” just push developers
> away from self-descriptive interactions and towards building clients
> that make assumptions like -> when I dereference this identifier I
> will get this “class” of data back.  The existence of “class” is
> encouraging developers to violate Fielding’s guidance that  “A REST
> API should never have “typed” resources that are significant to the
> client”.

I think the "typed" in that quote refers to types coming directly from the backend. That is, they leak implementation details. But anyway, Hydra uses classes as request templates or forms.


>  The “Create”, “Replace” and “Delete” operations redefine the
> uniform interface from the perspective of the client developer.  I
> don’t understand why those would be needed.

We actually decided to get rid of them quite a while ago :-)

  https://github.com/HydraCG/Specifications/issues/11



> Summary
> -----------
> 
> I think it is only natural that different people approach things in
> different ways and to a large extent that is very healthy.  It may be
> that my approach is fundamentally flawed, or Hydra’s is, or that there
> are some scenarios that are more suited to one approach vs the other
> and the two perspectives are complimentary.  I don’t know.  I’m going
> to keep experimenting and I am sure you folks will too.  I’m glad you
> persisted to get me to justify my statements.  The more I explore the
> subject the better I understand the pros and cons and maybe the more
> we understand of each other’s point of view, the closer our solutions
> will get.

Yep, I agree. We are all still trying to figure out the right trade-offs and find the right approach. I also don't see it as one vs. the other. I think we should try to learn us much as possible from each other and I personally at learn the most from people that disagree with me :-) So, thanks again very much that you took the time to write down your thoughts Darrel. I really appreciate it. I owe you a drink next time we meet in person :-)


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 3 May 2016 20:22:23 UTC