Skip to content

FastAPI ​

The FastAPI packages add Datum's server side to your own FastAPI application: form definitions served by id, submissions validated by the same program the page runs, the form and builder assets, PDF render, fill, sign and verify, and an RFC 3161 timestamp server. You include a router for each capability. A router adds a route only when its setting is on (the management router's health routes aside), and who may call it is your own FastAPI dependencies, never a Datum policy. The server hosts page compares the hosts.

Install ​

Python 3.12 or newer, asyncio. The packages are not published to PyPI yet: build the workspace from the repository, then add its members to your project with the extras you need.

sh
npm run fastapi:assets                  # the programs and browser files, from the repository root
cd integrations/fastapi && uv sync --all-packages --all-extras --frozen
ExtraAdds
submissionsThe programs, the sandbox runtime (datum-runtime-wasmtime) and the throttle
uisubmissions, plus the form and builder browser assets
pdfsubmissions, the PDF libraries and the PDF browser assets
timestampThe RFC 3161 server and client
revocationOffline revocation checking for the PDF trust policy
sqlalchemyThe library for SQL, see below
testingThe test helpers and an HTTP client for TestClient
allEvery extra but testing

datum-core is the framework-free core and imports no web framework. datum-fastapi adds the routers. datum-runtime-wasmtime runs the sandbox on wasmtime, which ships native libraries for 64-bit Linux (glibc and musl), macOS and Windows on x86_64 and arm64. datum-programs, the two asset distributions and the WASM runtime distribution carry the built programs, the browser files and the sandbox module. They must all be at one version, and the start refuses a mix.

The smallest application ​

Put the form definition in forms/intake.json, and set DATUM_FORMS__LOCATIONS='["forms/*.json"]'. The file's id is its key.

python
from fastapi import FastAPI

from datum_core.submissions import AcceptedSubmission, SubmissionReceipt
from datum_fastapi import DATUM_OPENAPI_TAGS, Datum, DatumSettings, routers


def keep(accepted: AcceptedSubmission) -> SubmissionReceipt:
    # a retried attempt may reach the handler twice: store once per (form_key, version, submission_key)
    return SubmissionReceipt(id="...", reference="...")


datum = Datum(config=DatumSettings().to_config(), handler=keep)

app = FastAPI(openapi_tags=DATUM_OPENAPI_TAGS)
app.include_router(routers.forms(datum))
app.include_router(routers.submissions(datum))

Without a handler the default logs the form, the channel and the receipt id, stores nothing, and the start warns once a route that takes submissions is on. Including a router also starts Datum, through its lifespan. If the application runs with lifespans off, every Datum route but /livez answers 503 server.unavailable.

Switching routers on ​

Every endpoint is off by default. Settings are read from environment variables (DATUM_ plus the dotted name in capitals, __ between levels), from a TOML file named by DATUM_CONFIG_FILE, or from keyword arguments to DatumSettings.

sh
export DATUM_WEB__API__ENDPOINTS__SUBMISSIONS=true
export DATUM_WEB__API__ENDPOINTS__VALIDATE=true
export DATUM_WEB__API__ENDPOINTS__DEFINITION=true
export DATUM_WEB__ASSETS__ENABLED=true
export DATUM_BUILDER__ENABLED=true
export DATUM_TSA__ENABLED=true

Settings are read in this order, the first source that names a setting wins: keyword arguments to DatumSettings, then environment variables, then the TOML file. datum.strict_env=true turns the warning about an unknown DATUM_* variable into a refusal to start. Every setting, with its default and bounds, is on FastAPI settings. The ones met most often are datum.web.api.max_body_size (1MiB), datum.web.api.problem_details, datum.runtime.validation.time_limit (5 s) and memory (32MiB), datum.host.time_zone, and datum.web.throttle.limit (60 per 60 s). A value that cannot work stops the start and names the setting, and an unknown DATUM_* variable is warned about. python -m datum_core.config.schema --out <path> writes the JSON Schema of every setting. The routes, bodies and codes behind these switches are on the wire.

Routers and endpoints ​

FactoryEndpointsSetting
routers.formsGET /api/forms/{key}/definition, GET /api/forms/{key}/translations, GET /api/data-sources/{id}datum.web.api.endpoints.definition, .data_sources
routers.submissionsPOST /api/submissions, POST /api/submissions/validate.submissions, .validate
routers.authoringPOST /api/submissions/test, POST /api/inspect.test, .inspect
routers.assetshost.json, datum-host.js and the bundles under /datum/assetsdatum.web.assets.enabled
routers.builderPOST /api/forms, PUT /api/forms/{key}, PUT /api/forms/{key}/translationsdatum.builder.enabled
routers.pdfPOST /api/pdf, /api/pdf/fill, /api/pdf/sign, /api/pdf/verify, GET /api/server/certificate.pdf, .fill, .sign, .verify, .certificate
routers.tsaPOST /tsa, GET /tsa/certificate, GET /tsa/certificatesdatum.tsa.enabled
routers.managementGET /livez, /readyz, /health, /info, and POST /recheckdatum.web.management.recheck for /recheck

