Navigating RESTCONF for Cisco Network Engineers

Navigating RESTCONF for Cisco Network Engineers

In both my personal education and in work projects, there’s been a slow but steady move into network automation. This document is written from the angle of a network engineer, and as such, the document approaches the topic from the angle of moving from the CLI to a true programmatic interface in an efficient manner.

What you can expect to gain from reading:

• The ‘cliff notes’ version of RESTCONF
• The ‘cliff notes’ version of YANG
• The ‘cliff notes’ version of the pyang tool
• Basic use of Postman
• A quick & dirty way to implement working
  RESTCONF on a Cisco device
• An elegant way to implement RESTCONF on a Cisco
  device

What you should not expect:

• Any Python (or any other programming language)
  education. There are countless trainings for Python elsewhere on the web.
• A deep dive of REST. This article assumes the
  reader has familiarity already.
• Much detail on NETCONF. While a lot of the
  information with RESTCONF overlaps with NETCONF (as RESTCONF’s origin
  technology), I chose to focus on RESTCONF due to almost all APIs being
  REST-based now.
• A thorough explanation of YANG. While
  researching this article, I read some unbelievably good deep-dives of YANG, but
  this article is about shifting from CLI to RESTCONF, and only a mid-level
  understanding of YANG is needed.

Some things you’ll need

• Postman
• A Linux machine or VM

With that said, what’s NETCONF?

Although just recently gaining traction, NETCONF has actually been around quite a long time – the RFC was published in 2006. NETCONF is an XML-based interface to configure and monitor network devices. One of the primary drivers for NETCONF is to augment SNMP. SNMP’s original use case was meant to be both read and write, but the “write” element never gained wide adoption – primarily because of the difficulty in navigating MIBs to figure out how to trigger the appropriate outcome. NETCONF typically works over an SSH session to TCP port 830. NETCONF can be informally thought of as SNMPv4.

What is YANG?

Building off the idea of SNMP, if MIBs are the index for SNMP, then YANG is the index for NETCONF. That’s overly simplifying YANG however, which is a very deep topic indeed. YANG is a hierarchical language, built in a tree-format, that defines in a readable format the generalized models required to configure a network. Understanding YANG at a high-level is necessary to use NETCONF.

Interesting note: YANG stands for “Yet Another Next Generation”. Strange name if you don’t know the origin. The competing technology was SNMP-based. SNMP uses SMI as its back-end data structure, and before YANG was created, SMI Next Generation (SMIng) was being created. Reference RFC 3780: https://tools.ietf.org/html/rfc3780. When Yet Another format was created, it was called YANG.

So, what’s RESTCONF?

RESTCONF swaps the SSH session that NETCONF uses and instead uses a REST-based API. The YANG models used are identical between NETCONF and RESTCONF. An easy way to think of RESTCONF is just putting a web API on top of the long-standing NETCONF framework. Additionally, RESTCONF expands on NETCONF’s XML interface by optionally offering JSON as a data format (XML can still be used as well). I personally enjoy using RESTCONF because I’m already familiar with REST APIs and therefore the interface is very familiar.

What else is different between NETCONF and RESTCONF?

NETCONF technically has a few more functional benefits than RESTCONF. The most obvious is that streaming telemetry (example: polling the CPU utilization every X seconds) requires a session to stay open. That’s possible with an SSH session, but with REST, every command is transactional and there is no session to keep that kind of data flowing. There are a few other benefits which are beyond the scope of this document.

So why would I want to use either of these?

The main use case is fairly obvious. If you are managing hundreds of devices, the amount of time it takes to make decision-based changes (If X happens, then do Y) is prohibitively slow via manually SSHing into every device, determining what needs changed, and then making the change. A well-written script and an API can do in minutes what a human would take hours to perform, and at the cost of zero man-hours.

Another more advanced use case is infrastructure-as-code.This is the idea that intent should define the network configuration, which is then deployed via software. This is beyond the scope of this document.

But… I’m already doing automation with expect scripts (or similar) CLI-based automation…

