Re: some more feedback

Hi there,

On Mon, Oct 6, 2014 at 2:40 PM, Markus Lanthaler
<markus.lanthaler@gmx.net> wrote:
> On 6 Okt 2014 at 14:16, Martijn Faassen wrote:
[snip]
>> I find that pretty unfortunate. It's okay with me that Hydra is
>> informed by RDF, is compatible with RDF tools, can be interpreted as
>> an RDF specification. That's what JSON-LD does. But to me, if I have
>> to *understand* RDF in order to understand Hydra, I find Hydra much
>> less attractive.
>
> This is an excellent argument. Maybe all we need to do is to describe it slightly differently and include a
> couple of examples. So we describe how it can be used to realize certain use cases but do not describe the
> relationship to RDFS etc. (it is in the machine-readable definition of the vocabulary for people that care
>  though). In other words we don't describe *why* it is used with JSON-LD's "@type" or Turtle's "a" but just
> describe how you do it and what features/use cases this enables.
>
> How does that sound?

Yes, that would help a lot! This relates to the examples I've been
calling for elsewhere.

[snip]
> No, you would have two or more ApiDocumentations. For instance
>
>    http://developers.example.com/api-doc.jsonld
>
> which includes *all* operations regardless of the permissions. The natural-language descriptions would make
> it clear that some operations may not be available to all users as they depend on their permissions. A
> resource could then nevertheless reference another ApiDocumentation at runtime:
>
>     GET /users/ HTTP/1.1
>     Host: api.example.com
>
>     ====================================
>
>     HTTP/1.1 200 OK
>     ...
>     Content-Type: application/ld+json
>     Link: </api-doc/dynamic.jsonld>; rel="http://www.w3.org/ns/hydra/core#apiDocumentation"
>
> You could use exactly the same tool to generate the nicely formatted HTML documentation but obviously the
> result would be different. What do you think?

It's rather odd that the human readable documentation generated from
the jsonld is based on is different from the API documentation jsonld
that is actually referred to in the page. I understand the two
audiences: developers for human readable documentation, software for
the linked API documentation. But this approach breaks the expectation
that I could just inspect an API and read the linked API doc in order
to find the full API documentation. Instead I need to be aware that
this is a limited API documentation based on my current permissions,
and then somehow know where the real full API documentation is. I'd
expect there at least to be a link from the dynamic docs to the full,
static version.

Formally api.example.com/api-doc/dynamic.jsonld is always a subset of
developers.example.com/api-doc.jsonld, but that relationship is not
made explicit anywhere.

Looking at the term "API documentation", I think everybody would agree
that the developer docs are API documentation. But would people agree
that what is linked is API documentation as well? It's an API
description, but it is aimed at software, and the word "documentation"
typically implies a human audience.

We can look at the term "API documentation" in another way. A
developer expects API documentation to be updated if the API is
changed in some way by *implementation changes*, not because of
runtime permissions. If it is a goal of Hydra to also be able to
describe API changes due to runtime permission changes by actually
changing the API documentation itself (instead of by changing types in
runtime resources, for instance), then perhaps "documentation" isn't
the correct term to use. "API description" is more neutral and doesn't
carry all the connotations of the word documentation.

Regards,

Martijn

Received on Monday, 6 October 2014 13:33:32 UTC