The RESTCONF API

Send a RESTCONF query to get a representation of the top-level resource, which is accessible through the path: /restconf.

GET /restconf
Accept: application/yang-data+xml

HTTP/1.1 200 OK
<restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
  <data/>
  <operations/>
  <yang-library-version>2019-01-04</yang-library-version>
</restconf>

As can be seen from the result, the server exposes three additional resources:

To fetch configuration, operational data, or both, from the server, a request to the data resource is made. In order to restrict the amount of returned data, the following example will prune the amount of output to only consist of the top most nodes. This is achieved by using the depth query argument as shown in the example below:

GET /restconf/data?depth=1
Accept: application/yang-data+xml

<data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
  <yang-library xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"/>
  <modules-state xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"/>
  <dhcp xmlns="http://yang-central.org/ns/example/dhcp"/>
  <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
  <netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring"/>
  <restconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"/>
  <aaa xmlns="http://tail-f.com/ns/aaa/1.1"/>
  <confd-state xmls="http://tail-f.com/yang/confd-monitoring"/>
  <last-logins xmlns="http://tail-f.com/yang/last-login"/>
</data>

Let's assume we are interested in the dhcp/subnet resource in our configuration. In the following examples, assume it is defined by a corresponding Yang module that we have named dhcp.yang, looking like this:

> yanger -f tree examples.confd/restconf/basic/dhcp.yang
module: dhcp
  +--rw dhcp
  +--rw max-lease-time?       uint32
  +--rw default-lease-time?   uint32
  +--rw subnet* [net]
  |  +--rw net               inet:ip-prefix
  |  +--rw range!
  |  |  +--rw dynamic-bootp?   empty
  |  |  +--rw low              inet:ip-address
  |  |  +--rw high             inet:ip-address
  |  +--rw dhcp-options
  |  |  +--rw router*        inet:host
  |  |  +--rw domain-name?   inet:domain-name
  |  +--rw max-lease-time?   uint32

We can issue a HTTP GET request to retrieve the value content of the resource. In this case we find that there is no such data, which is indicated by the HTTP return code 204 No Content.

Note also how we have prefixed the dhcp:dhcp resource. This is how RESTCONF handle namespaces, where the prefix is the YANG module name and the namespace is as defined by the namespace statement in the YANG module.

GET /restconf/data/dhcp:dhcp/subnet

HTTP/1.1 204 No Content

We can now create the dhcp/subnet resource by sending a HTTP POST request + the data that we want to store. Note the Content-Type HTTP header, which indicates the format of the provided body. Two formats is supported: XML or JSON. In this example we are using XML, which is indicated by the Content-Type value: application/yang-data+xml.

POST /restconf/data/dhcp:dhcp
Content-Type: application/yang-data+xml

<subnet xmlns="http://yang-central.org/ns/example/dhcp"
          xmlns:dhcp="http://yang-central.org/ns/example/dhcp">
  <net>10.254.239.0/27</net>
  <range>
    <dynamic-bootp/>
    <low>10.254.239.10</low>
    <high>10.254.239.20</high>
  </range>
  <dhcp-options>
    <router>rtr-239-0-1.example.org</router>
    <router>rtr-239-0-2.example.org</router>
  </dhcp-options>
  <max-lease-time>1200</max-lease-time>
</subnet>

# If the resource is created, the server might respond as follows:

HTTP/1.1 201 Created
Location: http://localhost:8080/restconf/data/dhcp:dhcp/subnet=10.254.239.0%2F27

Note the HTTP return code (201 Created) indicating that the resource was successfully created. We also got a Location header, which always is returned in a reply to a successful creation of a resource, stating the resulting URI leading to the created resource.

If we now want to modify a part of our dhcp/subnet config, we can use the HTTP PATCH method, as shown below. Note that the URI used in the request need to be URL-encoded, such that the key value: 10.254.239.0/27 is URL-encoded as: 10.254.239.0%2F27.

Also, note the difference of the PATCH URI compared to the earlier POST request. With the latter, since the resource does not yet exist, we POST to the parent resource (dhcp:dhcp), while with the PATCH request we address the (existing) resource (10.254.239.0%2F27).

