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

On 10 Jul 2014, at 13:29, Markus Lanthaler <markus.lanthaler@gmx.net> wrote:

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

As I wrote you yesterday, I am working on figuring it out. 

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

I am doing research in the domains of Web of Things (WoT) and Internet of Things (IoT) and currently interested in describing Web APIs of different services either working with IoT devices, or providing upper-layer services based on them. Basically, this is not much different from other Web APIs that Hydra is designed for.

A more challenging and research-wise interesting task is to provide a semantic description for the plethora of protocols and APIs exposed by IoT devices, e.g., CoAP [1] and MQTT [2]. This would require at least extension of Hydra vocabulary to support non-http protocols (which has already been mentioned in discussions here), but as of now I am at the very beginning to say more. 
I really like the rather pragmatic approach to Semantic Web taken by JSON-LD and Hydra, and I think there is a potential in applying it to many application domains.

>> 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 it was the explanation that the ApiDocumentation can be served dynamically to every client, and that it is actually used to describe properties of classes.
Before that, I thought that hydra:Class objects are described directly in the @context, and ApiDocumentation.supportedClass[] is used just to provide documentation for them.

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

Earlier in the discussion, you considered “premium access” to the API in the context that different ApiDocumentation can be sent to different clients. How do you plan to approach such cases in the tool generating human-readable documentation? 

Serving different human-readable documents to different users? Then, in terms of that hypothetical example, how would you indicate to “basic access” users, which “extra” functionality of your API they can get by obtaining a “premium access”?
It may not make much sense for this example, but I see a need to have an option to describe full API in a single document, without requiring developer to query every possible endpoint in every possible application state.

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

I actually did, multiple times. However, once I read it today again (4.2 Documenting a Web API) I don’t know why it wasn’t clear to me it in the first place.
It might be that something else got between reading the spec and trying to actually describe my API using Hydra, or that there are several examples in the spec where Hydra is applied to describe classes outside of ApiDocumentation.supportedClass[], which confused me.

I think a set of examples, from very trivial to more complex would be very helpful. The api-demo [3] is a good one, but it seems that the API documentation is machine-generated and hard to read, and it is not the simplest example I would prefer to start with.

>> 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 see your concerns. I think “ApiDescription” suggested by Chris is not that bad after all.
Unlike “specification”, it actually suggests that the described API is more like a hint than something set in stone.

Alex

[1] http://coap.technology/
[2] http://mqtt.org/
[3] http://www.markus-lanthaler.com/hydra/api-demo/

Received on Friday, 11 July 2014 12:19:05 UTC