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

Objective

Introduction

In this lesson you will learn how to use the NSO RESTCONF API to perform programmatic queries and CRUD operations against an NSO server. We focus on authentication (Basic over HTTPS) and the typical GET/POST/PUT/DELETE workflow used to retrieve system state and create/update service payloads. In production, RESTCONF lets automation tools (CI/CD pipelines, orchestration systems) query NSO for device state and push service configurations programmatically — for example, provisioning an interface on many devices in a single atomic transaction via NSO. This lesson assumes you completed the topology and device prep in Lesson 1 and builds on that environment.

Topology

Quick recap

This lesson uses the same topology you saw in Lesson 1. No new routers or interfaces are added here; we operate against the NSO server (hostname lab.nhprep.com) that already manages the lab devices.

Tip: If you need to re-check connectivity between your automation workstation and NSO, verify DNS resolves lab.nhprep.com to the NSO management IP in your lab.

ASCII topology (reference — no new IPs added in this lesson)

[Automation Workstation] -- HTTPS --> [NSO Server: lab.nhprep.com]
                                |
                                +-- NETCONF/CLI to managed devices (already configured per Lesson 1)

Device Table

Device	Role	Hostname / Domain
NSO server	RESTCONF API provider, orchestration	lab.nhprep.com
Automation Workstation	Runs Python/curl to invoke RESTCONF	workstation.lab.nhprep.com
Managed network devices	Devices managed by NSO (configured in Lesson 1)	see Lesson 1 topology

Warning: This lesson assumes NSO has the RESTCONF listener enabled and NSO credentials were provisioned during lab setup (admin / Lab@123). If your NSO admin username is different, substitute accordingly.

Key Concepts

Before touching the API, you must understand these foundation points:

RESTCONF: a REST-like HTTP interface to YANG-modeled device and controller data. Requests are typically over HTTPS and use standard verbs (GET, POST, PUT, DELETE) to implement CRUD (Create, Read, Update, Delete) against YANG data nodes. In production, RESTCONF is commonly used by orchestration tools to query inventory and push service definitions.
YANG models: Describe the schema NSO exposes. RESTCONF operations operate against YANG-defined resources (for example, services or device state). When you GET a resource, NSO returns YANG-structured JSON or XML. Understanding the model used for a resource is essential for forming correct payloads during POST/PUT.
Authentication / Transport: RESTCONF uses HTTPS. For lab simplicity we use Basic authentication (username/password) over TLS. In production, integrate NSO with stronger auth mechanisms (ACS, OAuth) and validate certificates. RESTCONF requests include Accept/Content-Type headers to indicate YANG JSON payloads.
Atomic transactions: When NSO receives a service configuration via RESTCONF, it can validate and apply changes transactionally across multiple devices. This is why NSO is used to ensure consistency when provisioning multi-device services in production networks.
exec-any & CLI NED: NSO can call device CLI using the CLI NED with exec any (when needed) to execute show commands or run platform-specific commands — useful when a device lacks a complete YANG model. When NSO calls CLI NED, the underlying behavior is that NSO translates the service request into CLI commands and sends them over NETCONF/SSH to the device.

Steps

Step 1: Verify RESTCONF Reachability (HTTP(S) GET)

What we are doing: Confirm that the NSO RESTCONF endpoint is reachable and responds to basic API queries. This verifies TLS and basic auth are working before attempting changes.

# From the automation workstation (shell)
curl -s -k -u admin:Lab@123 https://lab.nhprep.com/restconf/ -H "Accept: application/yang-data+json"

What just happened: The curl command performs an HTTPS GET to NSO's RESTCONF root. The -k option allows self-signed certificates in lab environments (do not use in production), -u admin:Lab@123 supplies Basic auth credentials, and the Accept header requests YANG JSON. If the server is reachable and authentication succeeds, NSO returns a brief index or supported capabilities in JSON.

Real-world note: In production, do not use -k; configure and validate TLS certificates, and use stronger auth than Basic where possible.

Verify:

# Expected output from the previous curl (example JSON)
{
  "restconf": {
    "implementation": "NSO",
    "version": "1.0"
  },
  "modules": [
    {
      "name": "ncs",
      "revision": "1-01-2024",
      "namespace": "urn:ietf:params:xml:ns:yang:ncs"
    }
  ]
}

Step 2: Retrieve NSO Version (GET against a known YANG node)

What we are doing: Retrieve the NSO system/version information via a RESTCONF GET to the version resource exposed by the NSO YANG model. This demonstrates how to query specific YANG nodes.

# From the automation workstation (shell)
curl -s -k -u admin:Lab@123 https://lab.nhprep.com/restconf/data/ncs-state:system/state/version -H "Accept: application/yang-data+json"

What just happened: The GET targets the YANG path ncs-state:system/state/version. NSO resolves the YANG path, reads the requested state leaf, and returns it as JSON. This is a read-only operation and does not alter NSO or device state.

Real-world note: Commonly used by inventory and monitoring scripts to confirm controller versions before applying device workflows.

Verify:

# Expected output (example JSON)
{
  "version": "8.1.0",
  "build": "2025-02-10",
  "platform": "ncs-2k"
}

Step 3: Create a Simple Service via RESTCONF (POST)

What we are doing: Use a RESTCONF POST to create a service instance in NSO. Services in NSO are YANG-modeled objects; creating one causes NSO to generate device-level configuration actions. This demonstrates the 'Create' portion of CRUD.

# Example JSON payload to create a simple interface service on a named device
# Save this file as create-loopback.json on the workstation
{
  "loopback-service": {
    "name": "lb-101",
    "device": "XR1",
    "interface": "Loopback101",
    "ip-address": "203.0.113.101/32"
  }
}

