Skip to main content

Management API

The OxiDNS management API is a separate control plane for health checks, configuration validation and persistence, process control, logs, upgrades, plugin extension APIs, and Prometheus metrics. This page is the interface map; detailed request formats, response fields, and examples live in topic pages.

  1. Configure listening, TLS, Basic Auth, CORS, and the WebUI through Conventions and Security.
  2. Check the listener with GET /api/healthz, then use GET /api/readyz for DNS service readiness.
  3. Validate configuration before saving it; apply it through reload and poll the reload status.
  4. Expose control, logs, upgrades, and plugin data only to trusted networks.
  5. Keep /api/metrics within the same access-control boundary as the management plane.

Interface map​

TopicMain routes
Conventions and SecurityListening, HTTPS/mTLS, Basic Auth, WebUI, CORS, route layout, configuration templates
Health, Control, Logs, and Upgrades/api/health*, /api/build, /api/control, reload, logs/SSE, and upgrade
Configuration APIRead, write, check, and validate configuration
Plugin Extension APIsCache, matcher, provider, reverse lookup, and query recorder
Prometheus Metrics/api/metrics and the metric catalog

Compatibility​

The management API reflects capabilities compiled into the current binary. Automation should inspect /api/build for bundle and plugin support and tolerate absent routes for optional plugins. Repeat readiness, configuration validation, and critical API smoke tests after an upgrade.