Introduced two new use cases related to API documentation and collection pagination

[alien-mcl]

Please find the attached use cases related to:

• API documentation of data structures
• API user documentation
• partial collection handling

---

This change is 

[lanthaler]

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

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 1 at r1 (raw file):

documentationt

Typo --> documentation

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 27 at r1 (raw file):

There are situations, when i.e. Rich...

should be "There are situations when, e.g., Rich..."

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 33 at r1 (raw file):

could be

--> is

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 34 at r1 (raw file):

vs.

--> and

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 44 at r1 (raw file):

api?documentation

Nit: While it wouldn't matter in practice, I think people will find the query parameter confusing. I'd thus suggest to place this at /api/documentation

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 58 at r1 (raw file):

{
    "@context": "/api/context.jsonld",
    "@id": "/api?documentation",

Please type it as hydra:ApiDocumentation

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 64 at r1 (raw file):

            "supportedProperty": [
                {
                    "property": "schema:eventName",

These all need to be separate objects (of type hydra:SupportedProperty)

---

drafts/use-cases/2.2.api-documentation-user-document.md, line 23 at r1 (raw file):

foreach (const operation of supportedProperty.supportedOperations)

Did you want to add some inner statements?

---

drafts/use-cases/3.2.pagination.md, line 35 at r1 (raw file):

Cleint

--> Client

---

Comments from Reviewable

[alien-mcl]

Review status: 4 of 5 files reviewed at latest revision, 9 unresolved discussions.

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 1 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…

> documentationt Typo --> documentation

Done.

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 27 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…

> There are situations, when i.e. Rich... should be "There are situations when, e.g., Rich..."

Done.

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 33 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…

> could be --> is

Done.

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 34 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…

> vs. --> and

Done.

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 44 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…

> api?documentation Nit: While it wouldn't matter in practice, I think people will find the query parameter confusing. I'd thus suggest to place this at `/api/documentation`

Hmm. Actually I didn't want the documentation to be confused with an actual API resource as other (/api/event to not to look to far) are addressed same way. Do we have another option?

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 58 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…

Please type it as `hydra:ApiDocumentation`

Done.

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 64 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…

These all need to be separate objects (of type `hydra:SupportedProperty`)

Argh - correct. I wanted it to be shorter and it ended up with some virtual stupidity. Done

---

drafts/use-cases/2.2.api-documentation-user-document.md, line 23 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…

> foreach (const operation of supportedProperty.supportedOperations) Did you want to add some inner statements?

Ahh, yep - jumped to another part of document and forgot to get back here. Done

---

drafts/use-cases/3.2.pagination.md, line 35 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…

> Cleint --> Client

Done.

---

Comments from Reviewable

[lanthaler]

Review status: 4 of 5 files reviewed at latest revision, 9 unresolved discussions.

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 1 at r1 (raw file):

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

Done.

Looks like you forgot to push your changes.

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 44 at r1 (raw file):

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

Hmm. Actually I didn't want the documentation to be confused with an actual API resource as other (`/api/event` to not to look to far) are addressed same way. Do we have another option?

What about /api-documentation then? It is an actual API resource btw. ;-) A crucial part of its interface

---

Comments from Reviewable

[alien-mcl]

Review status: 2 of 5 files reviewed at latest revision, 9 unresolved discussions.

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 1 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…

Looks like you forgot to push your changes.

Nope - looks like Reviable misbehaves. See (this)[https://github.com/HydraCG/Specifications/pull/159/files#diff-5d0fa46b254a904910d47b58d99d20d8] file - it's correct now.

---

drafts/use-cases/2.1.api-documentation-data-structures.md, line 44 at r1 (raw file):

Previously, lanthaler (Markus Lanthaler) wrote…

What about `/api-documentation` then? It is an actual API resource btw. ;-) A crucial part of its interface

Well, /api-documentation feels better.

I understand that that documentation is a crutial part of its interface, but I wouldn't like to see the documentation mixed with other business-logic related resources.

---

Comments from Reviewable

[lanthaler]

thanks!

---

Reviewed 2 of 3 files at r2. Review status: 4 of 5 files reviewed at latest revision, all discussions resolved.

---

Comments from Reviewable

[lanthaler]

Reviewed 1 of 3 files at r2. Review status: all files reviewed at latest revision, all discussions resolved.

---

Comments from Reviewable