Declarative Amsterdam

Roaster - declarative routing for eXist-db

Juri LeinoeXist-solutions
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.
Presentation, 5 November 2021
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.