That certainly can be done, but think of using NETCONF/RESTCONF as the “next level”. The CLI was written for humans to interpret. Imagine the output from “show ip bgp neighbor” – easy for you to read as a human, but try to parse that with automation. It can be done, but it’s very clunky. Or, imagine trying to dynamically configure an extended access-list with CLI commands, with a computer making the decisions. It works, but it’s clunky. The ideas behind NETCONF/RESTCONF + YANG are to take those same tasks and make them more computer readable/writable, instead of human readable/writable.

YANG in just a little more detail

We’re going to come at these topics in little bits, and the next step requires understanding YANG just a little bit, so that we can give some simple RESTCONF examples.

Some quick intro knowledge is that there are several different creators of YANG models. The first, and from my understanding, the original, is the IETF. IETF’s goals are idealistic – create a series of models that work with all manufacturers of network equipment. You could re-use the same code against Cisco, Juniper, Arista, etc, and end up with the same outcome on all of them. Sounds great, right? The problem becomes apparent the more you work with programmatic models, vendors just “do things differently”, and even though all networking is generally standard, the way things are handled inside a router are completely different.  An obvious example is you’ll never see an EIGRP or PFR IETF YANG model.

CALLOUT: Another vendor-neutral model is from Openconfig. It has similar goals to the IETF models but is backed by a group of manufacturers instead of the IETF:
https://www.openconfig.net/projects/models/

Next are the native models. As illustrated above, no matter how good an industry standard model is, it’s not going to cover anything vendor-specific (and many things that aren’t vendor-specific). I’ve not looked at any other vendor besides Cisco, but the Cisco native models are very extensive, complex, and can basically perform any router task you’d like. Side note – it’s my understanding that the vendor-neutral models are translated into the Cisco native models before processing, but I have no specific way of showing this.

Let’s get some basic samples going

I’ve never cared for reading learning material that doesn’t let you get your hands dirty until all the “learning” is done. So, before I go on any longer, let’s get this thing rolling.

You’re going to need a sample IOS-XE device. I strongly recommend a CSR1K, as it exhibits some different behavior than physical routers. I’m using v17.2.1, for reference. I’ll explain more on that different behavior later in the article.

You’re also going to need Postman: https://www.postman.com/

Why Postman? While it does far more than I’m going to write about here, it takes the “code writing” complexity out of testing an API. Writing code (presumably Python) adds a layer of complexity in dealing with data formats and logic. As mentioned at the beginning of the article, this isn’t about teaching how to program, it’s about teaching practical RESTCONF. Postman allows you to interact with a REST API without writing any code.

Assuming you have those things running, let’s make RESTCONF do something.

Prepping your router is very straightforward.

First, since we’ll be using TLS, you need an encryption key:  
csr1k#crypto key generate rsa

Then you’ll need to enable the secure HTTP server and setup local authentication:
csr1k#conf t

Enter configuration commands, one per line. End with CNTL/Z.

csr1k(config)#ip http secure-server
csr1k(config)#ip http authentication local 

After that enable RESTCONF:

csr1k(config)#restconf

You’ll also need a local user that’s privilege 15:
csr1k(config)#username cisco priv 15 secret cisco123

Now, let’s load up Postman and see if we can’t get restconf to do something.

After you’ve downloaded and signed into Postman, you should get a page that looks something like mine

The next page will look like this. Be sure to select the GET field as you see below.

Next, click on Authorization, change the type to “Basic Auth”, and put the username and password you created into the Username and Password blank.

Press the Send button in the upper-right

If you configured the router correctly, the response field should look like this:

NOTE: Nothing too useful here other than it tells us that RESTCONF is working. Note the output is in XML. If you prefer to get it back in JSON, make the changes in the following steps.

Click on the Headers tab:

Once here, uncheck the default “Accept” header:

Create a new Accept header at the bottom specifying application/yang-data+json:

Press “Send” again, and the output should now return in JSON:

I’ll proceed with using JSON from here on out of personal preference.

Expanding upon the idea

Now that we’ve confirmed that RESTCONF is running on the router and shown how to change to JSON output, let’s do a few more simple interactions to show what we’re trying to accomplish here.

