ABC of Cisco SDWAN Viptela

API Calls
RESTful API for vManage NMS
The vManage NMS supports a RESTful (Representational State
Transfer) API, which provides calls for retrieving real-time and static
information about the Viptela overlay network and the devices in the
network and for uploading device configuration templates and other
configuration-related information.

Using the RESTful API, you can design a custom portal for interacting
with the vManage NMS.
API calls are provided for the following categories of operations:

•Certificate Management
•Configuration
•Device and Device Inventory
•Monitoring
•Real-Time Monitoring
•Troubleshooting Tools
 Using the vManage REST APIs
The Viptela software provides a REST API, which is a programmatic interface
for controlling, configuring, and monitoring the Viptela devices in an overlay
network. You access the REST API through the vManage web server.
A REST API is a web service API that adheres to the REST, or
Representational State Transfer, architecture. The REST architecture
uses a stateless, client–server, cacheable communications protocol. The
Viptela vManage NMS web server uses HTTP and its secure counterpart,
HTTPS, as the communications protocol. REST applications communicate over
HTTP or HTTPS using standard HTTP methods to make calls between network
devices. These standard HTTP methods include:

•GET—Retrieve or read information.

•PUT—Update an object.
•POST—Create an object.
•DELETE—Remove an object.
REST is a simpler alternative to mechanisms such as remote
procedure calls (RPCs) and web services such as Simple Object
Access Protocol (SOAP) and Web Service Definition Language
(WSDL). The REST architecture has not been formally defined by any
standards bodies.
Available API Calls
The Viptela REST API calls expose the functionality of Viptela software and
hardware features and of the normal operations you perform to maintain
Viptela devices and the overlay network itself. In REST API terminology, each
of these features or operations is called a resource. A resource is an object
with a type, associated data, relationships to other resources, and a set of
methods that operate on it.
Resources are grouped into collections. Each collection contains a single
type of resource, and so is homogeneous. In the Viptela REST API, the
collection of resources is present at the top level of the API. The Viptela REST
API resources are grouped into the following collections:
Resource Resources for
Collection
Administration Managing users and user groups, viewing audit logs, and
managing the local vManage server.
Certificate Managing certificates and security keys.
Management
Configuration Creating feature and device configuration templates, retrieving
the configurations in existing templates, and creating and
configuring vManage clusters.
Device Inventory Collecting device inventory information, including serial
numbers and system status.
Monitoring Viewing status, statistics, and other information about
operational devices in the overlay network. Monitoring
information is what Viptela devices collect about themselves
every 10 minutes. After collecting these statistics, each Viptela
device places them into a zip file. The vManage server retrieves
these zip files every 10 minutes or, if the vManage server
cannot log in to the device, it retrieves them whenever it is next
able to log in.
Resource Resources for
Collection
Real-Time Monitoring Retrieving, viewing, and managing real-time statistics and
traffic information. Real-time monitoring information is gathered
in real time, approximately once per second.
Troubleshooting Troubleshooting devices, for determining the effect of policy, for
Tools updating software, and for retrieving software version
information.
Resource Data
The Viptela REST API uses the JavaScript Object Notation (JSON) data model
to represent the data associated with a resource. JSON has three types of
data:

•Scalar—Data types with a single value. Scalar types include numbers,

strings, and Booleans.
•Array—Ordered lists of values of an arbitrary type.
•Object—Unordered set of key: value pairs (also referred to as attributes),
where key is a string and the value can have an arbitrary type.
REST Methods
In a REST API, methods are executed on resources and
collections. The Viptela REST API uses the following standard
REST methods:

Metho Scope Shown Operation

d As
DELETE Resource Red Delete a resource
GET Collection, Blue Retrieve(or read) all resources in a
Resource collection or retrieve a single resource

POST Collection Green Create a new resource in a collection

PUT Resource Brown Update a resource

Viptela API Library & Documentation
A common REST principle is that APIs should be self-descriptive and self-documenting.
The resource collections and resources in the Viptela REST API are self-documenting,
describing the data you need to make a call and the response from each call. However,
the collections and resources do assume that you are familiar with the Viptela overlay
network concepts, software and hardware features, and capability.

The vManage REST API library and documentation are bundled with and installed on the
vManage web application software. To access the API documentation from a web
browser, use this URL:

