Back
Lesson 4 of 6

Template Management via API

Objective

In this lesson you will learn how to create, modify, and attach SD‑WAN device templates using the SD‑WAN Manager APIs, and how to perform bulk template operations. Template management via API allows automation at scale: in production networks this reduces manual configuration errors and speeds deployment of new sites or device generations. For example, a global retail chain uses API-driven templates to push standardized interface and VPN settings to hundreds of branch edge routers in minutes instead of days.

Quick Recap

This lesson continues the SD‑WAN Manager API work from earlier lessons. We add two logical hosts for the API lab:

  • SD‑WAN Manager: lab.nhprep.com (192.0.2.10)
  • Webhook / API client server: lab.nhprep.com-client (192.0.2.20)

Only the SD‑WAN Manager and the client/server are new to this lesson; device topology inside the SD‑WAN fabric remains the same as Lesson 1.

ASCII topology (logical):

[API Client / Webhook Server] -- 192.0.2.20
            |
            | HTTPS:443
            |
[SD-WAN Manager (API)] -- lab.nhprep.com -- 192.0.2.10
            |
            | (sends config to devices via controller)
            |
[SD-WAN Fabric: Edge devices referenced in Lesson 1]

Tip: In production, the API client often runs as a CI/CD pipeline job or an automation server (Ansible/Jenkins). The webhook server receives asynchronous events (template validation, device state changes).

Key Concepts

  • Template vs device config: A device template is a named configuration artifact that can be applied to multiple physical devices. Think of templates as reusable recipe cards; the SD‑WAN Manager keeps the canonical copy and pushes the result to devices.
    • Real-world: Use templates to enforce consistent SNMP settings, NTP servers, and overlay profiles across a region.
  • API authentication and session: SD‑WAN Manager APIs require an authenticated session token. Typical REST behavior: you POST credentials to obtain a token, then include that token in an Authorization header for subsequent calls.
    • Protocol behavior: The manager will validate the token on each request; expired tokens force re-authentication.
  • Create / Modify / Attach lifecycle: Create a template (POST), modify it (PUT), then attach it to devices (POST to attach endpoint). When attached, the controller generates device-specific configs and pushes them asynchronously.
    • Packet flow: API call → Manager validates → Manager updates database → Controller generates device config → Controller initiates device provisioning job.
  • Bulk operations: Bulk endpoints allow a single request to create or modify many templates, reducing API overhead. In production this matters when onboarding many devices or rolling a configuration change globally.
  • Idempotency and versioning: Template updates typically create a version or increments a sequence so the system can track changes and roll back if needed. Always verify the template version after a change.

Step-by-step configuration

Step 1: Authenticate and obtain API token

What we are doing: Obtain an API session token from the SD‑WAN Manager. This token authenticates subsequent requests and is required before creating or modifying templates.

# Obtain token (basic example with curl)
curl -i -k -X POST "https://lab.nhprep.com/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Lab@123","org":"NHPREP"}'

What just happened: The POST sends credentials to the Manager. On success the Manager returns an Authorization token (often in a JSON field like "token" or in a header). The token is short-lived and must be included in headers for later API calls.

Real-world note: Store tokens securely in your automation environment; do not hardcode credentials in scripts. Use Vault or a secrets manager.

Verify:

# Expected response (complete JSON response)
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 01 Jan 1970 00:00:00 GMT
Content-Length: 250

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.sampletoken",
  "user": "admin",
  "org": "NHPREP",
  "expires_in": 3600
}

Step 2: Create a device template

What we are doing: Create a reusable device template via API that defines base configuration (for example NTP, syslog, and loopback). This template will be the canonical source for devices that share those settings.

# Create a device template
curl -s -k -X POST "https://lab.nhprep.com/api/v1/templates/device" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOi...sampletoken" \
  -d '{
    "name": "Branch-Base-Template",
    "description": "Base NTP/SNMP/syslog for branch routers",
    "platform": "router",
    "config": {
      "ntp": ["192.0.2.100","192.0.2.101"],
      "snmp": {"community": "public", "location": "branch"},
      "syslog": {"servers": ["192.0.2.110"], "level": "informational"},
      "loopback": {"ip": "10.1.0.1/32"}
    }
  }'

What just happened: The Manager stored a new template named "Branch-Base-Template" in its template repository. The payload fields define what configuration elements will be pushed to devices. The Manager will assign a template ID and initial version.

Real-world note: Keep templates modular (one for base services, one for site-specific interfaces) so you can mix and match templates across device families.

