Chapter 5: Python Network Automation with RESTCONF

RESTCONF is an HTTPS-based protocol (RFC 8040) that exposes a Cisco IOS XE device's YANG data model as a set of addressable URLs. Python's requests library acts as the HTTP client, allowing you to read, create, update, and delete device configuration and state data using standard HTTP operations.

1.1 Enabling RESTCONF on IOS XE

Three IOS XE configuration commands are required before any Python script can reach the RESTCONF API:

ip http secure-server
ip http authentication local
restconf

username admin privilege 15 secret Cisco1234!

Verify the service is running with show platform software yang-management process and show restconf capabilities. If the yang-management process is active and capabilities are returned, the device is ready.

1.2 Python Environment and Headers

Always isolate RESTCONF projects in a virtual environment (pip install requests). Every RESTCONF script requires two elements:

• Headers — Accept and Content-Type must both be set to application/yang-data+json (RFC 8040 media type)
• Authentication — Use requests.auth.HTTPBasicAuth; never hard-code credentials — load from environment variables

RESTCONF_HEADERS = {
    'Accept': 'application/yang-data+json',
    'Content-Type': 'application/yang-data+json'
}
AUTH = HTTPBasicAuth(os.environ['RESTCONF_USER'], os.environ['RESTCONF_PASS'])

1.3 RESTCONF URI Construction

A RESTCONF URI is a direct serialization of the YANG model hierarchy. The formula is:

https://<device>/restconf/data/<module>:<container>/<list>=<key>/<leaf>

The IETF model uses interface=GigabitEthernet1 (single string key), while the Cisco native model splits on type: GigabitEthernet=1. Interface names containing forward slashes (e.g., GigabitEthernet1/0/1) must be percent-encoded using urllib.parse.quote(name, safe='') to prevent the slash from being interpreted as a path separator.

1.4 Choosing the Right YANG Model

On IOS XE 17.7.1+, run show running-config | format restconf-json on the device CLI to instantly discover the correct YANG URI for any existing configuration element.

The five HTTP methods map directly onto database CRUD operations. Understanding the exact semantics of each — especially the difference between PUT and PATCH — is essential for both the exam and production automation.

2.1 GET — Reading Configuration and State

GET retrieves the current value of any resource. Use the fields query parameter to fetch only specific leaves and dramatically reduce response size on devices with many interfaces:

# All interfaces
url = f"{DATA_URL}/ietf-interfaces:interfaces"

# Filtered response — only name and IPv4 address
url = f"{DATA_URL}/ietf-interfaces:interfaces?fields=interface/name;interface/ietf-ip:ipv4/address"

response = requests.get(url, headers=RESTCONF_HEADERS, auth=AUTH, verify=False)
response.raise_for_status()
data = response.json()

2.2 PUT vs. PATCH — The Critical Distinction

PUT fully replaces the target resource. If you PUT a payload that omits a field, that field is deleted from the device configuration. Use PUT for idempotent provisioning where you own the complete desired state.

PATCH merges the payload into the existing resource. Fields not present in the PATCH payload are left unchanged. Use PATCH for targeted single-field updates. Think of PUT as repainting an entire wall, PATCH as touching up a single scuff mark.

# PATCH — only updates description, leaves IP address untouched
payload = {
    "ietf-interfaces:interface": {
        "name": "GigabitEthernet1",
        "description": "Primary WAN — Updated 2024"
    }
}
response = requests.patch(url, headers=RESTCONF_HEADERS, auth=AUTH,
                          json=payload, verify=False)
# Returns 204 on success

2.3 POST and DELETE

POST creates a new child resource and returns 201 Created. If the resource already exists it returns 409 Conflict — always handle this in automation scripts or switch to PUT for create-or-replace semantics.

DELETE removes the target resource and returns 204 No Content. Target the leaf path precisely to avoid accidentally deleting a parent container and all its children.

2.4 Error Handling

Never assume a RESTCONF call succeeded without checking the status code. Build a reusable wrapper:

def restconf_request(method, url, payload=None):
    kwargs = {'headers': RESTCONF_HEADERS, 'auth': AUTH, 'verify': False}
    if payload:
        kwargs['json'] = payload
    response = requests.request(method, url, **kwargs)

    if response.status_code == 400:
        print(f"[ERROR 400] Bad request — check payload: {response.text}")
    elif response.status_code == 401:
        print("[ERROR 401] Authentication failed")
    elif response.status_code == 404:
        print(f"[ERROR 404] Path not found: {url}")
    elif response.status_code == 409:
        print("[ERROR 409] Resource already exists")
    return response

