Cisco RESTCONF on IOS-XE/XR: YANG Automation for 2026 Networks

Implementing programmatic control planes via YANG-modeled APIs is no longer an aspiration; it's a critical operational imperative for modern network infrastructure. Cisco's IOS-XE and IOS-XR platforms have matured their RESTCONF (RFC 8040) implementations significantly, offering HTTP/JSON-centric interfaces to their underlying YANG datastores. This guide dissects their capabilities, focusing on practical deployment, interoperability with NETCONF, and the pivotal role of various YANG model sets – IETF, OpenConfig, and Cisco-native – in driving scalable automation.

Enabling RESTCONF on IOS-XE and IOS-XR

To leverage RESTCONF, specific configurations are necessary to expose the API endpoints. On IOS-XE (17.x upwards), this typically involves enabling the restconf service, ensuring HTTPS is active, and often configuring AAA for secure access. The underlying HTTP server listens on port 443 by default. For brownfield upgrades, confirm no ACLs block this traffic and that ip http secure-server is active. Older IOS-XE versions might require restconf authentication local or similar directives depending on the AAA setup. For critical production systems, always integrate with a robust AAA policy server leveraging TACACS+ or RADIUS, ensuring granular authorization.

IOS-XR, with its distributed architecture, typically comes with RESTCONF enabled by default on recent versions (24.x onwards, formerly 7.x). However, network-wide access control lists (ACLs) or VRF configurations might still impede connectivity. Verify reachability and ensure the grpc package (which bundles RESTCONF, NETCONF, and gRPC) is operational. Unlike IOS-XE's more monolithic configuration for HTTP, XR's API services are often managed via process-specific configurations. Performance considerations dictate dedicating a separate management interface for API traffic, especially during large-scale configuration pushes or significant streaming telemetry subscriptions.

IOS-XE Catalyst 9300X-48HXN Configuration Snippet

interface GigabitEthernet1/0/1
 description --- RESTCONF Mgmt Interface ---
 vrf forwarding MGMT_VRF
 ip address 10.0.0.1 255.255.255.0
!
ip http secure-server
restconf
!
aaa new-model
aaa authentication login default local
aaa authorization exec default local
username admin privilege 15 secret 5 $1$f1.u$c4Y6aG7qG8Jc3Q0/x00x1
!

IOS-XR NCS 5501-SE Configuration Snippet (minimal for API access)

!
service grpc
    enable
    tls profile default
!
interface GigabitEthernet0/0/0/0
 description --- RESTCONF Mgmt Interface ---
 vrf MgmtVrf
 ipv4 address 10.0.0.2 255.255.255.0
!
username admin
 group root-lr
 password encrypted $6$R4LzXhG2$D/kEa.Q/D.r0x0y0z0W0v0U0s0P0o0N0l0K0j0I0h0g0f0e0d0c0b0a0
!

YANG Model Landscape: IETF, OpenConfig, and Cisco-Native

The strength of RESTCONF lies in its reliance on YANG (Yet Another Next Generation) data models. These models define the structure, syntax, and semantics of configuration and state data, enabling schema-driven interactions. A nuanced understanding of the available model sets is crucial for effective automation.

• IETF Models: Standardized models like ietf-interfaces, ietf-routing, ietf-bgp provide vendor-agnostic representation of fundamental network elements. They are excellent for interoperability but can sometimes lack vendor-specific nuances or advanced features.
• OpenConfig Models: Developed by network operators, OpenConfig (e.g., openconfig-interfaces, openconfig-network-instance, openconfig-bgp) aims for a consistent, vendor-neutral operational configuration across multi-vendor environments. They often offer richer operational state data than IETF models and are preferred for telemetry.
• Cisco-Native Models: These models (e.g., Cisco-IOS-XE-native, Cisco-IOS-XR-um-*) expose the entirety of CLI functionality, including proprietary features. While essential for full control, they tie automation scripts directly to Cisco-specific constructs, reducing portability. For brownfield migrations from CLI to API, mapping existing CLI config to native YANG models is often the most straightforward first step for auditing and automation.

