Re: Some questions about HYDRA

Hi Kristoffer

I'm glad you enjoy learning about hydra, especially when we're close
to have a spec in a release candidate stage (soon!).

Regarding your questions and doubts

>>My doubt about using the API documentation as the entry point is that I don't see where it would contain links back to the API resources,
>>which leaves me wondering how a client gets from the API documentation to an API resource without out of band information
From that point of view, an API documentation is no different to other
resources - it could have i.e. hydra:collection, hydra:search or any
other hydra:Link attached leading to any other resource within an API.
I believe it is not that common to have an API documentation act as an
entry point, but it is not forbidden by the spec. The only restriction
was that API documentation should have an entry point(s) provided and
the API response should have a LINK header leading to API
documentation so the client can discover an entry point(s) at any
time.

>>In terms of what I would expect from a hydra:EntryPoint class...well, honestly, not much.
I tend to see an analogy between an API entry point and a website's
landing page (main page) - it is supposed to attract you and provide a
fistful of links to other places.

>>I do recognize that there are no common characteristics per-se between resources that serve as entry points such that an EntryPoint class would provide any common metadata or constraints that would tell you anything useful.
You're right - entry point is no different than other resources. The
only thing is the client may want to start somewhere - that's the sole
purpose of an entry point.

>>I suppose my rationale is that it might help clarify and prompt developers on the design and usage of an entry point by making it clear that there is such a concept in the vocabulary,
Hmm - I was not aware this might be needed. Imagine a situation -
you've got to implement an integration with a third party web API.
What would be one of the first questions? I believe it would be "Where
is the instance I could use for tests" - answer to this would be an
entry point (a URI) to start playing with. Spec mentions an entry
point in 4.2 Documenting a Web API - it's not a wide description, but
I think it's enough. In case you feel it should be described in more
details, please give me a shout as I'm finalizing the spec.

>>As it stands, I have had several conversations about HYDRA at work that revolve around whether an entry point is simply a convention
>>that an API would include in special circumstances having to do with UI navigation, but that in general, it is sufficient to return the documentation when "/" is requested.
I think it has nothing to do with a convention. Spec clearly says API
responses should provide a link to the API documentation and the API
documentation should have an entry point defined, thus it is well
defined.
The spec however does not forbid serving an API documentation being an
entry point simultaneously. An entry point is not required to have any
specific class and the ApiDocumentation class is not disjoined with
any other classes.

I think whatever approach will do until it fits the spec. You could
give it a try and test how does your API behaves with the Heracles.ts
[1] or Heracles.net [2] reference client.

Hope it helps

Regards

Karol

[1] https://github.com/HydraCG/Heracles.ts
[2] https://github.com/HydraCG/Heracles.net

pon., 4 paź 2021 o 19:38 Kristoffer Garcia <lambdakris@gmail.com> napisał(a):
>
> Thank you so much for the answers. A couple of follow ups to my earlier questions.
>
> My doubt about using the API documentation as the entry point is that I don't see where it would contain links back to the API resources, which leaves me wondering how a client gets from the API documentation to an API resource without out of band information (eg, knowing the identity of the resource(s) they are interested in instead of just the api identity).
>
> In terms of what I would expect from a hydra:EntryPoint class...well, honestly, not much. I do recognize that there are no common characteristics per-se between resources that serve as entry points such that an EntryPoint class would provide any common metadata or constraints that would tell you anything useful. I suppose my rationale is that it might help clarify and prompt developers on the design and usage of an entry point by making it clear that there is such a concept in the vocabulary, though perhaps a deliberate introduction and discussion of the concept of an entry point in the specification would be more appropriate. As it stands, I have had several conversations about HYDRA at work that revolve around whether an entry point is simply a convention that an API would include in special circumstances having to do with UI navigation, but that in general, it is sufficient to return the documentation when "/" is requested (i.e. as the entry point - see my concern above about the apidoc serving as entrypoint), thus the reason why I have turned to the working group for more insight on this topic.
>
> And on the question of @context vs @type, thank you for your examples. I had actually asked the same question in the json-ld syntax repo and I received another very good answer: https://github.com/w3c/json-ld-syntax/issues/381#issuecomment-929900634
>
> Thanks again and I am greatly enjoying learning about HYDRA and the Semantic Web.
>
> - Kris
>
> On Wed, Sep 29, 2021, 1:35 AM Tomasz Pluskiewicz <tomasz@t-code.pl> wrote:
>>
>> Hello Kristoffer
>>
>> Thank you for asking those questions, they are very good indeed. Let me answer inline
>>
>> Tom
>>
>>
>> On 29 September 2021 at 09:12:00, Kristoffer Garcia (lambdakris@gmail.com) wrote:
>> > Greetings fellow HYDRA heads,
>> >
>> > I have a couple of HYDRA (and JSON-LD) related questions:
>> >
>> > 1. How essential is the entrypoint to a HYDRA api?
>>
>> Quite important. A client discovers a full picture of what constitutes a given API in a single representation of the ApiDocumentation resource. It is a single, mostly static resource which will get cached early on by clients and intermediaries.
>>
>> However, I see how you could argue that it might be superficial. The alternative would be to dereference models (classes) independently and provide possible operations inline. You probably will not escape the former but the latter would effective unnecessarily increase the size of all your responses.
>>
>> > Why isn't a dedicated EntryPoint class defined?
>>
>> I guess we never found a use for such a class. You would typically use an API-specific type or maybe schema:WebPage to offer predictable semantics. Hydra itself does not care what is the representation of the entrypoint. It is only important to offer that link to the clients.
>>
>> Let me ask you in return, what would you expect from a hypothetical hydra:EntryPoint class?
>>
>> > Could the ApiDocumentation function as the entrypoint resource (I doesn't seem so, but figured I'd ask)?
>>
>> Technically anything could be the entrypoint, given the weak semantic relation between the ApiDocumentation and API's entrypoint.
>>
>> IMO it could only make sense if you were to provide an API to control that very API. In that case however, you might in fact end up with two separate APIs altogether.
>>
>> >
>> > 2. What is the functional difference between the @context and the @type
>> > keywords? More specifically, why would you opt to use @type instead of or
>> > in addition to @context, when it seems that you can achieve sufficient
>> > descriptiveness with the use of just @context and sub/scoped contexts? I've
>> > read through https://json-ld.org/spec/latest/json-ld/#the-context and
>> > https://json-ld.org/spec/latest/json-ld/#specifying-the-type, but it is not
>> > clear what the use of one is accomplishing in contrast to the other.
>>
>> I’m not sure I understand what you mean by “sufficient descriptiveness”.
>>
>> @type is pretty mostly an alias of property rdf:type. Relating to @context, you can actually redefine any other JSON key to serve as a substitute of @type but I see limited utility of such a choice.
>>
>> Do compare the 3 JSON-LD below, all of which represent the same RDF data:
>>
>> https://tinyurl.com/3erhyf67
>> https://tinyurl.com/56w224z9
>> https://tinyurl.com/pux6wt72
>>
>> >
>> > Thank you all,
>> >
>> > Kris
>> >
>>

Received on Monday, 4 October 2021 18:37:45 UTC