Hub API and administration design¶

The Hub owns platform actions and Site resources. It provides the UI and the HTTP API used by platform automation. The OpenAPI files are the complete endpoint references:

• hub/src/ecmwf/sites/hub/static/specs/hub-api-spec.yaml (one file for both versions; it declares the v1 and v2 servers)
• hub/src/ecmwf/sites/hub/static/specs/site-api-spec.yaml

hub/tests/test_api_spec_coverage.py compares the specs with the routes in both directions: every route must be documented, and the spec must not document routes that do not exist. The Hub spec is compared against the registered Flask rules of the v1 and v2 blueprints; the Site spec is compared against the route registrations parsed from the Go source (site/.../api/main.go). Both spec files are Jinja templates; the test renders them with a fixed context. The Hub browser interface is documented in Hub web interface.

The Go Site API owns Site-volume operations. The boundary between the two APIs is described in Site API design.

Application assembly¶

hub/.../server.py builds the Flask application and registers, in order: the authentication blueprint, the redirects blueprint, the hub UI blueprint, the api_v1 and api_v2 blueprints, and the admin blueprint. It also:

• installs ProxyFix for the ingress-provided host, proto, and port headers;
• injects the branding template data and the requests_available context flag (true when a notification provider is active);
• registers app-level error handlers for 403, 404, 405, 410, 500, 502, 503, and for unhandled exceptions;
• registers the read-only and security-header rules (below) and the cross-site request forgery (CSRF) rule (see Authorization);
• installs the metrics counter hook when the metrics integration is active; the /hub/metrics/ route always exists and answers 503 while the integration is inactive (21).

Error shape. The two API blueprints register their own Exception handler: API failures return JSON ({status: ERROR, message}, code taken from the exception). The app-level handlers render the mapped error template instead, except when the request accepts JSON or its path contains /api/. The 405 handler is shared with read-only mode, so a blocked write returns JSON on API paths (Platform operations — Read-only mode).

CORS and audit. Every API route carries @cross_origin, imported from hub/src/ecmwf/sites/hub/cors.py. That wrapper forces Access-Control-Allow-Origin: * and never sends Access-Control-Allow-Credentials, whatever the call site passes. A browser page on another origin can therefore read a response only when it sends no cookie; session-cookie requests from other origins fail. The only routes without CORS headers are the specification routes of each version (/spec/ and /spec/swagger.json). Every API route carries the audit.log_access decorator except the high-frequency lookups that would flood the audit log: sites_status (polled by the Site view), users_list, sites_users_list, groups_list, sites_groups_list, and applications_list, in both versions. Those calls produce no action=access audit entries (17 — Logs and audit).

Web Server Gateway Interface (WSGI) serving layer¶

The Hub container starts with python -m ecmwf.sites.hub (hub/.../__main__.py): it reads /etc/build-date into BUILD_DATE, then launches Gunicorn with hub/.../conf/hub-gunicorn.py. There is no console_scripts entry point; python hub/.../server.py is the development run path and re-reads GUNICORN_WORKERS.

Scaling guidance for operators is in chart values — Hub concurrency.

Response minification. flask-minify (minify(app=...), no Go pipeline) minifies every rendered HTML page, including its inline CSS and JavaScript.

Static assets. The Hub serves static/, including a robots.txt asset (User-agent: *, Allow: /) reachable at /static/robots.txt. The platform publishes no /robots.txt route at the host root; site robots behaviour is the X-Robots-Tag feature of the site proxy (site proxy).

Request path and ownership¶

flowchart LR
    C["Hub UI or automation"] --> H["Hub API"]
    H --> K["Kubernetes API"]
    K --> CR["Site resource"]
    CR --> O["Site operator"]
    O --> W["Site workload"]
    C --> S["Site API for content operations"]

The Hub validates the request, applies the caller's role and Site access rules, then writes the Site resource or performs a platform action. The operator reconciles the resource. The Hub does not proxy Site content.

API versions and route groups¶

The Hub exposes v1 and v2 route groups (/hub/api/v1/, /hub/api/v2/). Both use the Hub authentication model; v2 is the current API surface for new automation. v2 repeats all 52 v1 route rules and adds exactly four endpoints; no route exists only in v1:

Differences that keep the same rules: v2 lists Sites with limit/offset pagination and returns a {total, offset, limit, count, items} envelope, while v1 returns the full filtered list with no pagination. The continuation_token query parameter is parsed on list requests for compatibility but never read: Hub pagination is limit/offset only. It is not the Site API's working continuation token (07 — Listing and download).

The exact paths, methods, request schemas, and response schemas are defined by the OpenAPI files and the route modules in hub/src/ecmwf/sites/hub/app/api/.

Tests¶

• hub/tests/test_api_spec_coverage.py — both specs against both route sources, in both directions.
• hub/tests/test_api_request_validation.py — request binding, list parameters, and the add/edit pre-initialization as administrator and non-administrator.
• hub/tests/test_csrf.py — the session CSRF rule end to end.
• hub/tests/test_sites_upgrade.py — force annotation and validation, lock 409 and release, role gates, and the failure-summary logging.
• hub/tests/test_sites_service.py, test_edit_site_reverted.py, test_notifications_required.py, test_routing_rules.py, test_oidc_initializer.py — listing and search, the public-to-private revert message, the 503 request gate, the read-only block rules, and the OIDC init file.
• Authentication internals: core/tests/test_api_authorization.py, test_authentication_chain_builder.py, test_master_token_compare.py, test_auth_view_utils.py.

Most app/api/common.py handlers (health, status, logs, export, backup, listings, analytics, restart, toggle) have no direct handler tests; they are covered through the UI flows at best. The table below is honest about it.

Behaviour requirements¶