Add an example showing how responses point to the ApiDocumentation

[lanthaler]

Otherwise people might have the impression that the link to the ApiDocumentation is solely used to find the API's entry point. See http://lists.w3.org/Archives/Public/public-hydra/2014Aug/0145.html

[conzett]

Sorry if this is better suited for the mailing list but since there is an open issue I thought I would try and confirm my assumptions here based on what has been written above.

I'm operating under the assumption right now that the link header with rel http://www.w3.org/ns/hydra/core#apiDocumentation can appear in any response and the supportedClass property provides a list of classes for that context, not necessarily all the supported classes for the entire application (I think this is what is unclear in the docs).

[tpluscode]

What do you mean by 👇?

a list of classes for that context

Don't treat this as an authoritative answer but I think that the API documentation actually does indeed list all classes supported by the API. This may not be a an exhaustive list though. For example unauthenticated users (or users with certain permissions) could only receive part of the API (classes). But it is not otherwise limited to the scope of any given resource.

On the other hand nothing forbids you from designing your API that way. Beware though that it must always include descriptions of any class that the client could have received, also in past responses. This would be to avoid a situation where you don't have details of how to perform a request for example (when a class is used with the hydra:expects but is not in the ApiDocumentation)

[asbjornu]

@tpluscode: That's my understanding of the ApiDocumentation as well. It represents the "complete" documentation for the entire API and is not scoped to a resource. It can change over time to reflect the current state of the application, though, but will still list classes that isn't relevant for the current resource. Afaik.

[conzett]

the API documentation actually does indeed list all classes supported by the API.
...
Beware though that it must always include descriptions of any class that the client could have received, also in past responses.

Ah ok, that does help clarify. This would end up being a very large document for the application I'm looking to build this into - that might be OK with caching though.

[lanthaler]

Interesting. The obvious question then might be what the boundary of an API is.