Using RESTCONF

WEB application developers have different tools and a resource-oriented data model which tends to keep them from adopting NETCONF over SSH as a programatic interface.

The RESTCONF Protocol is defined in RFC 8040.

The YANG Patch media type used by RESTCONF is defined in RFC 8072.

A WEB server is required to use RESTCONF.

It must support the FastCGI API, which is used by the restconf program for REST access to the netconfd-pro server

Refer to the RESTCONF Installation section installation instructions.

The restconf program is a FastCGI thin client that connects the WEB server to the netconfd-pro server to process HTTP requests.

It is usually installed in the /var/www/yang-api folder.

RESTCONF Features

The RESTCONF server has the following features:

Complete implementation of RESTCONF protocol, defined in RFC 8040
Complete implementation of YANG Patch, defined in RFC 8072.
Automatic support for all NETCONF operations, including the YANG 'insert' operation, defined in RFC 7950.
Supports the complete HTTP/1.1 transport defined in RFC 7230.
Complete XML 1.0 implementation with full support for XML Namespaces
Complete JSON implementation defined in RFC 7951
Automatic support for all capability registration and <hello> message processing
Fully recoverable, automatic database editing, using a simple 3 phase callback model
- 1. validate, 2) apply, 3) commit or rollback
Full support for database locking, editing, validation, including extensive user-callback capabilities to support device instrumentation.
Complete <rpc-error> reporting support, including user-defined errors via YANG error-app-tag and error-message statements.
Several <rpc-error> extensions, including <bad-value> and <error-number>, for easier debugging
Extend error handling
- HTTP status-lines are used to report success or failure for RESTCONF operations. Error information is returned for "4xx" class of status codes. This error information is adapted for use in RESTCONF.
Complete RFC 5277 Notification support, including notification replay via SSE W3C Working Draft
- Event stream monitoring defined in ietf-restconf-monitoring.yang
- Multiple event streams possible Using Custom Event Streams
Complete RFC 7895 YANG Module Library support, including full support of the YANG modules schema retrieval from the server and support of server-specific identifier representing the current set of modules and submodules.
Support new query parameters:
- The "depth" parameter is used to limit the number of levels of child resources that are returned by the server for a GET method request.
- The "content" parameter is used to select the type of data child resources (configuration or not configuration, or all data) that are returned by the server for a GET method request.
- The “with-defaults” parameter is used to select the type of data (report-all, report-all-tagged, trim, explicit) that are returned by the server for a GET method request.
Support GET on /restconf/data
- This mandatory resource represents the combined configuration and operational data resources that can be accessed by a client. It cannot be created or deleted by the client.
Support POST /restconf/operations
- This optional resource is a container that provides access to the data-model specific protocol operations supported by the server. The server may omit this resource if no data-model specific operations are advertised.
- Any data-model specific operations defined in the YANG modules advertised by the server may be available as child nodes of this resource.
RESTCONF capability support /restconf/data/restconf-state
- RESTCONF provides the YANG module capability information supported by the server, in case the client wants to use it. The URIs for custom protocol operations and datastore content are predictable, based on the YANG module definitions.
Support for new POST and PUT/create operations
- Support POST/PUT Request based on query parameters and protocol
Two "edit collision detection" mechanisms are provided in RESTCONF, for datastore and data resources.
- Timestamps
- Entity Tag
Support full conformance
- Support Accept header validation
- Support .well-known. The root of the RESTCONF API configured on the HTTP server, discovered by getting the .well-known/host-meta
- Support ietf-restconf-monitoring
- Supports notifications that populate a stream resource for each notification delivery service access point. A RESTCONF client can retrieve the list of supported event streams from a RESTCONF server using the GET operation on the /restconf/data/restconf-state/streams list.
- Supports a new event stream resource. This resource represents an SSE (Server-Sent Events) event stream. The content consists of text using the media type "text/event-stream", as defined by the HTML5 specification. Each event represents one <notification> message generated by the server. It contains a conceptual system or data-model specific event that is delivered within an event notification stream. Also called a "stream resource".
Complete RFC 8527 RESTCONF Extensions to Support the NMDA, including read-only support of new resources representing datastores as defined in RFC 8342. This feature is available starting in the 23.10T-3 release.
- These resources are available using the following resource path template:
  
  {+restconf}/ds/<datastore>
- Support GET and HEAD on /restconf/ds/<datastore>

RESTCONF Resource Types

