RESTCONF Protocol

Objective

In this lesson you will learn how to use the RESTCONF protocol over HTTPS to read and modify device YANG-modeled data using the HTTP methods GET, PUT, POST, PATCH, DELETE and how to request JSON and XML encodings. This matters in production because RESTCONF provides a standardized, firewall-friendly, and programmatic way to integrate network devices with orchestration and monitoring systems — for example, an automation server that reads CPU statistics (GET) and pushes interface definitions (PUT/POST) during provisioning. By the end of the lesson you will issue RESTCONF calls from a management host to an IOS XE device, interpret responses and verify changes.

Real-world scenario: In an enterprise NOC, a monitoring platform polls device operational data via RESTCONF (JSON preferred) while a network automation pipeline pushes new loopback interfaces and routing policy changes via RESTCONF PUT/PATCH during maintenance windows.

Topology

ASCII diagram showing management workstation and the IOS XE device used in this lesson. Every interface shows the exact IP address used in the lab.

Workstation (Management Host)

• Hostname: mgmt-host
• IP: 10.1.1.3/24

IOS XE Device

• Hostname: iosxe-router
• IP: 10.85.134.92/24

Simple connectivity:

mgmt-host (eth0: 10.1.1.3) <----> iosxe-router (mgmt0: 10.85.134.92)

Device Table

Device	Role	Management IP
mgmt-host	RESTCONF client (Ubuntu/CURL)	10.1.1.3
iosxe-router	IOS XE device exposing RESTCONF over HTTPS	10.85.134.92

Important: This lesson assumes RESTCONF (HTTPS) is available on the IOS XE device at 10.85.134.92 and that you have credentials to authenticate from the mgmt-host.

Quick Recap

Refer to the topology and device table above. No additional devices or IPs are added in this lesson. Previous lessons prepared NETCONF/RESTCONF-enabled devices; here we focus on RESTCONF client operations from the management host to the device IP 10.85.134.92.

Key Concepts (what you must understand before running commands)

• RESTCONF over HTTPS: RESTCONF uses HTTP methods (GET, PUT, POST, PATCH, DELETE) mapped to YANG-modeled resources. It requires HTTPS in production to protect credentials and data in transit; RESTCONF endpoints are typically under /restconf/.
• Resource path and YANG models: A RESTCONF URI addresses a YANG data node (data or config) using the module and node names (for example, /restconf/data/:). Correct model names and node paths are essential — incorrect paths yield 404.
• Encodings — JSON and XML: RESTCONF supports both application/yang-data+json and application/yang-data+xml via Accept and Content-Type headers. Servers respond in the requested encoding if supported.
• HTTP status codes map to operations: Successful GET returns 200 OK (with body); POST creating a resource usually returns 201 Created; PUT/PATCH usually return 200/204; DELETE returns 204 No Content. These codes are the primary verification signals for successful RESTCONF CRUD operations.
• Authentication and TLS: RESTCONF requires authentication. Labs may use basic auth with strong passwords (Lab@123 used in examples). In production, use client certificates or strong identity solutions. If TLS verification is disabled for lab testing (-k option in curl), never do this on production devices.

Steps

All commands below are executed from the management host (mgmt-host, IP 10.1.1.3). Replace credentials and hosts as needed in production. Each step includes the commands, purpose, explanation, and verification output.

Step 1: Test RESTCONF HTTPS reachability and request root data (GET)

What we are doing: We validate the RESTCONF HTTPS endpoint is reachable and demonstrate requesting device data in both JSON and XML encodings. This proves connectivity, TLS, and RESTCONF service availability before attempting config changes.

# GET device RESTCONF root in JSON
curl -k -u admin:Lab@123 -H "Accept: application/yang-data+json" https://10.85.134.92/restconf/data

# GET device RESTCONF root in XML
curl -k -u admin:Lab@123 -H "Accept: application/yang-data+xml" https://10.85.134.92/restconf/data

What just happened:

• The curl command opens an HTTPS connection (-k disables certificate validation for lab testing), authenticates with username admin and password Lab@123, and requests the RESTCONF root resource.
• The Accept header requests either JSON or XML encoding. The server replies with a listing of top-level YANG modules or data containers available under RESTCONF.

Real-world note: In production never use -k; instead provide the device CA to the client so TLS is validated.

Verify:

# Expected JSON response (example)
HTTP/1.1 200 OK
Content-Type: application/yang-data+json

{
  "ietf-restconf:modules-state": {
    "module": [
      {
        "name": "process-cpu-ios-xe-oper",
        "namespace": "http://cisco.com/ns/yang/Cisco-IOS-XE-process-cpu-oper",
        "revision": "2020-01-01"
      },
      {
        "name": "ietf-interfaces",
        "namespace": "urn:ietf:params:xml:ns:yang:ietf-interfaces",
        "revision": "2014-05-08"
      }
    ]
  }
}

# Expected XML response (example)
HTTP/1.1 200 OK
Content-Type: application/yang-data+xml

