ones_pyapi

---

Table of Contents

• Features
• Installation
• Quick Start
• Project Structure
• Client Initialization
• API Reference
  • User API
  • BGP API
  • Control Plane API
  • Fabric Manager API
  • Health API
  • Inventory API
  • Misc API
  • Traffic API
• Testing
• Contributing
• License

---

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

fromones.clientimportONESClientclient=ONESClient(
url="https://your-instance/",
username="your_username",
password="your_password"
)
client.connect()
# List all usersprint(client.user.list())
# Check fabric-wide healthprint(client.health.fabric_wise_health())
# List inventory itemsprint(client.inventory.mini_inventory())

---

Project Structure

ones_sdk/
│
├── ones/ # Main package
│ ├── client.py # Main entry point
│ ├── transport.py # HTTP layer
│ ├── exceptions.py # Custom errors
│ ├── constants.py # Endpoints and paths
│ ├── resources/ # API resource groups
│ │ ├── user.py
│ │ ├── health.py
│ │ ├── inventory.py
│ │ ├── bgp.py
│ │ ├── control_plane.py
│ │ ├── fm.py
│ │ ├── misc.py
│ │ └── traffic.py
│ ├── utils/ # Helper utilities
│ │ └── parser.py
│ └── models/ # Data models (optional)
│ └── user.py
│
├── tests/ # Test suite
├── examples/ # Usage examples
├── requirements.txt
├── setup.py / pyproject.toml
└── README.md

---

Client Initialization

All examples in this document use the following client setup:

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

---

API Reference

User API

# List all usersprint(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.

# List all BGP entriesbgp_list=client.bgp.bgp_list()
print("BGP List:", bgp_list)
# List BGP neighbors for a deviceneighbors=client.bgp.neighbor_list(
device_address="xx:xx:xx:xx:xx:xx",
vrf="default"
)
print("Neighbor List:", neighbors)
# Aggregated BGP protocol telemetry over a time windowprotocol_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)
# Aggregated BGP neighbor telemetry over a time windowprotocol_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 IPprotocol_bgps=client.bgp.protocols_bgp(ip_address="x.x.x.x")
print("Protocol BGPs:", protocol_bgps)
# VLAN to BGP mappingvlan_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 responsible for signaling, routing decisions, and protocol management. These APIs expose the following features:

Feature	Description
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 infovlan_info=client.control_plane.vlan()
print("VLAN Info:", vlan_info)
# MCLAG infomclag_info=client.control_plane.mclag()
print("MCLAG Info:", mclag_info)
# LACP infolacp_info=client.control_plane.lacp()
print("LACP Info:", lacp_info)
# VRRP infovrrp_info=client.control_plane.vrrp()
print("VRRP Info:", vrrp_info)

---

Fabric Manager (FM) API

Operation Type	Description
Day 1	Initial provisioning and configuration — defining intents, validating, and deploying to SONiC switches
Day 2	Ongoing lifecycle management — backups, restores, patches, and config drift monitoring

Day 1 — Fabric & Intent Management

# List all fabricsfabrics=client.fm.listFabric()
print("Fabrics:", fabrics)
# Upload an intent (initial desired state)client.fm.uploadIntent({"fabricId": "fab1", "intent": "..."})
# Validate the uploaded intent before applyingclient.fm.validateIntent({"fabricId": "fab1"})
# Check validation resultsvalidation=client.fm.getIntentValidation(fabricId="fab1")
print("Validation:", validation)
# Apply the intent to provision the fabricclient.fm.applyIntent({"fabricId": "fab1"})
# Check provisioning statusstatus=client.fm.getIntentStatus(fabricId="fab1")
print("Intent Status:", status)

Day 2 — Config Lifecycle Management

# Backup current device configurationbackup=client.fm.backupConfig({
"data": [{"ip": "xx.xx.xx.xx", "label": "my-backup"}]
})
print("Backup Config:", backup)
# Diff current config against last known good statediff=client.fm.diffConfig(fabricId="fab1")
print("Config Diff:", diff)
# Restore a previously backed-up configurationclient.fm.restoreConfig({"fabricId": "fab1", "backupId": "bkp123"})
# Commit pending configuration changesclient.fm.commitConfig({"fabricId": "fab1"})
# Check config operation statusconfig_status=client.fm.getConfigStatus(fabricId="fab1")
print("Config Status:", config_status)

Device Operations

# List devices in a fabricdevices=client.fm.listDevice(fabricId="fab1")
print("Devices:", devices)
# Reboot a deviceclient.fm.rebootDevice({"deviceId": "dev1"})
# Upgrade device firmwareclient.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 tenantstenants=client.fm.listTenant(fabricId="fab1")
print("Tenants:", tenants)

Job Tracking

# List all async jobsjobs=client.fm.listJobs()
print("Jobs:", jobs)
# Get status of a specific jobjob_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 devicesdevices=client.health.device_list()
print("Devices:", devices)
# Device health info over a time rangeinfo=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)
# Aggregated health telemetry over a time windowmega=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 devicetop_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 summaryfabric_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 interfacesinterfaces=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 infodevice_info=client.inventory.device_info(device_address="xx:xx:xx:xx:xx:xx")
print("Device Info:", device_info)
# Firmware versionfirmware=client.inventory.device_firmware(device_address="xx:xx:xx:xx:xx:xx")
print("Device Firmware:", firmware)
# Link topology infolink_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)
# Aggregated interface telemetryinterface_mega=client.inventory.interface_mega()
print("Interface Mega:", interface_mega)
# NIC infonic_info=client.inventory.nic_info(device_address="xx:xx:xx:xx:xx:xx")
print("NIC Info:", nic_info)
# Full device detailsdevice_details=client.inventory.device_details(device_address="xx:xx:xx:xx:xx:xx")
print("Device Details:", device_details)
# Orchestration inventory detailsinv_details_orchest=client.inventory.inv_details_orchest()
print("Inventory Details (Orchestration):", inv_details_orchest)
# YAML config files per devicedevice_yaml_files=client.inventory.device_yaml_files()
print("Device YAML Files:", device_yaml_files)
# Condensed inventory summarymini_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 enabledis_fm_enabled=client.misc.is_fm_enabled()
print("Is FM Enabled:", is_fm_enabled)
# World map topology dataworld_map_data=client.misc.world_map_data()
print("World Map Data:", world_map_data)
# Check if AI assistant is enabledis_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 regionsregion_list=client.misc.region_list()
print("Region List:", region_list)
# Telemetry preferencestelemetry_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 interfacepfc_status=client.traffic.is_interf_pfc_enabled(
device_address="xx:xx:xx:xx:xx:xx",
ifname="Ethernet1"
)
print("PFC Enabled:", pfc_status)
# List traffic profilestraffic_list=client.traffic.traffic_list(device_address="xx:xx:xx:xx:xx:xx")
print("Traffic List:", traffic_list)
# Interface details with layer and licensing contextinterface_details=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:", interface_details)
# Detailed interface telemetry over a time rangeinterface_details_range=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):", interface_details_range)
# Aggregated traffic telemetrytraffic_mega=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:", traffic_mega)
# QoS priority mapping for an interfacepriority_mapping=client.traffic.priority_mapping(
device_address="xx:xx:xx:xx:xx:xx",
ifname="Ethernet1"
)
print("Priority Mapping:", priority_mapping)

---

Testing

pytest tests/

---

Contributing

Contributions are welcome! For major changes, please open an issue first to discuss what you would like to change. Ensure all tests pass before submitting a pull request.

---

License

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

---

Links

• PyPI Package
• GitHub Repository

---

© 2026 Aviz Networks. All rights reserved.

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