The RESTCONF resources are accessed via a set of URIs. The set of YANG modules supported by the server will determine the data model specific operations, top-level data node resources, and event notification messages supported by the server.

The RESTCONF protocol defines a set of application specific media types to identify each of the available resource types. The following resource types are defined in RESTCONF:

RESTCONF Resource Types

Type	Resource	Accept Header
API	{+restconf}/ {+restconf}/operations {+restconf}/version {+restconf}/yang-library-version	application/yang-data+xml application/yang-data+json
Datastore	{+restconf}/data	application/yang-data+xml application/yang-data+json
Data	{+restconf}/data/<node>	application/yang-data+xml application/yang-data+json
Errors	RESTCONF specific	application/yang-data+xml application/yang-data+json
Operation	{+restconf}/operations/<operation>	application/yang-data+xml application/yang-data+json
Schema	{+restconf}/yang	application/yang
Event Stream	{+restconf}/stream	text/event-stream
NMDA Datastore	{+restconf}/ds/<datastore>	application/yang-data+xml application/yang-data+json
NMDA Data	{+restconf}/ds/<datastore>/<node>	application/yang-data+xml application/yang-data+json

Root Resource Discovery

A RESTCONF client can determine the root of the RESTCONF API by getting the /.well-known/host-meta resource and using the <Link> element containing the "restconf" attribute:

Example Request:

GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml

Example Response:

HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: 106

<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
  <Link rel='restconf' href='/restconf'/>
</XRD>

Operation Resource

Once discovering the RESTCONF API root, the client must prepend it to any subsequent request to a RESTCONF resource. For instance, using the /restconf path discovered above, the client can now determine the operations supported by the server.

Example Request:

GET /restconf/operations HTTP/1.1
Host: example.com
Accept: application/yang-data+xml

Example Response:

<operations xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
  <backup xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <cancel-subscription xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <clear-eventlog xmlns="http://yumaworks.com/ns/yumaworks-event-stream"/>
  <create-subscription xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"/>
  <delete-backup xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <delete-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"/>
  <establish-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"/>
  <get-bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk"/>
  <get-ha-status xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <get-module-tags xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <get-schema xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring"/>
  <get-support-save xmlns="urn:ietf:params:xml:ns:yang:yumaworks-support-save"/>
  <kill-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"/>
  <load xmlns="http://netconfcentral.org/ns/yuma-system"/>
  <load xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <load-bundle xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <modify-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"/>
  <no-op xmlns="http://netconfcentral.org/ns/yuma-system"/>
  <partial-lock xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"/>
  <partial-unlock xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"/>
  <refresh-backup-dir xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <restart xmlns="http://netconfcentral.org/ns/yuma-system"/>
  <restore xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <resync-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push"/>
  <set-log-level xmlns="http://netconfcentral.org/ns/yuma-system"/>
  <set-log-level xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <shutdown xmlns="http://netconfcentral.org/ns/yuma-system"/>
  <unload xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <unload-bundle xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</operations>

Event Stream Resource

A RESTCONF client can retrieve the list of supported event streams from a RESTCONF server using the GET method on the "stream" list. The restconf-state/streams container definition in the ietf-restconf-monitoring YANG module is used to specify the structure and syntax of the conceptual child resources within the "streams" resource.

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

The server might send the following response:

<data>
  <restconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
   <streams>
    <stream>
     <name>RESTCONF</name>
     <description>default RESTCONF event stream</description>
     <replay-support>true</replay-support>
     <replay-log-creation-time>2023-12-12T22:43:31Z</replay-log-creation-time>
     <access>
      <encoding>xml</encoding>
      <location>http://localhost/restconf/stream</location>
     </access>
    </stream>
   </streams>
  </restconf-state>
</data>

The value returned by the server for the events leaf can be used for the actual notification subscription.

The client will send an HTTP GET request for the URL returned by the server with the "Accept" type text/event-stream.

The server will treat the connection as an event stream, using the Server Sent Events transport strategy.

Example:

The client might send the following request to enable SSE event notification stream:

GET http://restconf-dev/restconf/stream HTTP/1.1
Host: example.com
Accept: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

An example SSE event notification encoded using XML:

data:
data:   <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
data:     <eventTime>2023-12-12T23:34:26Z</eventTime>
data:     <netconf-config-change xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
data:       <changed-by>
data:         <username>restconf</username>
data:         <session-id>19</session-id>
data:         <source-host>127.0.0.1</source-host>
data:       </changed-by>
data:       <datastore>running</datastore>
data:       <edit>
data:         <target
data:           xmlns:t="http://netconfcentral.org/ns/test">/t:uint32.1</target>
data:         <operation>delete</operation>
data:       </edit>
data:     </netconf-config-change>
data:   </notification>