I want to specifically call out that my next examples are on a CSR1K. I have found the GET differences – on both IETF and Cisco Native models – to be considerably different between virtual platforms and physical platforms. So, if you want to replicate my results be sure you’re on the CSR1K. Again, I’m using v17.2.1. I’ll show more on this later.

First, perform a GET on: https://10.200.200.100/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1

Since I’ve preconfigured my GigabitEthernet1 we get back some configuration details:

Let’s break down what we asked for in the GET: https://10.200.200.100/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1

• 10.200.200.100 = The hostname
• /restconf/data/ = This path will be specified for RESTCONF config data. (differs for RPCs, more below)
• /ietf-interfaces = We’re using the ietf-interfaces YANG module (more on YANG modules below)
• :interfaces = Specifying the “interfaces” container inside /ietf-interfaces (more on containers below)
• /interface = Specifying the list “interface”
• =GigabitEthernet1 = For the list “interface”, the key is the string “name”, and the name is GigabitEthernet1

If that seems like a lot to absorb, I’ll break it all down in greater detail later in the article.

Thus far we’ve focused on using GET, let’s change the IP address using PUT.

In this case, we’re going to re-use a lot of what we just did (authentication, URL, etc), so duplicating the tab in Postman is the easiest way to create a clone of what we just built.

Right-click on your current tab and press “Duplicate Tab”:

On the new tab, change your GET to a PUT:

As I had mentioned, this isn’t meant to serve as a REST tutorial, but while GET retrieves data, and POST creates new data, PUT is used for modifying existing data.

We’ll also need to go and modify the headers so that we’re sending JSON.

Uncheck the default Content-Type:

At the bottom of headers, as we did above for “Accept”, create a new Content-Type of application/yang-data+json:

To start preparing to send JSON to the CSR, click on “Body” and select “raw”:

Copy the output from your earlier GET of GigabitEthernet1. Building off this example, I’ve grabbed the JSON contents of it and modified one field – the IP address from .102 in the fourth octet to .103. I’ve also enabled the interface. This is what I pasted this into the Body field:

Press Send again, and you should get:

You can check your work by running the GET from your prior tab again, or you can just log in to the router and look:

Let’s also go ahead and create some data. Clearly you can’t create a physical interface, but you can certainly make a logical one. Let’s craft a new Loopback.


Duplicate your tab again. Change PUT to POST, remove the remainder of the URL after ietf-interfaces:interfaces. In the body, change the name to Loopback and a number of your choosing, change type to softwareLoopback, change the IP address to something that doesn’t overlap with other interfaces, and (optionally) change your netmask to a /32.

Press Send.

I think this example speaks for itself outside of why we trimmed the URL. We can’t POST to a list (an interface, in this case) that doesn’t exist yet. I’ll show more examples on this as we proceed.

The last HTTP verb to demonstrate would be DELETE. Let’s wipe out that Loopback we just created. Duplicate your tab again.

Change the POST to DELETE. Add the list back in at the end of our URL: https://your-ip-address/restconf/data/ietf-interfaces:interfaces/interface=Loopback1001

Something to note: The body is irrelevant in this type of request. Since we duplicated the tab, we inherited the body from the POST, and we could leave it there, or you can erase it. It doesn’t matter.

Additionally: The debugs on the router are near useless. When I first started on this topic, I was hoping for a translation of RESTCONF into CLI to show what was actually going on behind the scenes, but no such luck.

Debugs are turned on with: csr1k#debug restconf level debug

The output from creating a Loopback looks like this (I have trimmed it slightly for brevity and privacy):

%DMI-5-AUTH_PASSED: R0/0: dmiauthd: User 'cisco' authenticated successfully from <myIP> and was authorized for rest over http. External groups: PRIV15
%SYS-5-CONFIG_P: Configured programmatically by process iosp_vty_100001_dmi_syncfd_fd_179 from console as NETCONF on vty63
%DMI-5-CONFIG_I: R0/0: dmiauthd: Configured from NETCONF/RESTCONF by cisco, transaction-id 189

So basically, the debug shows that I logged in using an API and made a change… but no real details.

Now you’ve seen the basics on retrieving data, changing data, creating data, and deleting data. This is the easy part. Next, the real challenge begins in trying to figure out how to craft the body without having internet examples.

