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
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 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"
}
]
}
}