The server supports query parameters for a GET method on Event Stream resource. These parameters are specific to each event stream.

For more details refer to the RFC 8040.

Using CURL tool, to Receive RESTCONF Notifications subscribe to event stream by GET request as follows:

> curl http://restconf-dev/restconf/stream -H "Accept:text/event-stream"

RESTCONF Headers

There are several HTTP header lines utilized in RESTCONF messages. Messages are not limited to the HTTP headers listed in this section.

HTTP defines which header lines are required for particular circumstances. There are some request headers that are used within RESTCONF, usually applied to data resources. The following tables summarize the headers most relevant in RESTCONF message requests:

RESTCONF Request Headers

Accept	Response Content-Types that are acceptable
Content-Type	The media type of the request body
Host	The host address of the server
If-Match	Only perform the action if the entity matches ETag
If-Modified-Since	Only perform the action if modified since time
If-Unmodified-Since	Only perform the action if unmodified since time

The following tables summarize the headers most relevant in RESTCONF message responses:

RESTCONF Response Headers

Allow	Valid actions when 405 error returned
Cache-Control	The cache control parameters for the response
Content-Type	The media type of the response message-body
Date	The date and time the message was sent
ETag	An identifier for a specific version of a resource
Last-Modified	The last modified date and time of a resource
Location	The resource identifier for a newly created resource

The --restconf-strict-headers parameter specifies the server validation rules for Accept and Content-Type headers entries. If set to 'true' the server will only accept requests with normative header entries specified in RFC 8040. If set to 'false', the server will try to accept not normative header entries. The default is false.

RESTCONF Query Parameters

Each RESTCONF operation allows zero or more query parameters to be present in the request URI. The specific parameters that are allowed depends on the resource type, and sometimes the specific target resource used, in the request.

RESTCONF Query Parameters

content	GET	Select config and/or non-config data resources
depth	GET	Request limited sub-tree depth in the
fields	GET	Return all descendant data nodes reply content
filter	GET	Boolean notification filter for event stream resources
insert	POST/ PUT	Insertion mode for user-ordered data resources
point	POST/ PUT	Insertion point for user-ordered data resources
start-time	GET	Replay buffer start time for event stream resources
stop-time	GET	Replay buffer stop time for event stream resources
with-defaults	GET	Control retrieval of default values
with-origin	GET	Control retrieval of origin metadata annotations in responses

Query parameters can be given in any order. Each parameter can appear at most once in a request URI. A default value may apply if the parameter is missing.

If vendors define additional query parameters, they should use a prefix (such as the enterprise or organization name) for query parameter names in order to avoid collisions with other parameters.

Depth Query Parameter

In the RESTCONF implementation the "depth" parameter is used to limit the number of levels of child resources that are returned by the server for a GET method request.

leaf depth {
   type union {
     type enumeration {
       enum unbounded;
     }
     type uint32 {
       range "1..max";
     }
   }
   default unbounded;   // set to 1 in draft-01!
   description "Resource retrieval depth requested";
 }

The start level is determined by the target resource for the operation.

The first nest-level consists of the requested data node itself. Any child nodes which are contained within a parent node have a depth value that is 1 greater than its parent, so that a depth level of "1" includes just the target resource level itself. A depth level of "2" includes the target resource level and its child nodes.

To retrieve all the child resources, the "depth" parameter is not present or set to the default value "unbounded". The value of the "depth" parameter is either an integer between 1 and 65535, or the string "unbounded". "unbounded" is the default.

This parameter is only allowed for GET methods on API, datastore, and data resources. A 400 Bad Request error is returned if it used for other methods or resource types.

By default, the server will include all sub-resources within a retrieved resource, which have the same resource type as the requested resource. Only one level of sub-resources with a different media type than the target resource will be returned.

If the "depth" query parameter URI is listed in the "capability" leaf-list, then the server supports the "depth" query parameter.

Content Query Parameter

The "content" parameter is used to select the type of data child resources (configuration and/or not configuration) that are returned by the server for a GET method request.

The "content" parameter controls how descendant nodes of the requested data nodes will be processed in the reply.

The allowed values are:

config	Return only configuration descendant data nodes
nonconfig	Return only non-configuration descendant data nodes
all	Return all descendant data nodes

