I'm trying to understand the bidi yada aleph integration, the handler that alephs expect is a yada handler that has a uri param that is destructured by bidi?

The integration is optional and has 2 parts. First, if bidi vhosts are used, there will be an function placed in the request that provides the URL formation facility, and yada/url-info and friends provide convenient access.

Second, a yada handler is a record that satifies Bidi's Ring protocol, allowing it to be used as the righthand-side of a route pair.

For convenience, yada resource records also satisfy bidi's Ring protocol, so you don't have to wrap a resource in a handler record to put in a bidi route structure. This convenience actually makes the tree more naked data so easier to postwalk and process

The api-as-pure-data approach is useful. On Monday I have some client work to generate a PDF API document from it, should be straight-forward enough.