Re: Some questions about HYDRA

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