Cisco NETCONF and REST Device Management API Documentation
This document provides all the information you need to integrate and build NETCONF and REST Device Management applications.
The NETCONF and RESTCONF interfaces are defined by YANG models. You can browse the YANG models and identify leafs to create NETCONF or RESTCONF messages used to configure devices or read operational data.
You can send edit-config or get requests to verify NETCONF round trip configuration and send REST requests to devices. You can also submit delete requests.
You can also specify the expected device "show running" configuration to retrieve the device configuration. This enables you to validate the operation of the NETCONF or REST configuration interface.
You can also submit a NETCONF Capabilities message to the device, which will return a list of all capabilities and models implemented on the device.
The following protocols are supported:
- NETCONF: XML
- RESTCONF: XML/JSON
The following sections provide examples of how to use the supported NETCONF and RESTCONF protocols with the available YANG models.
Get a Device Interface Configuration
Get a Device Interface Configuration using NETCONF
NETCONF Request:
<get>
<filter type="subtree">
<if:interfaces xmlns:l2vpn-pw="urn:cisco:params:xml:ns:yang:pw"
xmlns:ospf="urn:ietf:params:xml:ns:yang:ietf-ospf"
xmlns:ip="urn:ietf:params:xml:ns:yang:ietf-ip"
xmlns:v6ur="urn:ietf:params:xml:ns:yang:ietf-ipv6-unicast-routing"
xmlns:eth="urn:cisco:params:xml:ns:yang:cisco-ethernet"
xmlns:if-ext="urn:ietf:params:xml:ns:yang:ietf-interfaces-ext"
xmlns:cisco-ospf="urn:ietf:params:xml:ns:yang:cisco-ospf"
xmlns:cisco-acl="urn:ietf:params:xml:ns:yang:cisco-acl"
xmlns:rt="urn:ietf:params:xml:ns:yang:ietf-routing"
xmlns:cisco-policy-target="urn:ietf:params:xml:ns:yang:cisco-policy-target"
xmlns:target="urn:ietf:params:xml:ns:yang:ietf-diffserv-target"
xmlns:if="urn:ietf:params:xml:ns:yang:ietf-interfaces"
xmlns:v4ur="urn:ietf:params:xml:ns:yang:ietf-ipv4-unicast-routing"/>
</filter>
</get>
NETCONF Response:
<data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
<interface>
<name>FastEthernet0/0/0</name>
<description>FE000</description>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<enabled>false</enabled>
<link-up-down-trap-enable>enabled</link-up-down-trap-enable>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
<ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
</interface>
<interface>
<name>FastEthernet0/0/1</name>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<enabled>true</enabled>
<link-up-down-trap-enable>enabled</link-up-down-trap-enable>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
<ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip">
<address>
<ip>2000:500:5::1</ip>
<prefix-length>48</prefix-length>
</address>
</ipv6>
</interface>
<interface>
<name>FastEthernet0/0/2</name>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<enabled>false</enabled>
<link-up-down-trap-enable>enabled</link-up-down-trap-enable>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
<ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
</interface>
<interface>
<name>FastEthernet0/0/3</name>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<enabled>false</enabled>
<link-up-down-trap-enable>enabled</link-up-down-trap-enable>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip">
<address>
<ip>3.4.5.6</ip>
<netmask>255.255.255.0</netmask>
</address>
</ipv4>
<ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip">
<address>
<ip>2003:500:5::1</ip>
<prefix-length>48</prefix-length>
</address>
</ipv6>
</interface>
<interface>
<name>FastEthernet0/0/3.9</name>
<description>FEther3.9b</description>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<enabled>true</enabled>
<link-up-down-trap-enable>enabled</link-up-down-trap-enable>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
<ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
</interface>
<interface>
<name>FastEthernet0/0/4</name>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<enabled>false</enabled>
<link-up-down-trap-enable>enabled</link-up-down-trap-enable>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
<ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
</interface>
<interface>
<name>FastEthernet0/0/5</name>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<enabled>false</enabled>
<link-up-down-trap-enable>enabled</link-up-down-trap-enable>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
<ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
</interface>
<interface>
<name>FastEthernet0/0/6</name>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<enabled>false</enabled>
<link-up-down-trap-enable>enabled</link-up-down-trap-enable>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
<ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
</interface>
<interface>
<name>FastEthernet0/0/7</name>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<enabled>false</enabled>
<link-up-down-trap-enable>enabled</link-up-down-trap-enable>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
<ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
</interface>
<interface>
<name>GigabitEthernet0</name>
<description>GE0</description>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<enabled>true</enabled>
<link-up-down-trap-enable>disabled</link-up-down-trap-enable>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip">
<address>
<ip>10.22.52.245</ip>
<netmask>255.255.255.192</netmask>
</address>
</ipv4>
<ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip">
<address>
<ip>2000:500:5::2</ip>
<prefix-length>48</prefix-length>
</address>
</ipv6>
</interface>
<interface>
<name>GigabitEthernet0.3</name>
<description>Gig0.3</description>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<enabled>true</enabled>
<link-up-down-trap-enable>enabled</link-up-down-trap-enable>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
<ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
</interface>
<interface>
<name>GigabitEthernet0.4</name>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<enabled>true</enabled>
<link-up-down-trap-enable>enabled</link-up-down-trap-enable>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
<ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
</interface>
<interface>
<name>Loopback0</name>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:softwareLoopback</type>
<enabled>true</enabled>
<link-up-down-trap-enable>enabled</link-up-down-trap-enable>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip">
<address>
<ip>2.2.2.2</ip>
<netmask>255.255.255.255</netmask>
</address>
</ipv4>
<ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
</interface>
</interfaces>
</data>
Use the NETCONF protocol to retrieve the device interface configuration using a get request.
Get a Device Interface Configuration using RESTCONF
REST GET Request to Get a Device Interface Configuration:
GET /api/running/interfaces?deep HTTP/1.1
Host: 10.22.52.246:8008
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/vnd.yang.data+json
Accept: application/vnd.yang.data+json
Cache-Control: no-cache
Postman-Token: 93bfbd7d-c25b-993b-2ed2-b464e7d926de
RESTCONF Response:
{
"ietf-interfaces:interfaces": {
"interface": [
{
"name": "FastEthernet0/0/0",
"description": "FE000",
"type": "ianaift:ethernetCsmacd",
"enabled": false,
"link-up-down-trap-enable": "enabled",
"cisco-ethernet:ethernet": {},
"cisco-pw:pw-neighbor": {
"load-balance": {}
},
"ietf-ip:ipv4": {},
"ietf-ip:ipv6": {
"ietf-ipv6-unicast-routing:ipv6-router-advertisements": {}
}
},
{
"name": "FastEthernet0/0/1",
"type": "ianaift:ethernetCsmacd",
"enabled": true,
"link-up-down-trap-enable": "enabled",
"cisco-ethernet:ethernet": {},
"cisco-pw:pw-neighbor": {
"load-balance": {}
},
"ietf-ip:ipv4": {},
"ietf-ip:ipv6": {
"address": [
{
"ip": "2000:500:5::1",
"prefix-length": 48
}
],
"ietf-ipv6-unicast-routing:ipv6-router-advertisements": {}
}
},
{
"name": "FastEthernet0/0/2",
"type": "ianaift:ethernetCsmacd",
"enabled": false,
"link-up-down-trap-enable": "enabled",
"cisco-ethernet:ethernet": {},
"cisco-pw:pw-neighbor": {
"load-balance": {}
},
"ietf-ip:ipv4": {},
"ietf-ip:ipv6": {
"ietf-ipv6-unicast-routing:ipv6-router-advertisements": {}
}
},
{
"name": "FastEthernet0/0/3",
"type": "ianaift:ethernetCsmacd",
"enabled": false,
"link-up-down-trap-enable": "enabled",
"cisco-ethernet:ethernet": {},
"cisco-pw:pw-neighbor": {
"load-balance": {}
},
"ietf-ip:ipv4": {
"address": [
{
"ip": "3.4.5.6",
"netmask": "255.255.255.0"
}
]
},
"ietf-ip:ipv6": {
"address": [
{
"ip": "2003:500:5::1",
"prefix-length": 48
}
],
"ietf-ipv6-unicast-routing:ipv6-router-advertisements": {}
}
},
{
"name": "FastEthernet0/0/3.9",
"description": "FEther3.9b",
"type": "ianaift:ethernetCsmacd",
"enabled": true,
"link-up-down-trap-enable": "enabled",
"cisco-ethernet:ethernet": {},
"cisco-pw:pw-neighbor": {
"load-balance": {}
},
"ietf-ip:ipv4": {},
"ietf-ip:ipv6": {
"ietf-ipv6-unicast-routing:ipv6-router-advertisements": {}
}
},
{
"name": "FastEthernet0/0/4",
"type": "ianaift:ethernetCsmacd",
"enabled": false,
"link-up-down-trap-enable": "enabled",
"cisco-ethernet:ethernet": {},
"cisco-pw:pw-neighbor": {
"load-balance": {}
},
"ietf-ip:ipv4": {},
"ietf-ip:ipv6": {
"ietf-ipv6-unicast-routing:ipv6-router-advertisements": {}
}
},
{
"name": "FastEthernet0/0/5",
"type": "ianaift:ethernetCsmacd",
"enabled": false,
"link-up-down-trap-enable": "enabled",
"cisco-ethernet:ethernet": {},
"cisco-pw:pw-neighbor": {
"load-balance": {}
},
"ietf-ip:ipv4": {},
"ietf-ip:ipv6": {
"ietf-ipv6-unicast-routing:ipv6-router-advertisements": {}
}
},
{
"name": "FastEthernet0/0/6",
"type": "ianaift:ethernetCsmacd",
"enabled": false,
"link-up-down-trap-enable": "enabled",
"cisco-ethernet:ethernet": {},
"cisco-pw:pw-neighbor": {
"load-balance": {}
},
"ietf-ip:ipv4": {},
"ietf-ip:ipv6": {
"ietf-ipv6-unicast-routing:ipv6-router-advertisements": {}
}
},
{
"name": "FastEthernet0/0/7",
"type": "ianaift:ethernetCsmacd",
"enabled": false,
"link-up-down-trap-enable": "enabled",
"cisco-ethernet:ethernet": {},
"cisco-pw:pw-neighbor": {
"load-balance": {}
},
"ietf-ip:ipv4": {},
"ietf-ip:ipv6": {
"ietf-ipv6-unicast-routing:ipv6-router-advertisements": {}
}
},
{
"name": "GigabitEthernet0",
"description": "GE0",
"type": "ianaift:ethernetCsmacd",
"enabled": true,
"link-up-down-trap-enable": "disabled",
"cisco-ethernet:ethernet": {},
"cisco-pw:pw-neighbor": {
"load-balance": {}
},
"ietf-ip:ipv4": {
"address": [
{
"ip": "10.22.52.245",
"netmask": "255.255.255.192"
}
]
},
"ietf-ip:ipv6": {
"address": [
{
"ip": "2000:500:5::2",
"prefix-length": 48
}
],
"ietf-ipv6-unicast-routing:ipv6-router-advertisements": {}
}
},
{
"name": "GigabitEthernet0.3",
"description": "Gig0.3",
"type": "ianaift:ethernetCsmacd",
"enabled": true,
"link-up-down-trap-enable": "enabled",
"cisco-ethernet:ethernet": {},
"cisco-pw:pw-neighbor": {
"load-balance": {}
},
"ietf-ip:ipv4": {},
"ietf-ip:ipv6": {
"ietf-ipv6-unicast-routing:ipv6-router-advertisements": {}
}
},
{
"name": "GigabitEthernet0.4",
"type": "ianaift:ethernetCsmacd",
"enabled": true,
"link-up-down-trap-enable": "enabled",
"cisco-ethernet:ethernet": {},
"cisco-pw:pw-neighbor": {
"load-balance": {}
},
"ietf-ip:ipv4": {},
"ietf-ip:ipv6": {
"ietf-ipv6-unicast-routing:ipv6-router-advertisements": {}
}
},
{
"name": "Loopback0",
"type": "ianaift:softwareLoopback",
"enabled": true,
"link-up-down-trap-enable": "enabled",
"cisco-ethernet:ethernet": {},
"cisco-pw:pw-neighbor": {
"load-balance": {}
},
"ietf-ip:ipv4": {
"address": [
{
"ip": "2.2.2.2",
"netmask": "255.255.255.255"
}
]
},
"ietf-ip:ipv6": {
"ietf-ipv6-unicast-routing:ipv6-router-advertisements": {}
}
}
]
}
}
Use the RESTCONF protocol to retrieve the device interface configuration using a get request.
Edit a Device Configuration
Change the Device Hostname using NETCONF
NETCONF Request:
NETCONF edit-config to change device hostname
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="">
<edit-config>
<target>
<running/>
</target>
<config>
<native xmlns="urn:ios">
<hostname>CSR1K-REST1</hostname>
</native>
</config>
</edit-config>
</rpc>
NETCONF Response:
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="4">
<ok/>
</rpc-reply>
The following NETCONF request can be used to edit the device configuration. In this example the request changes the device hostname:
Delete Part of a Device Configuration using NETCONF
NETCONF Request:
NETCONF edit-config to delete part of a device configurat6ion
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="">
<edit-config>
<target>
<running/>
</target>
<config>
<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
<interface nc:operation="delete" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<name>FastEthernet0/0/3.9</name>
<description>FEther3.9b</description>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<enabled>true</enabled>
<link-up-down-trap-enable>enabled</link-up-down-trap-enable>
<ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
<ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
</interface>
</interfaces>
</config>
</edit-config>
</rpc>
NETCONF Response:
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="6">
<ok/>
</rpc-reply>
The following NETCONF request can also be used to delete part of the device configuration:
Edit a Device Configuration using RESTCONF
REST PUT Request to Change the Device Hostname:
PUT /api/running/native/hostname HTTP/1.1
Host: 10.22.52.246:8008
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/vnd.yang.data+json
Accept: application/vnd.yang.data+json
Cache-Control: no-cache
Postman-Token: cdd08f47-3321-2599-0bcf-b74a010ba727
{
"hostname": "CSR1K-REST1"
}
RESTCONF Response:
204 No Content
The following RESTCONF request can be used to edit the device configuration. In this example the request changes the device hostname:
Add an Entry to a List using RESTCONF
REST PATCH Request to Add an Entry to a List:
PATCH /api/running/interfaces HTTP/1.1
Host: 10.22.52.246:8008
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/vnd.yang.data+json
Accept: application/vnd.yang.data+json
Cache-Control: no-cache
Postman-Token: 7c0cafc6-cd34-94b3-0f5e-774d5550a932
{
"ietf-interfaces:interfaces": {
"interface": [
{
"name": "FastEthernet0/0/3.1",
"description": "FEther3.1",
"type": "ianaift:ethernetCsmacd"
}
]
}
}
Delete a Device Configuration
REST DELETE Request to Delete a Device Configuration:
DELETE /api/running/interfaces/interface/GigabitEthernet2.1 HTTP/1.1
Host: 10.22.52.246:8008
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/vnd.yang.data+json
Accept: application/vnd.yang.data+json
Cache-Control: no-cache
Postman-Token: f5ba747e-c5be-0bb0-5c07-783957cf7605
RESTCONF Response:
"204 No Content" if the config existed and is now removed
"404 Not Found" if the config did not already exist
The following RESTCONF request can be used to delete the device configuration: