Network automation has become essential for modern infrastructure management, and RESTCONF provides a standardized, programmable interface for configuring and managing network devices. In this guide, I’ll walk you through practical examples of using RESTCONF with Cisco IOS-XE devices.
What is RESTCONF?
RESTCONF is a protocol defined in RFC 8040 that provides a RESTful API for accessing data defined in YANG models. It combines the simplicity of REST APIs with the power of YANG data modeling, making network automation more accessible to developers and network engineers alike.
The RESTCONF URL Structure
Understanding the URL structure is crucial for working with RESTCONF:
https://10.3.19.107/restconf/data/native/interface
Breaking this down:
- 10.3.19.107 - The device IP address
- restconf/data - The base path for all RESTCONF operations
- native/interface - The YANG path to the specific resource
HTTP Methods: The Language of RESTCONF
RESTCONF leverages standard HTTP methods, each serving a specific purpose:
- GET - Read configuration and operational data
- POST - Create new resources
- PUT - Replace existing configuration completely
- PATCH - Update/merge configuration with existing data
- DELETE - Remove configuration
Working with VLANs
Let’s start with a fundamental networking task: VLAN management.
Creating a Single VLAN
To create a VLAN with a custom name:
POST https://10.3.19.107/restconf/data/native/vlan
{
"Cisco-IOS-XE-vlan:vlan-list": {
"id": 10,
"name": "Printer"
}
}
Creating Multiple VLANs
Efficiency matters. Here’s how to create multiple VLANs in one API call:
POST https://10.3.19.107/restconf/data/native/vlan
{
"Cisco-IOS-XE-vlan:vlan-list": [
{
"id": 20,
"name": "Camera"
},
{
"id": 30,
"name": "Guest"
}
]
}
Updating VLANs with PATCH
When you need to update VLAN names without touching other configuration, use PATCH:
PATCH https://10.3.19.107/restconf/data/native/vlan/vlan-list
{
"Cisco-IOS-XE-vlan:vlan-list": [
{
"id": 10,
"name": "Printer"
},
{
"id": 20,
"name": "Camera"
},
{
"id": 30,
"name": "Guest"
}
]
}
The Difference: PUT vs PATCH
Here’s an important distinction:
PUT replaces the entire configuration:
PUT https://10.3.19.107/restconf/data/native/vlan/vlan-list=30
{
"Cisco-IOS-XE-vlan:vlan-list": {
"id": 30,
"name": "External",
"shutdown": [null]
}
}
This completely replaces VLAN 30’s configuration, including adding a shutdown state.
Targeted Deletions
Need to remove just the shutdown state? Use DELETE on the specific attribute:
DELETE https://10.3.19.107/restconf/data/native/vlan/vlan-list=30/shutdown
Access Control Lists: Standard ACLs
Access control lists are fundamental to network security. Here’s how to automate them.
Creating a Standard ACL
POST https://10.3.19.107/restconf/data/native/ip/access-list
{
"Cisco-IOS-XE-acl:standard": {
"name": "CatalystCenter",
"access-list-seq-rule": [
{
"sequence": 5,
"permit": {
"std-ace": {
"host-address": "10.3.19.200"
}
}
}
]
}
}
This creates a standard ACL equivalent to:
ip access-list standard CatalystCenter
5 permit host 10.3.19.200
Extended ACLs: More Granular Control
Extended ACLs provide protocol and port-level filtering. Here’s a practical example for guest network access:
POST https://10.3.19.107/restconf/data/native/ip/access-list
{
"Cisco-IOS-XE-acl:extended": {
"name": "GUEST_IN",
"access-list-seq-rule": [
{
"sequence": 5,
"ace-rule": {
"action": "permit",
"protocol": "udp",
"ipv4-address": "172.16.30.0",
"mask": "0.0.0.255",
"dst-any": [null],
"dst-eq": 53
}
},
{
"sequence": 10,
"ace-rule": {
"action": "permit",
"protocol": "tcp",
"ipv4-address": "172.16.30.0",
"mask": "0.0.0.255",
"dst-any": [null],
"dst-eq": 80
}
},
{
"sequence": 15,
"ace-rule": {
"action": "permit",
"protocol": "tcp",
"ipv4-address": "172.16.30.0",
"mask": "0.0.0.255",
"dst-any": [null],
"dst-eq": 443
}
}
]
}
}
This configuration:
- Permits DNS queries (UDP port 53)
- Allows HTTP traffic (TCP port 80)
- Allows HTTPS traffic (TCP port 443)
- Restricts source to the 172.16.30.0/24 network
Interface Configuration
Interface management is where RESTCONF really shines.
Reading Interface Configuration
Get all interfaces:
GET https://10.3.19.107/restconf/data/native/interface/GigabitEthernet
Get a specific interface (note the URL encoding of / as %2F):
GET https://10.3.19.107/restconf/data/native/interface/GigabitEthernet=1%2F0%2F3
Converting Switchport to Routed Mode
PATCH https://10.3.19.107/restconf/data/native/interface/GigabitEthernet=1%2F0%2F3
{
"Cisco-IOS-XE-native:GigabitEthernet": [
{
"name": "1/0/3",
"switchport-conf": {
"switchport": false
}
}
]
}
Configuring an IP Address
Once in routed mode, assign an IP address:
PUT https://10.3.19.107/restconf/data/native/interface/GigabitEthernet=1%2F0%2F3/ip/address
{
"Cisco-IOS-XE-native:address": {
"primary": {
"address": "192.0.2.3",
"mask": "255.255.255.0"
}
}
}
Removing IP Configuration
Clean up is simple:
DELETE https://10.3.19.107/restconf/data/native/interface/GigabitEthernet=1%2F0%2F3/ip/address
Converting Back to Switchport
PATCH https://10.3.19.107/restconf/data/native/interface/GigabitEthernet=1%2F0%2F3
{
"Cisco-IOS-XE-native:GigabitEthernet": [
{
"name": "1/0/3",
"switchport-conf": {
"switchport": true
}
}
]
}
Understanding YANG Models
YANG models define the structure of configuration data. The examples above use YANG paths like:
/native/vlan/vlan-list/native/ip/access-list/standard/native/interface/GigabitEthernet
You can explore YANG models using pyang:
pyang Cisco-IOS-XE-native.yang Cisco-IOS-XE-vlan.yang -f tree \
--tree-path=/native/vlan/vlan-list --max-status=current
Key Concepts to Remember
- POST for Creation - When adding items to YANG lists, always POST to the container level
- List Keys in URLs - Include keys using the format
/list-name=key-value - URL Encoding - Remember to encode special characters (e.g.,
/becomes%2F) - PUT vs PATCH - PUT replaces entirely, PATCH merges with existing configuration
- Targeted Operations - You can operate on specific attributes for surgical precision
Lab Environment
The examples in this post use a Cisco Site B topology with:
- 2x Catalyst 8000v IOS-XE routers (10.3.19.105-106)
- 2x Catalyst 9000v IOS-XE switches (10.3.19.107-108)
Conclusion
RESTCONF provides a powerful, standardized way to automate network configuration. By understanding the HTTP method semantics and YANG data models, you can build robust automation workflows that are both readable and maintainable.
The examples shown here are building blocks for more complex automation scenarios. Whether you’re managing VLANs across hundreds of switches, deploying consistent ACL policies, or orchestrating complex interface configurations, RESTCONF gives you the tools to do it programmatically.
Start small, experiment with GET operations to understand the data structures, and gradually build up to more complex workflows. The future of networking is programmable, and RESTCONF is your gateway to that future.