python-opennms

An unofficial, dependency-minimal Python 3 client for the OpenNMS REST API (Horizon 30+ and Meridian). 100% coverage of the Meridian 2025 REST API reference, live-validated read and write — see Compatibility.

OpenNMS resources: Docs · REST API reference · Community forum

Full API reference →

Features

• Covers every v1 (/opennms/rest/) and v2 (/opennms/api/v2/) endpoint
• Plain dicts in, plain dicts out — the few endpoints that require XML or form-encoded bodies are handled internally
• Single runtime dependency: requests
• Synchronous and straightforward — no async complexity
• TypedDict schemas for all write payloads — field names, types, and docs in your IDE
• Typed exception hierarchy — catch NotFoundError, ForbiddenError, etc. without importing requests
• Pagination helper — client.paginate() yields all items from any list endpoint automatically
• Full test suite with method coverage (mocked HTTP — no live server required)
• Read and write smoke tests live-validated against the Meridian 2025 foundation

Installation

pip install python-opennms

From source (latest development version):

git clone https://github.com/cnewkirk/python-opennms.git
cd python-opennms
pip install .

Quick start

import opennms

client = opennms.OpenNMS(
    url="https://opennms.example.com:8443",
    username="admin",
    password="admin",
)

# Server info
info = client.get_info()
print(info["displayVersion"])

# List alarms
alarms = client.get_alarms(limit=25, order_by="lastEventTime", order="desc")
for alarm in alarms["alarm"]:
    print(alarm["id"], alarm["severity"], alarm["nodeLabel"])

# Acknowledge an alarm
client.ack_alarm(alarm_id=42)

# List alarms with FIQL filter (v2)
alarms = client.get_alarms_v2(fiql="severity==MAJOR")

Error handling

HTTP errors raise typed exceptions — no need to import requests:

import opennms

try:
    node = client.get_node(99999)
except opennms.NotFoundError:
    print("Node does not exist")
except opennms.ForbiddenError:
    print("Insufficient permissions")
except opennms.AuthenticationError:
    print("Check your credentials")
except opennms.OpenNMSError:
    print("Unexpected error")

Full hierarchy: OpenNMSHTTPError (base, exposes .status_code and .response) → BadRequestError (400), AuthenticationError (401), ForbiddenError (403), NotFoundError (404), ConflictError (409), ServerError (5xx).

Pagination

client.paginate() transparently handles limit/offset pagination and yields individual items:

# Fetch every MAJOR alarm — no manual offset loop required
for alarm in client.paginate(client.get_alarms, "alarm", severity="MAJOR"):
    print(alarm["id"], alarm["nodeLabel"])

# Works with any list endpoint
for node in client.paginate(client.get_nodes, "node"):
    print(node["id"], node["label"])

The optional page_size argument (default 100) controls how many items are fetched per request.

API coverage

Compatibility

Certified coverage baseline: OpenNMS Meridian 2025. This library covers 100% of the resource areas in the Meridian 2025 REST API reference apart from the three web-UI-internal APIs (Menu, Web Assets, UI Extension) — 66 of 69 documented areas. COVERAGE.md has the full matrix. Read and write paths are smoke-tested against the Meridian 2025 foundation build (opennms/horizon:foundation-2025, Horizon 34.0.1) via tests/live/compose.yaml.

Expected server range: Horizon 30+ and corresponding Meridian releases. The v1 write contracts this library speaks (XML creates, form-encoded updates, per the OpenNMS REST docs) are stable across versions, and the JSON-first endpoints rely on JSON support present since Horizon 30. Horizon releases before 30 are end-of-life and not supported. Only the certified baseline above is verified by live testing; reports from other versions are welcome.

Per-method version exceptions (also noted in the affected docstrings):

• Event configuration (/api/v2/eventconf) requires Horizon 35+.
• Maps (/rest/maps) was removed upstream in Horizon 16; those methods only function on pre-16 servers.

Validation history: 0.4.5 was smoke-tested read-only against Meridian 2024.3.0; 0.5.0 is smoke-tested read and write against the Meridian 2025 foundation.

Authentication

Basic authentication is used. Pass verify_ssl=False to disable certificate verification (useful for self-signed certs in lab environments):

client = opennms.OpenNMS(
    url="https://opennms.example.com:8443",
    username="admin",
    password="admin",
    verify_ssl=False,
)

Smoke testing

smoke_test.py exercises the wrapper against a real OpenNMS server. It is intended for use against a dev or staging instance before each release — not as a substitute for the mocked unit suite.

Tests that depend on optional plugins or heavy endpoints are reported as WARN (non-fatal) rather than FAIL. Each warning includes the specific plugin or feature required.

Read-only mode (default) is safe to run against any server, including production. It issues only GET requests and makes no changes.

export OPENNMS_URL="https://opennms.example.com:8443"
export OPENNMS_USER="admin"
export OPENNMS_PASSWORD="secret"
export OPENNMS_VERIFY_SSL="false"   # omit or set to "true" for valid certs
export OPENNMS_TIMEOUT="60"         # per-request timeout in seconds (default 60)

python smoke_test.py

Write mode creates and then deletes objects on the server (events, categories, groups, requisitions, etc.). It will prompt for explicit confirmation and print the target URL before running a single write. Only use write mode against a dev or staging instance — never production. The throwaway instance in tests/live/compose.yaml is a safe target.

python smoke_test.py --write          # interactive prompt required
python smoke_test.py --write --yes    # skip prompt (CI pipelines only)
python smoke_test.py --no-color       # plain output for log files
python smoke_test.py --skip get_resources,get_flow  # skip slow tests

The --skip flag accepts a prefix — --skip get_flow skips all tests whose label starts with get_flow.

Development

git clone https://github.com/cnewkirk/python-opennms.git
cd python-opennms
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v

Contributing

Bug reports and pull requests are welcome on GitHub.

Acknowledgements

All API shapes are derived from the official OpenNMS REST API documentation.

requests handles all HTTP communication. MkDocs Material renders the documentation site.

GitHub, Read the Docs, and PyPI generously provide source hosting, CI, versioned docs, and package distribution free of charge for open source projects.