So – isn’t there some documentation? Well…

Well, there is none.

This hasn’t changed in the last five years. For writing code around RESTCONF, you’re on your own. Instead of documentation, you need to develop strategies to understanding creating the body. There are two strategies that I’ve used, one of which lacks finesse but is very fast, and another which is more likely what the YANG developers intended, but takes some patience and a deeper understanding of YANG.

Let’s start with the fast method.

Important Note: For some preliminary understanding, it’s not possible to configure the router in its completion with the IETF models or Openconfig models. However, the Cisco native models have a representation of all standard configuration. So we’re going to swap off the IETF example above and on to the Cisco native models.

When I first started working with RESTCONF, I found myself looking for the equivalence of snmpwalk for RESTCONF. The question I asked myself is “How do I index this thing?”

My natural tendency was to perform a GET at the highest URL “level”:

That’d be a GET to https://your-ip-address/restconf/data/Cisco-IOS-XE-native:native

Think of this as the RESTCONF version of “show running-config”

“204 No Content” This threw me off for quite a while until, on a lark, I tried it on a CSR1K:

As you can see, it works fine on a CSR, but not on an ISR – I would love an explanation if anyone knows why this is. I couldn’t find any information on it. Note, I did try multiple ISRs.

For brevity, I couldn’t show the entire config here, so I’ve just shown another relevant snippet from below:

As an example, let’s create a banner on the CSR:
csr1k#conf t
Enter configuration commands, one per line.  End with CNTL/Z.
csr1k(config)#banner exec 1 Restconf Banner 1

I deliberately picked ‘banner’ as it’s towards the top of the config, and makes the example easier in screenshots.

Getting the JSON down just takes some practice, but the body looks like this:

{
    "exec": {
        "banner": "1 NEW Restconf Banner 1"
    }
}

And here’s how it’s crafted in Postman:

And the proof can be seen from the CLI or from another GET:
csr1k(config)#do sh run | s banner exec
banner exec ^C NEW Restconf Banner ^C

As I mentioned, this is quick, dirty, and inelegant. Having to build all your config to understand how to address it in the API just isn’t a clean method. The elegant way is to become familiar enough with the YANG files to be able to interpret them as a form of self-documentation.

You Mentioned a More Elegant Method?

In order to go further with this, we need the YANG files. Since we’re also going to be using a tool that only works in Linux, you’ll need yourself a Linux box or VM from here on in.

All the YANG models are available for download via github. One of the cool things about this is that even the vendor native models are also on github, so you get all the relevant YANG files in one shot!

jeff@linuxlab:~$ git clone https://github.com/YangModels/yang.git
Cloning into 'yang'...
remote: Enumerating objects: 252, done.
remote: Counting objects: 100% (252/252), done.
remote: Compressing objects: 100% (200/200), done.
remote: Total 36526 (delta 98), reused 163 (delta 50), pack-reused 36274
Receiving objects: 100% (36526/36526), 76.68 MiB | 4.18 MiB/s, done.
Resolving deltas: 100% (27870/27870), done.
Updating files: 100% (40193/40193), done.

For illustration purposes, I’m going to swap back to the IETF models for now, as they’re not as daunting to read as the Cisco native ones.

jeff@linuxlab:~$ cd yang/vendor/cisco/xe/1721
jeff@linuxlab:~/yang/vendor/cisco/xe/1721$

Of Note: While I’m demoing on XE, there are XR and NX-OS models in the same folder structure

Taking a Referencing our prior example above: https://10.200.200.100/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1

Let’s take a look in ietf-interfaces and try and gain some basic understanding. As a reminder from the top of the blog, I am not intending to teach YANG thoroughly, but to give enough understanding that you could take the information and interface with the RESTCONF efficiently.

Pop open ietf-interfaces.yang in your favorite text editor:
jeff@linuxlab:~/yang/vendor/cisco/xe/1721$ vi ietf-interfaces.yang

