ones-pyapi 0.1.2

Python SDK for ONES (Aviz Networks)

ones_pyapi

A modern, easy-to-use Python SDK for interacting with the ONES API. Designed for clarity, extensibility, and robust error handling.

---

Features

• Simple and intuitive API client for Datacenter NetOps
• Supports Day 1 (provisioning) and Day 2 (lifecycle) operations for SONiC-based switches
• Organized resources for users, health, inventory, BGP, control plane, and more
• Custom exception handling for robust error management
• Comprehensive test suite and example usage scripts
• Designed for extensibility and clarity in modern Python projects

---

Installation

pip install ones_pyapi

---

Quick Start

from ones.client import OnesClient

client = OnesClient(api_key="YOUR_API_KEY")

# Get user info
user = client.user.get(user_id="12345")
print(user)

# Check API health
health = client.health.status()
print(health)

# List inventory items
items = client.inventory.list()
for item in items:
    print(item)

---

Project Structure

ones_sdk/
│
├── ones/                     # main package
│   ├── client.py             # main entry point
│   ├── transport.py          # HTTP layer
│   ├── exceptions.py         # custom errors
│   ├── constants.py          # endpoints, paths
│   ├── resources/            # API groups
│   │   ├── user.py
│   │   ├── health.py
│   │   └── inventory.py
│   ├── utils/                # helpers
│   │   └── parser.py
│   └── models/               # (optional, later)
│       └── user.py
│
├── tests/                    # test suite
├── examples/                 # usage examples
├── requirements.txt
├── setup.py / pyproject.toml
└── README.md

---

API Reference

OnesClient

Initialization

client = OnesClient(api_key="YOUR_API_KEY")

User API

client.user.get(user_id)
client.user.create(data)
client.user.update(user_id, data)
client.user.delete(user_id)

Health API

client.health.status()

Inventory API

client.inventory.list()
client.inventory.get(item_id)
client.inventory.create(data)
client.inventory.update(item_id, data)
client.inventory.delete(item_id)

---

Examples

See examples/basic_usage.py for more.

---

Testing

pytest tests/

---

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Links

• PyPI Package
• GitHub Repository

Usage

examples/basic_usage.py

# examples/basic_usage.py

Basic Client Setup

All examples below use the following client initialization:

from ones.client import ONESClient

client = ONESClient(
    url="https://your-instance/",
    username="your_username",
    password="your_password"
)

client.connect()

---

User API

# List all users
print(client.user.list())

---

BGP API

BGP (Border Gateway Protocol) is the routing protocol used to exchange routing information between network devices (e.g., SONiC switches). These APIs provide visibility into BGP sessions, neighbors, and telemetry data.

# BGP List
bgp_list = client.bgp.bgp_list()
print("BGP List:", bgp_list)

# Neighbor List
neighbors = client.bgp.neighbor_list(device_address="xx:xx:xx:xx:xx:xx", vrf="default")
print("Neighbor List:", neighbors)

# Protocol Mega — aggregated BGP protocol telemetry over a time window
protocol_mega = client.bgp.protocol_mega(
    from_date="2026-03-23 10:09:36",
    to_date="2026-03-23 11:09:36",
    window_size="1 hour",
    device_address="xx:xx:xx:xx:xx:xx",
    vrf="default"
)
print("Protocol Mega:", protocol_mega)

# Protocol Neighbor Mega — aggregated BGP neighbor telemetry over a time window
protocol_neighbor_mega = client.bgp.protocol_neighbor_mega(
    from_date="2026-03-23 10:09:36",
    to_date="2026-03-23 11:09:36",
    window_size="1 hour",
    device_address="xx:xx:xx:xx:xx:xx",
    vrf="default"
)
print("Protocol Neighbor Mega:", protocol_neighbor_mega)

# BGP protocols for a specific IP
protocol_bgps = client.bgp.protocols_bgp(ip_address="x.x.x.x")
print("Protocol Map:", protocol_bgps)

# VLAN to BGP mapping
vlan_mapping = client.bgp.vlan_mapping(device_address="xx:xx:xx:xx:xx:xx")
print("VLAN Mapping:", vlan_mapping)

---

Control Plane API

Control Plane refers to the part of a network switch (such as SONiC) responsible for signaling, routing decisions, and protocol management. These APIs expose key control plane features:

• VLAN – Virtual LAN segmentation
• MCLAG – Multi-Chassis Link Aggregation Group for redundancy
• LACP – Link Aggregation Control Protocol for bonding ports
• VRRP – Virtual Router Redundancy Protocol for gateway failover