PATCH /restconf/data/dhcp:dhcp/subnet=10.254.239.0%2F27

<subnet>
  <max-lease-time>3333</max-lease-time>
</subnet>

# If our modification is successful, the server might respond as follows:

HTTP/1.1 204 No Content

We can also replace the subnet with some new configuration. To do this we make use of the PUT HTTP method as shown below. Since the operation was successful and no body was returned, we will get a 204 No Content return code.

PUT /restconf/data/dhcp:dhcp/subnet=10.254.239.0%2F27
Content-Type: application/yang-data+xml

<subnet xmlns="http://yang-central.org/ns/example/dhcp"
          xmlns:dhcp="http://yang-central.org/ns/example/dhcp">
  <net>10.254.239.0/27</net>

  <!-- ...config left out here... -->

</subnet>

# At success, the server will respond as follows:

HTTP/1.1 204 No Content

To delete the subnet we make use of the DELETE HTTP method as shown below. Since the operation was successful and no body was returned, we will get a 204 No Content return code.

DELETE /restconf/data/dhcp:dhcp/subnet=10.254.239.0%2F27

HTTP/1.1 204 No Content

To view currently enabled capabilities, use the ietf-restconf-monitoring YANG model, which is available as: /restconf/data/ietf-restconf-monitoring:restconf-state .

GET /restconf/data/ietf-restconf-monitoring:restconf-state
Host: example.com
Accept: application/yang-data+xml

<restconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"
  xmlns:rcmon="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
<capabilities>
  <capability>
    urn:ietf:params:restconf:capability:defaults:1.0?basic-mode=explicit
  </capability>
  <capability>urn:ietf:params:restconf:capability:depth:1.0</capability>
  <capability>urn:ietf:params:restconf:capability:fields:1.0</capability>
  <capability>urn:ietf:params:restconf:capability:with-defaults:1.0</capability>
  <capability>urn:ietf:params:restconf:capability:filter:1.0</capability>
  <capability>urn:ietf:params:restconf:capability:replay:1.0</capability>
  <capability>http://tail-f.com/ns/restconf/collection/1.0</capability>
  <capability>http://tail-f.com/ns/restconf/query-api/1.0</capability>
  <capability>http://tail-f.com/ns/restconf/partial-response/1.0</capability>
  <capability>http://tail-f.com/ns/restconf/unhide/1.0</capability>
  <capability>urn:ietf:params:xml:ns:yang:traceparent:1.0</capability>
  <capability>urn:ietf:params:xml:ns:yang:tracestate:1.0</capability>
</capabilities>
</restconf-state>

This Capability identifies the basic-mode default-handling mode that is used by the server for processing default leafs in requests for data resources.

          urn:ietf:params:restconf:capability:defaults:1.0

The capability URL will contain a query parameter named basic-mode which value tells us what the default behaviour of the RESTCONF server is when it returns a leaf. The possible values are shown in the table below:

The values presented in the table above can also be used by the Client together with the with-defaults query parameter in order to override the default RESTCONF server behaviour. Added to these values, the Client can also use the report-all-tagged value.

Refering back to the example: Example 16, “NSO RESTCONF capabilities”, where the RESTCONF server returned the default capability:

urn:ietf:params:restconf:capability:defaults:1.0?basic-mode=explicit

It tells us that values that has been set by a client to the YANG default value will be reported but default values that has not been set by the Client will not be returned. Again, note that this is the default RESTCONF server behaviour which can be overridden by the Client by using the with-defaults query argument.

A set of optional RESTCONF Capability URIs are defined to identify the specific query parameters that are supported by the server. They are defined as:

For a description of the query parameter functionality see the chapter the section called “Query Parameters” .

The content query parameter controls if configuration, non-configuration or both types of data should be returned.

The allowed values are:

The depth query parameter is used to limit the depth of subtrees returned by the server. Data nodes with a value greater than the depth parameter are not returned in a response for a GET request.

The value of the depth parameter is either an integer between 1 and 65535 or the string "unbounded". The default value is: "unbounded".

The fields query parameter is used to optionally identify data nodes within the target resource to be retrieved in a GET method. The client can use this parameter to retrieve a subset of all nodes in a resource.

