Skip to content

cms-api

cms-api is the FastAPI service for the custom CMS (epic AISD-36) that replaces WordPress. It consumes hq.sql_models (the CMS data model) plus a dynamic DB connector, and serves several distinct REST surfaces from a single application factory.

What it serves

Block Prefix Audience Auth Mutating
Health /api infra / load balancers none no
Auth /admin/v1/auth admin UI (login) none (issues tokens) yes
Admin & editorial /admin/v1 cms-admin UI, editors, publishing workflows JWT + Redis session (admin role) yes
Public v1 /public/v1 comparison-app, public clients open / read-only no
Public v2 /public/v2 cms-cf-worker (Cloudflare Worker) worker API key (bearer) no

The two "shapes" of the service are the admin/editorial block (authenticated, mutating) and the public content blocks (read-mostly, cache/CDN-friendly). The public v2 surface is the worker-optimized read API designed in AISD-115 and built in AISD-116.

Documentation map

  • Architecture -- the app factory, the mount map, and the package layout under src/cms_api/.
  • Auth flow -- the two auth models: admin JWT + Redis sessions, and the worker API-key gate on /public/v2.
  • Request lifecycle -- how a request travels from middleware through routing, the auth dependency, the store, and back out through response shaping and cache headers.
  • Public v2 API -- the six worker-facing v2 endpoints, their parameters, schemas, the site resolver, and recorded deviations.
  • Store design -- the dual SqlPublicStore / MemoryPublicStore pattern and the shared v2_common shapers.
  • API reference -- autodoc generated from the module docstrings: Application, Authentication, Public store, Public v2 schemas.

Runtime

  • Python 3.12 (.python-version = 3.12; pyproject.toml pins >=3.12,<3.13).
  • FastAPI app factory in src/cms_api/main.py; boots uvicorn on :8080 for local development.
  • Configuration is ENVIRONMENT-driven and resolves secrets from AWS Secrets Manager via fs_config. ENVIRONMENT=test/local never touches AWS.

Build these docs locally

The doc toolchain is pinned in requirements_docs.txt and installed into a throwaway virtualenv (kept out of git by the .venv*/ rule), never the application venv:

cd cms-api
python3.12 -m venv .venv_docs && . .venv_docs/bin/activate
pip install -r requirements_docs.txt

# Strict build (the acceptance check): zero warnings, exit 0.
mkdocs build --strict

# Live-reload server at http://127.0.0.1:8000/
mkdocs serve

The mkdocstrings Python handler is configured with paths: [src], so it resolves identifiers such as cms_api.main and cms_api.public.store.sql against the package on disk without installing it.

Further reading (in-repo design artifacts)

These predate this portal and remain the authoritative contracts; they are linked here but not part of the nav:

  • docs/api-architecture.md -- the AISD-90 API architecture and the AISD-116 v2 field-to-table mapping.
  • docs/content-type-taxonomy.md -- the content-type taxonomy.
  • docs/openapi-admin.yaml / docs/openapi-public.yaml -- the OpenAPI contracts for the admin and public blocks.