Table of Contents
RESTCONF is an HTTP based protocol, very similar to the ConfD REST API. The ConfD implementation of RESTCONF is based on RFC 8040 - RESTCONF Protocol.
This chapter describes any extensions and/or deviations between our implementation and RFC 8040.
In order to enable RESTCONF in ConfD,
RESTCONF must be enabled in the confd.conf
configuration file. The web server configuration for RESTCONF
is shared with the WebUI's config.
However, the WebUI does not have to be enabled for RESTCONF to work.
Here's a minimal example of what is needed in the
confd.conf file:
Example 22.1. ConfD configuration for REST
<restconf>
<enabled>true</enabled>
</restconf>
<webui>
<enabled>false</enabled>
<transport>
<tcp>
<enabled>true</enabled>
<ip>0.0.0.0</ip>
<port>8008</port>
</tcp>
</transport>
</webui>
RESTCONF makes it possible to specify where the RESTCONF API is located, as described in RFC 8040.
As per default, the RESTCONF API root is /restconf.
To change this, configure the RESTCONF API root in the
confd.conf file as:
Example 22.2. ConfD configuration for RESTCONF
<restconf> <enabled>true</enabled> <rootResource>my_own_restconf_root</rootResource> </restconf>
The RESTCONF API root will now be /my_own_restconf_root.
In this document, all examples will assume the RESTCONF API root to be /restconf.
RESTCONF capabilities are described in Section 9.1 of RFC 8040.
To view currently enabled capabilities, use the ietf-restconf-monitoring YANG model. This is available via /restconf/data/restconf-state, example result:
Example 22.3. ConfD RESTCONF capabilities
<restconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"
xmlns:rcmon="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
<capabities>
<capility>
urn:ietf:params:restconf:capability:defaults:1.0?basic-mode=explicit
</capability>
<capility>urn:ietf:params:restconf:capability:depth:1.0</capability>
<capility>urn:ietf:params:restconf:capability:fields:1.0</capability>
<capility>urn:ietf:params:restconf:capability:with-defaults:1.0</capability>
<capility>http://tail-f.com/ns/restconf/collection/1.0</capability>
<capility>http://tail-f.com/ns/restconf/query-api/1.0</capability>
</capalities>
</restconf-state>
RFC 8040 Section 3.7 describes retrieval of YANG modules used by the
server via the RPC operation get-schema. The YANG source is
made available by ConfD in two ways: compiled into
the fxs file or put in the loadPath. See Section 15.6, “Monitoring of the NETCONF Server”.
To avoid any potential future conflict with the RESTCONF standard, any extensions made to the ConfD implementation of RESTCONF is located under the URL path: /restconf/tailf, or is controlled by means of a vendor specific media type.
There is no index of extensions under /restconf/tailf. To list extensions, access /restconf/data/modules-state and follow published links for schemas.
The RESTCONF specification states that a result containing multiple instances (e.g a number of list entries) is not allowed if XML encoding is used. The reason for this is that an XML document can only have one root node.
To remedy this, a HTTP GET request can make use of the "Accept:" media type: application/vnd.yang.collection+xml as shown in the following example.
The result will then be wrapped with a "collection" element as shown below:
Example 22.5. Use of collections
<collection xmlns:y="urn:ietf:params:xml:ns:yang:ietf-restconf"> .... </collection>
Refer to Section 21.9, “The Query API” for a complete description of this functionality.
The only difference in the ConfD implementation is the use of the RESTCONF URI root resource, and the RESTCONF media types. An example of how a curl request can look like is shown below:
curl -i 'http://admin:admin@localhost:8008/restconf/tailf/query' \
-X POST -T test.xml \
-H "Content-Type: application/yang-data+xml"
The ConfD RESTCONF server support all the mandatory parts of the specification and some optional parts. This chapter describes what is currently not supported and/or any other deviations from the specification.