Verify:

# GET template list and full details
curl -s -k -X GET "https://lab.nhprep.com/api/v1/templates/device?name=Branch-Base-Template" \
  -H "Authorization: Bearer eyJhbGciOi...sampletoken"

# Expected output (complete JSON)
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 01 Jan 1970 00:00:00 GMT
Content-Length: 430

{
  "templates": [
    {
      "id": "tmpl-0001",
      "name": "Branch-Base-Template",
      "description": "Base NTP/SNMP/syslog for branch routers",
      "platform": "router",
      "config": {
        "ntp": ["192.0.2.100","192.0.2.101"],
        "snmp": {"community": "public","location":"branch"},
        "syslog": {"servers":["192.0.2.110"],"level":"informational"},
        "loopback": {"ip":"10.1.0.1/32"}
      },
      "version": 1,
      "created_by": "admin",
      "created_at": "2026-04-01T12:00:00Z"
    }
  ]
}

Step 3: Modify an existing template

What we are doing: Update the template to add an additional syslog server and bump the description. Template modification is common when policy or central services change.

# Modify template tmpl-0001
curl -s -k -X PUT "https://lab.nhprep.com/api/v1/templates/device/tmpl-0001" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOi...sampletoken" \
  -d '{
    "description": "Base NTP/SNMP/syslog for branch routers - added backup syslog",
    "config": {
      "syslog": {"servers": ["192.0.2.110","192.0.2.111"], "level": "informational"}
    }
  }'

What just happened: The Manager updated template tmpl-0001’s configuration. The system should increment the template version (e.g., version 2) and record a change history. Device attachments referencing this template may now be eligible for a deploy/update job.

Real-world note: After modifying a template, plan the deployment window — pushing changes to many devices can cause unexpected behavior if not tested.

Verify:

# Get the updated template details
curl -s -k -X GET "https://lab.nhprep.com/api/v1/templates/device/tmpl-0001" \
  -H "Authorization: Bearer eyJhbGciOi...sampletoken"

# Expected output (complete JSON)
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 01 Jan 1970 00:05:00 GMT
Content-Length: 480

{
  "id": "tmpl-0001",
  "name": "Branch-Base-Template",
  "description": "Base NTP/SNMP/syslog for branch routers - added backup syslog",
  "platform": "router",
  "config": {
    "ntp": ["192.0.2.100","192.0.2.101"],
    "snmp": {"community":"public","location":"branch"},
    "syslog": {"servers":["192.0.2.110","192.0.2.111"],"level":"informational"},
    "loopback": {"ip":"10.1.0.1/32"}
  },
  "version": 2,
  "modified_by": "admin",
  "modified_at": "2026-04-01T12:05:00Z"
}

Step 4: Attach a template to devices (single and bulk attach)

What we are doing: Attach the template to devices so the controller knows which devices should receive the template configuration. We demonstrate attaching one device and performing a bulk attach to multiple devices.

# Attach tmpl-0001 to device dev-100 (single attach)
curl -s -k -X POST "https://lab.nhprep.com/api/v1/devices/dev-100/templates" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOi...sampletoken" \
  -d '{"template_id":"tmpl-0001"}'

# Bulk attach multiple devices
curl -s -k -X POST "https://lab.nhprep.com/api/v1/templates/attach/bulk" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOi...sampletoken" \
  -d '{
    "template_id": "tmpl-0001",
    "device_ids": ["dev-101","dev-102","dev-103"]
  }'

What just happened: The Manager recorded attachments between template tmpl-0001 and the specified devices. The Controller will schedule a job to generate per-device configurations and push them to the devices. Attachment does not always imply immediate push — typically the Manager creates a job that you can monitor.

Real-world note: Use attachments for lifecycle management: when you update the template later, the Manager recognizes which devices are affected and can create a deployment job automatically.

Verify:

# Verify device dev-100 attachments
curl -s -k -X GET "https://lab.nhprep.com/api/v1/devices/dev-100/templates" \
  -H "Authorization: Bearer eyJhbGciOi...sampletoken"

# Expected output (complete JSON)
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 01 Jan 1970 12:10:00 GMT
Content-Length: 230

{
  "device_id": "dev-100",
  "attached_templates": [
    {
      "template_id": "tmpl-0001",
      "name": "Branch-Base-Template",
      "version": 2,
      "attached_at": "2026-04-01T12:08:00Z"
    }
  ]
}

