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

On 11 Jul 2014 at 14:18, Alexandr Krylovskiy wrote:
> On 10 Jul 2014, at 13:29, Markus Lanthaler 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.

Great, 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?
> 
> 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.

Cool... W/IoT is getting a lot of interest these days... I think Hydra is a
particularly good fit for it as data integration etc. play a much more
prominent role in those kind of APIs than on typical user facing "mashups".


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

Yeah, this is definitely something we should keep in mind and look at in the
future. At the moment, however, I think we should focus on HTTP to not get
distracted too much.


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

OK, thanks.


[...]
>>> 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 haven't spent a lot of time thinking about that yet to be honest. To most
trivial thing would be of course to generate different documentations for
each ApiDocumentation variant. The alternative would be to generate a human
readable documentation comprising all features and either describe in prose
or indicate by different formatting which things are available under which
conditions.


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

This happens to me all the time :-)


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

Yeah. We should create a small API to be used in the spec.


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


--
Markus Lanthaler
@markuslanthaler

Received on Wednesday, 16 July 2014 15:44:17 UTC