diff --git a/docs/apis/apis.md b/docs/apis/apis.md new file mode 100644 index 0000000..d149933 --- /dev/null +++ b/docs/apis/apis.md @@ -0,0 +1,19 @@ +--- +sidebar_position: 1 +--- + +# Data-Centric APIs + +Data-centric APIs are designed to provide a structured and standardized way to access and +manipulate data. Unlike traditional APIs that focus on specific functionalities or services, +data-centric APIs emphasize the data itself, making it easier to integrate, query, and manage data +across different systems. These APIs often leverage semantic web technologies, such as RDF and SPARQL, +to enable rich data interactions and ensure interoperability between diverse data sources. + +## Kopflos + +[Kopflos](./kopflos) is Zazuko's data-centric API platform that provides a flexible solution for managing and +exposing data as APIs. The name, "Kopflos," is a German word that means "headless," reflecting the +platform's focus on data rather than presentation. However, Kopflos is flexible enough to accommodate +various data models and use cases, making it suitable for a wide range of applications, full-featured +websites using the latest Web technologies. diff --git a/docs/apis/kopflos/_category_.yml b/docs/apis/kopflos/_category_.yml new file mode 100644 index 0000000..9706ee2 --- /dev/null +++ b/docs/apis/kopflos/_category_.yml @@ -0,0 +1,2 @@ +label: Kopflos +position: 2 diff --git a/docs/apis/kopflos/explanations/_category_.yml b/docs/apis/kopflos/explanations/_category_.yml new file mode 100644 index 0000000..c506892 --- /dev/null +++ b/docs/apis/kopflos/explanations/_category_.yml @@ -0,0 +1,2 @@ +label: Explanations +position: 3 diff --git a/docs/apis/kopflos/explanations/request-pipeline.md b/docs/apis/kopflos/explanations/request-pipeline.md new file mode 100644 index 0000000..8f6eb66 --- /dev/null +++ b/docs/apis/kopflos/explanations/request-pipeline.md @@ -0,0 +1,70 @@ +--- +title: Request pipeline +sidebar_position: 1 +--- + +# Kopflos request pipeline + +``` +Incoming Request + │ + └─▶ Kopflos handler + │ + 4**/5** ◀─┴─▶ Resource Shape Lookup + │ + 4**/5** ◀─┴─▶ Resource Loader Lookup + │ + 4**/5** ◀─┴─▶ Load Resource + │ + 4** ◀─┴─▶ Authorization + │ + 400 ◀─┴─▶ Validation + │ + 4**/5** ◀─┴─▶ (User handler) + │ + └─▶ Reply +``` + +## Incoming request + +Incoming request is handled by the server library, such as express or fastify and then forwarded to Kopflos. + +## Kopflos handler + +Kopflos handler is the main entry point for all incoming requests. It is responsible for orchestrating the request pipeline. + +## Resource Shape Lookup + +Resource Shape Lookup executes SPARQL against the `default` query endpoint to find the shape targeting the requested resource. + +:::tip +See also: [How to Select which resources should be served by the API](../how-to/resource-shape.md) +::: + +## Resource Loader Lookup + Load Resource + +When the Resource Shape is found, a resource loader is selected based from `kopflos:resourceLoader` property, going bottom-up from the Resource/Property Shape to the share `kopflos:Config` resource. + +It is used to load the requested resource's Core Representation. + +:::info +The Core Representation are the triples returned by the resource loader. Typically, that would be the result of a SPARQL `DESCRIBE` query or contents of resource's "own graph". +::: + +:::warning +By default, a loader which returns the resource's own graph is used. +::: + +## Authorization + +Not implemented yet. + +## Validation + +Not implemented yet. + +## User handler + +Finally, the handler is executed. If no handler is defined, and the request method is a GET, the resource's Core Representation is returned. + +The result of the handler is forwarded back to the server library to be sent as a response. diff --git a/docs/apis/kopflos/how-to/_category_.yml b/docs/apis/kopflos/how-to/_category_.yml new file mode 100644 index 0000000..405427a --- /dev/null +++ b/docs/apis/kopflos/how-to/_category_.yml @@ -0,0 +1,2 @@ +label: How-To +position: 2 diff --git a/docs/apis/kopflos/how-to/express-middleware.md b/docs/apis/kopflos/how-to/express-middleware.md new file mode 100644 index 0000000..d40b973 --- /dev/null +++ b/docs/apis/kopflos/how-to/express-middleware.md @@ -0,0 +1,87 @@ +# Use express middleware + +The package `@kopflos-cms/express` allows you to use existing express middleware in your Kopflos project. +To do that, add a plugin `@kopflos-cms/express/middleware` to your `kopflos.config.js` file with `before` +and `after` keys. + +The `after` middleware are only executed when kopflos handler returns a `404` status code or throws an error. + +## Middleware from NPM packages + +In your `kopflos.config.js` file, you can add references to other modules, such as `cors` or `compression`. + +The requirements are that every such module default-exports a function which returns the actual middleware. + +To provide an additional config, add a two element array instead of just the module name, as shown below +on the example of `compression`. + +```javascript +export default { + // ...other settings + plugins: { + '@kopflos-cms/express/middleware': { + before: [ + 'cors', + ['compression', { level: 9 }], + ], + }, + }, +} +``` + +You can also reference named exports by adding a `#name` after the modue name. For example, +to use [express-rate-limit](https://www.npmjs.com/package/express-rate-limit), you can do the following: + +```javascript +export default { + // ...other settings + plugins: { + '@kopflos-cms/express/middleware': { + before: [ + ['express-rate-limit#rateLimit', { + windowMs: 15 * 60 * 1000, + limit: 100, + }], + ], + }, + }, +} +``` + +## Your own middleware or NPM packages which do not export a function + +If you want to include your own middleware or a package which does not export a function, you can do so by +exporting a function from your own module. + +```js +// ./lib/my-middleware.js +export default function myMiddleware() { + return (req, res, next) => { + // your middleware code here + next(); + }; +} +``` + +Then, you can reference it in your `kopflos.config.js` file by the absolute path: + +```javascript +import * as url from 'node:url' + +export default { + // ...other settings + plugins: { + '@kopflos-cms/express/middleware': { + before: [ + url.fileURLToPath(new URL('./lib/my-middleware.js', import.meta.url)), + ], + }, + }, +} +``` + +:::warning +The path must be absolute, thus the usage of `import.meta.url` to resolve the path relative to the +config file itself. For that reason, this method will only work with configuration files written as +code. (for commonjs, you can use `__dirname` instead) +::: diff --git a/docs/apis/kopflos/how-to/html-templates.md b/docs/apis/kopflos/how-to/html-templates.md new file mode 100644 index 0000000..40c8576 --- /dev/null +++ b/docs/apis/kopflos/how-to/html-templates.md @@ -0,0 +1,170 @@ +# Serve RDF in data-bound HTML + +This guide will show you how to serve HTML templates bound to RDF data. + +:::warning +These features are a work in progress. +::: + +## Prerequisites + +In an existing kopflos application, install the following dependencies: + +```sh +npm install @kopflos-labs/html-template @kopflos-labs/handlebars +``` + +## Create a template + +A template is a combination of HTML `