NHPREP — Hands-On CCNA, CCNP, CCIE Labs & Networking Courses

Objective

Understand the structure and basic usage of the SD‑WAN Manager REST APIs: how URIs are constructed, common HTTP methods, and how to authenticate and query inventory and templates. This lesson explains WHY APIs are used in production SD‑WAN operations, and provides hands‑on examples against the lab SD‑WAN Manager system IP so you can query the fabric programmatically.

In production networks, APIs remove repetitive human error and enable automation for tasks such as inventory collection, policy activation, and statistics aggregation. For example, an NOC can automatically poll device health and trigger remediation when a device’s BFD state degrades — all via the SD‑WAN Manager REST APIs.

Topology & Device Table

ASCII topology (system IPs shown on each device interface)

Device Table

Device	Interface	IP Address	Subnet Mask	Role
SD‑WAN Manager	S‑IP	100.0.0.1	/32	API server, GUI, docs
Controller	S‑IP	100.0.0.101	/32	Central controller/validator
Hub1 (on‑prem)	S‑IP	10.0.0.1	/32	Hub (on‑prem)
Hub2 (SIG)	S‑IP	10.0.0.2	/32	Hub (cloud/SIG)
Spoke1	S‑IP	10.0.0.3	/32	Spoke
Spoke2	S‑IP	10.0.0.4	/32	Spoke
Spoke3	S‑IP	10.0.0.5	/32	Spoke
Spoke4	S‑IP	10.0.0.4	/32	Spoke (note: same IP as Spoke2 in lab)

Important: The lab topology contains duplicate S‑IP addresses for Spoke2 and Spoke4 (both 10.0.0.4) as provided. In production, system IPs must be unique. The duplicate is intentional here to match the lab reference.

Key Concepts (theory + behavior)

REST Architecture — REST is stateless and uses standard HTTP methods (GET, POST, PUT, DELETE). Think of the SD‑WAN Manager as an HTTP server exposing resources (devices, templates, policies). Each request contains all information needed; the server does not keep request state between calls.
- Practical: When you script repeated polls, each HTTP GET is independent; session state must be handled by your script (cookies, tokens).
URI Structure & Resources — URIs point to resources. Example form:
```
https://<vmanage-ip>:<port>/dataservice/device/bfd/state/device?deviceId=1.1.1.7
```
The path identifies the resource collection (device, template, statistics) and query parameters scope results.
- Practical: Use the URI to filter server-side instead of downloading everything and filtering locally — more efficient and less network traffic.
Authentication Methods — Common API auth patterns are: session cookies, tokens (Bearer), or HTTP basic auth over TLS. Always use HTTPS and validate server certificates in production.
- Practical: For automation, token-based auth is preferable because it avoids embedding plaintext credentials and supports expiry/rotation.
HTTP Status Codes & Idempotence — GET is safe (read only). POST often creates or triggers actions (not idempotent). PUT and DELETE modify state; design scripts to handle retries and check for 200/201/204 vs. 4xx/5xx.
- Practical: When activating a policy, use GET first to check current state; avoid blindly POSTing an activation request.
API Documentation (Swagger/OpenAPI) — The manager exposes built‑in API docs at the /apidocs path. Use the swagger UI to explore endpoints, required parameters, and example payloads.
- Practical: The swagger UI is invaluable for quick experimentation and to see request/response schemas.

Step-by-step configuration (Hands‑on)

Note: The SD‑WAN Manager system IP in this lab is 100.0.0.1. Use the password Lab@123 where a password is required in examples.

Step 1: Retrieve the API documentation (Swagger UI)

What we are doing: Connect to the built‑in API documentation page. This helps discover available endpoints, parameters, and example payloads before writing automation.

curl -k -I https://100.0.0.1/apidocs

What this command does and why it matters: This HEAD request asks the server for headers for the apidocs resource. Even without browsing, getting headers verifies the endpoint is reachable and serving the documentation. The -k option is used in labs to ignore self-signed TLS certs; in production you should validate certificates.

Real-world note: In production, do not use -k. Instead, configure your client with the CA certificate used by the API server so TLS is verified.

Verify:

curl -k -I https://100.0.0.1/apidocs
HTTP/1.1 200 OK
Date: Thu, 01 Jan 1970 00:00:00 GMT
Server: SD-WAN-Manager
Content-Type: text/html; charset=utf-8
Content-Length: 12345

Expected: HTTP 200 OK and Content-Type indicating an HTML page (Swagger UI).

Step 2: Retrieve device inventory (example /dataservice/device)

What we are doing: Query the device inventory resource to list devices known to the manager. Inventory is the foundational dataset for many automation tasks (monitoring, activation).

curl -k -u admin:Lab@123 https://100.0.0.1/dataservice/device

What this command does and why it matters: A GET against /dataservice/device requests the manager’s inventory. The -u admin:Lab@123 provides basic auth; many deployments will use token/session auth — consult your API docs. Inventory responses show device hostnames, system IPs (S‑IP), and unique IDs used for later API calls.

Real-world note: Automation uses device UUIDs (deviceId) for unambiguous identification. System IP (S‑IP) is human-friendly but can change; prefer stable UUIDs if available.

Verify:

curl -k -u admin:Lab@123 https://100.0.0.1/dataservice/device
{
  "data": [
    {
      "host-name": "Hub1",
      "system-ip": "10.0.0.1",
      "uuid": "hub1-uuid-0001"
    },
    {
      "host-name": "Hub2",
      "system-ip": "10.0.0.2",
      "uuid": "hub2-uuid-0002"
    },
    {
      "host-name": "Spoke1",
      "system-ip": "10.0.0.3",
      "uuid": "spoke1-uuid-0003"
    },
    {
      "host-name": "Spoke2",
      "system-ip": "10.0.0.4",
      "uuid": "spoke2-uuid-0004"
    },
    {
      "host-name": "Spoke3",
      "system-ip": "10.0.0.5",
      "uuid": "spoke3-uuid-0005"
    },
    {
      "host-name": "SD-WAN-Manager",
      "system-ip": "100.0.0.1",
      "uuid": "vmgr-uuid-0100"
    },
    {
      "host-name": "Controller",
      "system-ip": "100.0.0.101",
      "uuid": "ctrl-uuid-0101"
    }
  ],
  "status": "success"
}

Expected: JSON data array containing each device and its system-ip. Use uuid values in later calls.

Step 3: Retrieve available templates

What we are doing: Pull the list of configuration templates from the manager. Templates are used to push consistent configs to devices and are frequently queried/changed by automation.

curl -k -u admin:Lab@123 https://100.0.0.1/dataservice/template

What this command does and why it matters: A GET on /dataservice/template returns templates (feature templates and device templates). Use template IDs to attach templates to devices or to inspect template content programmatically.

Real-world note: In production, templates are the canonical source of device configuration. Automation should check template versioning before pushing changes.

Verify:

curl -k -u admin:Lab@123 https://100.0.0.1/dataservice/template
{
  "data": [
    {
      "templateName": "Base-Template",
      "templateId": "tmpl-0001",
      "templateType": "device"
    },
    {
      "templateName": "BFD-Feature",
      "templateId": "tmpl-0002",
      "templateType": "feature"
    },
    {
      "templateName": "QoS-Policy",
      "templateId": "tmpl-0003",
      "templateType": "policy"
    }
  ],
  "status": "success"
}

Expected: JSON array listing templates with templateId and templateName.

Step 4: Query BFD state for a device (example URI)

What we are doing: Use the example URI from the API docs to query device BFD state. BFD state is a common operational check used by monitoring and health checks.

curl -k -u admin:Lab@123 "https://100.0.0.1/dataservice/device/bfd/state/device?deviceId=1.1.1.7"

What this command does and why it matters: This GET targets a specific resource path that returns BFD session status for a device (the deviceId parameter scopes the result). Monitoring scripts can poll this endpoint to detect BFD transitions (UP → DOWN) and trigger remediation.

Real-world note: BFD sessions are used to detect broken overlay tunnels quickly. Automated remediation (e.g., rerouting, reattaching policies) often responds to BFD DOWN events.

Verify:

curl -k -u admin:Lab@123 "https://100.0.0.1/dataservice/device/bfd/state/device?deviceId=1.1.1.7"
{
  "data": {
    "deviceId": "1.1.1.7",
    "bfdSessions": [
      {
        "peerIp": "10.0.0.1",
        "sessionState": "up",
        "localDiag": "none",
        "remoteDiag": "none",
        "uptime": "00:12:34"
      },
      {
        "peerIp": "10.0.0.2",
        "sessionState": "up",
        "localDiag": "none",
        "remoteDiag": "none",
        "uptime": "00:11:20"
      }
    ]
  },
  "status": "success"
}

Expected: JSON showing BFD sessions and sessionState values. A sessionState of down indicates a tunnel/adjacency issue that automation should handle.

Verification Checklist

Check 1: API docs accessible — use curl -k -I https://100.0.0.1/apidocs and expect HTTP 200 OK.
Check 2: Device inventory returns the expected S‑IP list — use curl -k -u admin:Lab@123 https://100.0.0.1/dataservice/device and verify S‑IP entries for 10.0.0.1–10.0.0.5 and 100.0.0.1/100.0.0.101.
Check 3: Templates listed — use curl -k -u admin:Lab@123 https://100.0.0.1/dataservice/template and verify presence of canonical template names.
Check 4: BFD state endpoint returns JSON with sessionState for deviceId=1.1.1.7.

Common Mistakes

Symptom	Cause	Fix
API call returns SSL/TLS error	Using `curl` without trusting or including the CA certificate	In lab use `-k`; in production, supply CA cert via `--cacert` or trust store
Empty device list or missing expected S‑IP	Using wrong credentials or insufficient API privileges	Verify credentials (user+password) and API role; use admin-level account for discovery
Incorrect `deviceId` when querying device-specific endpoints	Confusing `system-ip` with `deviceId` (UUID)	First retrieve `/dataservice/device` to map `system-ip` to `uuid`/`deviceId`
Scripts fail intermittently with 500/502	Not handling HTTP error codes or retry/backoff	Implement retries with exponential backoff and check for idempotence before reapplying changes

Key Takeaways

REST APIs on the SD‑WAN Manager are stateless, use standard HTTP verbs, and expose resources like devices, templates, policies, and statistics that automation can consume.
Always discover resource identifiers (device UUIDs, template IDs) via inventory endpoints before performing state‑changing operations.
Authentication and TLS are critical — in production prefer token‑based auth and validate certificates; do not use insecure options like -k.
Use the built‑in API docs (/apidocs) to explore endpoints and example payloads; automate with care (check current state before changing it) to avoid operational impact.

Tip: Think of the SD‑WAN Manager like a library: each URI is a catalog entry (resource), HTTP verbs are the allowed interactions (read, create, update, delete), and authentication is your library card granting permissions. Use the catalog first, then perform actions in a controlled, idempotent way.

SD-WAN Manager API Overview

Objective

Topology & Device Table

Key Concepts (theory + behavior)

Step-by-step configuration (Hands‑on)

Step 1: Retrieve the API documentation (Swagger UI)

Step 2: Retrieve device inventory (example /dataservice/device)

Step 3: Retrieve available templates

Step 4: Query BFD state for a device (example URI)

Verification Checklist

Common Mistakes

Key Takeaways