API documentation data structures

Story

As an application user I want to be presented with some editor forms So I can fill it with my data.

As an API consumer I want to be able to fetch entry-point's supported classes So I can pre-generate views and forms.

Usage

const apiDocumentation = await hydraClient.getApiDocumentation("http://temp.uri/");
for (const supportedClass of apiDocumentation.supportedClasses) {
    views[supportedClass.iri] = generateViewFor(supportedClass);
}

function generateViewFor(supportedClass: IClass): string {
    let result = `${supportedClass.displayName} ${supportedClass.iri} properties:`;
    for (const supportedProperty of supportedClass.supportedProperties) {
        result += `\n - ${supportedProperty.property.displayName} ${supportedProperty.property.iri}`; 
    }

    return result;
}

Details

There are situations when, e.g., Rich Internet Applications need to present a nice looking edit form for a data element. Previously, it was common to create that form by hard-coding it into the application, causing issues on data item structure updates.

By providing details on entry point's supported classes and their property details, it is possible to pre-generate that views (to some extend at least), so the client can be always up-to-date with it's structure and presentation.

Communication would look like this:

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",
    "@type": "hydra:ApiDocumentation",
    "supportedClass": [
        {
            "@id": "schema:Event",
            "supportedProperty": [
                {
                    "@type": "hydra:SupportedProperty",
                    "property": "schema:eventName"
                },
                {
                    "@type": "hydra:SupportedProperty",
                    "property": "schema:eventDescription"
                },
                {
                    "@type": "hydra:SupportedProperty",
                    "property": "schema:startDate"
                },
                {
                    "@type": "hydra:SupportedProperty",
                    "property": "schema:endDate"
                }
            ]
        }
    ]
}

By composing both payload and context client can gain knowledge on how the data element structure looks like (i.e. properties, their names and data types). With this knowledge it is possible to i.e. generate generic HTML views for editing or creating data items or to support dynamic IRI template composition.