The check route takes { document, scope } (and pageId for a page check): scope is required, and a bare envelope is 400 bad_document. It answers 200 { accepted, errors }, with notes for warnings only when there are any. An error or a note has a message when the sandbox or a validator gave one, and none otherwise. A run that fails gives no verdict. The check route, POST /api/submissions, the dry run, the PDF routes and POST /api/inspect all answer it 503 with the run's code (wasm.execution_error, outcome_too_large or, for a registered form nested too deep, definition.tooDeep) and no Retry-After, because the same run fails the same way. A definition posted to inspect that is nested too deep is the caller's: 422. Only a busy sandbox, 503 server.busy, carries Retry-After. The wire reference has the whole contract.

The dry run answers one flat report, the same on every Datum host. The wire reference lists its members. It has no accepted member and no nested report: read outcome, and the run's time is sandbox.elapsedMs.

Every factory takes prefix=, and every one but tsa takes dependencies=. The factories that run work for the caller or write (authoring, builder, pdf, management) require dependencies, so an unprotected router reads dependencies=[] in your source. At start the log lists the routes that are on, and warns (datum.W001) about a router included with every switch off. datum.enabled=false makes every router add nothing but the management router's health routes.

Hooks and stores ​

Everything you plug in is a keyword of Datum(...). A hook is a plain callable, sync or async, and a sequence keeps the order you give it.

KeywordPurpose
handlerStores the accepted submission and returns the receipt
pre_checksRefuse before the sandbox runs: (IncomingSubmission) -> Allow | Reject(code, message)
validatorsHost-side validation after the sandbox, with errors and warnings
rules_providers, context_contributors, host_options_customizersAdd host rules, context entries, or per-form run settings
host_contextWorks out the values a form's host. names read, from the request (see below)
definition_customizersAdjust the public copy of a form on its way to a filler
builder_save_customizers, builder_save_validatorsAdjust or judge a definition before it is stored
pdf_request_customizers, pdf_result_validatorsAdjust a PDF request, or judge the PDF before it leaves
form_repository, snapshot_store, translation_store, idempotency_storeWhere forms, versions, translations and receipts live
data_sourcesProviders for option lists
throttleYour own rate limiter, in place of the one built from datum.web.throttle
pdf_signer, timestamperThe seal key and where seals get their timestamps
signature_checkChecks a signed submission's signature (the passkey routes are not served, so a signed wrapper answers 503 signing.not_set_up by default)
timestamp_request_customizers, tsa_key_material, tsa_serial_allocator, tsa_log, tsa_client_store, tsa_time_source, tsa_transportThe timestamp server's policy hooks, signing key, serial numbers, issue log, clients, clock and the transport of the client
pdf_middleware, sandbox_middleware, pdf_trust_policyWrap the PDF program or the sandbox; decide which anchors make a signer trusted
pre_check_statusesMaps a pre-check's refusal to a status (403 and 429 by default)
runtime, sandbox, engine_settingsReplace the sandbox runtime or the engine's settings, for tests and special hosts
error_translators, run_log, listeners, now, withheld_assetsExtra error answers, the guest's run log, event listeners, the clock, assets the page glue must not serve

Customizers run in order, each over what the one before left, and the first refusal stops the rest. Validators all run, so every error is reported at once. A refusal is HookRefusedError: forbidden answers 403, conflict 409 and invalid 422, with a body of errors. Events follow the effect and never veto it: SubmissionValidatedEvent, SubmissionRejectedEvent, SubmissionThrottledEvent, SubmissionRedeliveredEvent, JourneyCheckedEvent, FormDefinitionSavedEvent, PdfRenderedEvent, PdfVerifiedEvent, TimestampIssuedEvent, TimestampRefusedEvent, DatumRuntimeReadyEvent and SandboxRunInterruptedEvent.

The stores that ship are in memory. The start warns (datum.W004) when a per-process store is in use, and fails (datum.E002) when the builder is on with in-memory stores and more than one worker. The timestamp server refuses to start with in-memory serials unless datum.tsa.allow_memory_stores acknowledges a single instance. The store protocols are the seam: implement one over your database and hold it to its contract with the classes in datum_core.testing.

The host context ​

A rule can read a fact about the visit, such as host.role. The server judges those rules only with values it works out itself. It never reads them from the request body. Give Datum one host_context provider. It takes the form key and the call's context, and answers a JSON object or None. Read the person from the context's principal, which your principal dependency answers from the request:

python
from fastapi import Request
from datum_fastapi import Datum

def current_user(request: Request) -> object | None:
    return getattr(request.state, "user", None)

def host_context(form_key: str, context) -> dict[str, str] | None:
    user = context.principal
    return {"role": user.role} if user is not None else None

datum = Datum(principal=current_user, host_context=host_context)

