Skip to content

API overview

fast-param-manager is the product's server: a FastAPI application over MongoDB, with authentication delegated to Keycloak and end-to-end OpenTelemetry instrumentation.

Responsibilities

Does Does not
Stores parameters grouped by application Notify anyone when a value changes
Validates the value against its declared type Coerce types automatically
Encrypts secret, user and users Keep a history of values
Authorizes writes by role Protect reads by default
Emits spans and metrics for every operation Negotiate client versions

Public surface

Three route groups, with different access regimes:

Prefix Purpose Who gets in
/auth Token issue and refresh, user info Open to issue, authenticated for userinfo
/parameters The application and parameter CRUD Varies per route — see Endpoints
/admin Runtime configuration Admin only

The route-by-route detail, with request and response bodies, is in Endpoints.

Data model

An application is a document; the parameters are a map inside it. Each parameter carries the value plus the metadata that governs validation:

{
  "value": "postgres://...",
  "description": "Connection string for the reporting database",
  "type": "secret",
  "user_editable": false,
  "min_length": 0,
  "max_length": 30,
  "min_value": 0,
  "max_value": 1000000,
  "referenced_params": null
}

The bound defaults are surprising

max_length defaults to 30 and min_value defaults to 0. That means a 40-character string is rejected and a negative number is rejected — in both cases without anyone having configured anything. The bounds are detailed in Parameter types.

On read, each parameter comes back enriched with audit metadata: created_at, created_by, updated_at and updated_by.

How a request crosses the API

The server is strictly layered, and one rule holds everything together: the controller never touches the database.

flowchart TD
    accTitle: Path of a request through the API
    accDescr: The request enters through the middleware that validates the Keycloak token, goes down through controllers, services and repositories, and ends at MongoDB. Keycloak, crypto_utils and OpenTelemetry sit alongside, wired to the layer that uses them.

    C["HTTP client<br/>param-manager · curl · frontend"]

    subgraph server["fast-param-manager"]
        direction TB
        M["middlewares/keycloak_auth<br/>validates RS256 JWT via PyJWKClient<br/>get_current_user · require_admin"]
        K["controllers/ — FastAPI routers<br/>wiring by Depends<br/>get_read_user resolves READ_AUTH_MODE<br/>off · warn · enforce"]
        S["services/ — business rules<br/>AppService · RuntimeConfigService<br/>_validate_permission · _encrypt_value"]
        R["repositories/ — Mongo access<br/>AppRepository · RuntimeConfigRepository<br/>compare-and-swap on params_version"]
    end

    D[("MongoDB<br/>singleton opened and closed by the lifespan")]
    KC["Keycloak — external<br/>issues and signs the token<br/>/auth/token · /refresh · /userinfo"]
    CR["security/crypto_utils<br/>PBKDF2 100k + AES-GCM<br/>salt · master_key · crypto_data"]
    OT["OpenTelemetry<br/>a span per operation<br/>+ metrics"]

    C --> M
    M --> K
    K --> S
    S --> R
    R --> D

    M -. JWKS .-> KC
    S -. secret/user/users .-> CR
    K -. span .-> OT
    S -. span .-> OT
    R -. span .-> OT

Each layer owns something the others are not licensed to take over: every business rule lives in services/, every data access in repositories/, and the controller merely translates HTTP into a business call. The per-layer detail, including the test contract that Depends injection creates, is in Architecture.

The access gate for each route — read, token or admin — is in the Endpoints table.

Versions that disagree

An honest warning for anyone about to package or release: there are currently three version declarations that contradict each other in the server repository.

Where Value
pyproject.toml 0.1.0
CHANGELOG.md 2.0.0
API_VERSION and service.version in traces 2.0.0

On top of that, CHANGELOG.md was hand-written in a format that does not match the configured title_format, and towncrier has never run on this project. Running towncrier build without resolving that first produces a corrupted changelog.