@hydrofoil/labyrinth

@hydrofoil/labyrinth

Labyrinth is an opinionated, batteries-included middleware for setting up a Hydra API with ease in data-centric manner.

It uses hydra-box internally and extends it to provide ready to use building blocks for rapid RDF-base API development.

Installation

npm i --save @hydrofoil/labyrinth

Setting up

Labyrinth exports an async factory function which creates an express handler.

import express from 'express'
import * as path from 'path'
import { hydraBox } from '@hydrofoil/labyrinth'

// base path to load JavaScript code referenced in Api Documentation
const codePath = path.join(__dirname, 'lib')
// path to load the Api Documentation from Turtle files
const apiPath = path.join(__dirname, 'hydra')
// base resource namespace
const baseUri = 'http://example.com/'

async function main() {
  const app = express()
    
  app.use(await hydraBox({
    codePath,
    apiPath,
    baseUri,
    path,        // (optional) ApiDocumentation URL path
    defaultBase, // (optional) base URI to parse API Documentation
    loader,      // (optional) hydra-box resource loader
    // SPARQL endpoint
    sparql: {
      endpointUrl, // Query
      updateUrl,   // (optional) Update 
      storeUrl,    // (optional) Graph Protocol,
      user,        // (optional) endpoint user name
      password     // (optional) endpoint password
    },
    options: {
      collection: {
        pageSize   // (optional) default page size of paged collections   
      }  
    },
    errorMappers: [] // (optional) map errors into problem+json
    middleware: {    // (optional) hydra-box middleware (arrays or function)
      operations,    // runs before final operation is selected. modify `req.hydra.operations` here
      resource,      // runs before operation is invoked. modify `req.hydra.resource` here
    }
  }))
  
  app.listen(8080)
}

main()

Features

• Generic handlers for getting individual resources
  • Eager loading linked resources
  • Resource preprocessor for custom resource logic before handler
• Generic hydra:Collection handler
  • Create any collection using hydra:manages block
  • Custom filtering
  • Ordering using property paths
  • Paging using hydra:pageIndex
• Secured using JWT tokens
  • Permission-based restrictions to operations
  • Restricting select properties or entire classes
• Error handling using Problem Details for HTTP APIs (RFC 7807)
  • See PDMLab/http-problem-details-mapper for instructions

Difference from hydra-box

In contrast to hydra-box it also makes some limiting assumptions:

• All resources are stored in triple store in named graph-per resource fashion
• Labyrinth provides its own loader which does SPARQL CONSTRUCT query to load said resources
  • Another loader can be used
• At the moment ApiDocumentation is only loaded from the filesystem. In the future loading from other sources may be added