# VLAN
vlan_info = client.control_plane.vlan()
print("VLAN Info:", vlan_info)

# MCLAG
mclag_info = client.control_plane.mclag()
print("MCLAG Info:", mclag_info)

# LACP
lacp_info = client.control_plane.lacp()
print("LACP Info:", lacp_info)

# VRRP
vrrp_info = client.control_plane.vrrp()
print("VRRP Info:", vrrp_info)

---

Fabric Manager (FM) API

Day 1 Operations refer to the initial provisioning and configuration of network devices — defining intents, validating configurations, and deploying them to SONiC switches for the first time.

Day 2 Operations refer to ongoing lifecycle management after initial deployment — such as backing up configs, restoring previous states, applying patches, and monitoring config drift.

# --- Day 1: Fabric & Intent Management ---

# List all fabrics
fabrics = client.fm.listFabric()
print("Fabrics:", fabrics)

# Upload an intent (Day 1 — initial desired state definition)
client.fm.uploadIntent({"fabricId": "fab1", "intent": "..."})

# Validate the uploaded intent before applying
client.fm.validateIntent({"fabricId": "fab1"})

# Check validation results
validation = client.fm.getIntentValidation(fabricId="fab1")
print("Validation:", validation)

# Apply the intent to provision the fabric
client.fm.applyIntent({"fabricId": "fab1"})

# Check provisioning status
status = client.fm.getIntentStatus(fabricId="fab1")
print("Intent Status:", status)

# --- Day 2: Config Lifecycle Management ---

# Backup current device configuration
backup = client.fm.backupConfig({
    "data": [
        {"ip": "xx.xx.xx.xx", "label": "my-backup"}
    ]
})
print("Backup Config:", backup)

# Diff current config against last known good state
diff = client.fm.diffConfig(fabricId="fab1")
print("Config Diff:", diff)

# Restore a previously backed-up configuration
client.fm.restoreConfig({"fabricId": "fab1", "backupId": "bkp123"})

# Commit pending configuration changes
client.fm.commitConfig({"fabricId": "fab1"})

# Check config operation status
config_status = client.fm.getConfigStatus(fabricId="fab1")
print("Config Status:", config_status)

# --- Device Operations ---

# List devices in a fabric
devices = client.fm.listDevice(fabricId="fab1")
print("Devices:", devices)

# Reboot a device
client.fm.rebootDevice({"deviceId": "dev1"})

# Upgrade device firmware
client.fm.upgradeDevice({"deviceId": "dev1", "version": "4.2.0"})

# --- Tenant Management ---

# Add a tenant (logical network partition)
client.fm.addTenant({"fabricId": "fab1", "tenantName": "tenant-a"})

# List tenants
tenants = client.fm.listTenant(fabricId="fab1")
print("Tenants:", tenants)

# --- Job Tracking ---

# List all async jobs
jobs = client.fm.listJobs()
print("Jobs:", jobs)

# Get status of a specific job
job_status = client.fm.getJobStatus(jobId="job-001")
print("Job Status:", job_status)

---

Health API

These APIs provide telemetry and health metrics for SONiC-managed network devices, including CPU usage, interface states, and fabric-wide health summaries.

# List all managed devices
devices = client.health.device_list()
print("Devices:", devices)

# Device health info over a time range
info = client.health.device_info(
    from_date="2026-03-23 00:56:30",
    to_date="2026-03-24 09:56:30",
    window_size="1 hour",
    device_address="xx:xx:xx:xx:xx:xx"
)
print("Device Info:", info)

# Mega API — aggregated health telemetry over a time window
mega = client.health.mega(
    from_date="2026-03-23 12:05:44",
    to_date="2026-03-24 12:05:44",
    window_size="1 day",
    device_address="xx:xx:xx:xx:xx:xx"
)
print("Mega:", mega)

# Top CPU-consuming services on a device
top_services = client.health.top_cpu_consuming_services(
    device_address="xx:xx:xx:xx:xx:xx"
)
print("Top CPU Consuming Services:", top_services)

# Fabric-wide health summary
fabric_health = client.health.fabric_wise_health()
print("Fabric Wise Health:", fabric_health)

---

Inventory API

Inventory APIs expose hardware and software details of SONiC devices including interfaces, NICs, peripherals, firmware versions, and link topology.

# Device interfaces
interfaces = client.inventory.device_interfaces(device_address="xx:xx:xx:xx:xx:xx")
print("Device Interfaces:", interfaces)

# Device peripherals (PSU, fans, etc.)
peripherals = client.inventory.device_peripherals(device_address="xx:xx:xx:xx:xx:xx")
print("Device Peripherals:", peripherals)

