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

var client = new HydraClient();
var apiDocumentation = client.get("http://example.com/").getApiDocumentation();
for (var $class of apiDocumentation.supportedClasses) {
    // generate a partial view for the _$class_
}

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.

API documentation and hypermedia controls precedence

It is unclear on how details obtain from API documentation and current hypermedia controls should be "merged". There are few possibilities here:

• hypermedia controls overrides API documentation
• hypermedia controls extends API documentation

Hydra Core Vocabulary specification would introduce several weaknesses in all cases here:

• if the control overrides API documentation behavior, there is no mechanism that would force it to extend it instead
• if the control extends API documentation behavior, there is no mechanism that would force it to override it instead

More specific situations:

• (API documentation data structures)[/2.1.api-documentation-data-structures.md]
• (API documentation user document)[/2.2.api-documentation-user-document.md]
• (Complete API documentation)[/2.3.complete-api-documentation.md]