RESTCONF
RESTCONF is a relatively new extension to NETCONF, with RFC8040 published in 2017. RESTCONF uses the same YANG models as NETCONF but with an HTTP-based interface instead of SSH-based.
RESTCONF allows for data to be encoded in JSON or XML. However, instead of application-type/json you use application/yang-data+json or application/yang-data+xml for Content-Type and Accept headers.
RESTCONF uses common REST verbs such as GET, POST, PUT, DELETE instead of NETCONF RPC actions.
Because RESTCONF is essentially a sub-set of NETCONF, not all NETCONF features are supported with RESTCONF. RESTCONF is stateless and lacks the ability to configure multiple datastores and preform datastore locking. There is no candidate config or commit operation. Because of this there is also no ability to preform network-wide transactions, in which a single change that fails on one device rolls back the change on all devices. However, the tradeoff for losing these stateful features is a RESTful API that uses familiar HTTP operations and JSON data encoding. Put simply, RESTCONF is not a replacement for NETCONF.
Enabling RESTCONF in IOS-XE
To enable RESTCONF we simply need to turn on the feature and enable HTTPS server:
To verify that RESTCONF is running we can use the following show command:
confd I believe is the same ConfD YANG agent that was developed by Tail-F. This is a web server that processes RESTCONF requests. nginx is essentially a proxy server that proxies HTTPS and transfers traffic to confd on the “backend.” ncsshd is the only process which isn’t running, which is the netconfd SSH daemon. Interestingly, nginx will be running whether or not RESTCONF is enabled.
RESTCONF on IOS-XR
RESTCONF is not supported on IOS-XR. YANG can only use NETCONF or gRPC on IOS-XR.
Using RESTCONF with CSR1000v
In this short lab we will use Postman to examine how RESTCONF works on a CSR1000v. Every HTTP request must have basic authorization which won’t be included in the screenshots.
RESTCONF URIs follow this format:
To look at the ietf-interfaces:interfaces model we use the following URI:
Let’s filter this output to only Gi3 by appending /interface=GigabitEthernet3
Now let’s configure an IP address by using Gi1 as a model from the previous output, pasting it to our body and editing it. We will need to set a header for Content-Type:application/yang-data+json and change the HTTP method to PUT. This is because the interface already exists on the router and we are editing it, not creating it. If we created a new interface like Loopback99 then we would POST.
A 204 No Content means the change was accepted.
If we do a GET on the interface again, we can see our change was applied:
To preform a wr mem we can POST to https://{{csr1000v_ipaddress}}/restconf/operations/cisco-ia:save-config/ with an empty body.
RESTCONF HTTP Operations
| Operation | NETCONF RPC Operation | Use |
|---|---|---|
GET | <get> and <get-config> | Get data from a resource |
POST | <edit-config> | Create a resource |
PUT | <edit-config> | Create or replace a resource |
PATCH | <edit-config> | Merge configuration with target resource |
DELETE | <edit-config> | Delete a resource |
The difference between POST, PUT, and PATCH can be a little confusing. In general, POST is only used to create a new resource. But what about PUT vs. PATCH? PUT is used to completely replace a configuration, and PATCH is used to add configuration alongside existing configuration. An example will help.
Let’s say we have the following configuration on Lo99:
We can also see this from Postman:
If we use a PATCH, we will add another IPv6 address alongside the existing IPv6 address:
The only IPv6 address listed here is 2001:db8:2::99
If we do another GET we now see two IPv6 addresses:
If we do the same thing again, but using PUT, we will only see a single IPv6 address. PUT replaces the entire object, while PATCH adds configuration alongside what is already existing.
Further Reading
Last updated