With no provider, or a provider that answers None, every rule that reads host. is left unjudged, as before. An object, even an empty one, judges every such rule, and a name it does not hold has no value. The provider is asked for the check route, submissions, the dry run and the PDF routes. A retried submission keeps its first verdict and asks nothing. The handler sees the same values as AcceptedSubmission.host_context, and a PDF is drawn with them. A provider that raises, or answers something that is not a JSON object within the sandbox's bounds (64 levels deep), is a fault in your application: the call answers 503 server.unavailable and nothing is judged. Values from the host shows the formulas.

Builder and drafts ​

datum.builder.enabled adds POST /api/forms, PUT /api/forms/{key} and PUT /api/forms/{key}/translations, and the author's copy at GET /api/forms/{key}/definition?public=false, which only routers.builder serves. Protect the router with dependencies=. A save is checked by the sandbox kernel and refused with 409 form.outdated when it builds on an out-of-date version. The bodies and codes are on the wire. With in-memory stores and more than one worker the start refuses a builder (datum.E002).

The router does not serve draft routes. A server: draft store calls four routes you write yourself: see Drafts.

Serving the form from the host ​

datum.web.assets.enabled serves host.json, the page glue datum-host.js and the bundles under their build id. Server hosts shows the page code and lists every DatumHost method.

Sealing PDFs and timestamps ​

The seal needs a key. Put it in files and name them.

sh
export DATUM_PDF__SEAL__ENABLED=true
export DATUM_PDF__SIGNING__TYPE=PKCS12
export DATUM_PDF__SIGNING__PKCS12_FILE=/etc/datum/seal.p12
export DATUM_PDF__SIGNING__PKCS12_PASSWORD=...
export DATUM_PDF__SEAL__TIMESTAMP=true
export DATUM_PDF__SIGNING__TSA__URL=https://tsa.example/tsa
SettingDoes
datum.pdf.seal.enabled, .layouts, .certify, .reason, .location, .visibleTurn the seal on, limit it to some layouts, and set what the signature says. Without a key the start warns (datum.W013).
datum.pdf.signing.type, .pkcs12_file, .pkcs12_password, .key_file, .cert_file, .key_passwordThe key: a PKCS#12 file, or a PEM key and a certificate chain. Or pass your own pdf_signer.
datum.pdf.seal.timestampAsk for a token over each seal. With no timestamp source the start warns (datum.W011).
datum.pdf.signing.tsa.url, .bearer_token, .basic_user, .basic_password, .policy, .timeoutA timestamp server you name. Or pass your own timestamper.
datum.pdf.signing.trust_anchors, .retired_certificatesAnchors the verify route builds a chain to, and the certificates the seal key replaced.
datum.pdf.seal.posted_answersSeal the PDFs of posted, unstored answers with the real key. Off, they keep a test seal.

The host's own timestamp server is datum.tsa.enabled with datum.tsa.policy, a signing key under datum.tsa.signer.*, and datum.tsa.access: clients (the default) requires a client key from your tsa_client_store, and open lets anyone ask within the flood limits. Every setting is on FastAPI settings.

Access control ​

Datum ships no access policy. Pass your own FastAPI dependencies, and they run before Datum's own checks, so a refused caller meets your 401 or 403 first.

python
from fastapi import Depends

app.include_router(routers.builder(datum, dependencies=[Depends(require_author)]))
app.include_router(routers.management(datum, dependencies=[Depends(require_operator)]))

FastAPI(exception_handlers=access_errors(datum)) gives your 403 the catalog's access.denied body. Datum(principal=..., locale=...) take dependencies that name the caller and the language for the hooks. Behind a proxy let the ASGI server decide request.client (uvicorn's --proxy-headers), because the throttle never reads X-Forwarded-For itself. FastAPI has no CSRF protection of its own and Datum adds none, but the JSON endpoints accept application/json only. The definition with its server-secret rules is reachable only through routers.builder.

Testing ​

Starlette's TestClient as a context manager runs the lifespan, so Datum starts once for the block. Share one app across a module's tests, because the runtime compiles its sandbox module on start. Install the testing extra. To test without the sandbox, pass runtime= or sandbox= to Datum.

datum_core.testing has contract classes that hold a store of your own to its protocol. To check a running deployment against the wire contract, run datum-host-check from the conformance suite.

Health and logs ​

Requests are named in the logs by the X-Request-ID header, or the trace id. The management router's /health reports the runtime and the stores, and /readyz reads the runtime alone. Datum's own checks log under datum.checks with stable ids; datum.silenced_checks silences a notice or a warning by id (never an error). FastAPI settings lists every id, its cause and what to do about it.

What is not served ​

FastAPI serves no passkey routes, so a form cannot require a passkey signature here, and DatumHost.passkeys() is refused in the page unless you pass an endpoint. No SQL store ships either: the sqlalchemy extra installs the library, and the stores that ship are in memory. To run more than one worker, see Server hosts.

Supported versions ​

Python 3.12 and later. FastAPI 0.133 or newer and Starlette 1.x. wasmtime-py is held to one tested major at a time.

Every setting is on FastAPI settings, and every route on The wire.

MIT licence. Your forms, your data, your keys.