- From: Markus Lanthaler via GitHub <sysbot+gh@w3.org>
- Date: Sun, 03 Jun 2018 16:00:07 +0000
- To: public-hydra-logs@w3.org
Review status: all files reviewed at latest revision, 4 unresolved discussions. --- *[drafts/use-cases/2.3.complete-api-documentation.md, line 40 at r1](https://reviewable.io/reviews/hydracg/specifications/164#-LBHP4uv4JwardklmAHo:-LE5L2B_48kpCwrW_9rV:b-ufsl23) ([raw file](https://github.com/hydracg/specifications/blob/c46a6c87fb68dce55656d41ee200d38e2cbf051d/drafts/use-cases/2.3.complete-api-documentation.md#L40)):* <details><summary><i>Previously, alien-mcl (Karol Szczepański) wrote…</i></summary><blockquote> But `<>` is an API's entry point, which is not it's API documentation. </blockquote></details> 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](https://reviewable.io/reviews/hydracg/specifications/164#-LBHPFNZ4g8XnxpvBz9L:-LE5LmXL-tp3Zw9goFqW:bheh3r0) ([raw file](https://github.com/hydracg/specifications/blob/c46a6c87fb68dce55656d41ee200d38e2cbf051d/drafts/use-cases/2.3.complete-api-documentation.md#L48)):* <details><summary><i>Previously, alien-mcl (Karol Szczepański) wrote…</i></summary><blockquote> 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? </blockquote></details> 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](https://reviewable.io/reviews/hydracg/specifications/164#-LBHQaX47tRg58Q2OLvi:-LE5Mme-2q1zXV89ntR4:b9h2nkq) ([raw file](https://github.com/hydracg/specifications/blob/c46a6c87fb68dce55656d41ee200d38e2cbf051d/drafts/use-cases/2.3.complete-api-documentation.md#L119)):* <details><summary><i>Previously, alien-mcl (Karol Szczepański) wrote…</i></summary><blockquote> 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. </blockquote></details> 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](https://reviewable.io/reviews/hydracg/specifications/164)* <!-- Sent from Reviewable.io --> -- GitHub Notification of comment by lanthaler Please view or discuss this issue at https://github.com/HydraCG/Specifications/pull/164#issuecomment-394171985 using your GitHub account
Received on Sunday, 3 June 2018 16:00:11 UTC