This section applies CRUD primitives to four real-world IOS XE automation tasks aligned with the ENAUTO exam: interface fleet management, static route configuration, ACL provisioning, and VLAN management.

3.1 Interface Fleet Automation

For Day 2 automation across multiple devices, build thin wrapper functions and iterate over a device list. Use PUT for idempotent provisioning — the same script can be re-run safely:

DEVICES = ['10.10.20.48', '10.10.20.49', '10.10.20.50']

def configure_interface_on_device(device_ip, iface_config):
    base = f"https://{device_ip}/restconf/data"
    encoded = urllib.parse.quote(iface_config['name'], safe='')
    url = f"{base}/ietf-interfaces:interfaces/interface={encoded}"
    payload = {"ietf-interfaces:interface": iface_config}
    response = requests.put(url, headers=HEADERS, auth=AUTH,
                            json=payload, verify=False)
    status = "OK" if response.status_code == 204 else f"FAIL ({response.status_code})"
    print(f"  {device_ip} -> {iface_config['name']}: {status}")

3.2 Static Route Configuration

Static routes live under Cisco-IOS-XE-native:native/ip/route. Use PATCH to add a route without disturbing other existing routes — PATCHing the native container merges the new route into the existing configuration.

3.3 ACL Management

Named extended ACLs are managed via Cisco-IOS-XE-native:native/ip/access-list/extended=<name>. Use PUT to create or replace the entire ACL atomically. Use PATCH to add a single new ACE entry to an existing ACL without replacing the whole list.

3.4 Idempotent VLAN Provisioning

VLAN management uses the Cisco-IOS-XE-vlan model. PUT per VLAN ID is idempotent and safe to run repeatedly — it creates the VLAN if absent, or silently overwrites the name if the VLAN ID already exists, with no 409 conflict:

def provision_vlans(device_ip, vlans):
    base = f"https://{device_ip}/restconf/data"
    for vlan in vlans:
        url = f"{base}/Cisco-IOS-XE-native:native/vlan/vlan-list={vlan['id']}"
        payload = {
            "Cisco-IOS-XE-vlan:vlan-list": {
                "id": vlan['id'], "name": vlan['name']
            }
        }
        response = requests.put(url, headers=HEADERS, auth=AUTH,
                                json=payload, verify=False)
        result = "CREATED/UPDATED" if response.status_code == 204 else f"ERROR {response.status_code}"
        print(f"  VLAN {vlan['id']} ({vlan['name']}): {result}")

4.1 Configuration Data vs. Operational Data

Configuration data represents intended state — what you have told the device to do. It is read-write, stored in the running configuration datastore, and accessible via all HTTP methods.

Operational data represents actual state — what the device is currently doing. It is read-only and generated in real time. In YANG schemas, operational data nodes are marked config false. Attempting PUT/PATCH/POST/DELETE on these nodes returns an error.

4.2 Key Operational YANG Modules

4.3 Retrieving Interface Statistics

def get_interface_stats(device_ip, iface_name=None):
    base = f"https://{device_ip}/restconf/data"
    if iface_name:
        encoded = urllib.parse.quote(iface_name, safe='')
        url = f"{base}/Cisco-IOS-XE-interfaces-oper:interfaces/interface={encoded}"
    else:
        fields = "interface/name;interface/oper-status;interface/statistics"
        url = f"{base}/Cisco-IOS-XE-interfaces-oper:interfaces?fields={fields}"
    response = requests.get(url, headers=HEADERS, auth=AUTH, verify=False)
    response.raise_for_status()
    return response.json()

4.4 RESTCONF Polling vs. Model-Driven Telemetry

RESTCONF is a synchronous request-response protocol — it does not push data to you. For monitoring, you must poll at an interval. This has architectural implications:

4.5 Capability Discovery

Before scripting against a specific YANG module, confirm it is loaded on the target device. Different IOS XE versions support different modules — targeting a missing module returns 404:

def list_yang_modules(device_ip, filter_prefix=None):
    url = f"https://{device_ip}/restconf/data/ietf-yang-library:modules-state"
    response = requests.get(url, headers=HEADERS, auth=AUTH, verify=False)
    modules = response.json().get('ietf-yang-library:modules-state', {}).get('module', [])
    if filter_prefix:
        modules = [m for m in modules if m.get('name', '').startswith(filter_prefix)]
    return [(m['name'], m.get('revision', 'unknown')) for m in modules]