API Documentation

Story

As a API consumer I want to be able to get an overview of the structure and capabilities of a Hydra API so that I can understand how to interact with the API and make those interactions more efficient.

Usage

const apiDocumentation = await hydraClient.getApiDocumentation("http://example.com/");
for (const $class of apiDocumentation.supportedClasses) {
    // generate a partial view for the *$class*
}

const event = apiDocumentation.supportedClasses.ofType("http://schema.org/Event");
if (event === null) {
    throw "Class not supported.";
}

Details

The documentation obtain may be a large payload, thus client is expected to store it temporarily at least for the current session.

GET /

HTTP 200 OK
Link: </api?documentation>; rel="http://www.w3.org/ns/hydra/core#apiDocumentation"

GET /api?documentation

HTTP 200 OK

{
    "@context": "/api/context.jsonld",
    "@id": "/api?documentation",
    "supportedClass": [
        {
            "@id": "schema:Event",
            "supportedProperty": [
                {
                    "property": {
                        "@id": "eventName"
                    }
                },
                {
                    "property": {
                        "@id": "eventDescription"
                    }
                },
                {
                    "property": {
                        "@id": "startDate"
                    }
                },
                {
                    "property": {
                        "@id": "endDate"
                    }
                }
            ]
        }
    ]
}

In order to i.e. generate views for each supported class, a complete type definition should be provided. Currently, Hydra Core Vocabulary allows that using RDFS/OWL vocabularies.

The documentation should also contain some human readable details like:

operation's expected type and its role
operation's returned type and its role
operation name
operation description
parameters and their descriptions and roles

Considerations

Entry-Point/API Documentation fetching precedence

In the previous scenario, application fetched an entry-point data as its first action. It might be worth of considering the opposite - taking an API documentation if available.

Few possibilities here are available:

sending an OPTIONS HTTP request to the base URL, but HTTP specification does not allow to cache these responses
sending an GET HTTP request to the base URL with some HTTP header; header Expect would be a candidate, but it's not allowed in AJAX communication; another option would be a Prefer

Once the API documentation is fetched and processed, client would then display some base view with further options, i.e. a main menu with all supported classes.

Data structure description

As already mentioned, Hydra Core Vocabulary allows to embed class description using RDFS/OWL constructs. Unfortunately, using those may prove difficult in parsing. In the scenario above, we'd need to use rdfs:range predicate to denote the types a given property accepts. For simple scenarios it may be just xsd:string, but what if server will come out with a union of classes?

Embedding class supported operations

We could embed within each of the supported class details on what can be done with those classes, i.e. how can we obtain all instances or how we can create a new one. This may be an alternative to entry point, where an UI application could create it's main menu presented to the user with all possibilities, from which some may be denied later. In case of an entry-point and embedded hypermedia controls, only those that are allowed in the current state are expect . Currently, Hydra Core Vocabulary does not give a clear answer on how such a construct should be created and handler.