Dear Hank… Help Myself with RESTCONF URL Creation

I get queries sent from engineers focusing on network automation occasionally. I’m humbled that anyone would think about me if they are stuck on another question, and when it’s a issue that I could help with I love to take time to reply.

Recently I received a contact from an engineer who was simply working through my Network Programmability Basics Video Course in DevNet. Their question linked to focusing on how the URLs for RESTCONF are usually made of the YANG versions, and how to utilize the feature for something similar to updating IP addresses. It had been an excellent query and permitted me to dive in to the topic a little more than I generally do during a program on YANG. I’m furthermore a sucker for just about any chance to explore even more of the depth of the protocols. The issue (and my reply) was so excellent I thought more people might be thinking about checking them out.

Here may be the question:

“While functioning through Network gadget APIs, video #3, “Learn to CRUD with GET, DELETE and post using RESTCONF,” I’m stuck on delivering a Place to configure GigabitEthernet2. I’m attempting to realize the YANG design and how it ties in. Specifically, how exactly to craft the reference address for the user interface, where “interface” versus “interfaces” fall into the road. Also, where will “ietf-ip:ipv4” match the paths for dealing with IP addresses?”

And my answer:

Very first, the URL for RESTCONF is taken from the YANG models and follows the main element that I discuss in the video. Therefore, with the ietf-interfaces design that appears like this:

module: ietf-interfaces 
   +--rw interfaces 
   |  +--rw user interface* [name] 
   |     +--rw name                        string 
   |     +--rw description?                string 
   |     +--rw type                        identityref 
   |     +--rw enabled?                    boolean 
   |     +--rw link-up-down-trap-enable?   enumeration if-mib? 

(somewhat edited for the post)

The resource area of the URL for GigabitEthernet2 will be:

/restconf/data/ietf-interfaces:interfaces/user interface=GigabitEthernet2

The query indicated confusion on “interfaces” vs “interface” inside the URL. The proven fact that “user interface” appears three times in the route makes it confusing. But there exists a reason for all of them:

  1. ietf-interfaces – the module name
  2. :interfaces– the title of the list which has individual elements
  3. interface – the main element for a person interface element

Today, let’s discuss configuring the Ip for an interface. It is possible to retrieve and revise the IP for an user interface by returning or dealing with the user interface URI as we talked about above, but that URI is usually for all information on an interface, not really the Ip just. In order to just use the Ip, you asked an excellent question concerning the path for ietf-ip:ipv4.

This takes us in to the subject of YANG design augmentation, something We don’t go into through the Basics training course, but I do discuss in this Cisco Live Session that you could watch out for free. The complete session would be excellent to watch since it will go deeper into NETCONF/RESTCONF/YANG, however the relevant component starts at half an hour.

The short edition is that through augmentation, the ietf-interfaces design is “augmented” by the ietf-ip design to include IPv4 and IPv6 addressing to an interface. Right here is a brief snippet of this model:

module: ietf-ip 
  augment /if:interfaces/if:user interface: 
    +--rw ipv4! 
    |  +--rw enabled?      boolean 
    |  +--rw forwarding?   boolean 
    |  +--rw mtu?          uint16 
    |  +--rw tackle* [ip] 
    |  |  +--rw ip                     inet:ipv4-address-no-zone 
    |  |  +--rw (subnet) 
    |  |     +--:(prefix-length) 
    |  |     |  +--rw prefix-duration?   uint8 
    |  |     +--:(netmask) 
    |  |        +--rw netmask?         yang:dotted-quad ipv4-non-contiguous-netmasks? 

With this new design info, we are able to build the road to retrieve the IPv4 deal with for an user interface to be:

/restconf/data/ietf-interfaces:interfaces/user interface=GigabitEthernet2/ietf-ip:ipv4/tackle

Notice the coloring for where in fact the additional elements of the URI result from.

A Reach this path would come back something that appears like this:

    "ietf-ip:deal with": [ 
            "ip": "", 
            "netmask": "" 

A good interface might have more than a single Ip, so “address” is really a list. If you knew the precise IP you wished to retrieve, the URL will be:

GET /restconf/information/ietf-interfaces:interfaces/user interface=GigabitEthernet2/ietf-ip:ipv4/tackle=

Today suppose you need to update the Ip for this user interface. There are some options accessible to you, each with

The first option, and most straightforward, is you could send the PUT demand to the URL for the Ip that you need to increase the configuration. This might appear to be this:

PUT /restconf/data/ietf-interfaces:interfaces/user interface=GigabitEthernet2/ietf-ip:ipv4/deal with= 
    "ietf-ip:tackle": [ 
            "ip": "", 
            "netmask": "" 

This will Include the IP to interface GigabitEthernet2. The main element here’s that it adds the IP… any current Ip on the interface it’s still there.

To remove a vintage IP from an user interface, you could send the DELETE to the Ip.

DELETE /restconf/data/ietf-interfaces:interfaces/user interface=GigabitEthernet2/ietf-ip:ipv4/deal with=

A good obvious issue to ask is, “How do i modification the IP of an user interface in a single step? Because of the way the specifications of NETCONF/RESTCONF/YANG are usually written, working with an inventory item has some annoying features. One of these is that you can’t Upgrade or DELETE an entire list in a single targeted request. This means a DELETE or Place at the URL for the tackle list won’t function.

This WON’T function:
Place /restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet2/ietf-ip:ipv4/deal with

There is really a tiny “work around” because of this limitation. You can up-date the complete INTERFACE with the required configuration utilizing a PUT request. In this situation it is vital that you know that the info you send must are the entire desired user interface configuration, not only the brand new IP address. For example, you would have to are the current interface explanation together with the IP addresses. If you still left the explanation off, it will be taken off the interface. This would appear to be:

PUT /restconf/information/ietf-interfaces:interfaces/user interface=GigabitEthernet2 
    "ietf-interfaces:user interface":  
        "name": "GigabitEthernet2", 
        "description": "Configured by RESTCONF", 
        "type": "iana-if-kind:ethernetCsmacd", 
        "enabled": real, 
            "address": [ 
                    "ip": "", 
                    "netmask": "" 

With this payload and API contact, the interface will be configured with ONLY the IP listed. Any presently configured address will be removed from the user interface and changed with this particular data.

We hope this can help clarify the facts behind how RESTCONF and the URLs function. You are most certainly on the right course with these queries and thinking how it works. Area of the exploration of programmability gets to the stage where you understand enough to also ask the questions.

What questions are you experiencing?

Thus what can you think? I’m hoping that my solution helped an individual who delivered it my method, but think about you? Did this assist you to better understand YANG?

Get to out and i want to know in the remarks here, or higher on Twitter I’m @hfpreston. Or needless to say there’s always email as well ? You will get me at hapresto@cisco.com.

Related resources

%d bloggers like this: