Re: Interesting discussion on Twitter

Hey folks,

I’m not sure whether to feel browbeaten into defending my position, or honoured that you care what I think. 😊

Disclaimer
--------------
Let me preface my response with a clarification that I am making statements about Hydra from a place of ignorance.  I have a basic understanding of JSON-LD, but it has taken me quite a while to get to that position despite having an above average tolerance for spec reading!

As developers we are pulled in many different directions, so we sometimes don’t have the luxury of spending the necessary time to get an in-depth understanding of a tech before making a judgement call on whether to adopt or not.  We learn to decide based largely on past experience, first impressions and gut feel.

Perhaps I got it all wrong.

Different Perspectives
------------------------------
My initial reading of the Hydra core vocabulary indicates a different perspective on how link semantics are conveyed.  For example,

In HTML this usually means that all links in anchor elements (the <a> tag) are followed but, e.g., most references in link elements (the <link> tag), such as used in the example above, are ignored. Since in RDF serializations no such distinction exists, the best a client can do is to blindly try to dereference all URIs.

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.

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.  

My approach requires a client to at least recognize a Term before it can process it.  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.  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.   I accept that this prevents me from writing a JSON-LD hypermedia crawler.  However, consider the fact that web crawlers only work because they understand the semantics of how HTML defines an anchor tag.


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.


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

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

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.