For a full definition of the fields value can be constructed, refer to the RFC 8040, Section 4.8.3.

NOTE: The fields query parameter cannot be used together with the exclude query parameter. This will result in an error.

GET /restconf/data/dhcp:dhcp?fields=subnet/range(low;high)
Accept: application/yang-data+xml

HTTP/1.1 200 OK
<dhcp xmlns="http://yang-central.org/ns/example/dhcp" \
      xmlns:dhcp="http://yang-central.org/ns/example/dhcp">
  <subnet>
    <range>
      <low>10.254.239.10</low>
      <high>10.254.239.20</high>
    </range>
  </subnet>
  <subnet>
    <range>
      <low>10.254.244.10</low>
      <high>10.254.244.20</high>
    </range>
  </subnet>
</dhcp>

The exclude query parameter is used to optionally exclude data nodes within the target resource from being retrieved with a GET request. The client can use this parameter to exclude a subset of all nodes in a resource. Only nodes below the target resource can be excluded, not the target resource itself.

NOTE: The exclude query parameter cannot be used together with the fields query parameter. This will result in an error.

The exclude query parameter uses the same syntax and have the same restrictions as the fields query parameter, as defined in RFC 8040, Section 4.8.3.

Selecting multiple nodes to exclude can be done the same way as for the fields query parameter, as described in RFC 8040, Section 4.8.3.

exclude using wildcards (*) will exclude all child nodes of the node. For lists and presence containers the parent node will be visible in the output but not it's children, i.e. it will be displayed as an empty node. For non-presence containers the parent node will be excluded from the output as well.

exclude can be used together with the depth query parameter to limit the depth of the output. In contrast to fields, where depth is counted from the node selected by fields, for exclude the depth is counted from the target resource, and the nodes are excluded if depth is deep enough to encounter an excluded node.

GET /restconf/data/dhcp:dhcp/subnet
Accept: application/yang-data+xml

HTTP/1.1 200 OK
<subnet xmlns="http://yang-central.org/ns/example/dhcp"
          xmlns:dhcp="http://yang-central.org/ns/example/dhcp">
  <net>10.254.239.0/27</net>
  <range>
    <dynamic-bootp/>
    <low>10.254.239.10</low>
    <high>10.254.239.20</high>
  </range>
  <dhcp-options>
    <router>rtr-239-0-1.example.org</router>
    <router>rtr-239-0-2.example.org</router>
  </dhcp-options>
  <max-lease-time>1200</max-lease-time>
</subnet>

GET /restconf/data/dhcp:dhcp/subnet?exclude=range(low;high)
Accept: application/yang-data+xml

HTTP/1.1 200 OK
<subnet xmlns="http://yang-central.org/ns/example/dhcp"
          xmlns:dhcp="http://yang-central.org/ns/example/dhcp">
  <net>10.254.239.0/27</net>
  <range>
    <dynamic-bootp/>
  </range>
  <dhcp-options>
    <router>rtr-239-0-1.example.org</router>
    <router>rtr-239-0-2.example.org</router>
  </dhcp-options>
  <max-lease-time>1200</max-lease-time>
</subnet>

These query parameters are only allowed on an event stream resource and is further described in the chapter: the section called “Streams” .

The insert query parameters is used to specify how a resource should be inserted within an ordered-by user list. The allowed values are as shown in the table below.

This parameter is only valid if the target data represents a YANG list or leaf-list that is ordered-by user. In the example below we will insert a new router value, first, in the ordered-by user leaf-list of dhcp-options/router values. Remember that the default behaviour is for new entries to be inserted last in an ordered-by user leaf-list.

# Note: we have to split the POST line in order to fit the page
POST /restconf/data/dhcp:dhcp/subnet=10.254.239.0%2F27/dhcp-options?\
     insert=first
Content-Type: application/yang-data+xml

<router>one.acme.org</router>

# If the resource is created, the server might respond as follows:

HTTP/1.1 201 Created
Location /restconf/data/dhcp:dhcp/subnet=10.254.239.0%2F27/dhcp-options/\
         router=one.acme.org

To verify that the router value really ended up first:

