Re: Interesting discussion on Twitter

Hi Darrel

Thanks for sharing your thoughs on the topic. While I’ll try to deliberate more in next days, let me just argume a bit on one thing you touched.

>Terms like “expects”, “returns”, “statusCodes” just push developers away from 
>self-descriptive interactions
While I agree on that, I believe an entry point level API description might provide additional “precomputational” value.
I’m a developer myself and in general, I’d prefer to execute some logic in advance rather than to be “surprised” in the middle.

> and towards building clients that make assumptions like -> when I dereference 
>this identifier I will get this “class” of data back. 
I think that the notion of the “class” is misused here – I acknowledge it just as a part of the description.
Knowing that this is a class in RDF terms I know I can dereference it hoping to get it’s description. This and only this.

>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’d also add that Fielding writes also about server’s implementation details that shouldn’t be exposed to the client and the only thing the client should care about is the representation’s media type and relations.
First of all, no one said that given “class” is actually a structure used by the server – It may be that way, but it’s not mandatory. Again, “class” here is almost like saying “JPEG” – it has it’s internal structure defined with data structures and all. In parallel, person class has its structure also described, just a different way the JPEG has it.

The other thing with media types is just the one I feel uneasy about. Following that we would need to inform a client that what he actually received is i.e. :
application/person+ld+json or application/article+ld+json or ... and we’ve just ended up with dozen of custom media types just only to fulfill that requirements. While indeed there is a discussion on whether the media type for hydra driven payloads should be standard RDF media type with content profile pointing to Hydra or should it use a dedicated media type, but I believe this dozen of media types that would be required just to describe a given domain won’t work.

>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.
Well, these would be just shortcuts defining standard HTTP operations in Hydra way.

I hope to write more soon

Best

Karol

From: Darrel Miller 
Sent: Thursday, April 28, 2016 7:22 PM
To: public-hydra@w3.org 
Subject: 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.