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.