# POST the service to NSO
curl -s -k -u admin:Lab@123 -X POST https://lab.nhprep.com/restconf/data/services/ -H "Content-Type: application/yang-data+json" -d @create-loopback.json

What just happened: The POST sends a service instance payload to NSO. NSO validates the payload against the service YANG model, compiles the corresponding device configuration (using templates/NEDs/YANG), and applies the configuration to the target device(s) in a transaction. If successful, NSO returns a 201 Created or a representation of the created resource.

Real-world note: In real environments, service YANG models are often more complex and include validation logic; always validate payloads in a staging environment before mass deployment.

Verify:

# Expected response: service creation confirmation (example JSON)
{
  "created": {
    "service-id": "lb-101",
    "status": "applied",
    "applied-on": "XR1"
  }
}

# Confirm the service exists with a GET
curl -s -k -u admin:Lab@123 https://lab.nhprep.com/restconf/data/services/loopback-service=lb-101 -H "Accept: application/yang-data+json"

# Expected GET output (example)
{
  "loopback-service": {
    "name": "lb-101",
    "device": "XR1",
    "interface": "Loopback101",
    "ip-address": "203.0.113.101/32",
    "status": "applied"
  }
}

Step 4: Update the Service (PUT) — modify the IP

What we are doing: Demonstrate updating an existing service instance using PUT (or PATCH depending on API design) to change attributes. This shows the 'Update' part of CRUD.

# Prepare updated payload (update-loopback.json)
{
  "loopback-service": {
    "name": "lb-101",
    "ip-address": "203.0.113.102/32"
  }
}

# Use PUT to replace the resource
curl -s -k -u admin:Lab@123 -X PUT https://lab.nhprep.com/restconf/data/services/loopback-service=lb-101 -H "Content-Type: application/yang-data+json" -d @update-loopback.json

What just happened: The PUT request replaces the service instance at the identifier lb-101 with the new payload. NSO validates the change and computes the necessary delta to device configurations, then applies the delta transactionally to the managed device(s).

Real-world note: Use PUT for full replacement and PATCH for partial updates if NSO supports PATCH operations; understanding the API semantics prevents unintended deletions.

Verify:

# GET to confirm update
curl -s -k -u admin:Lab@123 https://lab.nhprep.com/restconf/data/services/loopback-service=lb-101 -H "Accept: application/yang-data+json"

# Expected output reflecting updated IP (example)
{
  "loopback-service": {
    "name": "lb-101",
    "device": "XR1",
    "interface": "Loopback101",
    "ip-address": "203.0.113.102/32",
    "status": "applied"
  }
}

Step 5: Delete the Service (DELETE)

What we are doing: Remove the service instance using RESTCONF DELETE to demonstrate the 'Delete' portion of CRUD. This will cause NSO to revert or remove the configuration from the managed device(s).

# Issue DELETE for the service instance
curl -s -k -u admin:Lab@123 -X DELETE https://lab.nhprep.com/restconf/data/services/loopback-service=lb-101

What just happened: NSO receives the DELETE call, performs validation and a transactional revert of the service-defined configuration on the target devices. The service instance is removed from NSO's configuration datastore and the device state is reconciled to remove the changes.

Real-world note: Deleting services in production should be managed under change control to avoid accidental service disruption; NSO's transaction logs and dry-run features are helpful safeguards.

Verify:

# GET should return 404 or empty result after delete
curl -s -k -u admin:Lab@123 https://lab.nhprep.com/restconf/data/services/loopback-service=lb-101 -H "Accept: application/yang-data+json"

# Expected response (example)
{
  "error": {
    "error-type": "application",
    "error-tag": "operation-failed",
    "error-message": "Resource not found: services/loopback-service=lb-101"
  }
}

Verification Checklist

Check 1: RESTCONF root reachable — run the curl GET to https://lab.nhprep.com/restconf/ and confirm JSON index is returned.
Check 2: NSO version successfully retrieved — run the GET to the system/version YANG node and confirm the version string.
Check 3: Create / Update / Delete service lifecycle works — perform POST to create, GET to verify, PUT to modify, and DELETE to remove; each step must report successful apply status in JSON.

Common Mistakes

Symptom	Cause	Fix
curl returns SSL certificate error or connection refused	Using `-k` hides cert errors; connection refused often means RESTCONF listener not running or wrong port	Confirm NSO RESTCONF listener is enabled and reachable. Use `curl -v` for diagnostics and validate host/port.
Authentication fails (401)	Wrong username/password or Basic auth disabled	Verify credentials (admin / Lab@123) and check NSO user config. In production, use service account with limited privileges.
POST returns schema validation error	Payload does not match YANG model	Validate your JSON against the service YANG model. Fetch model definitions from NSO to confirm field names.
Changes applied to wrong device or no device	Wrong device identifier in payload or device not provisioned in NSO	Confirm device name matches NSO device inventory (from Lesson 1), and the device is online.
DELETE reported success but device still has config	NSO could not apply rollback on device or NED mapping issue	Check NSO transaction logs, device connectivity, and NED (YANG/CLI) compatibility; re-run dry-run to inspect planned changes.

Key Takeaways

RESTCONF provides a YANG-model-aware HTTP interface to NSO for programmatic automation — think of it as "YANG over HTTPS" for create/read/update/delete operations.
Always authenticate over TLS and prefer stronger auth in production; Basic auth + -k is useful for labs only.
Understand the YANG model before crafting payloads; payload shape must match the model for NSO to accept and apply changes.
NSO enforces transactional application of services — this is why orchestration via NSO reduces misconfiguration risk when provisioning multi-device services.

Final tip: Treat NSO as the single source of truth for service intent; always query NSO for device/service state programmatically rather than directly querying individual devices in an automation workflow. This ensures consistent, auditable changes across your network.