This parameter is only allowed for GET methods on datastore and data resources. A 400 Bad Request error is returned if used for other methods or resource types. The default value is for the "content" parameter is "nonconfig".

To retrieve all the child resources, the "content" parameter is set to "all".

The client might send:

GET /restconf/data/example-events:events?content=all HTTP/1.1
Host: example.com
Accept: application/yang-data+json

The server might respond:

HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:11:30 GMT
Server: example-server
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/yang-data+json

{
  "example-events:events" : {
    "event" : [
     {
       "name" : "interface-up",
       "description" : "Interface up notification count",
       "event-count" : 42
     },
     {
       "name" : "interface-down",
       "description" : "Interface down notification count",
       "event-count" : 4
      }
    ]
  }
}

YANG definition:

container query {
  ncx:abstract;
  ncx:hidden;
  description "RESTCONF Query String Parameters";

  leaf content {
    type enumeration {
      enum config;
      enum nonconfig;
      enum all;
    }
  }
  description
    "controls how descendant nodes of the requested
     data nodes will be processed in the reply .";
}

The content parameter is similar to the “config” YANG-API query parameter.

Filter Query Parameter

Currently this parameter is not supported, it will be available in the next releases.

The "filter" parameter is used to indicate which subset of all possible events are of interest. If not present, all events not precluded by other parameters will be sent.

This parameter is only allowed for GET methods on a text/event-stream data resource. A 400 Bad Request error is returned if used for other methods or resource types.

The format of this parameter is an XPath 1.0 expression, and is evaluated in the following context:

The set of namespace declarations is the set of prefix and namespace pairs for all supported YANG modules, where the prefix is the YANG module name, and the namespace is as defined by the "namespace" statement in the YANG module. The function library is the core function library defined in XPath 1.0.
The set of variable bindings is empty.
The context node is the root node.

If the boolean result of the expression is true when applied to the conceptual "notification" document root, then the event notification is delivered to the client.

If the "filter" query parameter URI is listed in the "capability" leaf-list, then the server supports the "filter" query parameter.

The following URIs show some examples of notification filter specifications (lines wrapped for display purposes only):

// filter = /event/event-class='fault'
GET /mystreams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault'

// filter = /event/severity<=4
GET /mystreams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4

// filter = /*/reporting-entity/card!='Ethernet0'
GET /mystreams/NETCONF?filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0'

// filter = /*/email-addr[contains(.,'company.com')]
GET /mystreams/critical-syslog?filter=%2F*%2Femail-addr[contains(.%2C'company.com')]

// Note: the module name is used as prefix.
// filter = (/example-mod:event1/name='joe' and
// /example-mod:event1/status='online')
GET /mystreams/NETCONF?filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and%20%2Fexample-mod%3Aevent1%2Fstatus%3D'online')

Fields Query Parameter

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.

A value of the "fields" query parameter matches the following rule:

fields-expr = path '(' fields-expr / ')' /
  path ';' fields-expr / path
  path = api-identifier [ '/' path ]

The ";" character is used to select multiple nodes. For example, to retrieve only the "genre" and "year" of an album, use:

fields=genre;year

Parentheses are used to specify sub-selectors of a node. For example, to retrieve only the "label" and "catalog-number" of an album, use:

fields=admin(label;catalogue-number)

The "/" character is used in a path to retrieve a child node of a node. For example, to retrieve only the "label" of an album, use:

fields=admin/label

This parameter is only allowed for GET methods on api, datastore, and data resources. A 400 Bad Request error is returned if used for other methods or resource types.

If the "fields" query parameter URI is listed in the "capability" leaf-list, then the server supports the "fields" parameter.

In this example the client is retrieving the API resource, but retrieving only the "name" and "revision" nodes from each module, in JSON format:

GET /restconf/data?fields=modules-state/module(name;revision) HTTP/1.1
Host: example.com
Accept: application/yang-data+json

The server might respond as follows.

HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:01:00 GMT
Server: example-server
Content-Type: application/yang-data+json

{
  "ietf-yang-library:modules-state": {
    "module": [
      {
        "name" : "example-jukebox",
        "revision" : "2015-06-04"
      },
      {
        "name" : "ietf-inet-types",
        "revision" : "2013-07-15"
      },
      {
        "name" : "ietf-restconf-monitoring",
        "revision" : "2015-06-04"
      },
      {
        "name" : "ietf-yang-library",
        "revision" : "2015-01-30"
      },
      {
        "name" : "ietf-yang-types",
        "revision" : "2013-07-15"
      }
    ]
  }
}