Roaster - declarative routing for eXist-db
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.
Introduction
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.
- rest
- has some quirks
- does not encourage RESTful interface best-practices
- can be hard to secure
- restXQ
- 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
- controller.xq
- 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
History
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.
Hands-On
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's next?
What are our medium and long-term goals and how can you contribute.
Juri Leino is a software gardener from Berlin with over 15 years of experience in web development. In most recent years he has joined the exist-db project as a core developer focussing on the XQuery runtime. Next to consulting for exist-solutions and jinntec he also maintains and develops node-exist and gulp-exist and created XQuery libraries like xbow, exist-jwt and dicey.