When designing automation workflows, prioritize OpenConfig or IETF models where feasible for future-proofing and vendor independence. Reserve Cisco-native models for specific features not yet covered by standardized YANG or for transitional phases where direct CLI-to-YANG translation is required. Establishing clear YANG model governance is paramount for large-scale deployments.

Datastores and URI Encoding

RESTCONF interacts with various datastores on the device:

• running (IOS-XE/XR): The currently active configuration. Directly modifying running config is common on IOS-XE.
• candidate (IOS-XR): A proposed configuration that can be manipulated and then committed. This provides a transaction-like workflow, crucial for complex changes. IOS-XE does not typically expose a candidate datastore via RESTCONF, relying on direct running configuration modifications.
• intended (IOS-XR): Represents the desired state.
• operational (IOS-XE/XR): Read-only state data (e.g., interface status, routing table entries).

URI encoding is critical for accessing specific data nodes. Key-value pairs in lists are specified directly in the URI, with special characters requiring standard URL encoding (e.g., '/' becomes '%2F'). For instance, targeting a specific interface in the native datastore on IOS-XE:

/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=1%2F0%2F1

Or an OpenConfig interface:

/restconf/data/openconfig-interfaces:interfaces/interface=GigabitEthernet1%2F0%2F2

Understanding the YANG path structure and how it translates to the RESTCONF URI is foundational for crafting accurate API calls. Tools like pyang or the built-in YANG explorer on Cisco devices (e.g., show yang tree or web-based explorers) are invaluable for navigating the model hierarchy and identifying correct paths.

CRUD Operations: GET, POST, PATCH, PUT, DELETE

RESTCONF maps standard HTTP methods to CRUD operations on YANG data nodes.

• GET: Retrieves configuration or operational state data. This is typically the most frequently used operation for auditing and monitoring.
• POST: Creates a new data resource (e.g., a new interface, a new VLAN). It's used for adding new elements to a list or creating singleton nodes.
• PUT: Replaces an entire data resource or creates it if it doesn't exist. Use with caution; a PUT to a list item will replace all attributes of that item. A PUT to a container can replace all its children.
• PATCH: Modifies existing data resources. This is the preferred method for making atomic, partial updates to configuration elements, as it only sends the changed attributes. This minimizes the risk of unintended side effects and reduces bandwidth consumption.
• DELETE: Removes a data resource.

Content negotiation uses Accept and Content-Type headers. application/yang-data+json is generally preferred over application/yang-data+xml for its readability and lightweight nature, especially in modern cloud-native environments. When working with actions, the media type shifts to application/yang.data+json or application/yang.data+xml. These distinctions are critical for successful API interactions and often overlooked, leading to HTTP 415 (Unsupported Media Type) errors.

Example: Enabling an L3 Interface on IOS-XE via OpenConfig PATCH

We'll configure Gig1/0/2 with IP 10.0.0.3/24 using OpenConfig models. Note the use of PATCH for partial update.

# Step 1: Add a new interface (if it doesn't exist) and set its name and type
curl -k -v -u 'admin:Pa55w0rd!@#' -X POST https://10.0.0.1/restconf/data/openconfig-interfaces:interfaces \
   -H 'Accept: application/yang-data+json' -H 'Content-Type: application/yang-data+json' -d '
{
    "openconfig-interfaces:interface": [
        {
            "name": "GigabitEthernet1/0/2",
            "config": {
                "type": "iana-if-type:ethernetCsmacd",
                "description": "Configured via RESTCONF OpenConfig"
            }
        }
    ]
}
'

# Step 2: Configure the interface properties and enable it
curl -k -v -u 'admin:Pa55w0rd!@#' -X PATCH https://10.0.0.1/restconf/data/openconfig-interfaces:interfaces/interface=GigabitEthernet1%2F0%2F2 \
   -H 'Accept: application/yang-data+json' -H 'Content-Type: application/yang-data+json' -d '
{
    "openconfig-interfaces:interface": [
        {
            "name": "GigabitEthernet1/0/2",
            "config": {
                "enabled": true
            },
            "subinterfaces": {
                "subinterface": [
                    {
                        "index": 0,
                        "openconfig-if-ip:ipv4": {
                            "addresses": {
                                "address": [
                                    {
                                        "ip": "10.0.0.3",
                                        "config": {
                                            "ip": "10.0.0.3",
                                            "prefix-length": 24
                                        }
                                    }
                                ]
                            },
                            "config": {
                                "enabled": true
                            }
                        }
                    }
                ]
            }
        }
    ]
}
'

