search

HydraCG / Specifications

Specifications created by the Hydra W3C Community Group
Other
138 stars 26 forks source link

Attempt to describe extensively an API used in Heracles.ts #164

Closed alien-mcl closed 6 years ago

alien-mcl commented 6 years ago

Please find the attached use case focused on extensive API documentation of the API used in the Heracles.ts implementation that is related to events.

Please feel free to elaborate as it came out that the task was not easy.

This change is Reviewable

alien-mcl commented 6 years ago

@lanthaler, @tpluscode, @elf-pavlik, any update on this?

lanthaler commented 6 years ago

Reviewed 2 of 2 files at r1. Review status: all files reviewed at latest revision, all discussions resolved.

drafts/use-cases/2.3.complete-api-documentation.md, line 18 at r1 (raw file):

  - name
  - description
  - base classes

Do you mean parent/super-classes?

drafts/use-cases/2.3.complete-api-documentation.md, line 40 at r1 (raw file):

@base <http://temp.uri/api> .

<?apiDocumentation> a hydra:ApiDocumentation;

I'd think making this <> instead of <?apiDocumentation> would simplify things.

drafts/use-cases/2.3.complete-api-documentation.md, line 48 at r1 (raw file):

schema:Event a hydra:Class ;
    hydra:supportedOperation doc:get-events-operation ,
        doc:new-event-operation ,

I'd get rid of the doc: prefix and instead use relative IRIs directly, in this case <#new-even-operation>. That makes it clear that the description can be found further down in the same doc

drafts/use-cases/2.3.complete-api-documentation.md, line 84 at r1 (raw file):

# Below are operations related to schema:Event supported class.
# Unfortunately, it is not possible to link them directly to the supported class
# as the hydra:Operation does not allow to define the URL to be invoked.

You could reference the issue in which we are working on that here

drafts/use-cases/2.3.complete-api-documentation.md, line 89 at r1 (raw file):

# The link below does not allow to describe the fact returned payload is a collection of schema:Event,
# thus the only hint for the client to connect it with that class is comparing supported operations 
# defined in this link and the class itsefl.

itsefl --> itself

drafts/use-cases/2.3.complete-api-documentation.md, line 110 at r1 (raw file):

doc:update-event a hydra:TemplatedLink ;
    hydra:title "Updates an event." ;
    hydra:template "http://temp.uri/api/events/{id}"^^hydra:Rfc6570Template ;

hydra:template and hydra:mapping can't be used on the definition of a TemplatedLink. They need to be set when such a link is instantiated.

drafts/use-cases/2.3.complete-api-documentation.md, line 119 at r1 (raw file):

    ] .

# Link below cannot be directly connected with schema:Event class as it does not mention it.

What do you mean by this? You declared there to be a supported operation of schema:Event that allows deleting the event. In general, I don't understand what you use these TemplatedLinks here for!?

Comments from Reviewable

alien-mcl commented 6 years ago

Review status: all files reviewed at latest revision, 7 unresolved discussions.

drafts/use-cases/2.3.complete-api-documentation.md, line 18 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…
Do you mean parent/super-classes?

Yes, should I retype it?

drafts/use-cases/2.3.complete-api-documentation.md, line 110 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…
`hydra:template` and `hydra:mapping` can't be used on the definition of a TemplatedLink. They need to be set when such a link is instantiated.

OK, but are there any alternatives? How to tell on API documentation level that there is an IRI template link?

Comments from Reviewable

lanthaler commented 6 years ago

Review status: all files reviewed at latest revision, 7 unresolved discussions.

drafts/use-cases/2.3.complete-api-documentation.md, line 18 at r1 (raw file):

Previously, alien-mcl (Karol Szczepański) wrote…
Yes, should I retype it?

Yeah, I think it would clarify it

drafts/use-cases/2.3.complete-api-documentation.md, line 110 at r1 (raw file):

Previously, alien-mcl (Karol Szczepański) wrote…
OK, but are there any alternatives? How to tell on API documentation level that there is an IRI template link?

That's currently not possible

Comments from Reviewable

alien-mcl commented 6 years ago

Review status: all files reviewed at latest revision, 7 unresolved discussions.

drafts/use-cases/2.3.complete-api-documentation.md, line 18 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…
Yeah, I think it would clarify it

Done.

drafts/use-cases/2.3.complete-api-documentation.md, line 40 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…
I'd think making this `<>` instead of `` would simplify things.

But <> is an API's entry point, which is not it's API documentation.

drafts/use-cases/2.3.complete-api-documentation.md, line 48 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…
I'd get rid of the `doc:` prefix and instead use relative IRIs directly, in this case <#new-even-operation>. That makes it clear that the description can be found further down in the same doc

As previously - @base points to the API entry point, doc: prefix points to the API documentation, which are separate beings. I feel some IRI re-factorization is necessary here - any suggestions?

drafts/use-cases/2.3.complete-api-documentation.md, line 84 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…
You could reference the issue in which we are working on that here

Done.

drafts/use-cases/2.3.complete-api-documentation.md, line 89 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…
itsefl --> itself

Done.