<ietf-restconf:modules-state xmlns:ietf-restconf="urn:ietf:params:xml:ns:yang:ietf-restconf">
  <module>
    <name>process-cpu-ios-xe-oper</name>
    <namespace>http://cisco.com/ns/yang/Cisco-IOS-XE-process-cpu-oper</namespace>
    <revision>2020-01-01</revision>
  </module>
  <module>
    <name>ietf-interfaces</name>
    <namespace>urn:ietf:params:xml:ns:yang:ietf-interfaces</namespace>
    <revision>2014-05-08</revision>
  </module>
</ietf-restconf:modules-state>

Step 2: Retrieve CPU utilization with RESTCONF GET (JSON and XML)

What we are doing: We read device operational CPU metrics using the same YANG path used in telemetry examples. This demonstrates RESTCONF’s ability to return operational data (read-only) using YANG paths similar to the telemetry XPath shown in the reference material.

# GET CPU utilization as JSON (operational data)
curl -k -u admin:Lab@123 -H "Accept: application/yang-data+json" https://10.85.134.92/restconf/data/process-cpu-ios-xe-oper:cpu-usage/cpu-utilization

# GET CPU utilization as XML (operational data)
curl -k -u admin:Lab@123 -H "Accept: application/yang-data+xml" https://10.85.134.92/restconf/data/process-cpu-ios-xe-oper:cpu-usage/cpu-utilization

What just happened:

• The GET targets the specific module and container: process-cpu-ios-xe-oper:cpu-usage/cpu-utilization, which is the same path used previously for telemetry filters. RESTCONF translates the URI to the corresponding YANG data node and returns current operational CPU values.
• The device produces the data encoded as requested (JSON or XML).

Real-world note: Monitoring systems can choose JSON for ease of parsing in modern toolchains, while XML may be useful where tooling expects NETCONF-like XML.

Verify:

# Expected JSON response (example)
HTTP/1.1 200 OK
Content-Type: application/yang-data+json

{
  "cpu-utilization": {
    "total-cpu": 12,
    "one-minute": 10,
    "five-minute": 8,
    "fifteen-minute": 7,
    "timestamp": "2026-04-02T10:30:01Z"
  }
}

# Expected XML response (example)
HTTP/1.1 200 OK
Content-Type: application/yang-data+xml

<cpu-utilization xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-process-cpu-oper">
  <total-cpu>12</total-cpu>
  <one-minute>10</one-minute>
  <five-minute>8</five-minute>
  <fifteen-minute>7</fifteen-minute>
  <timestamp>2026-04-02T10:30:01Z</timestamp>
</cpu-utilization>

Step 3: Create a new Loopback interface using RESTCONF PUT (idempotent replace)

What we are doing: We demonstrate a configuration change via RESTCONF PUT by writing a loopback interface definition to the standard YANG interface model. PUT replaces the target resource; it’s idempotent and suitable for making known-good configurations.

# PUT a Loopback interface (JSON payload)
curl -k -u admin:Lab@123 -X PUT -H "Content-Type: application/yang-data+json" \
  -d '{"ietf-interfaces:interface": {"name": "Loopback100","type": "iana-if-type:softwareLoopback","enabled": true,"ietf-ip:ipv4": {"address":[{"ip":"100.100.100.1","netmask":"255.255.255.255"}]}}}' \
  https://10.85.134.92/restconf/data/ietf-interfaces:interfaces/interface=Loopback100

What just happened:

• The PUT request targets ietf-interfaces:interfaces/interface=Loopback100 and provides a full representation of the Loopback100 resource in JSON. PUT instructs the device to create the resource if absent or replace it if present.
• In RESTCONF, a successful PUT commonly returns 201 Created (if new) or 204 No Content/200 OK (if replaced).

Real-world note: Use PUT when your automation has the full desired state. It avoids partial-state surprises that can happen with PATCH.

Verify:

# Expected HTTP response for successful creation
HTTP/1.1 201 Created
Content-Length: 0

# Verify with a GET to show the new interface
curl -k -u admin:Lab@123 -H "Accept: application/yang-data+json" https://10.85.134.92/restconf/data/ietf-interfaces:interfaces/interface=Loopback100

# Expected verification GET output (example)
HTTP/1.1 200 OK
Content-Type: application/yang-data+json

{
  "interface": {
    "name": "Loopback100",
    "type": "iana-if-type:softwareLoopback",
    "enabled": true,
    "ipv4": {
      "address": [
        {
          "ip": "100.100.100.1",
          "netmask": "255.255.255.255"
        }
      ]
    }
  }
}

Step 4: Partially change configuration using RESTCONF PATCH (non-idempotent/partial)

What we are doing: We show a PATCH to change a single attribute (for example, toggling the interface enabled state or changing an IP). PATCH is used for partial updates where you do not want to replace the entire resource.

# PATCH to disable Loopback100 (JSON Patch payload)
curl -k -u admin:Lab@123 -X PATCH -H "Content-Type: application/yang-data+json" \
  -d '{"ietf-interfaces:interface": {"enabled": false}}' \
  https://10.85.134.92/restconf/data/ietf-interfaces:interfaces/interface=Loopback100