GET /restconf/data/dhcp:dhcp/subnet=10.254.239.0%2F27/dhcp-options
Accept: application/yang-data+xml

HTTP/1.1 200 OK
<dhcp-options xmlns="http://yang-central.org/ns/example/dhcp"
              xmlns:dhcp="http://yang-central.org/ns/example/dhcp">
  <router>one.acme.org</router>
  <router>rtr-239-0-1.example.org</router>
  <router>rtr-239-0-2.example.org</router>
</dhcp-options>

The point query parameters is used to specify the insertion point for a data resource that is being created or moved within an ordered-by user list or leaf-list. In the example below we will insert the new router value: two.acme.org, after the first value: one.acme.org in the ordered-by user leaf-list of dhcp-options/router values.

# Note: we have to split the POST line in order to fit the page
POST /restconf/data/dhcp:dhcp/subnet=10.254.239.0%2F27/dhcp-options?\
     insert=after&\
     point=/dhcp:dhcp/subnet=10.254.239.0%2F27/dhcp-options/router=one.acme.org
Content-Type: application/yang-data+xml

<router>two.acme.org</router>

# If the resource is created, the server might respond as follows:

HTTP/1.1 201 Created
Location /restconf/data/dhcp:dhcp/subnet=10.254.239.0%2F27/dhcp-options/\
         router=one.acme.org

To verify that the router value really ended up after our insertion point:

GET /restconf/data/dhcp:dhcp/subnet=10.254.239.0%2F27/dhcp-options
Accept: application/yang-data+xml

HTTP/1.1 200 OK
<dhcp-options xmlns="http://yang-central.org/ns/example/dhcp"
              xmlns:dhcp="http://yang-central.org/ns/example/dhcp">
  <router>one.acme.org</router>
  <router>two.acme.org</router>
  <router>rtr-239-0-1.example.org</router>
  <router>rtr-239-0-2.example.org</router>
</dhcp-options>

There are additional NSO query parameters available for the RESTCONF API. These additional query parameters are described below.

If rollbacks have been enabled in the configuration using the rollback-id query parameter, the fixed id of the rollback file creating during an operation is returned in the results. The below examples shows creation of a new resource and removal of that resource using the rollback created in the first step.

POST /restconf/data/dhcp:dhcp?rollback-id=true
Content-Type: application/yang-data+xml

<subnet xmlns="http://yang-central.org/ns/example/dhcp">
  <net>10.254.239.0/27</net>
</subnet>

HTTP/1.1 201 Created
Location: http://localhost:8008/restconf/data/dhcp:dhcp/subnet=10.254.239.0%2F27

<result xmlns="http://tail-f.com/ns/tailf-restconf">
<rollback>
  <id>10002</id>
</rollback>
</result>

Then using the fixed id returned above as input to the apply-rollback-file action:

POST /restconf/data/tailf-rollback:rollback-files/apply-rollback-file
Content-Type: application/yang-data+xml

<input xmlns="http://tail-f.com/ns/rollback">
  <fixed-number>10002</fixed-number>
</input>

HTTP/1.1 204 No Content

The RESTCONF protocol supports YANG-defined event notifications. The solution preserves aspects of NETCONF event notifications [RFC5277] while utilizing the Server-Sent Events, W3C.REC-eventsource-20150203, transport strategy.

RESTCONF event notification streams are described in Sections 6 and 9.2 of RFC 8040, where also notification examples can be found.

RESTCONF event notification is a way for RESTCONF clients to retrieve notifications for different event streams. Event streams configured in NSO can be subscribed to using different channels such as the RESTCONF or the NETCONF channel.

More information on how to define a new notification event using Yang is described in RFC 6020.

How to add and configure notifications support in NSO is described in the ncs.conf(3) man page.

The design of RESTCONF event notification is inspired by how NETCONF event notification is designed. More information on NETCONF event notification can be found in RFC 5277.

For this example we will define a notification stream, named interface in the ncs.conf configuration file as shown below.

We also enable the builtin replay store which means that NSO automatically stores all notifications on disk, ready to be replayed should a RESTCONF event notification subscriber ask for logged notifications. The replay store uses a set of wrapping log files on disk (of a certain number and size) to store the notifications.