https://ip-address:port/apidocs
Requested Information API Call
List all network devices dataservice/device
Health status of hardware device dataservice/device/hardware/environment?
components, such as CPU, memory, fan, deviceId=system-ip-address
and power
Status of a device's transport interfaces dataservice/device/interface?
deviceId=system-ip-address&port-
type=transport
Interface statistics, errors, and packet dataservice/device/interface?
drops deviceId=system-ip-address
dataservice/device/control/connections?
DTLS/TLS control connection status
deviceId=system-ip-address
dataservice/device/omp/peers?
OMP peering
deviceId=system-ip-address
dataservice/device/bgp/neighbors?
BGP peering on the service side
deviceId=system-ip-address
API calls for real-time monitoring of vBond orchestrator
information:

• Connections
• Connections History
• Local Properties
• Summary
• Valid vEdge Routers
• Valid vSmart Controllers
Connections
List the Viptela devices that have active DTLS connections to the vBond
orchestrator (on vBond orchestrators only).

CLI Equivalent: show orchestrator

connections URL:
https://vmanage-ip-address/dataservice/device/orchestrator/connections?
deviceId=deviceId

https://198.18.1.10/dataservice/device/orchestrator/connections?deviceI
d=11.11.11.11
Connections History
List the history of connections and connection attempts made by
the vBond orchestrator (on vBond orchestrators only).

CLI Equivalent: show orchestrator connections-history

URL:
https://vmanage-ip-address/dataservice/device/orchestrator/conn
ectionshistory?deviceId=deviceId
Local Properties
Display the basic configuration parameters of a vBond orchestrator
(on vBond orchestrators only).

CLI Equivalent: show orchestrator local-properties

URL:
https://vmanage-ip-address/dataservice/device/orchestrator/localpr
operties?deviceId=deviceId
Summary
Display a count of the vEdge routers, vManage Network
Management Systems (NMSs), and vSmart controllers in the
overlay network (on vBond orchestrators only). For vBond
orchestrators running on virtual machines (VMs) that have more
than one core, this API call shows the number of devices that
each vdaemon process is handling.

CLI Equivalent: show orchestrator summary

URL:
https://vmanage-ip-address/dataservice/device/orchestrator/sum
mary?deviceId=deviceId
Valid vEdge Routers List the chassis numbers of the valid vEdge
routers in the overlay network (on vBond orchestrators only).

CLI Equivalent: show orchestrator valid-vedges

URL:
https://vmanage-ip-address/dataservice/device/orchestrator/valid
vedges?deviceId=deviceId
Valid vSmart Controllers List the serial numbers of the valid
vSmart controllers in the overlay network (on vBond
orchestrators only).

CLI Equivalent: show orchestrator valid-vsmarts

URL:
https://vmanage-ip-address/dataservice/device/orchestrator/valid
smarts?deviceId=deviceId
OSPF API calls for real-time monitoring of OSPF information:

• Database
• Database Summary
• External Database
• Interface
• Neighbor
• Process
• Routes
CLI Equivalent: show ospf database
URL:
https://vmanage-ip-address/dataservice/device/ospf/database?deviceId=deviceId

CLI Equivalent: show ospf database-summary

URL: https://vmanage-ip-address/dataservice/device/ospf/databasesummary?
deviceId=deviceId

CLI Equivalent: show ospf database external

URL: https://vmanage-ip-address/dataservice/device/ospf/databaseexternal?
deviceId=deviceId

CLI Equivalent: show ospf interface

URL:
https://vmanage-ip-address/dataservice/device/ospf/interface?deviceId=deviceId
CLI Equivalent: show ospf neighbor

URL: https://vmanage-ip-address/dataservice/device/ospf/neighbor?
deviceId=deviceId

CLI Equivalent: show ospf process

URL:
https://vmanage-ip-address/dataservice/device/ospf/process?deviceId=d
eviceId

CLI Equivalent: show ospf routes

URL: https://vmanage-ip-address/dataservice/device/ospf/routes?
deviceId=deviceId
Alarms
Display information about cleared and currently active alarms.
Alarms Using GET Method
If the query size is less than 2048 characters, use the GET method.
URL:
https://vmanage-ip-address/dataservice/alarms?query=query
https://198.18.1.10/dataservice/alarms