# Device info
device_info = client.inventory.device_info(device_address="xx:xx:xx:xx:xx:xx")
print("Device Info:", device_info)

# Firmware version
firmware = client.inventory.device_firmware(device_address="xx:xx:xx:xx:xx:xx")
print("Device Firmware:", firmware)

# Link topology info
link_info = client.inventory.link_info(device_address="xx:xx:xx:xx:xx:xx")
print("Link Info:", link_info)

# Interface flap events — useful for diagnosing instability
interface_flaps = client.inventory.interface_flaps(
    start_time="2026-03-23 02:09:36",
    end_time="2026-03-24 11:09:36",
    limit=10
)
print("Interface Flaps:", interface_flaps)

# Interface telemetry mega — aggregated interface stats
interface_mega = client.inventory.interface_mega()
print("Interface Mega:", interface_mega)

# NIC info
nic_info = client.inventory.nic_info(device_address="xx:xx:xx:xx:xx:xx")
print("NIC Info:", nic_info)

# Full device details
device_details = client.inventory.device_details(device_address="xx:xx:xx:xx:xx:xx")
print("Device Details:", device_details)

# Orchestration inventory details
inv_details_orchest = client.inventory.inv_details_orchest()
print("Inventory Details Orchestration:", inv_details_orchest)

# YAML config files per device
device_yaml_files = client.inventory.device_yaml_files()
print("Device YAML Files:", device_yaml_files)

# Condensed inventory summary
mini_inventory = client.inventory.mini_inventory()
print("Mini Inventory:", mini_inventory)

---

Misc API

Miscellaneous APIs expose global platform settings and feature flags.

# Check if Fabric Manager is enabled
is_fm_enabled = client.misc.is_fm_enabled()
print("Is FM Enabled:", is_fm_enabled)

# World map topology data
world_map_data = client.misc.world_map_data()
print("World Map Data:", world_map_data)

# Check if AI assistant is enabled
is_ai_assistant_enabled = client.misc.is_ai_assistant_enabled()
print("Is AI Assistant Enabled:", is_ai_assistant_enabled)

# Retrieve illustrator YAML (topology visualization config)
illustrator_yaml = client.misc.get_illustrator_yaml()
print("Illustrator YAML:", illustrator_yaml)

# List regions
region_list = client.misc.region_list()
print("Region List:", region_list)

# Telemetry preferences
telemetry_preferences = client.misc.telemetry_preferences()
print("Telemetry Preferences:", telemetry_preferences)

---

Traffic API

Traffic APIs provide interface-level traffic telemetry for SONiC switches, including PFC (Priority Flow Control) — a lossless Ethernet mechanism used in data center networks to prevent buffer overflow on specific traffic priorities.

# Check if PFC is enabled on an interface
resp1 = client.traffic.is_interf_pfc_enabled(
    device_address="xx:xx:xx:xx:xx:xx",
    ifname="Ethernet1"
)
print("PFC Enabled:", resp1)

# List traffic profiles
resp2 = client.traffic.traffic_list(device_address="xx:xx:xx:xx:xx:xx")
print("Traffic List:", resp2)

# Interface details with layer and licensing context
resp3 = client.traffic.get_interface_details(
    device_address="xx:xx:xx:xx:xx:xx",
    hostname="switch1",
    ipaddress="192.168.1.1",
    layer="L2",
    time_bucket="5m",
    window_size=10,
    license_="standard"
)
print("Interface Details:", resp3)

# Detailed interface telemetry over a time range
resp4 = client.traffic.interface_details(
    from_date="2024-06-01T00:00:00Z",
    to_date="2024-06-02T00:00:00Z",
    window_size=10,
    device_address="xx:xx:xx:xx:xx:xx",
    active_tab="tab1",
    ifname="Ethernet1"
)
print("Interface Details (Time Range):", resp4)

# Aggregated traffic telemetry (mega)
resp5 = client.traffic.traffic_mega(
    from_date="2024-06-01T00:00:00Z",
    to_date="2024-06-02T00:00:00Z",
    window_size=10,
    device_address="xx:xx:xx:xx:xx:xx",
    active_tab="tab1",
    ifname="Ethernet1"
)
print("Traffic Mega:", resp5)

# QoS priority mapping for an interface
resp6 = client.traffic.priority_mapping(
    device_address="xx:xx:xx:xx:xx:xx",
    ifname="Ethernet1"
)
print("Priority Mapping:", resp6)

---

Copyright & Disclaimer

© 2026 Aviz Networks. All rights reserved.

For questions, support, or feature requests, please open an issue or contact the maintainers via GitHub.

---