ietf-interfaces.yang is one of the smallest “major” YANG files, but it’s still 725 lines long. It is considerably more readable than SNMP MIBs are, but it’s a lot to digest. I struggled finding a way to illustrate this without bloating the blog… and didn’t come up with anything. So seriously, pop these files open and take a look. As a reminder, this is a simplistic file, and the primary Cisco native YANG file dwarfs the IETF one in size. We’ll come back more on the solution to this shortly.

As I mentioned above, the files are laid out in a tree. I’m going to pick out key bits of the file to reference how this works.

Let’s start by trying to figure out the URL we used earlier: https://10.200.200.100/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1

You’ll note the first line in the file defines the module name: module ietf-interfaces {

 Scrolling down a bit, we’ll find the interfaces container:

  container interfaces {
    description
      "Interface configuration parameters.";

Followed immediately by the interface list. Note the key of “name” below:

       list interface {
         key "name";
   	
            leaf name {
               type string;

This gives us all the building blocks of the URL below.

https://10.200.200.100/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1

As mentioned /hostname/restconf/data is in every RESTCONF URL on IOS-XE.

The important bits are after that: ietf-interfaces:interfaces/interface=GigabitEthernet1.

Let’s pause and talk about data types for a moment

These are definitions to be familiar with for the purpose of this article. Note, this is not exhaustive, it’s just the bits needed to get through the common RESTCONF use cases.

Containers: Contains other nodes types, including other containers. This is basically just a logical grouping.
List: Contains a sequence of list entries, which is uniquely identified by leafs. The unique identifier is the Key, defined in the list.
Leaf: Contains a single value (Leaf types are the end of the tree)
Leaf-List: Contains a sequence of leaf nodes

Comparing this back to our earlier example:

I’ll show this in a better visual when we get to demoing pyang. This probably doesn’t seem too complicated just yet, but if you’re looking closely, there were a lot more IETF files.

Here’s a first major point of understanding: The files are not standalone. They work as a group.

Reference back to our first IETF example:

Go back to the text edit of the ietf-interfaces.yang file and search for “ipv4”:

I can assure you we’re viewing the right top-level file in ietf-interfaces.yang, but there’s no mention of IP addressing. This is where YANG gets trickier to decipher.

The YANG model we’re looking for is actually in ietf-ip.yang.

Let’s take a look inside the ietf-ip.yang:

augment "/if:interfaces/if:interface" {
   description
     "Parameters for configuring IP on interfaces.
      If an interface is not capable of running IP, the server
      must not allow the client to configure these parameters.";
   container ipv4 {

So the container for ipv4 is in a separate file from ietf-interfaces, even though it augments it. The potentially confusing matter here is that the augmenting file (ietf-ip.yang) refers back to the augmented file (ietf-interfaces.yang).

Let’s demonstrate

Run this GET in Postman: https://10.200.200.100/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1/ipv4/address

This is the same URL we’ve been using for our example, but with /ipv4/address at the end.

You’ll get this more-specific subset of the body:

With ietf-ip.yang augmenting ietf-interfaces.yang, the URL above breaks down visually as follows:

Getting hard to visualize? Hopefully you’re following along in the actual files. The IETF files are some of the easiest to interpret via plain text, yet it’s easy to demonstrate how complex this can be to read in plain text.

Introducing pyang

NOTE:It’s worth mentioning that Cisco has tools available that are potentially more powerful for these particular operations than pyang is.

These are:
Yang-Explorer: https://github.com/CiscoDevNet/yang-explorer
Yang-Suite: https://github.com/CiscoDevNet/yangsuite

Yang Explorer is end-of-support – it was flash based. I have not tried installing it. Yang Suite is brand new, as in it launched while I was typing this document. I attended the kick-off. It looks rather impressive, and according to the webinar I attended, it apparently sorts out the confusion around augments. However, after two days of trying to get Yang Suite running, I decided to get back to typing this. Inevitably, if you have the time to figure it out, Yang Suite is potentially a better tool for this operation than pyang.

With that covered, back to pyang.

As I mentioned above, pyang only runs in Linux, so back to your Linux box!

Installation varies slightly from Linux distro to distro, but the basics are simple:
jeff@linuxlab:~$ pip install pyang

pyang does more than I’m going to cover here, but what we basically want it for is to summarize YANG files in tree format (as well as help with augments…)

Our initial usage of pyang will be:
pyang -f tree <file1.yang> <file2.yang> … <fileX.yang>

Run this against ietf-interfaces.yang

Now we can easily conceptualize the YANG module in a tree:

That sure simplifies reading a large YANG file, but it doesn’t get us the IP address information that we noted above is missing. This requires a little bit of interpretative work.

I have already pointed it out, but it’s pretty obvious from the file structure that IP address information would be inside ietf-ip.yang. Now we just need to see them both in the same tree. Note I’ve asked pyang to create a tree for both ietf-interfaces.yang and ietf-ip.yang simultaneously.

One benefit is pyang is smart enough to process the augment in ietf-ip and insert it into the correct spot in the ietf-interfaces tree. Compare to the prior screenshot of pyang that didn’t have the ipv4 tree information in it.

Now it’s much easier to figure out the needed URL: https://10.200.200.100/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1/ipv4/address

That’s an easy way to show some simple usage. Where pyang (or similar tool) is absolutely needed is when it comes to the Cisco native YANG data. For reference, all the Cisco-supported IETF YANG files combined are less than 14,000 lines combined. However, on 17.2.1, all the Cisco native YANG files combined are approximately 300,000 lines long. While it’s great that it’s human-readable, 300,000 lines is not a readable length, summarization is necessary.

Let’s take a quick look at the Cisco-IOS-XE-native.yang file with pyang: jeff@linuxlab:~/yang/vendor/cisco/xe/1721$ pyang -f tree Cisco-IOS-XE-native.yang

This looks great at first glance, but if you run the same command in your lab, you’ll find that the tree index alone for just Cisco-IOS-XE-native.yang is 34,709 ***lines long (just shy of three times the size of all the plaintext data from the IETF files combined!). Referencing above, this doesn’t include any of the other augmenting files, which are absolutely necessary to do most functions.

We need to narrow this down further before we start adding in more files.

This is where the tree-depth argument comes in handy: jeff@linuxlab:~/yang/vendor/cisco/xe/1721$ pyang -f tree Cisco-IOS-XE-native.yang –tree-depth=2

Tree-depth limits how deep the tree is displayed. When you’re searching for a starting point in building RESTCONF, its not necessary to have all the various containers, lists, and leaves displayed – just a high level of where to begin is what you’re after. A tree depth of 2 is a little small to be useful, but it made for a better screenshot.

Much like the IETF YANG files, there’s quite a lot of additional Cisco YANG files augmenting the Cisco-IOS-XE-native module – on IOS-XE 17.2.1, there’s 306 of them! Let’s start by trying to find BGP.

The logical place to start would be to see if it’s include natively (no pun intended) inside the main module. We’ll want to start piping the output to a file to make this manageable.

jeff@linuxlab:~/yang/vendor/cisco/xe/1721$ pyang -f tree Cisco-IOS-XE-native.yang –tree-depth=3 > native.out

jeff@linuxlab:~/yang/vendor/cisco/xe/1721$ vi native.out

Search for “bgp”

Let’s take a look at the other Cisco native YANG files in the directory, filtering for the word “bgp” in the file names:

The correct file is fairly obvious:Cisco-IOS-XE-bgp.yang.

Let’s add it in to our pyang tree:

jeff@linuxlab:~/yang/vendor/cisco/xe/1721$ pyang -f tree Cisco-IOS-XE-native.yang Cisco-IOS-XE-bgp.yang --tree-depth=3 > native.out
jeff@linuxlab:~/yang/vendor/cisco/xe/1721$ vi native.out

Searching for “bgp” produces several hits, but having a working knowledge of networking, and a basic understanding of YANG, makes the correct one obvious:

This requires scrolling up a bit to figure out the tree leading up to router, and frankly, you should be pulling the files out to notepad++ or a similar tool to make following a large tree easier.

The full path is:

Cisco-IOS-XE-native [module]
   native [container]
      router [container]
         bgp [list]

So, if I’m crafting a URL for this, I would use: https://10.200.200.100/restconf/data/native/router/bgp

Note the small trick there, Cisco-IOS-XE-native:native can be abbreviated as just “native”

Let’s say our goal is to turn up the BGP process and add a neighbor. We still need to know more than what we have, because ideally, we should be able to build the full PUT or POST straight off the YANG data and our own pre-existing network know-how. What we want is a deeper view of the tree starting at that one location.

Introducing –tree-path: pyang -f tree Cisco-IOS-XE-native.yang Cisco-IOS-XE-bgp.yang –tree-path /native/router/bgp –tree-depth=5

Inspecting the outcome from the data, we can find the next key elements:

Futher down the output, we find how to create neighbors:

Note the “201 Created”. Double checking our work at the command line:

csr1k#sh run | s router bgp
router bgp 100
 bgp log-neighbor-changes
 neighbor 4.4.4.4 remote-as 101
 neighbor 5.5.5.5 remote-as 102

Some final thoughts…

What’s up with lists?

I referred to lists throughout the document without really covering why they exist. The BGP example is a good use case. Each BGP neighbor, and all the config associated with it, is a list. An element in a list is usually not a 1:1 match up with a single line of IOS configuration.

Take for example creating users on the router:

<username>
        <name>admin1</name>
        <privilege>15</privilege>
        <secret>
            <encryption>9</encryption>
            <secret>(omitted)</secret>
        </secret>
    </username>
    <username>
        <name>admin2</name>
        <privilege>15</privilege>
        <secret>
            <encryption>9</encryption>
            <secret>(omitted)</secret>
        </secret>
    </username>

That’s two elements in a list “username”. The key to the list is “name”, which must be unique, so that it can be independently referenced, modified, or deleted.

Each element equals one line of configuration in IOS:

csr1k#sh run | s username
username admin1 privilege 15 secret 9 <omitted>
username admin2 privilege 15 secret 9 <omitted>

The BGP example is also a good one, where a list can create more than one line of IOS configuration. Let’s say on neighbor 5.5.5.5 we also wanted to enable ebgp-multihop.

The POST would’ve looked like this:

Now in the user example, one list = one line of IOS config. However, in this example, one list = multiple lines of config:

csr1k(config)#do sh run | s router bgp
router bgp 100
 bgp log-neighbor-changes
 neighbor 4.4.4.4 remote-as 101
 neighbor 5.5.5.5 remote-as 102
 neighbor 5.5.5.5 ebgp-multihop 255

This takes a little practice to wrap your head around, but it’s really not too bad. Going back to my original statement that the CLI was built for humans and APIs are built for code, it really makes a lot of sense.

Read-Only vs Read-Write

This blog has focused entirely on read-write configuration. There’s actually quite a lot of read-only YANG models that can be referenced by RESTCONF and is specified in YANG. Think about a BGP neighbor state, or an interface error count – things you would’ve perhaps previously monitored with SNMP. All the samples I’ve pasted above have had a “rw” next to them for read/write as my blog focus was about creating configuration, but there’s a whole side of this just for programmatically monitoring statuses.

For a quick example:

If you’re looking inside the YANG file itself, this is denoted differently:

container interfaces-state {
    config false;
    description
      "Data nodes for the operational state of interfaces.";

“config false” is what denotes read-only.

Remote Procedure Calls (RPC)

If you’ve tested SNMP writes, you’ve probably seen the example of why never to leave unguarded “write” SNMP access on: you can actually write a value to reboot the router. That’s an example of an SNMP-triggered RPC. NETCONF and RESTCONF have their own rich set of RPCs.

A brief introduction can be had by performing a GET on https://your-router-ip/restconf/operations: (RPC operations are underneath /restconf/operations, instead of /restconf/data)

For simplicity’s sake, let’s just demonstrate rebooting the router:

In closing, with the increasing use of network automation it’s important to familiarize yourself with RESTCONF and YANG. As shown in this article you can use the RESTCONF protocol to simplify and manage network configurations and operational features. I’ve always been a believer in working smarter, not harder. While this article was written with a high level overview, there are a myriad of resources to take a deeper dive into YANG, the pyang tool, and how to implement RESTCONF on Cisco devices if you’re wanting a deeper look into these great tools.