drafts/use-cases/2.3.complete-api-documentation.md, line 110 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…
That's currently not possible

I've added an issue to address this.

drafts/use-cases/2.3.complete-api-documentation.md, line 119 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…
What do you mean by this? You declared there to be a supported operation of schema:Event that allows deleting the event. In general, I don't understand what you use these TemplatedLinks here for!?

I'd like to give a client a hint, that it can use GET, PUT and DELETE methods on a very specific instances that can be addressed with an IRI template.

Comments from Reviewable

lanthaler commented 6 years ago

Review status: all files reviewed at latest revision, 4 unresolved discussions.

drafts/use-cases/2.3.complete-api-documentation.md, line 40 at r1 (raw file):

Previously, alien-mcl (Karol Szczepański) wrote…
But `<>` is an API's entry point, which is not it's API documentation.

It's a relative URL so it depends on where it is hosted (resp. what @base says). The main I'd like to avoid is the use of a query param. If you don't like <> please make it </apiDocumentation> or something similar. I have seen people being confused about this in the past where they thought they would need to return the API docs if something like ?apiDocumentation is appended to any of their URLs.

drafts/use-cases/2.3.complete-api-documentation.md, line 48 at r1 (raw file):

Previously, alien-mcl (Karol Szczepański) wrote…
As previously - `@base` points to the API entry point, `doc:` prefix points to the API documentation, which are separate beings. I feel some IRI re-factorization is necessary here - any suggestions?

I typically prefer to use relative URLs (mostly fragments) for everything that can be found in the same document. Let's just get rid of @base and use full, absolute URLs (or path-absolute URLs) for everything else

drafts/use-cases/2.3.complete-api-documentation.md, line 119 at r1 (raw file):

Previously, alien-mcl (Karol Szczepański) wrote…
I'd like to give a client a hint, that it can use `GET`, `PUT` and `DELETE` methods on a very specific instances that can be addressed with an IRI template.

I think what you want in that case is a concrete IRI template with those operations attached to it. You don't need a TemplatedLink property for that. That being said, a client wouldn't necessarily use this as of now as there's no way to connect it to a ApiDocumentation (but it would be straightforward to add)

Comments from Reviewable

alien-mcl commented 6 years ago

Review status: all files reviewed, 3 unresolved discussions (waiting on @lanthaler)

drafts/use-cases/2.3.complete-api-documentation.md, line 40 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…
It's a relative URL so it depends on where it is hosted (resp. what `@base` says). The main I'd like to avoid is the use of a query param. If you don't like `<>` please make it `` or something similar. I have seen people being confused about this in the past where they thought they would need to return the API docs if something like `?apiDocumentation` is appended to any of their URLs.

Done.

drafts/use-cases/2.3.complete-api-documentation.md, line 48 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…
I typically prefer to use relative URLs (mostly fragments) for everything that can be found in the same document. Let's just get rid of `@base` and use full, absolute URLs (or path-absolute URLs) for everything else

Done.

drafts/use-cases/2.3.complete-api-documentation.md, line 119 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…
I think what you want in that case is a concrete IRI template with those operations attached to it. You don't need a TemplatedLink property for that. That being said, a client wouldn't necessarily use this as of now as there's no way to connect it to a ApiDocumentation (but it would be straightforward to add)

Done.

Comments from Reviewable

lanthaler commented 6 years ago
:lgtm:

Reviewed 1 of 1 files at r3. Review status: all files reviewed, 1 unresolved discussion (waiting on @lanthaler)

drafts/use-cases/2.3.complete-api-documentation.md, line 48 at r1 (raw file):

Previously, alien-mcl (Karol Szczepański) wrote…
Done.

You forgot to get rid of @base

Comments from Reviewable

alien-mcl commented 6 years ago

Review status: all files reviewed, 1 unresolved discussion (waiting on @lanthaler)

drafts/use-cases/2.3.complete-api-documentation.md, line 48 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…
You forgot to get rid of `@base`

Done

Comments from Reviewable

lanthaler commented 6 years ago

Reviewed 1 of 1 files at r4. Review status: :shipit: complete! all files reviewed, all discussions resolved

Comments from Reviewable

hyprdia commented 9 months ago

I know this has been a while since this was merged, but I start to design a quite complex API using Hydra and I have an issue with (not the example but the hydra:SupportedProperty ): 

    a hydra:SupportedProperty ;
    hydra:propety vocab:id ;
    hydra:required "true"^^xsd:boolean ;
    hydra:writable "true"^^xsd:boolean ;
    hydra:readable "true"^^xsd:boolean ] ;

since this is defined in the documentation, it seems to assume that the required, writable and readable values will be valid in all situations. In my API, a particular supportedClass, and I have many examples of this, may sometimes support writable(readable) but sometimes not, it could depend on many factors such as: the context in which the supportedClass instance is found, its state, the permissions of the user/client seeing the instance.

My questions: can the API documentation not provide this information when it cannot be provided (are they required properties)? Would the API still be Hydra compatible in such case?

hyprdia commented 9 months ago

Just saw the maxCardinality in the last spec version. No need to answer, thanks.