Background
The Swagger UI at /docs covers all ingestion and sync operations, but it is designed for developers exploring an API — not for country health teams or HISP groups setting up a Climate API instance for the first time. The gap is discoverability and guided workflow, not missing functionality.
Goal
A simple management interface that lets operators ingest and sync data without needing to know API endpoint details or dataset template IDs.
Incremental implementation path
Step 1 — Show available dataset templates on the landing page
Extend the existing landing page (GET /) to list dataset templates from the YAML registry alongside the already-ingested datasets table. Each template row shows its name, variable, period type, and a link to the relevant Swagger endpoint or the management form (step 2).
This is zero JavaScript — server-rendered in the existing Jinja2 template. It immediately answers "what data can I ingest?" without leaving the landing page.
Step 2 — Server-rendered management forms at /manage
A new HTML page at GET /manage with simple server-rendered forms for the two most common operations:
Ingest a dataset
- Dropdown of available dataset templates (from the YAML registry)
- Start date / end date fields (pre-populated with sensible defaults)
- Extent pre-filled from the configured
CLIMATE_API_CONFIG extent
- Submit →
POST /ingestions
Sync
- Per-dataset sync buttons for ingested datasets
- Submit →
POST /sync
Status
- Current ingestion list with dataset name, temporal coverage, publication status, and last updated time — same data as the landing page datasets table but with action buttons alongside
Server-rendered HTML forms keep the implementation consistent with the landing page pattern (Jinja2 template, importlib.resources, no JS framework). Operations are synchronous — the form submits and the page reloads with the updated status. This is sufficient for guided first-time setup and manual re-sync.
Step 3 — Richer JS-based interface (future)
Live status updates, background job progress, and log streaming would require a JavaScript frontend. This is a separate effort and only makes sense once the user base and operational requirements are better understood.
Notes
GET /manage follows the same ?f=json content negotiation pattern as GET / — JSON clients can still access the underlying data.
- The management page should be linked from the landing page Explore section.
- No new dependencies are required — Jinja2 and Starlette form handling are already available.
- Authentication/authorisation is out of scope; Climate API instances are assumed to be deployed behind appropriate network controls.
Background
The Swagger UI at
/docscovers all ingestion and sync operations, but it is designed for developers exploring an API — not for country health teams or HISP groups setting up a Climate API instance for the first time. The gap is discoverability and guided workflow, not missing functionality.Goal
A simple management interface that lets operators ingest and sync data without needing to know API endpoint details or dataset template IDs.
Incremental implementation path
Step 1 — Show available dataset templates on the landing page
Extend the existing landing page (
GET /) to list dataset templates from the YAML registry alongside the already-ingested datasets table. Each template row shows its name, variable, period type, and a link to the relevant Swagger endpoint or the management form (step 2).This is zero JavaScript — server-rendered in the existing Jinja2 template. It immediately answers "what data can I ingest?" without leaving the landing page.
Step 2 — Server-rendered management forms at /manage
A new HTML page at
GET /managewith simple server-rendered forms for the two most common operations:Ingest a dataset
CLIMATE_API_CONFIGextentPOST /ingestionsSync
POST /syncStatus
Server-rendered HTML forms keep the implementation consistent with the landing page pattern (Jinja2 template,
importlib.resources, no JS framework). Operations are synchronous — the form submits and the page reloads with the updated status. This is sufficient for guided first-time setup and manual re-sync.Step 3 — Richer JS-based interface (future)
Live status updates, background job progress, and log streaming would require a JavaScript frontend. This is a separate effort and only makes sense once the user base and operational requirements are better understood.
Notes
GET /managefollows the same?f=jsoncontent negotiation pattern asGET /— JSON clients can still access the underlying data.