sdmxlib-rest

A generic SDMX-REST HTTP surface over a sdmxlib LocalRegistry.

It owns the parts of an SDMX-REST service that are the same everywhere — URL grammar, content negotiation, localisation, streaming, response assembly — and leaves everything catalog-specific to the consumer, behind explicit seams.

from sdmxlib_rest.app import RestSettings, create_app, library_routers
from sdmxlib_rest.runtime import CatalogRuntime

runtime = CatalogRuntime(MyCatalogProvider())
app = create_app(
    runtime,
    RestSettings(title="my-sdmx-api", version="1.0.0"),
    routers=list(library_routers()),
)

That serves the structure, metadata and availability planes. Serving data is the consumer's job — see Why there is no data route below.

What you supply

Everything catalog-shaped is a Protocol on CatalogRuntime, each with a no-op default. A bare consumer implements only the first one.

The defaults are all inert, not broken: a consumer that installs none of them gets a correct service, just one that recomputes more than it needs to.

What create_app gives you

Routes are the easy part. The assembly is what's worth not rewriting:

• The middleware stack, in the one order that works. The chain has real adjacency constraints — the ETag has to hash uncompressed bytes, so it runs inside compression; ?lang= has to rewrite the header before the ETag layer reads it; CORS has to be outermost or preflights fall through to a 404 that browsers report as a CORS failure. Each constraint is documented at _install_middleware.
• Runtime sharing across mounts, so a service exposing several surfaces (a canonical one plus compatibility variants) opens the registry once.
• A multi-spec docs page, which has to be hand-rolled because FastAPI's helper emits a single-spec page and Swagger UI renders nothing when given both url and urls.

Why there is no data route

The library owns data-plane helpers — key and query-parameter parsing, projection, paging headers, binding-driven SQL fragments, and the arrow→CSV/parquet encoders, all under sdmxlib_rest.data. It does not own the /data route itself.

That is deliberate. Orchestration is where response caching, partition pushdown and vendor extensions live, and every catalog shapes those differently — one catalog's hierarchy descent and partition-pruning tricks are noise to the next. A second consumer gets the hard, fiddly parts and writes its own handler around them.

Status

Extracted from a production SDMX-REST service and versioned independently from 0.1.0. The seam set is settled; the create_app signature may still move before 1.0.

Licence

Apache-2.0.