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

  • 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 uint16 {
       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"
      }
    ]
  }
}