W3C home > Mailing lists > Public > public-hydra@w3.org > July 2014

Re: Specifying operations for instances

From: Alexandr Krylovskiy <alexandr.krylovskiy@gmail.com>
Date: Thu, 10 Jul 2014 12:00:44 +0200
Cc: public-hydra@w3.org, Markus Lanthaler <markus.lanthaler@gmx.net>
Message-Id: <71A5E1EC-94F3-4DFE-940D-4410A9F25B69@gmail.com>
To: Chris Chapman <chris@pentandra.com>
You can count another confused developer here. 
Although my intentions to use Hydra are broader than just implementing a specific API, this is where I started to learn it, and so far I ended up with mostly the same questions raised here.

After reading this thread, I finally get what “ApiDocumentation” in Hydra means. But it was **very** confusing before I did, and I don’t think that mentioning in the spec that “ApiDocumentation can be dynamic” would have clarified it for me. I still see a fundamental difference between the api “documentation” and its “specification" that Hydra provides (dynamically) at runtime.

When I started, I thought that the “ApiDocumentation” is there just to document the api, which can be then used to generate a human-readable documentation (if at all needed), or to be used to explore the API with a tool like Hydra Console. It had never occurred to me that “ApiDocumentation” is actually supposed to be used to describe the api *specification* to be used by the Hydra client. 

I think distinguishing between the API *documentation* and its *specification* will simplify and streamline Hydra concepts for me and facilitate their understanding.
Also see several other comments inline.

On 09 Jul 2014, at 21:47, Chris Chapman <chris@pentandra.com> wrote:

