Before we start with this lesson, I'd like to quickly explain some terms and concepts upfront.
- What is an API? (Application Programming Interface) - API is just an interface that allows software to interact with another software;
- What is SDK? (Software Development Kit) - SDK is a set of tools used to develop software for a specific platform;
- What is the difference between API and SDK? - API is purposely built to allow specific communication between applications. SDKs allow for the creation of applications including APIs.
And the non-technical explanation - the SDK represents an entire office: all engineers, salespersons, furniture, and all office gear. An API represents just the Internet lines that allow communication in and out of the office.
Ok, now back to Cisco SD-WAN...
The Business Need
Legacy network devices were designed to be managed and operated by humans. They were not made to communicate natively to other software. That's why traditional networks are not extensible and automated in a native way. Nowadays, all other IT verticals are software-driven, so businesses are pushing the networks in that direction as well.
Cisco SD-WAN has been designed with automation and extensibility in mind. Cisco vManage provides northbound RESTful APIs that allow customers to build their own unique business logic on top of the SD-WAN solution. For example, enterprises can integrate their existing OSS (Operational Support System) and BSS (Billing Support System) tools and consume telemetry data, automate incident tickets creation and lifecycle, and automate the deployment of new services.
The northbound APIs open a new world of possibilities to network engineers as well. Many trivial operational tasks that consume lots of time and effort in a large-scale environment can be easily automated. For example, configuration audits, network/security audits, inventory reports, automated backup/restore, 3rd-party tools integration, and so on.
Let's take a look at the most typical use-cases.
vManage REST APIs provide endless possibilities for the automation of user-defined tasks. You can basically write software that can interact with the Cisco SD-WAN solution without human supervision. For the most simple cases, this software would be a python script. However, for more advanced scenarios, sophisticated Ansible playbooks can be leveraged.
One of the beauties of the vManage RESTful APIs is that they can be leveraged by other domain controllers, such as Cisco DNA Center or Cisco ACI, in order to deliver a unified single management plane across multiple technology verticals. This allows for the emergence of a single-pane-of-glass tool for service orchestration, configuration, administration, and troubleshooting. Such integration might finally allow for a full-scale intent-based network that can enforce business intend across the entire infrastructure from user to applications to cloud.
Technically, the REST APIs allow for the integration of non-Cisco SD-WAN controllers as well but at the current stage, interoperability between SD-WAN vendors is not present.
3rd-Party OSS, BSS, and SP tools
The vManage REST APIs allow Service Providers and MSPs to integrate their existing operational and billing systems (OSS/BSS). Most typical examples of such integrations are:
- Service and data usage statistics are collected using the RESTful APIs and then feed into the service provider's billing system;
- Using the RESTful API, service providers can design custom self-servicing portals that allow users to subscribe to new services or change the operational status of existing ones. For example, purchasing and deploying new SD-WAN security features, network segmentation and slicing, and so on;
- Automated deployment of new customers;
- CI/CD pipeline integrations, automated change scheduling, and rollbacks.
- SIEM (Security Information and Event Management) integrations, that can perform automated remediative actions against security alarms and incidents.
vManage's Embedded API Library
Cisco includes very sophisticated API documentation as part of the vManage software using the following URL:
A screenshot of the provided API library is shown in figure 2.
The documentation is divided into a few major categories of API calls:
- Certificate Management
- Device Inventory
- Real-Time Monitoring
- Troubleshooting Tools
When you select a particular API class. The documentation shows its response class, required parameters, and the returned status codes.
Table 1 below shows some typical examples of vManage API calls:
|Requested Info||API Call|
|Environment health status of device's hardware components||dataservice/device/hardware/environment?deviceId=system-ip-address|
|A list of all cisco sd-wan devices||dataservice/device|
|Status of the transport interfaces of a device||dataservice/device/interface?deviceId=system-ip-address&port-type=transport|
|Status of DTLS control connection||dataservice/device/control/connections?deviceId=system-ip-address|
|Interface statistics and packet drops||dataservice/device/interface?deviceId=system-ip-address|
|A list of OMP peers||dataservice/device/omp/peers?deviceId=system-ip-address|
|A list of BGP peers||dataservice/device/bgp/neighbors?deviceId=system-ip-address|
Cisco SD-WAN Python SDK
Cisco has provided a full-fledged Python-based SDK for Cisco vManage that has tools, libraries, and documentation to simplify the interactions with the REST API. It is intended for engineers interested in automating the administration and operation of the SD-WAN solution using Python without any GUI interaction.
There are many great things that you can do when using Cisco vManage programmatically. A few typical use-cases are:
- Software integrations with other platforms;
- Programatically keeping track of device status and acting upon change;
- Management of policies and device templates in an automated fashion;
- Automated backup and restore;
- CI/CD integrations;
- Automatic querying and aggregating of device and traffic statistics.