csrd-versioning
API versioning, dispatch, docs, and actuator for FastAPI.
Package: csrd.versioning · Import: from csrd.versioning import compose_versioned_apps, configure_versioned_api
What's included
- Version dispatch — raw ASGI middleware for version-aware routing (streaming/SSE safe)
- Swagger UI — custom docs with version picker, dark mode, SRI hashes, plugin system
- Actuator — Spring Boot-style management endpoints (health, info, env)
- Exception handlers — structured
APIErrorResponseJSON for HTTP and validation errors - Dependency wiring — auto path-param injection, bearer guard opt-out
Installation
uv pip install "csrd-versioning @ git+ssh://git@github.com/csrd-api/fastapi-common.git#subdirectory=packages/versioning"
Quick start
from enum import Enum
from fastapi import FastAPI
from csrd.versioning import compose_versioned_apps, VersionedApiConfig, VersionedAppComposeConfig
class Versions(Enum):
Unversioned = "Unversioned"
V1 = "2025-06-20"
unv = FastAPI()
v1 = FastAPI()
app = compose_versioned_apps(
{Versions.Unversioned: unv, Versions.V1: v1},
config=VersionedAppComposeConfig(
api=VersionedApiConfig(prefix="api"),
),
)
Readiness gates for /_info/health
/_info/health (unversioned, used by container healthchecks) answers 200 as
soon as the app serves requests. Services with startup state that must exist
before they are useful pass health_gates; while any gate returns False
(or raises) the endpoint answers 503 {"status": "DOWN", "gates": {...}}:
from csrd.versioning import VersionedApiConfig, state_health_gate
api = VersionedApiConfig(
prefix="/",
# Ready once the lifespan put an initialised KeyRingManager on app.state
health_gates={"keyRing": state_health_gate("key_ring", "initialized")},
)
A gate is any Callable[[FastAPI], bool | Awaitable[bool]]. With no gates the
endpoint behaves as before. The actuator also auto-discovers a keyRing
indicator from app.state.key_ring.
Health-probe access logs
configure_versioned_api / compose_versioned_apps mount the unversioned
health endpoint INFO_HEALTH_PATH (/_info/health). Container healthchecks
probe it. The same call installs HealthProbeAccessLogFilter on the
uvicorn.access logger, so these probes stay out of the access log. Other
access lines are unaffected. The route and the filter use the same constant,
so they cannot drift apart. Installing is idempotent: one filter per process,
and further paths are added to it.
- Opt out:
VersionedApiConfig(suppress_health_access_log=False). - Custom paths, for an app without versioning:
install_health_access_log_filter(("/healthz",)).
Security notes
/actuator/env: TheShowValues.ALWAYSsetting exposes environment variable values. UseShowValues.NEVER(default) in production to redact sensitive data.- CORS: Add
CORSMiddlewarebefore callingconfigure_versioned_api. The version dispatch middleware must be the outermost middleware. Example:
app = FastAPI()
app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com"], ...)
configure_versioned_api(app, version_mapping, ...)
Dependencies
csrd-models,csrd-context(Tier 1 packages —csrd-versioningis Tier 3)- For JWT auth, use
csrd-authalongside this package
1 maintainer
Metadata
1 maintainer
Release files for csrd-versioning 0.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| csrd_versioning-0.8.0.tar.gz | 77.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| csrd_versioning-0.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 163.4 kB
Release files / csrd_versioning-0.8.0.tar.gz
| Download URL | csrd_versioning-0.8.0.tar.gz |
|---|---|
| Size | 77.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e1a548335e84abfc257657eef741b92dfe84ce4f9d061e84318602591f20134e
|
|
BLAKE2b-256 checksum How to use checksums |
6cde737a57885102259ed3bc9c4df82703eaf6414aa13dee5f3fa3ff99680786
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logRelease files / csrd_versioning-0.8.0-py3-none-any.whl
| Download URL | csrd_versioning-0.8.0-py3-none-any.whl |
|---|---|
| Size | 85.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0f15931c9d2f8a5517a429633128b4e03d298e4afbef2951b8c3045482cc3028
|
|
BLAKE2b-256 checksum How to use checksums |
9052149fdee466c84c7db1198a4c765672a1f07e46cf5d6b449e536f2036fa7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency log
