NETCONF and RESTCONF — Model-Driven Network APIs

The one-sentence mental model

Screen-scraping the CLI is fragile. Model-driven APIs are contracts. Instead of parsing “show ip interface brief” text output, you fetch a YANG-shaped tree of interface state — same on every version, same across platforms that share the model.

Layers stacked together

  Your automation code (Python / Ansible / Terraform)
       ↓
  Protocol:  NETCONF (XML / SSH) or RESTCONF (JSON / HTTPS)
       ↓
  YANG data model  (structure of the config / state)
       ↓
  Device (IOS-XE, NX-OS, IOS-XR, JunOS, Arista, etc.)

• YANG = the schema. Defines what fields exist and their types.
• NETCONF / RESTCONF = the wire protocols that carry YANG-modeled data.
• gNMI = a newer alternative — same YANG models but over gRPC (see the telemetry topic).

NETCONF quick facts

• Transport: SSH, port 830 (default).
• Encoding: XML.
• Operations: <get>, <get-config>, <edit-config>, <commit>, <lock>, <validate>, <discard-changes>, <close-session>.
• Datastores: running (live), candidate (staging area), startup (saved), sometimes intended.
• Capabilities: on session open, device advertises which YANG modules + features it supports.

Typical flow:

1. Open SSH session on port 830.
2. Exchange <hello> — device sends capabilities.
3. <lock> the candidate datastore.
4. <edit-config> to stage changes.
5. <validate> (optional) — syntax check.
6. <commit> to apply.
7. <unlock> → <close-session>.

Because commit is atomic across the candidate → running move, either everything applies or nothing does. That’s the killer feature vs REST.

RESTCONF quick facts

• Transport: HTTPS.
• Encoding: JSON (application/yang-data+json) or XML.
• Operations: standard HTTP verbs — GET, POST (create), PUT (replace), PATCH (merge), DELETE.
• Base URL: https://<device>/restconf/data/<yang-module>:<container>/...

Sample GET on IOS-XE for a specific interface:

curl -k -u admin:pass \
  -H "Accept: application/yang-data+json" \
  https://10.0.0.1/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1

Sample PUT to set an IP:

curl -k -u admin:pass -X PUT \
  -H "Content-Type: application/yang-data+json" \
  -d '{"ietf-interfaces:interface":{"name":"GigabitEthernet1","enabled":true,"ietf-ip:ipv4":{"address":[{"ip":"10.10.1.1","netmask":"255.255.255.0"}]}}}' \
  https://10.0.0.1/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1

Turning them on (IOS-XE)

netconf-yang
restconf
ip http secure-server

Then confirm:

show netconf-yang datastores
show netconf-yang sessions
show platform software yang-management process

Python quickstart

NETCONF with ncclient:

from ncclient import manager
with manager.connect(host="10.0.0.1", port=830, username="admin",
                     password="pass", hostkey_verify=False) as m:
    print(m.get_config(source="running").data_xml[:2000])

RESTCONF with requests:

import requests
requests.packages.urllib3.disable_warnings()
r = requests.get(
    "https://10.0.0.1/restconf/data/ietf-interfaces:interfaces",
    auth=("admin","pass"),
    headers={"Accept": "application/yang-data+json"},
    verify=False)
print(r.json())

Ansible ships modules for both (ansible.netcommon.netconf_get, ansible.netcommon.restconf_config).

When to pick which

NETCONF when:

• You need atomic multi-change transactions (candidate + commit).
• You need <lock> to prevent parallel changes during a change window.
• You’re using a mature framework like NSO / OpenDaylight.

RESTCONF when:

• You want to script quick tooling with curl / Postman / vanilla requests.
• Your team already speaks REST.
• Transactional atomicity isn’t required (single-request changes).

gNMI when:

• You want telemetry (streaming state changes over persistent connection).
• Multi-vendor at scale — gNMI is more standardized across vendors than either.

Common exam / real-world mistakes

1. Confusing YANG with NETCONF. YANG is the schema; NETCONF is the transport. Same YANG can be used over NETCONF, RESTCONF, or gNMI.
2. Assuming RESTCONF is transactional. It isn’t. A PATCH that touches many fields may partially apply and error out. Reach for NETCONF if you need atomic.
3. Mixing OpenConfig and Cisco-native models. Every device supports both. Same feature, different YANG structure. Standardize on one per project or pay in translation code.
4. Ignoring capabilities. Two IOS-XE versions may advertise different YANG modules. Always fetch the device’s capabilities before assuming a path exists.
5. Password in the config. Basic auth over HTTPS is convenient in the lab but painful in prod. Move to certificate-based auth or vault-managed secrets.

Cheat strip

YANG        the schema. Both protocols speak it.

NETCONF     XML over SSH port 830. Rich: locks, candidate/running/startup,
            commit/rollback, atomic transactions. Client: ncclient.
RESTCONF    JSON (or XML) over HTTPS. Standard REST verbs. curl-friendly.
            Client: requests / Postman / any HTTP tool.

Enable IOS-XE:
  netconf-yang
  restconf
  ip http secure-server

Operations
  NETCONF   <get> <get-config> <edit-config> <commit> <lock> <validate>
  RESTCONF  GET / POST / PUT / PATCH / DELETE

Pick        transactional multi-change   → NETCONF
            quick REST scripts           → RESTCONF
            streaming telemetry          → gNMI