Example: Configuring a BGP Neighbor on IOS-XR via OpenConfig PATCH

This configures a basic BGP neighbor using OpenConfig models. Assume AS 65000 and neighbor 10.0.0.10.

curl -k -v -u 'admin:Pa55w0rd!@#' -X PATCH https://10.0.0.2/restconf/data/openconfig-network-instance:network-instances/network-instance=default/protocols/protocol=BGP,global/bgp:bgp \
    -H 'Accept: application/yang-data+json' -H 'Content-Type: application/yang-data+json' \
    -d '
{
    "openconfig-bgp:bgp": {
        "global": {
            "config": {
                "as": 65000
            }
        },
        "neighbors": {
            "neighbor": [
                {
                    "neighbor-address": "10.0.0.10",
                    "config": {
                        "neighbor-address": "10.0.0.10",
                        "peer-as": 65000,
                        "description": "RESTCONF BGP Neighbor"
                    },
                    "afi-safis": {
                        "afi-safi": [
                            {
                                "afi-safi-name": "openconfig-bgp-types:IPV4_UNICAST",
                                "config": {
                                    "afi-safi-name": "openconfig-bgp-types:IPV4_UNICAST",
                                    "enabled": true
                                }
                            }
                        ]
                    }
                }
            ]
        }
    }
}
'

Retrieving Operational State and Telemetry

Monitoring network devices via RESTCONF involves GET requests to operational state datastores. For streaming telemetry, YANG-Push (RFC 8641) over HTTP/2 is the RESTCONF counterpart to NETCONF subscriptions. This allows clients to subscribe to specific data nodes and receive updates when changes occur, significantly improving visibility and reducing polling overhead.

Example: Getting Operational State of Interfaces on IOS-XE

Using the openconfig-interfaces:interfaces-state model for vendor-neutral operational data.

curl -k -v -u 'admin:Pa55w0rd!@#' -X GET https://10.0.0.1/restconf/data/openconfig-interfaces:interfaces-state \
   -H 'Accept: application/yang-data+json'

Response snippet:

HTTP/1.1 200 OK
Content-Type: application/yang-data+json

{
  "openconfig-interfaces:interfaces-state": {
    "interface": [
      {
        "name": "GigabitEthernet1/0/1",
        "statistics": {
          "in-octets": "1234567",
          "out-octets": "7654321"
        },
        "admin-status": "UP",
        "oper-status": "UP",
        "mtu": 1500
      },
      {
        "name": "GigabitEthernet1/0/2",
        "statistics": {
          "in-octets": "1234",
          "out-octets": "4321"
        },
        "admin-status": "UP",
        "oper-status": "UP",
        "mtu": 1500
      }
    ]
  }
}

YANG-Push Subscription (i.e., Streaming Telemetry)

Subscribing to streaming telemetry requires a POST request to the /restconf/operations/ietf-yang-push:establish-subscription endpoint, specifying the data to monitor and the update frequency. The response establishes a persistent HTTP/2 stream for event notification. This is crucial for real-time monitoring and proactive anomaly detection, moving beyond traditional SNMP polling. For instance, monitoring BGP peer state changes:

curl -k -v -u 'admin:Pa55w0rd!@#' -X POST https://10.0.0.2/restconf/operations/ietf-yang-push:establish-subscription \
   -H 'Accept: application/yang.data+json' -H 'Content-Type: application/yang.data+json' -d '
{
    "ietf-yang-push:input": {
        "datastore": "operational",
        "subtree-filter": {
            "openconfig-network-instance:network-instances": {
                "network-instance": [
                    {
                        "name": "default",
                        "protocols": {
                            "protocol": [
                                {
                                    "identifier": "openconfig-bgp-types:BGP",
                                    "name": "global",
                                    "bgp": {
                                        "neighbors": {}
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        "period": 10000, "encoding": "encode-json", "stream": "yang-push", "transport": "ietf-yang-push:http2"
    }
}
'

The device would then push JSON updates to the API client whenever the BGP neighbor state changes or relevant metrics are updated, every 10 seconds (10000ms duration).

RESTCONF vs. NETCONF vs. gNMI/gNOI

While RESTCONF offers an HTTP/JSON interface, NETCONF (RFC 6241) provides a more robust, transaction-oriented XML-based protocol over SSH (typically port 830). NETCONF has stronger error handling capabilities and explicit commit/rollback semantics, which are particularly valuable for complex, multi-stage configuration changes. IOS-XR natively supports a candidate datastore via NETCONF, providing a full transaction lifecycle.

gNMI (gRPC Network Management Interface) and gNOI (gRPC Network Operations Interface) are emerging standards, notably on IOS-XR, offering high-performance, bidirectional streaming based on Google's gRPC framework. They leverage Protobuf for data serialization, which is more efficient for high-volume telemetry. While RESTCONF is widely supported and simpler to integrate with web-based tooling, gNMI/gNOI are gaining traction for carrier-grade telemetry and operational tasks due to their efficiency. For 2026, expect gNMI to become the de facto standard for high-volume streaming telemetry, while RESTCONF and NETCONF will continue to coexist for traditional configuration and occasional state retrieval.

Feature	RESTCONF	NETCONF	gNMI/gNOI
Protocol	HTTP/HTTPS (REST)	SSH	gRPC over HTTP/2
Data Encoding	JSON, XML	XML	Protobuf
Datastores	running, operational, (candidate, intended on XR)	running, startup, candidate, operational	operational, candidate, intended
Transaction Mgt.	Depends on device (explicit commit on XR, direct to running on XE)	Full commit/rollback (explicit)	Transaction-like via Set
Telemetry	YANG-Push (HTTP/2)	NETCONF Notifications	Streaming Telemetry (high-perf)
Complexity	Lower (web browser tools)	Medium (specialized clients)	Higher (Protobuf schema, custom client)
Use Case	Web-centric automation, simple CRUD, ad-hoc scripting	Robust configuration management, complex change control	High-scale telemetry, fast operational tasks, cloud-native integration

Automation Tooling: YDK, Ansible, NSO

Effective utilization of RESTCONF demands robust tooling:

• Pyang/YANG Explorer: Essential for model discovery, syntax validation, and understanding data paths.
• Python with requests: For direct RESTCONF interactions. Offers maximum flexibility but requires writing more boilerplate code.
• YDK-Py (YANG Development Kit): Cisco's SDK for YANG-driven automation. It generates API bindings for various programming languages from YANG models, simplifying interaction with network elements. While powerful, it adds another layer of abstraction and dependency. The YDK framework supports both NETCONF and RESTCONF protocols, making it a versatile choice.
• Ansible: The cisco.ios and cisco.iosxr collections offer modules like ios_restconf, ios_config, iosxr_netconf, and iosxr_config. While Ansible's network_resource modules (e.g., ios_l3_interface) abstract away YANG/CLI complexities, cli_config or direct RESTCONF modules offer explicit control for brownfield CLI-to-YANG translation. For example, using ios_restconf directly maps to the RESTCONF API.
• Cisco NSO (Network Services Orchestrator): A multi-vendor, model-driven orchestration platform. NSO acts as a single source of truth for network configuration, translating generic service models into device-specific YANG or CLI commands via ConfD. NSO's device and service modeling capabilities are unparalleled for large, heterogeneous networks where transactionality and rollback are non-negotiable.

For day-0 zero-touch provisioning (ZTP) scenarios, PnP (Plug and Play) combined with RESTCONF can automate initial device onboarding, allowing devices to pull configuration from a centralized controller. This drastically reduces manual intervention and accelerates deployment cycles. During day-2 operations, RESTCONF becomes the backbone for configuration audits, drift detection, and automated remediation, ensuring policy adherence across the network.

Example: Python using requests to retrieve interfaces

import requests
from requests.auth import HTTPBasicAuth
import json

def get_interfaces(host, username, password):
    url = f"https://{host}/restconf/data/openconfig-interfaces:interfaces-state"
    headers = {
        "Accept": "application/yang-data+json"
    }
    try:
        response = requests.get(url, headers=headers, auth=HTTPBasicAuth(username, password), verify=False)
        response.raise_for_status() # Raise an exception for HTTP errors
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"API request failed: {e}")
        return None

if __name__ == "__main__":
    IOS_XE_HOST = "10.0.0.1"
    IOS_XE_USER = "admin"
    IOS_XE_PASS = "Pa55w0rd!@#"

    interfaces_data = get_interfaces(IOS_XE_HOST, IOS_XE_USER, IOS_XE_PASS)
    if interfaces_data:
        print(json.dumps(interfaces_data, indent=2))

Field Engineering Scenarios and Challenges

In brownfield environments, the biggest challenge is mapping existing CLI configurations to YANG models. This often starts with extensive 'show run' output analysis, followed by trial-and-error with RESTCONF GET requests to observe the device's rendered YANG state. The Cisco-IOS-XE-native:native model greatly eases this, as its structure closely mirrors the CLI. However, for future-proofing, translating selected components to OpenConfig should be a strategic goal.

Day-2 operations heavily benefit from RESTCONF for proactive monitoring and configuration drift detection. Regularly pulling the running configuration via GET and comparing it against an intended baseline (e.g., in Git) can flag unauthorized changes. For example, an unexpected change on a Catalyst 9300X-48HXN's VLAN configuration, or an unapproved BGP neighbor on an ASR 1001-HX. Automating such audits with a Python script or an Ansible playbook ensures configuration integrity and compliance, mitigating configuration errors caused by manual interventions. Early detection of misconfigurations on critical links can prevent widespread outages.

Failure modes in production often arise from malformed RESTCONF requests (incorrect URI, invalid JSON payload, missing headers), leading to HTTP 400 (Bad Request) or 404 (Not Found). Incorrect authentication results in 401 (Unauthorized) or 403 (Forbidden), often due to misconfigured AAA on the device. Rate limiting on the device's management plane can also cause issues under heavy load, leading to HTTP 429 (Too Many Requests). Designing client applications with proper error handling, retries with exponential backoff, and robust logging is paramount. In high-stakes environments, such as a major service provider operating NCS 5500 series, a failed commit via RESTCONF from an orchestration system could leave the device in an inconsistent state if not properly handled with transaction mechanisms or idempotency. This is where NETCONF's explicit commit/rollback offers a safety net that RESTCONF lacks on IOS-XE.

Verdict

For brownfield IOS-XE deployments where CLI-centric muscle memory is prevalent, RESTCONF with native YANG models offers the quickest path to API-driven automation, especially for auditing and simple configuration tasks (e.g., interface descriptions, IP address changes on Catalyst 9300X-48HXN or Catalyst 9500-24Y4C). It's a natural evolution from expect scripts.

For greenfield or strategic upgrades targeting multi-vendor environments and modern CI/CD pipelines, OpenConfig over RESTCONF (or NETCONF/gNMI where available) is the superior choice. It emphasizes vendor neutrality and robust telemetry, critical for architects making seven-figure procurement decisions involving Nexus 9k or ASR 9000 series platforms.

For mission-critical deployments requiring robust transactionality, explicit commit/rollback, and efficient bulk operations (e.g., provisioning hundreds of VPNs), NETCONF over SSH with a candidate datastore (on IOS-XR) remains the gold standard. For pure, high-volume telemetry, gNMI on IOS-XR is quickly becoming the undisputed champion for platforms like the NCS 5500 series and ASR 9000.

The choice is not binary; a hybrid approach often yields the best results, using RESTCONF for agile, lightweight automation, NETCONF for structured configuration, and gNMI for high-fidelity operational insights. The key is to understand each protocol's strengths and weaknesses relative to the specific operational requirement and platform capabilities.

Related reading

• Fortinet FortiGate 7.6 NGFW Design Considerations for Large Enterprises
• Ansible Network Automation: Strategies for Building Resilient Playbooks
• Cisco NSO Service Modeling Deep Dive for Multi-Vendor Orchestration
• Implementing Zero Trust with Adaptive Access Control in Hybrid Clouds
• SD-WAN Multi-Cloud Connectivity Architectures for 2025