<notifications>
  <eventStreams>
    <stream>
      <name>interface</name>
      <description>Example notifications</description>
      <replaySupport>true</replaySupport>
      <builtinReplayStore>
        <dir>./</dir>
        <maxSize>S1M</maxSize>
        <maxFiles>5</maxFiles>
      </builtinReplayStore>
    </stream>
  </eventStreams>
</notifications>

To view the currently enabled event streams, use the ietf-restconf-monitoring YANG model. The streams are available under the /restconf/data/ietf-restconf-monitoring:restconf-state/streams container.

GET /restconf/data/ietf-restconf-monitoring:restconf-state/streams
Accept: application/yang-data+xml

HTTP/1.1 200 OK

<streams xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"
         xmlns:rcmon="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">

  ...other streams info removed here for brewity reason...

  <stream>
    <name>interface</name>
    <description>Example notifications</description>
    <replay-support>true</replay-support>
    <replay-log-creation-time>
      2020-05-04T13:45:31.033817+00:00
    </replay-log-creation-time>
    <access>
      <encoding>xml</encoding>
      <location>https://localhost:8888/restconf/streams/interface/xml</location>
    </access>
    <access>
      <encoding>json</encoding>
      <location>https://localhost:8888/restconf/streams/interface/json</location>
    </access>
  </stream>
</streams>

Note the URL value we get in the location element in the example above. This URL should be used when subscribing to the notification events as is shown in the next example.

RESTCONF clients can determine the URL for the subscription resource (to receive notifications) by sending an HTTP GET request for the location leaf with the stream list entry. The value returned by the server can be used for the actual notification subscription.

The client will send an HTTP GET request for the (location) URL returned by the server with the Accept type text/event-stream as shown in the example below. Note that this request works like a long polling request which means that the request will not return. Instead, server side notifications will be sent to the client where each line of the notification will be prepended with data: .

GET /restconf/streams/interface/xml
Accept: text/event-stream

   ...NOTE: we will be waiting here until a notification is generated...

HTTP/1.1 200 OK
Content-Type: text/event-stream

data: <notification xmlns='urn:ietf:params:xml:ns:netconf:notification:1.0'>
data:     <eventTime>2020-05-04T13:48:02.291816+00:00</eventTime>
data:     <link-up xmlns='http://tail-f.com/ns/test/notif'>
data:       <if-index>2</if-index>
data:       <link-property>
data:         <newly-added/>
data:         <flags>42</flags>
data:         <extensions>
data:           <name>1</name>
data:           <value>3</value>
data:         </extensions>
data:         <extensions>
data:           <name>2</name>
data:           <value>4668</value>
data:         </extensions>
data:       </link-property>
data:     </link-up>
data: </notification>

   ...NOTE: we will still be waiting here for more notifications to come...

Since we have enabled the replay store, we can ask the server to replay any notifications generated since the specific date we specify. After those notifications have been delivered we will continue waiting for new notifications to be generated.

GET /restconf/streams/interface/xml?start-time=2007-07-28T15%3A23%3A36Z
Accept: text/event-stream

HTTP/1.1 200 OK
Content-Type: text/event-stream

data: ...any existing notification since given date will be delivered here...

   ...NOTE: when all notifications are delivered, we will be waiting here for more...

Errors occurring during streaming of events will be reported as Server-Sent Events (SSE) comments as described in W3C.REC-eventsource-20150203 as shown in the example below.

: error: notification stream NETCONF temporarily unavailable

In order to create the resources, we send a HTTP PATCH request where the Content-Type indicates that the body in the request consists of a Yang-Patch message. Our Yang-Patch request will initiate two edit operations where each operation will create a new subnet. In contrast, compare this with using "plain" RESTCONF where we would have needed two POST requests to achieve the same result.

PATCH /restconf/data/dhcp:dhcp
Accept: application/yang-data+xml
Content-Type: application/yang-patch+xml

