Declarative approach to routing requests in eXist-db
A brief introduction into the status quo, followed by a presentation of a new approach to declaratively design APIs and route requests with examples for several use cases.
I will explain the basics of routing in general.
After that, we will have a look at the status quo of routing requests in eXist-db.
In particular using rest, RestXQ and the controller.xq and their pros and cons.
- has some quirks
- does not encourage RESTful interface best-practices
- can be hard to secure
- route handlers can be somewhere in a package
- can lead to duplicate code for multiple output formats
- parameter handling authentication and error handling is left to the user
- can be hard to secure
- parameter, authentication and error handling is left to the user
- complex controllers can get hard to read
- can only pass strings as parameters to handlers
Because of said limitations of all routing options on exist-db I made several attempts to come up with a better solution that maps a route to a function.
2019 I had a series of small breakthroughs and a working prototype that roughly modelled after the express router known from nodeJS.
By mid 2020 Wolfgang Meier expressed the need for a better routing option to use with TEI-publisher. I showed him what I got and he ran with it.
He had the brilliant idea to implement the OpenAPI standard and thus created a router where you first create the documentation. You declare which routes exist and what they expect and return.
In this configuration you also set things like headers, mime-types and more.
This ongoing collaboration is now part of e-editiones, the same society that governs TEI-publisher.
At the beginning we will have a look at an example JSON file that declares a simple API of an exist-db package.
1. Using a test page created from our declaration
2. Looking at the JSON file itself
Then we will create a new route that will output different formats like (HTML, XML, JSON, CSV).
I will show how to set arbitrary headers per route, in a handler function, dynamically, for cacheing and also using a middleware for all routes.
To round things up, how to secure routes with cookies and basic auth, how to handle authorisation of requests and how to use a custom authentication method.
What are our medium and long-term goals and how can you contribute.