docs: configuring sparql endpoints

docs/apis/apis.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 1
+---
+
+# Data-Centric APIs
+
+TBD - introduce the concept of data-centric APIs

docs/apis/kopflos/_category_.yml

@@ -0,0 +1,2 @@
+label: Kopflos
+position: 2

docs/apis/kopflos/how-to/_category_.yml

@@ -0,0 +1,2 @@
+label: How-To
+position: 2

docs/apis/kopflos/how-to/sparql-endpoints.md

@@ -0,0 +1,66 @@
+# Configure SPARQL endpoints
+
+Kopflos can be configured with one or more SPARQL endpoints which can be accessed at runtime by
+handler implementors. A single endpoint is required, named `default`.
+
+To configure the endpoints, one of three methods is supported.
+
+## From endpoint URL
+
+The simplest option is to provide a single unauthenticated endpoint URL which will be used for queries and updates.
+
+```js
+import Kopflos from '@kopflos-cms/core'
+
+let graph
+
+const kopflos = new Kopflos(graph, {
+  sparql: {
+    default: 'http://example.com/query',
+  }
+})
+```
+
+## From endpoint configuration object
+
+A more complex scenario will often require separate query and update URLs and authentication. In such
+cases, provide a full settings object as required by [`sparql-http-client`](https://github.com/rdf-ext/sparql-http-client).
+
+```js
+import Kopflos from '@kopflos-cms/core'
+
+let graph
+
+const kopflos = new Kopflos(graph, {
+  sparql: {
+    default: {
+      endpointUrl
+    }
+  }
+})
+```
+
+## Provide instances of SPARQL clients
+
+Lastly, it is possible to create the clients manually in code and pass them to Kopflos. 
+Both `stream` and `parsed` clients are required.
+
+```js
+import StreamClient from 'sparql-http-client'
+import ParsingClient from 'sparql-http-client/ParsingClient.js'
+import Kopflos from '@kopflos-cms/core'
+
+let graph
+
+const stream = new SparqlClient({ endpointUrl })
+const parsed = new ParsingClient({ endpointUrl })
+
+const kopflos = new Kopflos(graph, {
+  sparql: {
+    default: {
+      stream,
+      parsed
+    }
+  }
+})
+```

docs/cubes/cubes.md

@@ -4,4 +4,4 @@ sidebar_position: 1
 
 # RDF Data Cubes
 
-This sections contains information about practical usage of RDF Data Cubes represented with the [cube.link Cube Schema](https://cube.link/).
+This section contains information about practical usage of RDF Data Cubes represented with the [cube.link Cube Schema](https://cube.link/).

docusaurus.config.mjs

@@ -83,6 +83,12 @@ const config = {
             position: 'left',
             label: 'Workflows',
           },
+          {
+            type: 'docSidebar',
+            sidebarId: 'apisSidebar',
+            position: 'left',
+            label: 'APIs',
+          },
           {
             type: 'docSidebar',
             sidebarId: 'cubesSidebar',

sidebars.js

@@ -17,6 +17,7 @@ const sidebars = {
   aboutSidebar: [{type: 'autogenerated', dirName: 'about'}],
   rdfjsSidebar: [{type: 'autogenerated', dirName: 'rdfjs'}],
   workflowsSidebar: [{type: 'autogenerated', dirName: 'workflows'}],
+  apisSidebar: [{type: 'autogenerated', dirName: 'apis'}],
   cubesSidebar: [{type: 'autogenerated', dirName: 'cubes'}],
 
   // But you can create a sidebar manually

src/components/HomepageFeatures/index.tsx

@@ -30,6 +30,16 @@ const FeatureList: FeatureItem[] = [
       </>
     ),
   },
+  {
+    page: '/docs/apis/',
+    title: 'APIs',
+    image: '/img/kopflos.png',
+    description: (
+      <>
+        Simply create APIs for your data-centric applications
+      </>
+    ),
+  },
   {
     page: '/docs/cubes/',
     title: 'Cubes',