API Documentation graph requires a hardcoded base IRI

[tpluscode]

The problem

When loaded from a file, the Hydra API doc has to be hardcoded with a concrete base, and it's impossible to replace, for example to run a hydra-box app in different deployment environments.

# Cannot change this to run in a hosting environment
BASE <http://localhost:5000>

<api> a hydra:ApiDocumentation .
# ...

I'd rather that the document did not need a base at all, but have it provided to the parser.

Proposed solution

I would propose a method to load one or multiple graphs which would be combined to build the ApiDocumentation.

import hydraBox from 'hydra-box'

const path = path.join(__dirname, './hydra')
const baseIRI = process.env.BASE_URI

hydraBox.fromFileSystem('/api', path, baseIRI, {
  contextHeader: '/context/'
})

Homegrown example

Here's what I did in a project to load a single

import hydraBox from 'hydra-box'
import $rdf from 'rdf-ext'
import Parser from '@rdfjs/parser-n3'
import { createReadStream } from 'fs'

const parser = new Parser({ baseIRI: process.env.BASE_URI })

async function hydraMiddleware () {
  const dataset = await $rdf.dataset()
    .import(parser.import(createReadStream(path.join(__dirname, 'hydra/api.ttl'))))

  return hydraBox('/api', dataset,
    {
      contextHeader: '/context/',
    }
  )
}

In the ultimate implementation I would propose to use a universal parser such as rdf-parse so that the developers can use any RDF format to author the Api Documentation.

[bergos]

The rdf-utils-fs package could need an update, then we can use it with a baseIRI argument.

One idea I had for the refactoring is to have a API class. It would contain the path for the hosting of the API documentation. It would also contain the dataset of the API documentation. To manipulate the API, we could add a .mapIRIs() method to change one namespace to another one. This would solve the problem you mentioned but also for formats/parsers that don't support baseIRIs.

The code could look like this:

hydraBox(Api
  .fromFile('api.nt', '/api')
  .mapIRIs('http://example.org/', 'http://localhost:8080/'))

[tpluscode]

Mhm, good point about base IRI not being possible for all formats.

But I would insist on loading from more than a single file. Even a relatively simple API will quickly grow to hundreds of lines in turtle. Breaking the graph into smaller chunks (for example per-SupportedClass) would make it more manageable

[bergos]

I think that would work very well with the API class approach. Besides the static .fromFile method, we could also have an instance method. Then other parts of the API can be merged like this:

hydraBox(Api
  .fromFile('api.nt', '/api')
  .fromFile('api2.nt')