Re: [Specifications] Attempt to describe extensively an API used in Heracles.ts

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