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

Is the term ApiDocumentation misleading (ISSUE-61) / was: RE: Specifying operations for instances

From: Markus Lanthaler <markus.lanthaler@gmx.net>
Date: Thu, 10 Jul 2014 13:29:40 +0200
To: <public-hydra@w3.org>
Message-ID: <05fa01cf9c32$417d1cd0$c4775670$@gmx.net>
First of all: Alexandr, could you please join the W3C Community Group at


This is important to ensure that we don't run into IPR issues if we move
Hydra to an official W3C Working Group. Thanks!

On Thursday, July 10, 2014 12:01 PM, Alexandr Krylovskiy wrote:
> You can count another confused developer here.  Although my intentions

OK. So it seems this should be discussed further. I've created ISSUE-61 [1]
for this.

> to use Hydra are broader than just implementing a specific API, this

I would be very interested to hear how you intend to use Hydra. Can you
share some more information with us?

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

What exactly in this thread helped you to 'finally get what
"ApiDocumentation" in Hydra means'? It might help other people as well.

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

Please try to post in plain-text in the future. This makes it simpler for
people to reply.

> On 09 Jul 2014, at 21:47, Chris Chapman wrote:
> >> On 9 Jul 2014 at 20:22, McBennett, Pat wrote:
> >>> Markus Lanthaler wrote on July 09, 2014 5:48 PM wrote:
> >> 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
> >> does differently than anything else and thus require more research. We
> >> to start with something developers are already familiar with to
> >> 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.

Yep. An Hydra ApiDocumentation can be used to generate such a human-readable
documentation. Creating such conversion tool is one of the top most things
on my to do list.

> >> I'm very concerned that introducing new terminology such as DAPIs we
> >> 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
> >> 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..

Do you have any concrete proposals for an alternative term?

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

Yeah, these discussions really indicate that this has to be clarified in the
spec. I assume both of you actually took the time to read the spec.. did
you? :-)

> ApiSpecification? ApiDescription is also good, although I find it a
> bit too generic.

I actually find ApiSpecification much more misleading. IMO one of the
fundamental characteristics of a specification is that it is stable and
doesn't change. The terms description and documentation are more or less
synonymous for me.

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


[1] https://github.com/HydraCG/Specifications/issues/61

Markus Lanthaler
Received on Thursday, 10 July 2014 11:30:19 UTC

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