What Is Cisco SD-WAN?

Cisco SD-WAN is a software-defined wide area network (WAN) solution that enables organizations to enable secure connectivity for users and applications. It provides software overlays that run over standard network transports such as Multiprotocol Label Switching (MPLS) links, broadband connections, and the public internet, aggregating all these into an efficient, reliable source of connectivity.

Cisco’s SD-WAN virtualized network runs on its widely deployed routing technologies, from physical branch routers such as the Cisco Catalyst 8000 Edge Platform Series to virtual machines in the cloud such as the Cisco vEdge Cloud router. These devices include centralized controllers that monitor the SD-WAN control plane, managing the configuration, maintenance, and security of the entire overlay network.

Cisco provides vManage, a visual network operations dashboard. It provides centralized configuration, management, operation, and monitoring across SD-WAN fabrics. vManage can be accessed programmatically, enabling API access to extract data, increase visibility, and provide actionable insights.

What Is Cisco SD-WAN vManage API?

The Cisco SD-WAN vManage API is a REST API for controlling, configuring, and monitoring Cisco devices in an SD-WAN overlay network spanning multiple data centers. The API can be used for equipment health monitoring, device configuration, such as attaching templates to devices, device statistics queries, and access to alerts.

vManage API capabilities include:

• Management of users, groups, and tenants, software maintenance, backup and recovery, and container management.
• Access to alerts, including setting up alerts and event notifications, querying existing alerts, and retrieving events and audit logs.
• Configuration of feature templates, device templates, device policies, device certificates, device behavior, operational status, retrieving device inventory, etc.
• Monitoring of equipment making up the SD-WAN fabric, including network devices, links, applications, and systems.
• Discovering device state, including health, usage statistics, and bulk queries on events and logs.
• Troubleshooting devices and the overlay network.

All data service API requests start with the following base URI:

https://<vmanage-server>/dataservice

Working With Request and Response Formats

Most vManage APIs use request payloads in JSON format. Responses can have one of several formats:

• Data block in JSON: In this format, there are two top-level JSON objects: header and data. The header contains a timestamp, column sections that defines display names and attributes for vManage UI data, and a fields section that defines the data type of the response data.
• Task/process ID: Some APIs take a lot of time to process, so they work asynchronously, immediately returning a task/process ID and allowing the client to check back when the operation is complete. The caller can use the ID to query the status of the request and get the result. The format of these asynchronous APIs is typically similar to this: {taskId: {task-uuid}}, {id: {uuid}}.
• Object ID: Some POST APIs return the object ID of the created object. It is then possible to retrieve the object containing the full response. Object IDs look this this: {"policyId":"124a06be-04a7-4037-9fce-e1536dfe9a40"}.
• Empty response body: Many of the APIs do not have response data in the body. In this case, the API has an empty response body.

Device and Monitoring APIs

List Devices

To retrieve the list of devices with vManage REST APIs:

1. Open a command prompt shell on Windows.

2. Use the following command to see what command line options are available in the Python application script named vManage_apis.py:py -3.7 vManage_apis.pyA sample response looks like the following:

3. Use the following command to make an API call that retrieves a listing of all the devices in the SD-WAN fabric:vManage_apis.py device-list

The response to this command brings us information like Host-name, Site-ID, and system-ip in tabular format:

On the backend, it runs a GET request to get the list of devices. Then, it stores the API’s returned JSON data in a variable. Specifically, it extracts the data portion of the JSON data and creates a table with the required fields.

Control Status

To get the control status through the vManage_apis.py:
Use the following command to get the control connection’s status:

py -3.7 vManage_apis.py control-status --system_ip 10.12.0.5

The command returns a response that shows the status of each control connection associated with a WAN edge router system:

The system’s IP address is specified with the --system_ip flag in the command. In this case, it is 10.12.0.5. On the backend, the API call uses the resource URI /device/control/synced/connections?deviceId= to fetch the control connections.

Network Interface Status

To retrieve the interface status of a system with vManage REST APIs:
Use the following command to get the interface status:

py -3.7 vManage_apis.py interface-status --system_ip 10.1.0.1

The command returns a WAN edge router system’s interface status as the response:

The command uses the interface-status option, and the API calls the resource URI device/interface/synced?deviceId=<system-ip>. It then retrieves the network device’s interface status.

Device Counters

To retrieve the number of devices associated with a system with vManage REST APIs:

Use the following command to get a count of a system’s associated devices:

py -3.7 vManage_apis.py device-counters --system_ip 10.1.0.1

The command returns information like the number of Overlay Management Protocol (OMP) Peers up or down and vSmart connections for a WAN edge router system’s interface status as the response:

On the backend, the API calls use the resource URI /device/counters?deviceId=<system-ip> to fetch the information about OMP Peers, vSmart connections, and BFD sessions.

System Status

To get the system status through the vManage API:
Run the following command to get the system status information:

py -3.7 vManage_apis.py system-status --system_ip 10.1.0.1

It returns a WAN edge router’s uptime, system version, memory, and CPU usage statistics. Specifically, it retrieves the information of a router with the system IP address 10.12.0.5:

On the backend, the API uses the resource URI /device/system/status?deviceId=<system-ip> to fetch such a network device’s system status. The <system-ip> part of the URI gets replaced with the IP address passed with the command.

Conclusion

In this article, I explained the basics of the Cisco SD-WAN API and showed how to perform a few common operations:

• List devices: Identifying devices that make up the SD-WAN network fabric
• Control status: Receive the operating status of each device (up or down) and related information
• Interface status: Receive the status of the network interfaces operated by the devices
• Device counters: Displaying the number of OMP peers and vSmart connections for each device
• System status: Detailed system status for a WAN edge router

I hope this will be useful as you step up your software-defined networking skills and learn to define networks as code.