What just happened:

• The PATCH request submits only the portion of the resource to change. The server updates the specific nodes while leaving other nodes intact.
• If successful, PATCH commonly returns 200 OK or 204 No Content.

Real-world note: PATCH is useful during orchestrations that need to toggle a single parameter without risking unintended replacement of other config.

Verify:

# Expected HTTP response for successful PATCH
HTTP/1.1 204 No Content

# Verify with GET
curl -k -u admin:Lab@123 -H "Accept: application/yang-data+json" https://10.85.134.92/restconf/data/ietf-interfaces:interfaces/interface=Loopback100

# Expected verification GET output (example)
HTTP/1.1 200 OK
Content-Type: application/yang-data+json

{
  "interface": {
    "name": "Loopback100",
    "type": "iana-if-type:softwareLoopback",
    "enabled": false,
    "ipv4": {
      "address": [
        {
          "ip": "100.100.100.1",
          "netmask": "255.255.255.255"
        }
      ]
    }
  }
}

Step 5: Delete a configuration resource using RESTCONF DELETE

What we are doing: We remove the created Loopback100 to return the device to the prior state. DELETE is the standard RESTCONF method to remove a config node.

# DELETE the Loopback100 interface
curl -k -u admin:Lab@123 -X DELETE https://10.85.134.92/restconf/data/ietf-interfaces:interfaces/interface=Loopback100

What just happened:

• The DELETE targets the exact YANG resource identified in the URI. On success the server removes the configuration node and returns 204 No Content. This is a destructive operation; ensure you point at the correct resource.

Real-world note: Automation pipelines should confirm the resource targeted for DELETE is exactly what is intended — mistakes can remove production services.

Verify:

# Expected HTTP response for successful DELETE
HTTP/1.1 204 No Content

# Verify the resource no longer exists
curl -k -u admin:Lab@123 -H "Accept: application/yang-data+json" https://10.85.134.92/restconf/data/ietf-interfaces:interfaces/interface=Loopback100

# Expected verification GET output when not found
HTTP/1.1 404 Not Found
Content-Type: application/yang-data+json

{
  "ietf-restconf:errors": {
    "error": [
      {
        "error-type": "protocol",
        "error-tag": "data-not-found",
        "error-severity": "error",
        "error-message": "Data for a node or value is missing"
      }
    ]
  }
}

Verification Checklist

• Check 1: RESTCONF root reachable — run the curl GET to https://10.85.134.92/restconf/data and confirm HTTP 200 and module list.
  Verification command: see Step 1 curl; expected 200 OK with module entries.
• Check 2: Operational CPU data retrievable — run the Step 2 GET and confirm JSON or XML contains cpu-utilization fields.
  Verification command: Step 2 curl; expected 200 OK with cpu-utilization payload.
• Check 3: CRUD operations behave as expected — PUT returns 201/204, PATCH returns 204, DELETE returns 204, and subsequent GET verifies state.
  Verification commands: Steps 3–5 curl commands and their verification GETs showing created/updated/deleted state.

Common Mistakes

Symptom	Cause	Fix
curl returns SSL certificate error or connection refused	TLS not trusted or RESTCONF/HTTPS disabled on device	Ensure RESTCONF/HTTPS is enabled and provide CA or use lab-only -k temporarily; in production install device cert chain on client
404 Not Found on GET for YANG path	Wrong module or data-node name in URI	Confirm YANG module and container names (remember module-name:container) and use /restconf/data/:
401 Unauthorized or 403 Forbidden	Wrong credentials or insufficient privileges	Verify username and password (Lab@123 in examples) and account has RESTCONF access; check AAA/policy on device
Successful HTTP status but config not applied	Using GET or wrong HTTP method (e.g., GET instead of PUT) or PATCH payload incorrect	Ensure method semantics — use PUT for replace, POST for create under a parent, PATCH for partial update; verify Content-Type matches payload
Device returns XML but client expects JSON	Missing or incorrect Accept header	Set Accept: application/yang-data+json for JSON or application/yang-data+xml for XML

Key Takeaways

• RESTCONF is HTTP-based and uses standard methods (GET, PUT, POST, PATCH, DELETE) mapped to YANG-modeled data; use HTTPS and proper authentication in production.
• JSON and XML encodings are both supported; use the Accept and Content-Type headers to request and send the desired format.
• Use GET for read-only operational/config data, PUT for idempotent replace operations, POST to create resources under a parent container, PATCH for partial updates, and DELETE to remove resources — verify via HTTP status codes and subsequent GETs.
• In production, avoid disabling TLS verification; use proper PKI or client certificates. Also, always validate YANG model names and paths before issuing write operations to prevent accidental misconfiguration.

Tip: Think of RESTCONF like a web API to the device: YANG models define the API schema (like JSON schema), the resource path is the URL, and HTTP methods define how you interact with the resource. This makes integrating with orchestration tools consistent and predictable.