Cisco IOS-XE REST API Tutorial: From Zero to Production with YANG Models and Real-World Pitfalls

Why This Matters

Let’s cut the crap. Cisco IOS-XE REST API is a good idea executed poorly.

Our team started down the network automation rabbit hole last year. The goal was simple—replace manual CLI configuration with code. Cisco’s marketing says the REST API “provides an alternative method to the Cisco IOS XE CLI to provision selected functions.” Sounds great on paper.

Reality? The documentation is garbage.

One Reddit user put it perfectly:

“I’m trying to build an APP, for configuring Cisco IOS XE devices. My problem is that I can’t find documentation for the exact paths of the endpoints.”

I felt that pain for three months. This tutorial is what I wish I’d had starting out.

Architecture: Where Does the REST API Actually Live?

Here’s the data flow:

graph TD
    A[Automation Script / App] -->|HTTPS PUT/GET/POST/DELETE| B[Cisco IOS-XE REST API]
    B --> C[nginx Reverse Proxy]
    C --> D[guest shell / Python Process]
    D --> E[YANG Model Layer]
    E --> F[IOS-XE Config Database]
    F --> G[running-config]
    
    H[CLI] -->|Traditional Method| F
    
    style A fill:#4CAF50,stroke:#333,stroke-width:2px
    style B fill:#FF9800,stroke:#333,stroke-width:2px
    style F fill:#2196F3,stroke:#333,stroke-width:2px

The REST API translates your JSON/XML requests into YANG model operations, which ultimately modify the IOS-XE running-config.

Critical distinction: Cisco’s REST API and RESTCONF are NOT the same thing. REST API is Cisco’s proprietary implementation. RESTCONF is the IETF standard (RFC 8040). IOS-XE supports both, but the API paths are completely different.

Use RESTCONF. I’ll explain why later.

Environment Setup: Enabling REST API on CSR1000v

For CSR1000v running IOS-XE 16.12+, enabling the REST API is straightforward:

! Enable REST API
ip http secure-server
rest-api

! Verify status
show rest-api status

Expected output:

REST API is enabled
HTTP Server: Enabled
HTTPS Server: Enabled
Authentication: Local

Simple, right? The complexity comes later.

The Documentation Nightmare

Finding Endpoint Paths

The Reddit user’s problem is universal. Cisco’s official docs give a few examples but nothing comprehensive.

Here’s the workaround I discovered—use GET to discover available paths:

# Discover all available API paths
curl -k -u admin:password \
  https://192.168.1.1/restconf/data

The response lists all supported YANG modules. From there, you can drill down.

Key path reference (took me a month to compile):

Notice the version column—different IOS-XE versions support different YANG models. Using 16.9 docs on a 17.3 box will break things.

Authentication Gotchas

Cisco REST API uses local authentication by default. But here’s the kicker—it doesn’t support CSRF tokens. If you’re sending POST/PUT requests, make sure you’re not including CSRF headers, or you’ll get a 403.

# Correct request format
curl -k -u admin:password \
  -X PUT \
  -H "Content-Type: application/yang-data+json" \
  -H "Accept: application/yang-data+json" \
  -d '{
    "ietf-interfaces:interface": {
      "name": "GigabitEthernet1",
      "type": "iana-if-type:ethernetCsmacd",
      "enabled": true,
      "ietf-ip:ipv4": {
        "address": [
          {
            "ip": "192.168.2.1",
            "netmask": "255.255.255.0"
          }
        ]
      }
    }
  }' \
  https://192.168.1.1/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1

The Commit Trap

IOS-XE REST API applies changes immediately. Unlike NETCONF with its candidate config, a PUT request writes directly to running-config.

This means: one wrong parameter and your device goes offline. We learned this the hard way—forgot to specify a netmask when changing an interface IP, and the interface dropped. Remote access gone. Had to call the datacenter to plug in a console cable.

For production, follow these rules:

1. Always GET current config before making changes
2. Use PATCH instead of PUT for incremental changes
3. Backup config before and after every operation

Real-World Example: Automated NAT Deployment

Another frequent Reddit topic—“deploying NATs to clients.” Here’s how we automated it with RESTCONF:

import requests
import json
from urllib3.exceptions import InsecureRequestWarning

# Disable SSL warnings (test environment only)
requests.packages.urllib3.disable_warnings(category=InsecureRequestWarning)