<yang-patch xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
  <patch-id>add-subnets</patch-id>
  <edit>
    <edit-id>add-subnet-239</edit-id>
    <operation>create</operation>
    <target>/subnet=10.254.239.0%2F27</target>
    <value>
      <subnet xmlns="http://yang-central.org/ns/example/dhcp" \
              xmlns:dhcp="http://yang-central.org/ns/example/dhcp">
        <net>10.254.239.0/27</net>
          ...content removed here for brevity...
        <max-lease-time>1200</max-lease-time>
      </subnet>
    </value>
  </edit>
  <edit>
    <edit-id>add-subnet-244</edit-id>
    <operation>create</operation>
    <target>/subnet=10.254.244.0%2F27</target>
    <value>
      <subnet xmlns="http://yang-central.org/ns/example/dhcp" \
              xmlns:dhcp="http://yang-central.org/ns/example/dhcp">
        <net>10.254.244.0/27</net>
          ...content removed here for brevity...
        <max-lease-time>1200</max-lease-time>
      </subnet>
    </value>
  </edit>
</yang-patch>

# If the YANG Patch request was successful,
# the server might respond as follows:

HTTP/1.1 200 OK
<yang-patch-status xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
  <patch-id>add-subnets</patch-id>
  <ok/>
</yang-patch-status>

Let us modify the 'max-lease-time' of one 'subnet' and delete the 'max-lease-time' value of the second 'subnet'. Note that the delete will cause the default value of 'max-lease-time' to take effect, which we will verify using a RESTCONF GET request.

PATCH /restconf/data/dhcp:dhcp
Accept: application/yang-data+xml
Content-Type: application/yang-patch+xml

<yang-patch xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
  <patch-id>modify-and-delete</patch-id>
  <edit>
    <edit-id>modify-max-lease-time-239</edit-id>
    <operation>merge</operation>
    <target>/dhcp:subnet=10.254.239.0%2F27</target>
    <value>
      <subnet xmlns="http://yang-central.org/ns/example/dhcp" \
              xmlns:dhcp="http://yang-central.org/ns/example/dhcp">
        <net>10.254.239.0/27</net>
        <max-lease-time>1234</max-lease-time>
      </subnet>
    </value>
  </edit>
  <edit>
    <edit-id>delete-max-lease-time-244</edit-id>
    <operation>delete</operation>
    <target>/dhcp:subnet=10.254.244.0%2F27/max-lease-time</target>
  </edit>
</yang-patch>

# If the YANG Patch request was successful,
# the server might respond as follows:

HTTP/1.1 200 OK
<yang-patch-status xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
  <patch-id>modify-and-delete</patch-id>
  <ok/>
</yang-patch-status>

To verify that our modify and delete operations took place we make use of two RESTCONF GET request as shown below.

GET /restconf/data/dhcp:dhcp/subnet=10.254.239.0%2F27/max-lease-time
Accept: application/yang-data+xml

HTTP/1.1 200 OK
<max-lease-time xmlns="http://yang-central.org/ns/example/dhcp"
                xmlns:dhcp="http://yang-central.org/ns/example/dhcp">
                1234
</max-lease-time>

GET /restconf/data/dhcp:dhcp/subnet=10.254.244.0%2F27/max-lease-time?\
      with-defaults=report-all-tagged
Accept: application/yang-data+xml

HTTP/1.1 200 OK
<max-lease-time wd:default="true"
                xmlns:wd="urn:ietf:params:restconf:capability:defaults:1.0"
                xmlns="http://yang-central.org/ns/example/dhcp"
                xmlns:dhcp="http://yang-central.org/ns/example/dhcp">
                7200
</max-lease-time>

Note how we in the last GET request make use of the with-defaults query parameter to request that a default value should be returned and also be tagged as such.

The API consists of the following Requests:

The API consists of the following Replies:

In the following examples, we'll use this data model:

container x {
  list host {
    key number;
    leaf number {
      type int32;
    }
    leaf enabled {
      type boolean;
    }
    leaf name {
      type string;
    }
    leaf address {
      type inet:ip-address;
    }
  }
}]

The actual format of the payload should be represented either in XML or JSON. Note how we indicate the type of content using the Content-Type HTTP header. For XML it could look like this:

POST /restconf/tailf/query
Content-Type: application/yang-data+xml

