Hydra and Linked Data APIDocumentation

[charlesvardeman]

Here is a link to the zazuko/hydra-box express middleware that exposes the API as linked data using the hydra core vocabulary. This would facilitate a linked-data application to consume JSON-LD through the hydra entry point specification. There is also a hydra-validator to test the apidocumentation specification.

The idea would be to breadcrumb out of OpenAPI spec using x-oas-draft-alternativeSchemas

openapi: 3.0.1
info:
  title: "A sample API conforming to the draft standard OGC API - Features - Part 1: Core"
  version: '1.0.0-draft.2'
  description: |-
    This is a sample OpenAPI definition that conforms to the conformance 
    classes "Core", "GeoJSON", "HTML" and "OpenAPI 3.0" of the draft
    standard "OGC API - Features - Part 1: Core".
    
    This example is a generic OGC API Features definition that uses path 
    parameters to describe all feature collections and all features. 
    The generic OpenAPI definition does not provide any details on the 
    collections or the feature content. This information is only available 
    from accessing the feature collection resources.
    
    There is [another example](ogcapi-features-1-example2.yaml) 
    that specifies each collection explicitly.
paths:
  '/':
    get:
      tags:
        - Capabilities
      summary: landing page
      description: |-
        The landing page provides links to the API definition, the conformance
        statements and to the feature collections in this dataset.
      operationId: getLandingPage
      responses:
        '200':
          $ref: 'https://raw.githubusercontent.com/opengeospatial/WFS_FES/master/core/openapi/ogcapi-features-1.yaml#/components/responses/LandingPage'
           content:
                application/ld+json:
                     x-oas-draft-alternate-schema:
                     type: hydra-core
                     externalValue: ./API/hydradoc.jsonld

The http link headers should also correctly breadcrumb the link to the apidocumentation as indicated in the hydra spec doc.

GET /api/items HTTP/1.1
Host: api.example.com
Accept: application/ld+json

====================================

HTTP/1.1 200 OK
...
Content-Type: application/ld+json
Link: <http://api.example.com/doc/>; rel="http://www.w3.org/ns/hydra/core#apiDocumentation"

{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "@id": "http://api.example.com/api/items",
  "title": "Items collection",
  ...

This is somewhat painful right now, but there is some python tooling to generate the hydra spec from openapi.