> ----- Original Message -----
>> From: "Markus Lanthaler" <markus.lanthaler@gmx.net>
>> To: public-hydra@w3.org
>> Sent: Wednesday, July 9, 2014 12:52:05 PM
>> Subject: RE: Specifying operations for instances
>> On 9 Jul 2014 at 20:22, McBennett, Pat wrote:
>>> Markus Lanthaler wrote on July 09, 2014 5:48 PM:
>>>> On 8 Jul 2014 at 13:35, Tomasz Pluskiewicz wrote:
>>>>> On Tue, Jul 8, 2014 at 1:16 PM, McBennett, Pat wrote:
>>>>>> Markus Lanthaler wrote on July 07, 2014 6:51 PM:
>>>>>>> This can be addressed by serving different API documentations to
>>>>>>> different users.
>>>>>> Wow - this sentence was a huge light-bulb moment for me :) ! I simply
>>>>>> never thought of the API documentation in that way, and checking the
>>>>>> Hydra specification again, I can't find any direct explicit
>>>>>> references to such an interpretation.
>>>> We could certainly add a statement mentioning this.
>>> 'Could'? I think this is essential, especially as both myself and Tomasz
>>> took
>>> so long to realize it, and in fact I think it really captures a fundamental
>>> difference
>>> between a genuinely RESTful API and a 'traditional' API (and does so very
>>> succinctly!).
>> OK. I've added a comment to ISSUE-59 so that we don't forget it
>>>>>> So it leads me to think that simply calling this the 'API
>>>>>> Documentation' is in fact a very misleading misnomer, given the
>>>>>> automatic association any experienced developer (like me) will have
>>>>>> between an API and some static description (in fact, in my mind 'API'
>>>>>> almost seems to *mandate* a large degree of static-ness!).
>>>> API isn't the best term but unfortunately that's the term most people use
>>>> for
>>>> these "service interfaces".
>>> But my point is that API is the term most people use to describe something
>>> *completely
>>> different* - i.e. they use that term to describe 'traditional' APIs that
>>> have always (without
>>> exception) been 'static' by their very nature (until the next version comes
>>> along of course -
>>> i.e. DLL-hell!).
>> I think Web APIs and Hypermedia APIs are two well established terms by now
>> even though API by itself means something entirely different. I'm not
>> convinced that it makes a lot of sense to use introduce a different term. I
>> think it makes more sense to describe the difference (as you did above) in a
>> couple sentences in the spec.
>>>> On the other, it isn't the case that the interface
>>>> changes all the time. It is *quite* static in most cases but a user
>>>> might not have access to everything.
>>> Very true, but isn't the '*quite* static in most cases' nature of
>>> RESTful interfaces a dangerous thing to even mention initially.
>>> Personally I'd leave that detail to the end of any discussion -
>>> almost like an optimization. If any developer senses that an API
>> Absolutely. It is an optimization and is called caching.
>>> will be 'mostly static', or 'static most of the time' then they'll
>>> be very tempted to fall back to their familiar local-system
>>> thinking, and therefore start 'hard-coding for now' and we'll start
>>> drifting back to where we are today with brittle systems...
>> Yeah. Probably the intro of section 3 in the spec should emphasize this a bit
>> more:
>>   http://www.hydra-cg.com/spec/latest/core/#hydra-at-a-glance
>>>>> My thoughts exactly. I even had an unsent draft with the exact same
>>>>> conclusion and programming API analogy as well. The word document is
>>>>> derived from latin documentum - example, which shares the stem doc-
>>>>> with the word docere - to teach [1]. In that sense I think most people
>>>>> will intuitively understand the ApiDocumentation as a place to learn
>>>>> from.
>>>> So the term ApiDocumentation isn't that bad after all :-)
>>> Well, yes it is still 'bad', 'cos any developer coming across it for
>>> the first time will naturally think of '#includes', or Java
>>> interfaces, or CORBA IDL, or WSDL (they've no choice, as they're the
>>> only APIs that they've ever seen). Using the terms DAPI and DAPID
>>> (Dynamic Application Programming Interface Documentation) on the
>>> other hand would force them to investigate what's different here,
>>> hence leading them to at least think about the need for truly
>>> dynamic interfaces.
>> Most developers are busy people and the thing they are most interested in is
>> to get their job done. There are already quite a lot of things that Hydra
>> does differently than anything else and thus require more research. We need
>> to start with something developers are already familiar with to gradually
>> introduce to Hydra.
I think the only way to introduce Hydra gradually (or any similar technology for that matter), is to enable its coexistence with the existing technologies, tools, and mentalities. Hypermedia and dynamic apis is quite a paradigm shift, but it does’t mean that, e.g., there may not exist a document describing the API, which developers can use as a reference. It just means that they should be warned that this document is merely a hint and it will change over time. Taking a risk ending up with a broken client or increasing the complexity of its implementation should be their decision.

I think most here agree that as long as APIs and their clients are implemented by human developers, there will be a need for human-readable documentation. Having a URL to a self-describing genuine RESTful/Hypermedia API is great for (semi-)automated clients, but it is not enough for developers used to the closed world assumption. I think that if Hydra aims at providing a feasible alternative to the current development paradigms, it needs to consider that.

>>>>>> Instead I really like the idea of expressly describing Hydra as a
>>>>>> vocabulary for describing 'Dynamic Application Programming
>>>>>> Interfaces' - i.e. a DAPI, and *not* an API (nor a 'Dynamic API', see
>>>>>> [1]). This seems like an opportunity to introduce a new acronym
>>>>>> (DAPI) to try to very explicitly and clearly express the fundamental
>>>>>> difference between traditional APIs based on the Closed World
>>>>>> Assumption, and DAPIs based on the Open World Assumption...
>>>> There already exists a quite similar acronym, DAP, which describes this
>>>> already:
>>>>   http://en.wikipedia.org/wiki/Domain_Application_Protocol
>>>> Unfortunately, very few people are familiar with this term. Thus I decided
>>>> to
>>>> call this thing simply a ApiDocumentation.
>>> Even though I've read that book (REST in Practice), the term DAP didn't
>>> really resonate with me. It doesn't communicate the truly 'dynamic'
>>> nature of the interfaces we're trying to describe and document here (and
>>> anyway, any API, whether static or dynamic, is going to inherently
>>> define a 'domain application protocol', so it's not helping to
>>> differentiate anything for me). But I don't think falling back to simply
>>> using API is going to help either, as I can definitely see many other
>>> developers falling into the same misconceptions as myself and Tomasz.
>> I see it from a different perspective. A developer has a problem to solve,
>> namely "to build a Web API". Since there aren't any well-established
>> processes and standards to do so yet, typically the next step is research.
>> So the developer goes to his favorite search engine and looks for
>> approaches/technologies/tools/... to build a Web API. Typically this leads
>> to long list of candidates HAL, Siren, JSON-LD, Hydra, RAML, Swagger, ...
>> Obviously, there isn't enough time to really get to know each approach
>> properly so most specs are just skimmed. A few are considered worth a closer
>> look. In the end, most developers then decide that all of these approaches
>> are "nice in theory" but they need something else and that they already
>> wasted way too much time to do all this research and so they simply stick to
>> plain old JSON.
>> I'm very concerned that introducing new terminology such as DAPIs we lose
>> developers too early. We can explain this things in prose but the major
>> keywords developers are familiar with need to be there to convince them that
>> Hydra is worth a closer look.

Using the word “documentation” to describe a "dynamic specification" of an api at runtime for me is misusing a common concept in an unknown domain, which doesn’t make understanding the Hydra concepts in any easier..

> I was that developer not too long ago, and found things like HAL, Siren, api+json, Collection+json, Collection.Doc+json but found all of the approaches based on media types too constraining. I knew enough about code generation to steer clear of Swagger. Never heard of RAML. JSON-LD seemed like it had some good things going for it, and could possibly serve as a basis for something that could work... I think I may have stumbled across Hydra in my research, but at the time it didn't look finished and it had this stuff about ApiDocumentation, and I thought, isn't the point of REST to get rid of all this API documentation? So I didn't look into it further. Since rediscovering Hydra a few months ago I have learned that the ApiDocumentation is for the machine, not for the developer per se. And that is OK, I think (though I've tossed around the term ApiDescription). But it may be good to clarify that (early) in the spec if it is not already? 
ApiSpecification? ApiDescription is also good, although I find it a bit too generic.

> I also think that even though the terms API and REST are the most misconstrued and ambiguous terms in the history of the web, we should use them, along with Hypermedia API and Web API (or hypermedia-driven Web API). That is what developers will be looking for.
Completely agree with that. I think introducing another term will simply add to the confusion.

Received on Thursday, 10 July 2014 10:01:17 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 20:29:42 UTC