Chapter 2: NETCONF, RESTCONF, and Building YANG Payloads

1.1 The Four-Layer NETCONF Architecture

NETCONF (RFC 6241) is built on a clean four-layer model that separates concerns cleanly. The transport layer (SSH) handles encryption and authentication. The message layer wraps every operation in a consistent <rpc> envelope with a unique message-id for correlation. The operations layer defines a small, precise set of verbs. The content layer is where YANG lives — the device accepts any valid XML document conforming to its loaded YANG models.

1.2 Capabilities Exchange and Datastores

After SSH is established, both sides simultaneously send a <hello> message listing URNs for every supported feature. This includes NETCONF base versions, capability URNs (candidate, confirmed-commit, validate), and a namespace URI + revision date for every loaded YANG module — effectively a machine-readable bill of materials for the device's management API.

RFC 6241 defines three standard datastores:

On Cisco IOS XE, enable the candidate datastore with:

netconf-yang
netconf-yang feature candidate-datastore

1.3 Core RPC Operations

1.4 Confirmed Commit Workflow

The confirmed commit (capability URN: urn:ietf:params:netconf:capability:confirmed-commit:1.1) is the critical safety net for production changes. When a confirmed commit with <confirm-timeout> is issued:

1. The candidate config is committed to running (change takes effect immediately).
2. A countdown timer starts (default: 600 seconds).
3. If a confirming <commit> arrives before timeout, the change is permanent.
4. If the timer expires without confirmation, the device automatically rolls back to the pre-commit configuration.

Key use case: if the change breaks the management path and your session drops, you cannot send a confirming commit. Ten minutes later the device self-recovers without any console intervention.

1.5 Best-Practice Candidate Datastore Workflow

If anything fails between steps 3 and 5, issue <discard-changes> to reset the candidate before unlocking.

1.6 Complete edit-config Example

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config>
    <target><candidate/></target>
    <config>
      <native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
        <interface>
          <GigabitEthernet>
            <name>1</name>
            <description>Uplink to Core</description>
            <ip>
              <address>
                <primary>
                  <address>192.168.1.1</address>
                  <mask>255.255.255.0</mask>
                </primary>
              </address>
            </ip>
          </GigabitEthernet>
        </interface>
      </native>
    </config>
  </edit-config>
</rpc>

2.1 What is RESTCONF?

RESTCONF (RFC 8040) exposes the same YANG data models as NETCONF through a conventional HTTP/HTTPS REST API. Any developer who has consumed a REST API can apply those same skills to a Cisco device. RESTCONF is explicitly a subset of NETCONF: it omits datastores, explicit locking, and confirmed commits in exchange for universal accessibility via HTTPS and native JSON support.

2.2 Enabling RESTCONF on Cisco IOS XE

netconf-yang
restconf
ip http secure-server

netconf-yang must be configured first — RESTCONF reuses the YANG model infrastructure that NETCONF initializes. The API root is discoverable via GET https://{device}/.well-known/host-meta; on IOS XE this points to /restconf. Data resources live under /restconf/data/; operations (RPCs/actions) under /restconf/operations/.

2.3 URI Construction

URI construction is one of the highest-frequency exam topics. The pattern is:

https://{device}/restconf/data/{module-name}:{top-container}/{child}/{list}={key}

Concrete example — GigabitEthernet 1 via the native model:

https://192.168.1.1/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=1

Additional rules: module boundary augmentations require the augmenting module prefix (e.g. openconfig-if-ip:ipv4); multiple list keys are comma-separated (/BGPNeighbor={address},{vrf}); special characters in key values must be percent-encoded.

2.4 HTTP Methods and Their NETCONF Equivalents

2.5 Content Negotiation and Query Parameters

3.1 RFC 7951 JSON Encoding Rules

Every failed RESTCONF call fails for the same root cause: the payload does not match the YANG model. RFC 7951 defines the encoding rules:

1. Module name as namespace prefix — at every module boundary, prefix the key with the module name and a colon: "Cisco-IOS-XE-native:native".
2. Lists become JSON arrays — each list entry is a JSON object; the key field is a regular property within that object.
3. Containers become JSON objects — standard key-value maps.
4. Leaf-lists become JSON arrays of primitives — e.g., an array of strings.
5. Empty-type leaves — represented as [null].

3.2 Mapping a YANG Tree to JSON

Using pyang to view the relevant YANG tree section:

pyang -f tree --tree-path /native/interface/GigabitEthernet Cisco-IOS-XE-native.yang

module: Cisco-IOS-XE-native
  +--rw native
     +--rw interface
        +--rw GigabitEthernet* [name]      <-- list, key=name
           +--rw name          string
           +--rw description?  string      <-- optional leaf (?)
           +--rw ip
              +--rw address
                 +--rw primary
                    +--rw address  inet:ipv4-address
                    +--rw mask     inet:ipv4-address

Translated to JSON for a full PATCH targeting the native container:

{
  "Cisco-IOS-XE-native:native": {
    "interface": {
      "GigabitEthernet": [
        {
          "name": "1",
          "description": "Uplink to Core",
          "ip": {
            "address": {
              "primary": {
                "address": "192.168.1.1",
                "mask": "255.255.255.0"
              }
            }
          }
        }
      ]
    }
  }
}

3.3 pyang Workflows for JSON Payload Construction

3.4 Cisco YANG Suite GUI Workflow

YANG Suite (available as a Docker container at http://localhost:8480) provides a point-and-click workflow: create a YANG Set, navigate the visual tree, check nodes and enter values, select RESTCONF + JSON encoding, and review the generated URI and payload. Click "Run RPC" to execute directly, or copy the payload for use in Python/Ansible/Postman.

Validate any JSON payload before sending to a device using yanglint:

yanglint --format json Cisco-IOS-XE-native.yang my_payload.json

4.1 XML Namespace Rules for NETCONF Payloads

XML is the exclusive data format for NETCONF. Every top-level container element in a <config> block must carry an xmlns attribute declaring the namespace URI of the YANG module. Getting this wrong is the most common cause of NETCONF payload failures.

The namespace appears once on the top-level container element and is inherited by all children within the same module. Child elements at a module boundary (augmentations) must declare their own xmlns.

To delete a specific element, add the operation attribute to the target node:

<description nc:operation="delete"
  xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"/>

4.2 Subtree and XPath Filters

Subtree filter — uses XML element matching; empty elements select all content beneath:

<filter type="subtree">
  <native xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
    <interface>
      <GigabitEthernet><name>1</name></GigabitEthernet>
    </interface>
  </native>
</filter>

XPath filter — uses an XPath expression string; requires the XPath capability to be advertised:

<filter type="xpath"
  select="/native/interface/GigabitEthernet[name='1']"
  xmlns:ios="http://cisco.com/ns/yang/Cisco-IOS-XE-native"/>

4.3 NETCONF vs. RESTCONF: Protocol Comparison

The most exam-tested distinction: RESTCONF has no candidate datastore, no locking, and no confirmed commit. For any scenario requiring transactional safety or automatic rollback, NETCONF is the answer.