# Verify bulk attach reporting
curl -s -k -X GET "https://lab.nhprep.com/api/v1/templates/tmpl-0001/attachments" \
  -H "Authorization: Bearer eyJhbGciOi...sampletoken"

# Expected output (complete JSON)
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 01 Jan 1970 12:10:30 GMT
Content-Length: 420

{
  "template_id": "tmpl-0001",
  "attachments": [
    {"device_id":"dev-100","status":"attached","attached_at":"2026-04-01T12:08:00Z"},
    {"device_id":"dev-101","status":"attached","attached_at":"2026-04-01T12:09:00Z"},
    {"device_id":"dev-102","status":"attached","attached_at":"2026-04-01T12:09:05Z"},
    {"device_id":"dev-103","status":"attached","attached_at":"2026-04-01T12:09:10Z"}
  ]
}

Step 5: Bulk create templates

What we are doing: Demonstrate creating multiple templates in a single call. Bulk creation is useful when onboarding multiple device types or creating separate templates for different roles.

# Bulk create templates
curl -s -k -X POST "https://lab.nhprep.com/api/v1/templates/device/bulk" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOi...sampletoken" \
  -d '{
    "templates": [
      {
        "name": "Branch-Security-Template",
        "description": "ACLs and security hardening",
        "platform": "router",
        "config": {"acl": {"inbound":"deny 10.0.0.0/8"}}
      },
      {
        "name": "Branch-Interface-Template",
        "description": "Interface naming and VLANs",
        "platform": "router",
        "config": {"interfaces":[{"name":"Gig0/0","vlan":10},{"name":"Gig0/1","vlan":20}]}
      }
    ]
  }'

What just happened: The Manager created two new templates in one transaction and returned identifiers for each. Bulk creation reduces API chattiness and ensures templates are created atomically by the Manager if supported.

Real-world note: For large migrations, bulk operations reduce load on the controller and minimize partial states. Validate the templates in a staging environment first.

Verify:

# List templates by prefix
curl -s -k -X GET "https://lab.nhprep.com/api/v1/templates/device?prefix=Branch-" \
  -H "Authorization: Bearer eyJhbGciOi...sampletoken"

# Expected output (complete JSON)
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 01 Jan 1970 12:15:00 GMT
Content-Length: 720

{
  "templates": [
    {
      "id": "tmpl-0001",
      "name": "Branch-Base-Template",
      "version": 2
    },
    {
      "id": "tmpl-0002",
      "name": "Branch-Security-Template",
      "version": 1
    },
    {
      "id": "tmpl-0003",
      "name": "Branch-Interface-Template",
      "version": 1
    }
  ]
}

Verification Checklist

  • Check 1: Authentication token obtained — verify with GET /api/v1/auth/status or check that subsequent requests return 200.
  • Check 2: Template created and version = 1 (then incremented on modification) — verify with GET /api/v1/templates/device/{template_id}.
  • Check 3: Template attached to device(s) — verify with GET /api/v1/devices/{device_id}/templates and GET /api/v1/templates/{template_id}/attachments.

Common Mistakes

SymptomCauseFix
API returns 401 UnauthorizedToken missing, expired, or wrong credentialsRe-authenticate with correct username/password (Lab@123 for lab examples), include token in Authorization header
Template shows version unchanged after PUTPUT request failed silently or updated different template idVerify template id used in URL; check response body for errors; use GET to confirm version
Devices do not receive new config after attachAttach created job but deployment not executed, or device not reachableCheck device reachability and job status; initiate deployment job if required
Bulk create partially succeededValidation error in one template prevented others (transaction semantics vary)Validate each template payload; perform smaller bulk batches and check error messages

Key Takeaways

  • Templates are reusable configuration artifacts; manage them via the SD‑WAN Manager API to scale and standardize deployments.
  • Always authenticate first, include the token in requests, and monitor token expiry.
  • Use modular templates (base, security, interfaces) and attach them to devices to produce per-device configurations.
  • Bulk endpoints are powerful for onboarding and large-scale changes — but validate payloads to avoid partial failures.
  • After changing templates, verify versioning and the device deployment job status to ensure the change was pushed successfully.

Important: In production networks, automate verification (GET template details, GET attachment status, and job execution logs) so you detect and remediate failed pushes quickly.

Warning: The examples in this lesson use lab credentials and the domain lab.nhprep.com. Never reuse lab credentials for production systems. Store real credentials securely and follow your organization's change-control and maintenance windows when pushing template changes.

Practice with Hands-On Labs

30 step-by-step labs for CCNA, CCNP Enterprise & Security