- From: Asbjørn Ulsberg <asbjorn@ulsberg.no>
- Date: Thu, 28 Apr 2016 23:09:56 +0200
- To: Darrel Miller <darrel@tavis.ca>
- Cc: "public-hydra@w3.org" <public-hydra@w3.org>
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