<start-query xmlns="http://tail-f.com/ns/tailf-rest-query">
  <foreach>
    /x/host[enabled = 'true']
  </foreach>
  <select>
    <label>Host name</label>
    <expression>name</expression>
    <result-type>string</result-type>
  </select>
  <select>
    <expression>address</expression>
    <result-type>string</result-type>
  </select>
  <sort-by>name</sort-by>
  <limit>100</limit>
  <offset>1</offset>
  <timeout>600</timeout>
</start-query>]

The same request in JSON format would look like:

POST /restconf/tailf/query
Content-Type: application/yang-data+json

{
 "start-query": {
   "foreach": "/x/host[enabled = 'true']",
   "select": [
     {
       "label": "Host name",
       "expression": "name",
       "result-type": ["string"]
     },
     {
       "expression": "address",
       "result-type": ["string"]
     }
   ],
   "sort-by": ["name"],
   "limit": 100,
   "offset": 1,
   "timeout": 600
 }
}]

An informal interpretation of this query is:

For each /x/host where enabled is true, select its name, and address, and return the result sorted by name, in chunks of 100 result items at a time.

Let us discuss the various pieces of this request. To start with, when using XML, we need to specify the name space as shown:

<start-query xmlns="http://tail-f.com/ns/tailf-rest-query">

The actual XPath query to run is specified by the foreach element. In the example below will search for all /x/host nodes that has the enabled node set to true:

<foreach>
  /x/host[enabled = 'true']
</foreach>

Now we need to define what we want to have returned from the node set by using one or more select sections. What to actually return is defined by the XPath expression.

Choose how the result should be represented. Basically, it can be the actual value or the path leading to the value. This is specified per select chunk. The possible result-types are: string , path , leaf-value and inline.

The difference between string and leaf-value is somewhat subtle. In the case of string the result will be processed by the XPath function: string() (which if the result is a node-set will concatenate all the values). The leaf-value will return the value of the first node in the result. As long as the result is a leaf node, string and leaf-value will return the same result. In the example above, the string is used as shown below. Note that at least one result-type must be specified.

The result-type inline makes it possible to return the full sub-tree of data, either in XML or in JSON format. The data will be enclosed with a tag: data.

It is possible to specify an optional label for a convenient way of labeling the returned data:

<select>
  <label>Host name</label>
  <expression>name</expression>
  <result-type>string</result-type>
</select>
<select>
  <expression>address</expression>
  <result-type>string</result-type>
</select>

The returned result can be sorted. This is expressed as an XPath expression, which in most cases is very simple and refers to the found node set. In this example we sort the result by the content of the name node:

<sort-by>name</sort-by>

With the offset element we can specify at which node we should start to receive the result. The default is 1, i.e., the first node in the resulting node-set.

<offset>1</offset>

It is possible to set a custom timeout when starting or resetting a query. Each time a function is called, the timeout timer resets. The default is 600 seconds, i.e. 10 minutes.

<timeout>600</timeout>

The reply to this request would look something like this:

<start-query-result>
  <query-handle>12345</query-handle>
</start-query-result>

The query handle (in this example '12345') must be used in all subsequent calls. To retrieve the result, we can now send:

<fetch-query-result xmlns="http://tail-f.com/ns/tailf-rest-query">
  <query-handle>12345</query-handle>
</fetch-query-result>

Which will result in something like the following:

<query-result xmlns="http://tail-f.com/ns/tailf-rest-query">
  <result>
    <select>
      <label>Host name</label>
      <value>One</value>
    </select>
    <select>
      <value>10.0.0.1</value>
    </select>
  </result>
  <result>
    <select>
      <label>Host name</label>
      <value>Three</value>
    </select>
    <select>
      <value>10.0.0.3</value>
    </select>
  </result>
</query-result>

If we try to get more data with the fetch-query-result we might get more result entries in return until no more data exists and we get an empty query result back:

<query-result xmlns="http://tail-f.com/ns/tailf-rest-query">
</query-result>

Finally, when we are done we stop the query:

<stop-query xmlns="http://tail-f.com/ns/tailf-rest-query">
  <query-handle>12345</query-handle>
</stop-query>

If we want to go back in the "stream" of received data chunks and have them repeated, we can do that with the 'reset-query' request. In the example below we ask to get results from the 42:nd result entry:

