Interpreting RESTCONF and NETCONF Results and YANG Models

What it is

A RESTCONF or NETCONF query returns structured data that follows a YANG model, and you must be able to read both the reply and the model.

The reply shows the real values on a device. The YANG model shows the shape of that data, with its names, types and which parts are configuration.

Once you can read the model, you can predict what a reply looks like, and the other way round.

How it works

Start with the model, then match the reply against it.

A RESTCONF reply

A GET on the interfaces path returns JSON like this.

{
  "ietf-interfaces:interfaces": {
    "interface": [
      {
        "name": "GigabitEthernet1",
        "description": "WAN link",
        "type": "iana-if-type:ethernetCsmacd",
        "enabled": true,
        "ietf-ip:ipv4": {
          "address": [
            {"ip": "192.0.2.1", "netmask": "255.255.255.0"}
          ]
        }
      }
    ]
  }
}

Reading it:

• The top key is the module name, a colon, and the container name.
• interface is a JSON list, with one entry per interface.
• Each entry has leaves such as name, enabled and description.
• Keys with a prefix, such as ietf-ip:ipv4, come from another module that adds to the model.
• In Python the value is data["ietf-interfaces:interfaces"]["interface"][0]["name"].

RESTCONF status codes

A NETCONF reply

A NETCONF reply is XML. Because it is a tree of named elements, it can be pictured as an outline.

rpc-reply
  data
    interfaces
      interface
        name: GigabitEthernet1
        description: WAN link
        enabled: true

The reply is an rpc-reply element, and its data element holds the answer to a get or get-config request. The element names match the YANG names. The XML namespace tells you which module each element belongs to.

If the request works but returns no data, the reply holds an empty data element. A successful change has an ok element, and a failure has an rpc-error element.

In Python with ncclient, the reply object has an xml attribute with the text, and data_xml for the data part. Parse it with xmltodict or ElementTree.

A basic YANG module

module example-interfaces {
  namespace "urn:example:interfaces";
  prefix exif;

  container interfaces {
    list interface {
      key "name";

      leaf name {
        type string;
      }
      leaf description {
        type string;
      }
      leaf enabled {
        type boolean;
        default "true";
      }
      leaf mtu {
        type uint16 {
          range "68..9000";
        }
      }
      leaf oper-status {
        type string;
        config false;
      }
    }
  }
}

Reading the module

Anything that lacks config false can be configured. The range on mtu limits it to 68 to 9000, and the device refuses values outside it.

From this module you can predict the RESTCONF path to one entry, which is /restconf/data/example-interfaces:interfaces/interface=GigabitEthernet1, with the list key after an equals sign.

The pyang tree view

The pyang tool prints a compact tree of a module.

$ pyang -f tree example-interfaces.yang
module: example-interfaces
  +--rw interfaces
     +--rw interface* [name]
        +--rw name           string
        +--rw description?   string
        +--rw enabled?       boolean
        +--rw mtu?           uint16
        +--ro oper-status?   string

Here rw means read and write, and ro means read only. A star marks a list, and the key is in square brackets. A question mark marks an optional leaf.

Matching replies to models

If a reply lacks a leaf that the model marks optional, the value was not set. If a list key is missing from a request, the device cannot tell which entry you mean.