class CiscoIOSXERestconf:
    def __init__(self, host, username, password, port=443):
        self.base_url = f"https://{host}:{port}/restconf"
        self.auth = (username, password)
        self.headers = {
            "Content-Type": "application/yang-data+json",
            "Accept": "application/yang-data+json"
        }
    
    def configure_nat(self, inside_interface, outside_interface, acl_number):
        """
        Configure dynamic NAT (PAT)
        """
        nat_config = {
            "Cisco-IOS-XE-native:ip": {
                "nat": {
                    "inside": {
                        "source": {
                            "list": [
                                {
                                    "access-list": acl_number,
                                    "interface": outside_interface,
                                    "overload": [None]
                                }
                            ]
                        }
                    }
                }
            }
        }
        
        url = f"{self.base_url}/data/Cisco-IOS-XE-native:native/ip/nat"
        
        response = requests.put(
            url,
            auth=self.auth,
            headers=self.headers,
            json=nat_config,
            verify=False
        )
        
        if response.status_code in [200, 201, 204]:
            print(f"NAT configured successfully: {response.status_code}")
        else:
            print(f"NAT configuration failed: {response.status_code}")
            print(f"Error: {response.text}")
        
        return response
    
    def get_running_config(self):
        """Read-only operation to fetch running config"""
        url = f"{self.base_url}/data/Cisco-IOS-XE-native:native"
        response = requests.get(
            url,
            auth=self.auth,
            headers=self.headers,
            verify=False
        )
        return response.json()

# Usage
device = CiscoIOSXERestconf(
    host="192.168.1.1",
    username="admin",
    password="password"
)

device.configure_nat(
    inside_interface="GigabitEthernet1",
    outside_interface="GigabitEthernet2",
    acl_number=100
)

This works on CSR1000v 17.6. But be warned—YANG model structures differ across IOS-XE versions, especially how fields like overload are represented.

REST API vs RESTCONF vs NETCONF: Which One to Pick?

Here’s the comparison table:

My recommendation: Use RESTCONF. Don’t touch Cisco’s proprietary REST API.

RESTCONF is a standard protocol. Learn it once, use it on Juniper, Arista, whatever. Cisco’s REST API has terrible documentation, poor community support, and breaks with every IOS-XE upgrade.

Production Considerations

Performance

REST API is slower than CLI. Our benchmarks:

• CLI configure interface: ~50ms
• REST API configure interface: ~200ms
• RESTCONF configure interface: ~150ms

The overhead comes from HTTP parsing and YANG model translation. For bulk operations (hundreds of interfaces), use NETCONF or push raw CLI scripts.

Security

REST API only supports local authentication by default. For production:

1. Use HTTPS, never HTTP
2. Configure ACLs to restrict API access
3. Create dedicated API accounts with limited privileges

! Create API-only account
username api-user privilege 15 secret StrongPassword123!

! Restrict REST API access
ip http access-class 10
access-list 10 permit 192.168.100.0 0.0.0.255
access-list 10 deny any

Community Sentiment: What Everyone’s Complaining About

Reddit discussions about Cisco IOS-XE REST API boil down to three themes:

1. Documentation is the #1 pain point. Almost every thread complains about finding endpoint paths. One user said: “I have been searching for online documentation about Cisco IOS-XE RESTConf Modules but I still cannot find a good reference.”

2. Version compatibility sucks. YANG model structures differ between 16.x and 17.x. The same configuration needs different JSON structures on different versions. Cross-version automation scripts are a nightmare.

3. Cisco’s REST API is half-baked. Many features are only accessible via CLI. Advanced BGP features, QoS policies—REST API doesn’t support them.

Honestly? I agree with all of it. Our team’s final decision: REST API for read-only monitoring and simple configs. NETCONF or Ansible for complex changes.

FAQ

Q1: What’s the difference between Cisco IOS-XE REST API and RESTCONF?

A: Cisco REST API is a proprietary HTTP API with limited YANG model support and poor documentation. RESTCONF is the IETF standard (RFC 8040) with full YANG model support and cross-vendor compatibility. Always prefer RESTCONF.

Q2: How do I find the REST API path for a specific configuration?

A: Use GET /restconf/data to discover all available YANG modules and paths. Alternatively, explore using Postman with Cisco’s YANG model browser at yangcatalog.org.

Q3: Do I need to save configuration after using the REST API?

A: Yes. Changes only go to running-config, not startup-config. You need to execute copy running-config startup-config, which can be done via REST API using the Cisco-IOS-XE-rpc:copy-config operation.

Q4: Is the REST API safe for production use?

A: It depends on your security configuration. You must enable HTTPS, configure ACLs to restrict access, and create dedicated API accounts with limited privileges. Never expose the REST API directly to the internet.

Q5: Which IOS-XE versions support the REST API?

A: CSR1000v supports REST API from IOS-XE 16.6, and RESTCONF from 16.12+. For physical devices (ISR4000, ASR1000), check Cisco’s official documentation for your specific hardware and IOS-XE version.

Final Thoughts

Cisco IOS-XE REST API is a decent idea buried under terrible documentation and half-baked implementation. If you’re doing network automation:

1. Use RESTCONF, not Cisco’s proprietary REST API
2. Budget time for documentation spelunking
3. Always have a rollback plan in production
4. Use NETCONF or Ansible for complex configurations

The sad reality: in 2026, Cisco’s documentation is still this bad. Traditional networking vendors’ software engineering capabilities are years behind what we expect from modern infrastructure tooling.