my cheat sheet on SDWAN API

Home

1 SDWAN API

sd-wan.png

Figure 1: sd-wan

The API is a REST API through the SD-WAN controller, vManage.

Much like the ACI GUI itself uses the ACI API to manage ACI, the SD-WAN vManage GUI uses the SD-WAN API to manage SD-WAN.

So, it is dead simple to examine the HTTP request that your vManage GUI makes to learn the API calls.

1.1 The REST API URL

Server, Resource, Parameters

vmanage-URL.png

Figure 2: vManage URL

https://vmanage_ip/dataservice/device/bfd/state/device?deviceId=1.1.1.5 to list just a specific few, or specific one, or

https://vmanage_ip/dataservice/device/bfd/state/device?device to list all the devices 

Response code: 200
Response headers:
{
    "cache-control": "no-cache, no-store, must-revalidate",
    "content-encoding": "gzip",
    "content-type": "application/json",
    "date": "Tue, 19 Oct 2019 21:32:55 GMT",
    "server": "nginx/1.13.12",
    "status": "200",
    "strict-transport-security": "max-age=31536000; includeSubDomains",
    "vary": "Accept-Encoding",
    "x-frame-options": "DENY"
}

Response body: 
<... output omitted ...>
    "data": [
    {
        "deviceId": "192.168.4.90",
        "system-ip": "192.168.4.90",
        "host-name": "vmanage",
        "reachability": "reachable",
        "status": "normal",
        "personality": "vmanage",
        "device-type": "vmanage",
        "timezone": "UTC",
        "device-groups": [
        "\"No groups\""
        ],

<... output omitted ...>

sdwan-case.png

Figure 3: SDWAN API Use Case

sdwan-url.png

Figure 4: SD-WAN API URL

1.2 SDWAN API Collections

The top level of the API you will find these collections:

1.2.1 /device/action

Manage device actions like, reboot, upgrade and lxcinstall

1.2.2 /system/device

Retrieve device inventory information, including serial numbers

1.2.3 /template

Create feature and device *configuration* templates, create and configure vManage clusters

1.2.4 /certificate

Manage certificates and security keys

1.2.5 /alarms, /statistics, /events

Monitoring i.e. View status, statistics, and other information about operational services in the overlay network.

1.2.6 /device/app-route/statistics, /device/bfd/status

Real-time monitoring : Retrieve, view, and manage real-time statistics and traffic information

1.2.7 /device/action/software, /device/tools/ping

Troubleshooting : Troubleshoot devices, determine the effect of the policy, update software, and retrieve software version information

1.2.8 /partner

Cross-domain integration

sd-wan-docs.png

Figure 5: SD-WAN API documentation sample

You see in the docs, that everything you need is there, including: the model schema of the response class, response status codes, and error messages.

You can run requests directly from the documentation page. How convenient!

1.3 Self-documenting REST API

The resources in the SD-WAN REST API are self-documenting, explaining the data you need to make a call, and the response you should expect.

2 SDWAN Webhooks

Included in the API are webhooks for 3rd party apps to receive data when a specified event occurs.

  • push notifications sent in near real time. If you insist, you can still poll for info from vManage, but push notifications are slicker, quicker and more efficient.

2.1 Home