<reset-query xmlns="http://tail-f.com/ns/tailf-rest-query">
  <query-handle>12345</query-handle>
  <offset>42</offset>
</reset-query>

If we want to get the entire result sent back to us, using only one request, we can do this by using the immediate-query. This function takes similar arguments as start-query and returns the entire result analogous with the result from a fetch-query-result request. Note that it is not possible to paginate or set an offset start node for the result list; i.e. the options limit and offset are ignored.

The yanger tool is a YANG parser and validator that provides options to convert YANG modules to a multitude of formats including Swagger. You use the -f swagger option to generate a Swagger definition from one or more YANG files. The following command generates a Swagger file named example.json from the example.yang YANG file:

yanger -t expand -f swagger example.yang -o example.json
        

It is only supported to generate Swagger from one YANG module at a time. It is possible however to augment this module by supplying additional modules. The following command generates a Swagger document from base.yang which is augmented by base-ext-1.yang and base-ext-2.yang:

yanger -t expand -f swagger base.yang base-ext-1.yang base-ext-2.yang -o base.json
        

Only supplying augmenting modules is not supported.

Use the --help option to the yanger command to see all available options:

yanger --help
        

The complete list of options related to Swagger generation is:

Swagger output specific options:
  --swagger-host                    Add host to the Swagger output
  --swagger-basepath                Add basePath to the Swagger output
  --swagger-version                 Add version url to the Swagger output.
                                    NOTE: this will override any revision
                                    in the yang file
  --swagger-tag-mode                Set tag mode to group resources. Valid
                                    values are: methods, resources, all
                                    [default: all]
  --swagger-terms                   Add termsOfService to the Swagger
                                    output
  --swagger-contact-name            Add contact name to the Swagger output
  --swagger-contact-url             Add contact url to the Swagger output
  --swagger-contact-email           Add contact email to the Swagger output
  --swagger-license-name            Add license name to the Swagger output
  --swagger-license-url             Add license url to the Swagger output
  --swagger-top-resource            Generate only swagger resources from
                                    this top resource. Valid values are:
                                    root, data, operations, all [default:
                                    all]
  --swagger-omit-query-params       Omit RESTCONF query parameters
                                    [default: false]
  --swagger-omit-body-params        Omit RESTCONF body parameters
                                    [default: false]
  --swagger-omit-form-params        Omit RESTCONF form parameters
                                    [default: false]
  --swagger-omit-header-params      Omit RESTCONF header parameters
                                    [default: false]
  --swagger-omit-path-params        Omit RESTCONF path parameters
                                    [default: false]
  --swagger-omit-standard-statuses  Omit standard HTTP response statuses.
                                    NOTE: at least one successful HTTP
                                    status will still be included
                                    [default: false]
  --swagger-methods                 HTTP methods to include. Example:
                                    --swagger-methods "get, post"
                                    [default: "get, post, put, patch,
                                    delete"]
  --swagger-path-filter             Filter out paths matching a path filter.
                                    Example: --swagger-path-filter
                                    "/data/example-jukebox/jukebox"

Using the example-jukebox.yang from the RESTCONF RFC 8040, the following example generates a comprehensive Swagger definition using a variety of the Swagger-related options:

yanger -p . -t expand -f swagger example-jukebox.yang \
       --swagger-host 127.0.0.1:8080 \
       --swagger-basepath /restconf \
       --swagger-version "My swagger version 1.0.0.1" \
       --swagger-tag-mode all \
       --swagger-terms "http://my-terms.example.com" \
       --swagger-contact-name "my contact name" \
       --swagger-contact-url "http://my-contact-url.example.com" \
       --swagger-contact-email "my-contact-email@example.com" \
       --swagger-license-name "my license name" \
       --swagger-license-url "http://my-license-url.example.com" \
       --swagger-top-resource all \
       --swagger-omit-query-params false \
       --swagger-omit-body-params false \
       --swagger-omit-form-params false \
       --swagger-omit-header-params false \
       --swagger-omit-path-params false \
       --swagger-omit-standard-statuses false \
       --swagger-methods "post, get, patch, put, delete, head, options"