Re: Interesting discussion on Twitter

2016-04-28 19:22 GMT+02:00 Darrel Miller <darrel@tavis.ca>:

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

When in doubt, be honoured, I'd say! ;-)

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

I think that's a very important perspective and one I have myself as
well. I've been involved in standardization work for years, but I am
first and foremost a practician and a developer by trade.

> Perhaps I got it all wrong.

Perhaps. We'll see. :-)

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

I think you have a skewed perspective on the relationship between HTML
and RDF. I think it all might make more sense if you separate the
semantics in HTML from the "application" of HTML. Please allow me to
elaborate.

The semantics of HTML, i.e. the meaning of <a>, <h1>, etc., is
approximately equivalent to the semantics conveyed by RDF. In Hydra,
the semantics are conveyed through JSON-LD, which is a
JSON-serialization of RDF. While HTML is a centralized vocabulary, RDF
is the underpinning of a decentralized one.

The "application" of HTML, i.e. what a client is supposed to do with
the interpreted HTML, is more or less equal to Hydra. In HTML you have
hypermedia controls like <a>, <img>, <form>, etc., while in Hydra you
have "property" and "operation" that are comparable.

What should normally drive an HTML application is an end user through
a browser. What should normally drive a Hydra application is an end
user through a Hydra "browser". While the web browser is a very mature
and feature-rich user agent and there currently doesn't exist Hydra
clients that are anywhere near that level of sophistication, the basic
idea still holds:

As it is possible to create a generic HTML browser, able to browse any
web page on the Internet, it should be possible to create a generic
Hydra browser, able to browse any Hydra-powered API on the Internet.

> 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 =””/>

Yep. That's a good analogy.

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

Yep. Replace "stylesheet" with any property defined in RDF, and all of
the above accurately applies to Hydra.

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

Yes, that's the same as with HTML. To create a usable HTML client
today, you need to implement at least all of the HTML5 vocabulary.

> Clients generally follow a must ignore policy on content they don’t understand.

Yes, that's the big advantage of JSON and REST over XML, XSD, WSDL and
SOAP, which had a "Must Understand" policy.

> URLs are no different than strings and numbers in this regard for me.

In essence, they aren't different, either. URLs can be dereferenced,
which is a nice self-documenting aspect of it, but otherwise, it's
just a (unique) string.

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

To be accurate, it's actually JSON-LD that does this through its
definition of the "@id" type, but yes.

> I tend to avoid trying to do things with links I don’t have any understanding
> of.

Sounds reasonable! :)

> If I want a client to handle links generically then usually polymorphism can
> be applied to achieve this.

Yes, that's one approach, but basically you would need the client to
be able to convey the meaning of the link to the end user. A dumb
client could just present the schema.org description of the term and
have the user decipher it and figure out which link to follow.

But since schema.org and most ontologies have defined properties with
data types for each term, much more intelligence can be built into the
client based on the knowledge of these terms.

What's powerful about this is that the terms are globally
standardized, stable and can occur in any thinkable combination. So
any time a client finds the term "http://schema.org/AboutPage", it
knows that it is a "Web page type: About page." that may have
properties such as:

- breadcrumb (A set of links that can help a user understand and
navigate a website hierarchy)
- lastReviewed (Date on which the content on this web page was last
reviewed for accuracy and/or completeness)
- mainContentOfPage (Indicates if this web page element is the main
subject of the page)

It also knows the data type of each property and can thus present the
property with an appropriate GUI control, such as a date picker or
calendar for "lastReviewed".

> I accept that this prevents me from writing a JSON-LD hypermedia crawler.

Google does that quite fine already. What we're mostly interested in
is building incredibly smart and flexible clients without reinventing
the wheel every time. :-)

> However, consider the fact that web crawlers only work because they
> understand the semantics of how HTML defines an anchor tag.

Exactly. It's precisely the same as with JSON-LD and Hydra.

> I think a limited amount of inline metadata can be useful for helping
> clients create HTTP requests.

Agreed.

> For example, I think URI Templates are very useful.

Absolutely.

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

With Hydra, you can do both. You can have inline hypermedia controls,
and/or link to an external ApiDocumentation. Both can be as dynamic or
static as you want.

> Adding inline interaction metadata to every affordance seems wasteful
> and redundant to me.

Since it's impossible to prescribe the perfect balance between inline
and referenced hypermedia controls, Hydra gives you the possibility to
use both. Inline controls might make more sense if they are very
volatile, i.e. vary by every request based on factors such as
authentication or application state.

> One exception that comes to mind is Collection+Json.  Having an
> embedded template for creating new items to the list is a reasonable
> compromise.

Yes, but it's not very flexible. As mentioned, in Hydra, you can do
this and much more.

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

I think that's a concern you share with everyone in the Hydra CG. :-)

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

I think you put more into "class" than what it means in RDF and Hydra.
Either way, no matter how you build your API, you need the client to
understand a predefined set of server-provided "structures" (classes,
types, objects; what have you), represented through a predefined set
of MIME types.

Without Hydra, JSON-LD and RDF, a lot of developers base this on stuff
like JSON Schema, API Blueprint, Swagger, or similar. In Hydra, you
instead have more loosely coupled RDF terms that can (but don't have
to) be grouped into predefined types that are comparable to those
defined by JSON Schema, but are much more flexible in nature.

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

Like with religious scripture, I think it's important to understand
and read quotes in context and figure out the underlying meaning
behind the uttered words. Fielding goes into a bit detail[1] by
writing:

> The only types that are significant to a client are the current representation’s
> media type and standardized relation names.

To explore this further, I think Mike Amundsen explains it succinctly[1]:

> there is no requirement in Fielding's description that clients act w/o
> understanding _content_. the point is that clients should be able to act w/o
> sharing knowledge of server-side internal coding details.

So, what seems to be okay, is to agree on MIME types and generic
descriptions of semantics and hypermedia controls within the resource
representations. I think this sounds like an exact description of how
Hydra works, to be honest. :-)

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

It's an abstraction over which HTTP method to use, which URI to
perform the request on and a way to define a template (like an HTML
form) for the expected input. This abstraction makes the client
independent on which HTTP method and URI the operation uses, which
gives the server quite a bit of flexibility to redefine its operations
without breaking the client.

> 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 think you may have misinterpreted a few details, but overall and as
far as I can understand, it seems like you're very much in agreement
with Hydra's core principles.

> I’m going to keep experimenting and I am sure you folks will too.

You bet! :-)

> I’m glad you persisted to get me to justify my statements.

I'm glad you took the time to write them down!

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

Definitely!

[1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
[2] https://groups.google.com/forum/#!topic/hypermedia-web/xdcyaUAMPt0

-- 
Asbjørn Ulsberg           -=|=-        asbjorn@ulsberg.no
«He's a loathsome offensive brute, yet I can't look away»

Received on Thursday, 28 April 2016 21:10:26 UTC