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

First of all: Alexandr, could you please join the W3C Community Group at

  http://www.w3.org/community/hydra/

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

+1


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

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.

Great


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


--
Markus Lanthaler
@markuslanthaler

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