RE: some more feedback

Hi Martijn,

On 6 Okt 2014 at 15:33, Martijn Faassen wrote:
> On Mon, Oct 6, 2014 at 2:40 PM, Markus Lanthaler wrote:
>> On 6 Okt 2014 at 14:16, Martijn Faassen wrote:
>> 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.

Fair enough. I raised ISSUE-75 [1] to track this.


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

I personally regard "documentation" and "description" as synonyms.


> 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

It is not a goal, it is a consequence of the chosen design.


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

I don't have a strong opinion about this but (as a non-native speaker) I don't really see how calling it ApiDescription instead of ApiDocumentation would help people understand that subtle detail. In any case, before making a change, I would like to hear more opinions/concerns about this.


Thanks,
Markus


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


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 13 October 2014 14:02:17 UTC