[Specifications] Strongly typed collections in API documentation (#233)

alien-mcl has just created a new issue for https://github.com/HydraCG/Specifications:

== Strongly typed collections in API documentation ==
## Describe the requirement

I was wondering on how to describe a strongly typed (closed generic) collection in API documentation.

## Hydra-agnostic example

There are situations when client could benefit from known in advance what kind of collection members are in the collection.
One of the reason would be answer to question "what should I do to obtain a list of users".

## Proposed solutions

There are two approaches. One would be to include a piece of a collection mentioned by the API documentation with that documentation itself:
```turtle
  @base <http://temp.uri/api> .
  </api> a hydra:ApiDocumentation;
    hydra:supportedClass api:User.
  hydra:collection </api/users>.
  </api/users> hydra:memberAssertion [
    hydra:predicate rdf:type;
    hydra:object api:User].
```

This does not require any new terms, but it may be unwanted to mix metadata (an API documentation) with pieces of actual resources. Alternative would be a new term that would allow to more direct and abstract description:

```turtle
  @base <http://temp.uri/api> .
  </api> a hydra:ApiDocumentation;
    hydra:supportedClass api:User;
    api:users </api/users> .
  api:users a hydra:Link;
    hydra:supportedOperation [
      hydra:method "GET";
      hydra:returns [
        rdfs:subClassOf hydra:Collection;
        hydra:memberAssertionEquivalent [
          hydra:predicate rdf:type;
          hydra:object api:User]
      ]
  ] .
```

The example above introduces a hypothetical `hydra:memberAssertionEquivalent` term (name is a subject to change).
Another alternative would be:

```turtle
  @base <http://temp.uri/api> .
  </api> a hydra:ApiDocumentation;
    hydra:supportedClass api:User;
    api:users </api/users> .
  api:users a hydra:Link;
    hydra:supportedOperation [
      hydra:method "GET";
      hydra:returns hydra:Collection;
      hydra:memberAssertionEquivalent [
          hydra:predicate rdf:type;
          hydra:object api:User]
      ]
  ] .
```

A brand new term is introduced and attached in a different place (less nesting) compared to the previous example. Slight modification for the two above would require reusing existing `hydra:memberAssertion` with it's domain modified (currently `hydra:Collection`). Both of the cases above are abstract descriptions and there are no statements in which the actual resource instance is a subject for.

Feel free to deliberate on the best approach.

Please view or discuss this issue at https://github.com/HydraCG/Specifications/issues/233 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Tuesday, 13 April 2021 19:36:48 UTC