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 programmatic 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.

  • 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

  • Fully recoverable, automatic database editing, using a simple 3 phase callback model

      1. validate, 2) apply, 3) commit or rollback

  • Full support for database editing and validation, including extensive user-callback capabilities to support device instrumentation.

  • Complete <error> reporting support, including user-defined errors via YANG error-app-tag and error-message statements.

  • Extended 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 Old 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.

  • Complete RFC 8525 New YANG Module Library support, including the '/yang-library' subtree and the deprecated '/modules-state' subtree.

  • 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 Client

The RESTCONF server implements the RESTCONF protocol in RFC 8040. RESTCONF communication is handled through a WEB server such as Apache HTTP Server. For HTTPS, the TLS channel is managed by the WEB server. Refer to the YumaPro Installation Guide and Setup TLS Certificates for the RESTCONF Site for TLS configuration details.

The RESTCONF client is implemented as a feature of the yangcli-pro client. Existing yangcli-pro commands are used to initiate RESTCONF operations. This feature is not available in the yangcli-basic package. It is available in all other binary packages. Source builds require the WITH_RESTCONF=1 make flag for yangcli-pro.

Example:

connect protocol=restconf

The RESTCONF client adds the following capabilities:

  • Introduces the protocol flag "restconf" to distinguish RESTCONF from NETCONF operations.

  • Handles HTTP and HTTPS communication with the RESTCONF server.

  • Translates yangcli-pro commands to HTTP requests.

  • Parses HTTP responses from the RESTCONF server.

  • Handles errors returned by RESTCONF operations.

  • Displays RESTCONF-related system information.

OpenSSL is required for secure RESTCONF client connections and must be installed on the client host.

On Ubuntu, install the libssl-dev package:

sudo apt-get install libssl-dev

A thin HTTP generator/parser layer is used over the OpenSSL connection to handle RESTCONF request and response processing.

Apache Configuration for RESTCONF Client Sessions

To use the RESTCONF client, Apache2 must be installed and configured for RESTCONF. Refer to the RESTCONF Installation section for server setup.

To keep RESTCONF sessions open longer, update the Apache site configuration for the RESTCONF service. This overrides master apache.conf values when set:

## Set if yangcli-pro is used to keep the session alive
## Note: these values will overwrite master apache.conf values
## if any.
KeepAlive on
MaxKeepAliveRequests 1000
## Set KeepAliveTimeout to big number to maintain session alive
KeepAliveTimeout 10

Apache may also close a client connection after returning an HTTP error response (4xx or 5xx). The restconf program and the netconfd-pro server run behind Apache and do not control this behavior.

For example, a request that results in an "invalid-value" error may return a "400 Bad Request" response and include a "Connection: close" header:

HTTP/1.1 400 Bad Request
Connection: close

Apache may also recycle FastCGI worker processes after a fixed number of requests. In the default restconf.conf configuration, the mod_fcgid directive "FcgidMaxRequestsPerProcess" is set to 1000. After 1000 requests, the current FastCGI process may exit and a new process will be started. This can appear as the RESTCONF session being dropped.

To change this behavior, update the RESTCONF site configuration:

<IfModule mod_fcgid.c>
    ...
    FcgidMaxRequestsPerProcess 1000
    ...
</IfModule>

Enable the RESTCONF site and restart Apache:

sudo a2ensite restconf.conf
sudo apachectl restart
sudo apachectl -S

Connecting with yangcli-pro (RESTCONF)

Use the "restconf" protocol flag in the yangcli-pro connect command:

connect server=localhost protocol=restconf user=username password=password transport=tls

Then run RESTCONF operations using standard yangcli-pro commands:

get-config

RESTCONF API Discovery

RESTCONF API discovery uses the well-known host-meta resource:

GET http://restconf-dev/.well-known/host-meta

Most browsers do not support the application/xrd+xml media type. Use a REST client tool such as Postman or curl to retrieve the response.

RESTCONF Server Status

To enable server status reporting, enable the Apache status module and set ExtendedStatus:

ExtendedStatus On

Then retrieve the server status:

GET http://restconf-dev/server-status

RESTCONF Operations and yangcli-pro Commands

The following table maps common yangcli-pro commands to RESTCONF operations.

yangcli-pro command

RESTCONF operation

Notes

create

POST

Create if and only if data does not exist

replace

PUT

Replace if data exists or create if data does not exist

merge

PATCH

Create or update but not delete

insert

POST, PUT, or PATCH

HTTP method is based on the operation parameter

delete/remove

DELETE

Delete data if it exists

sget

GET

Retrieve configuration and operational data with the content=all query parameter

get-config

POST

Invoke the <get-config> operation

any rpc operation

POST

Invoke the YANG RPC operation

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.

To receive RESTCONF notifications, subscribe to the event stream using a GET request:

curl http://restconf-dev/restconf/streams -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

Message-ID

An identifier for the RESTCONF request

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

Message-ID

The identifier for the RESTCONF request, echoed back

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 Notifications

The RESTCONF server supports event stream notifications using the IETF RESTCONF and W3C SSE standard for notification delivery.

Note

  • RESTCONF SSE is only supported for Apache2 and lighttpd

  • NGINX does not properly handle concurrent requests for FastCGI programs written in C

The ABNF for the SSE Event Stream:

stream        = [ bom ] *event
event         = *( comment / field ) end-of-line
comment       = colon *any-char end-of-line
field         = 1*name-char [ colon [ space ] *any-char ] end-of-line
end-of-line   = ( cr lf / cr / lf )

; characters
lf            = %x000A ; U+000A LINE FEED (LF)
cr            = %x000D ; U+000D CARRIAGE RETURN (CR)
space         = %x0020 ; U+0020 SPACE
colon         = %x003A ; U+003A COLON (:)
bom           = %xFEFF ; U+FEFF BYTE ORDER MARK
name-char     = %x0000-0009 / %x000B-000C / %x000E-0039 / %x003B-10FFFF
                    ; a Unicode character other than U+000A LINE FEED (LF), U+000D CARRIAGE RETURN (CR), or U+003A COLON (:)
any-char      = %x0000-0009 / %x000B-000C / %x000E-10FFFF
                ; a Unicode character other than U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR)

The following messages are sent by the RESTCONF server:

  • The field named 'data' is sent for each line in a notification message

  • An empty line is sent after the last 'data' line in a notification

  • If SSE Keepalives are enabled then the 'comment' may also be sent

Example

Command:

curl http://localhost/restconf/stream

Example output:

data:
data:  <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
data:   <eventTime>2025-06-21T20:02:10.239879Z</eventTime>
data:   <netconf-session-start xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
data:    <username>andy</username>
data:    <session-id>4</session-id>
data:    <source-host>127.0.0.1</source-host>
data:   </netconf-session-start>
data:  </notification>

data:
data:  <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
data:   <eventTime>2025-06-21T20:02:13.513806Z</eventTime>
data:   <netconf-session-end xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
data:    <username>andy</username>
data:    <session-id>4</session-id>
data:    <source-host>127.0.0.1</source-host>
data:    <termination-reason>dropped</termination-reason>
data:   </netconf-session-end>
data:  </notification>

SSE Deployment Limitations

The SSE standard is difficult to handle because it is a never-ending GET operation. The RESTCONF server uses the 'restconf' C program as a thin FastCGI client between the WEB server and the netconfd-pro process.

Refer to the RESTCONF Installation section for details on the configuration options needed to use Notifications.

Timeout Issues

Configuration parameters usually need to be set so an inactive connection is not closed, or a '504 Gateway Timeout' error occurs.

  • Apache2 has the 'IdleTimeout' setting to control this timeoui

Buffering Issues

Configuration parameters usually need to be set so the WEB server does not buffer notifications, and instead sends them right away.

Error 499: Client Closed Request

This error occurs if the client terminates the request (e.g. control-C the 'curl' request).

None of the WEB servers handle this error correctly. The 'restconf' subsystem is not notified and the session to the netconfd-pro server is not closed.

Broken Pipe Detection

Starting in 23.10-22, the 'restconf' subsystem does handle the '499' error by detecting a 'broken pipe' signal (SIGPIPE) when there is data to write to STDOUT. The WEB server will send this signal to the FastCGI program.

Due to operating system limitations, the broken pipe is not detected until the 2nd notification is written after the client closes the connection. The first notification does not trigger a broken pipe error.

The 'restconf' program will terminate the connection with the 'netconfd-pro' process when any of the following signals are received:

  • For lighttpd, the default 'kill-signal' parameter should be used (15:SIGTERM)

Signal

Number

Description

SIGHUP

1

Hangup

SIGINT

2

Interrupt

SIGUSR1

10

User1

SIGPIPE

13

Broken pipe

SIGTERM

15

Terminated

Concurrent Requests

Only the Apache2 and lighttpd servers supports multiple concurrent requests to the same netconfd-pro server (i.e. '/restconf' Location).

The NGINX server is used with the 'fastcgi-wrapper' module which does not support multiple concurrent requests to the same backend FastCGI script. Since it waiting for the SSE request to finish, no other requests get through or get processed.

A future release may support the 'php-fpm' module which does provide this support, but it only supports FastCGI programs written in PHP. The 'restconf' program would need to be rewritten in PHP first.

SSE Keepalives

Starting in 23.10-22, the 'restconf' subsystem can send periodic keep-alive messages to the client:

  • prevent dropped connections due to timeouts

  • mitigate buffering delays

  • detect broken pipe errors even if the server is idle

The following comment is sent the client if the timeout occurs:

:SSE keepalive

SSE_KEEPALIVE Parameter

The 'SSE_KEEPALIVE' fastcgi_param configuration is needed to enable the keepalive messages. This allows the FastCGI program to detect a broken pipe to 'STDOUT' (e.g., because the client has terminated the connection).

It takes at least 2 keepalives (or notifications from the server) before the FastCLI handler will send a 'SIGPIPE' signal to the 'restconf' program. E.g., if the keepalive is sent every 30 seconds then it will take at least 60 seconds for the connection to be properly terminated.

Apache2 Example:

## RESTCONF SSE keepalive timeout in seconds
## type uint16 { range "0 | 5..3600"; }
## Server sends SSE comment ':SSE keepalive' at timeout
## Not needed on Apache; Needed on NGINX and lightty
## 0 = do not use (default)
## suggest 30 - 120 (must be less than fastcgi_read_timeout)
SetEnv SSE_KEEPALIVE "30"

NGINX Example:

### RESTCONF SSE keepalive timeout in seconds
### type uint16 { range "0 | 5..3600"; }
### Server sends SSE comment ':SSE keepalive' at timeout
### Not needed on Apache; Needed on NGINX and lightty
### 0 = do not use (default)
### suggest 30 - 120 (must be less than fastcgi_read_timeout
fastcgi_param          SSE_KEEPALIVE 30;

lighttpd Example:

fastcgi.server += (
  "/restconf" =>
   (( "host" => "0.0.0.0",
      "port" => 1026,
      "bin-path" => "/usr/sbin/restconf",
      "check-local" => "disable",
      "bin-environment" => (
         "SSE_KEEPALIVE" => "30"
      ),
      "idle-timeout" => 3600,
      "max-procs" => 16
   ))
)

The YANG definition for this parameter:

leaf SSE_KEEPALIVE {
   type uint16 {
     range "0 | 5 .. 3600";
   }
   default 0;
   units seconds;
   description
     "The number of seconds to be idle before sending an 'SSE keepalive'
      message to the client. The value '0' indicates no SSE keepalive
      will be sent.";
}

The keepalive comment is sent if the program is idle for the timeout interval. If any input is received from the netconfd-pro server then the idle timer starts over.

If the netconfd-pro server is idle for a long period of time, then it will require 2 - 3 timeout intervals to expire before a broken pipe will be detected and the session is properly terminated.

RESTCONF Subscriptions

The RESTCONF server fully supports RFC 8650, allowing RESTCONF clients to subscribe to any event stream or datastore, using the full features available in NETCONF.

Features:

  • RESTCONF Subscriptions support YANG Push

  • RESTCONF Subscriptions support full parameters for Event Streams

  • Uses the same SSE delivery mechanism defined in RESTCONF Notifications

  • Supports XML or JSON encoding (CBOR not allowed in SSE)

  • First release: 25.10-2

Differences From NETCONF:

  • 'uri' leaf returned in the 'rpc-reply' response the <establish-subscription>

  • notification delivery does not start right away

  • A separate GET request is required to start notification delivery

  • A RESTCONF session can only receive events for one subscription. NETCONF allows unlimited subscriptions on the same session.

  • YumaPro NETCONF and Binary Push support CBOR encoding. RFC 8650 uses SSE which only supports text encoding

  • Replay subscriptions (e.g. using 'replay-start-time' parameter) are not supported for RESTCONF subscriptions

RESTCONF Subscription Usage

The dynamic subscriptions are the same as for NETCONF except the session starting the subscription is not session that receives the notifications.

  • The <establish-subscription> operation to setup the subscription in advance, using the same parameters available in NETCONF.

  • A URI for the subscription is returned to the client in the 'rpc-reply'. This leaf is only returned for the RESTCONF protocol. It is not used in NETCONF subscriptions.

    leaf uri {
  type inet:uri;
  config false;
  description
    "Location of a subscription-specific URI on the publisher.";
}

  • The RESTCONF client does a GET on this URI to start the subscription

Example: Subscribe to 'NETCONF' stream

RFC 8040 subscription:

curl http://localhost/restconf/streams/json-NETCONF

RFC 8650 subscription:

There is a 2 step procedure defined in RFC 8650.

Step 1: POST

  • JSON File 'post1.json' contains the input parameters:

{
   "ietf-subscribed-notifications:input": {
      "stream": "NETCONF",
      "encoding": "encode-json"
   }
}

  • curl command example

curl -X POST -H "Content-Type: application/yang-data+json" -d @post1.json \
http://localhost/restconf/operations/ietf-subscribed-notifications:establish-subscription

Check the <establish-subscription> response

HTTP/1.1 200 OK
Content-Type: application/json
Status: 200 OK
Cache-Control: no-cache
Pragma: no-cache

{
 "ietf-subscribed-notifications:output": {
  "id":1,
  "ietf-restconf-subscribed-notifications:uri":"http://localhost/restconf/subscriptions/1",
  "ietf-distributed-notif:message-publisher-ids": [
   1
  ]
 }
}

Step 2: GET using the returned 'uri' to start receiving events

curl http://localhost/restconf/subscriptions/1

data: {
data:  "ietf-restconf:notification": {
data:   "eventTime":"2025-10-31T20:41:12.273967Z",
data:   "ietf-netconf-notifications:netconf-session-start": {
data:    "username":"andy",
data:    "session-id":9,
data:    "source-host":"127.0.0.1"
data:   }
data:  }
data: }

RESTCONF YANG Push Examples

This example shows an on-change subscription to all /interfaces-state/interface entries:

  • JSON File 'post2.json' contains the input parameters:

{
   "ietf-subscribed-notifications:input": {
       "ietf-yang-push:datastore": "operational",
       "ietf-yang-push:datastore-xpath-filter": "/interfaces-state/interface",
       "ietf-yang-push:on-change": {
           "dampening-period": 500
       },
       "encoding": "encode-json"
   }
}

  • curl command example

curl -X POST -H "Content-Type: application/yang-data+json" -d @post2.json \
http://localhost/restconf/operations/ietf-subscribed-notifications:establish-subscription

Check the <establish-subscription> response

HTTP/1.1 200 OK
Content-Type: application/json
Status: 200 OK
Cache-Control: no-cache
Pragma: no-cache

{
 "ietf-subscribed-notifications:output": {
  "id":2,
  "ietf-restconf-subscribed-notifications:uri":"http://localhost/restconf/subscriptions/2",
  "ietf-distributed-notif:message-publisher-ids": [
   1
  ]
 }
}

Example GET session receiving a <push-update> Event:

curl http://localhost/restconf/subscriptions/2


data: {
data:  "ietf-restconf:notification": {
data:   "eventTime":"2025-10-31T20:54:59.998953Z",
data:   "ietf-yang-push:push-update": {
data:    "id":2,
data:    "ietf-distributed-notif:message-publisher-id":1,
data:    "datastore-contents": {
data:      "ietf-interfaces:interfaces-state": {
data:        "ietf-interfaces:interface": [
data:         {
data:          "name":"lo",
data:          "type":"iana-if-type:softwareLoopback",
data:          "oper-status":"up",
data:          "phys-address":"00:00:00:00:00:00",
data:          "speed":"0",
data:          "statistics": {
data:           "in-octets":"20732554",
data:           "in-unicast-pkts":"75896",
data:           "in-multicast-pkts":"0",
data:           "in-discards":0,
data:           "in-errors":0,
data:           "out-octets":"20732554",
data:           "out-unicast-pkts":"75896",
data:           "out-discards":0,
data:           "out-errors":0
data:          }
data:         },
data:         {
data:          "name":"eno1",
data:          "type":"iana-if-type:ethernetCsmacd",
data:          "oper-status":"up",
data:          "phys-address":"88:ae:dd:55:16:11",
data:          "speed":"1000000000",
data:          "statistics": {
data:           "in-octets":"2817777357",
data:           "in-unicast-pkts":"2195109",
data:           "in-multicast-pkts":"38199",
data:           "in-discards":109,
data:           "in-errors":0,
data:           "out-octets":"171954971",
data:           "out-unicast-pkts":"763201",
data:           "out-discards":0,
data:           "out-errors":0
data:          }
data:         },
data:         {
data:          "name":"wlxe0ad47008a71",
data:          "type":"iana-if-type:ethernetCsmacd",
data:          "oper-status":"down",
data:          "phys-address":"e0:ad:47:00:8a:71",
data:          "speed":"0",
data:          "statistics": {
data:           "in-octets":"0",
data:           "in-unicast-pkts":"0",
data:           "in-multicast-pkts":"0",
data:           "in-discards":0,
data:           "in-errors":0,
data:           "out-octets":"0",
data:           "out-unicast-pkts":"0",
data:           "out-discards":0,
data:           "out-errors":0
data:          }
data:         }
data:        ]
data:      }
data:    }
data:   }
data:  }
data: }

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

Using RPC Operations in RESTCONF

The 'operation' resource defined in RFC 8040 Section 3.6 is used to invoke YANG 'rpc' operations. These are often called 'NETCONF operations' but any protocol can support the YANG 'rpc' statement, including RESTCONF.

The RESTCONF POST method is used to send the operation and the parameters.

All YANG "rpc" statements are available as RESTCONF operation resources, including the NETCONF operations.

Locking Note

Each RESTCONF request is treated as a separate session. A <lock> operation is honored, but the lock is released immediately when the request completes, because the session terminates at the end of the request.

Operation Resource Form

POST /restconf/operations/<operation-name> HTTP/1.1
Host: <hostname>
Content-Type: <media-type>

{input parameters}

Example RESTCONF NETCONF Operation (JSON)

POST /restconf/operations/ietf-netconf:delete-config HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json

{ "ietf-netconf:input" : {
    "target" : {
      "startup" : [null]
    }
  }
}

Example NETCONF RPC Request

A <get-bulk> operation request is shown here:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="6"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <get-bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
  <list-target>/interfaces-state/interface</list-target>
  <last-keys>
   <name xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">lo</name>
  </last-keys>
 </get-bulk>
</rpc>

Converting the RPC Request to RESTCONF Input Data

  • The 'rpc' element is removed

  • The method element (e.g., 'get-bulk') is changed to 'input'

  • The namespace and contents of this element are not changed

<?xml version="1.0" encoding="UTF-8"?>
<input xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
 <list-target>/interfaces-state/interface</list-target>
 <last-keys>
  <name xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">lo</name>
 </last-keys>
</input>

Example RESTCONF RPC Request Using curl

  • The 'input' parameters are saved in a file (e.g. 'walk1.xml')

  • The proper 'Content-Type is shown although 'text/xml' will also be accepted

curl -H "Content-Type: application/yang-data+xml" --data @walk1.xml localhost/restconf/operations/yumaworks-getbulk:get-bulk

The server might respond as follows:

<?xml version="1.0" encoding="UTF-8"?>
<output xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
 <bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
  <data
   xmlns:ya="http://yumaworks.com/ns/yumaworks-attrs"
   ya:datapath="/if:interfaces-state">
   <interface xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
    <name>eno1</name>
    <type
     xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
    <oper-status>up</oper-status>
    <phys-address>3c:7c:3f:1d:83:aa</phys-address>
    <speed>1000000000</speed>
    <statistics>
     <in-octets>17518208743</in-octets>
     <in-unicast-pkts>11751776</in-unicast-pkts>
     <in-multicast-pkts>22247119</in-multicast-pkts>
     <in-discards>48</in-discards>
     <in-errors>0</in-errors>
     <out-octets>7948948114</out-octets>
     <out-unicast-pkts>7053021</out-unicast-pkts>
     <out-discards>0</out-discards>
     <out-errors>0</out-errors>
    </statistics>
   </interface>
  </data>
  <last-keys xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
   <name xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">eno1</name>
  </last-keys>
 </bulk>
</output>

Using JSON With RESTCONF Operations

Some NETCONF operations support multiple encoding formats. If JSON is not supported then an 'operation-not-supported' error-tag will be returned.

  • The input parameters (if any) must be encoded in JSON in order for the output to be sent in JSON.

  • An Accept header is not required if a Content-Type header is sent

  • The default encoding in the server for RESTCONF is JSON so if no 'Content-Type' or 'Accept' header is provided then JSON will be used.

Example input parameters encoded in JSON:

{
    "yumaworks-getbulk:input": {
        "list-target" : "/interfaces-state/interface",
        "last-keys" : {
            "ietf-interfaces:name" : "lo"
        }
    }
}

  • The 'input' parameters are saved in a file (e.g. 'walk1.json').

  • The proper 'Content-Type is shown although 'text/json' will also be accepted

  • The YANG module name is shown (e.g. 'yumaworks-getbulk') as specified in the standard. The server will accept the target-resource without the module name part, if there is only one match for the RPC operation name.

curl -H "Content-Type: application/yang-data+json" --data @walk1.json localhost/restconf/operations/yumaworks-getbulk:get-bulk

The server might respond as follows:

{
 "ietf-restconf:output": {
  "yumaworks-getbulk:bulk": {
   "data": {
    "ietf-interfaces:interface": [
     {
      "name":"eno1",
      "type":"iana-if-type:ethernetCsmacd",
      "oper-status":"up",
      "phys-address":"3c:7c:3f:1d:83:aa",
      "speed":"1000000000",
      "statistics": {
       "in-octets":"17532536554",
       "in-unicast-pkts":"11768418",
       "in-multicast-pkts":"22267277",
       "in-discards":48,
       "in-errors":0,
       "out-octets":"7952234284",
       "out-unicast-pkts":"7063603",
       "out-discards":0,
       "out-errors":0
      }
     }
    ]
   },
   "last-keys": {
    "name":"eno1"
   }
  }
 }
}

Using CURL POST Without Input Parameters

If the RPC operation does not have any input parameters then the 'data' parameter for curl must not be used. The -H parameter should be used instead.

curl -X POST localhost/restconf/operations/ietf-netconf:get

Example using JSON encoding:

curl -X POST localhost/restconf/operations/yuma-mysession:get-my-session

The server may respond:

{
 "yuma-mysession:output": {
  "indent":"2",
  "linesize":"72",
  "with-defaults":"explicit",
  "message-indent":"1"
 }
}

Example Error if JSON Not Supported

In this example the NETCONF <get> operation is invoked but the server does not support JSON output for this operation

curl -X POST localhost/restconf/operations/ietf-netconf:get

The server might respond:

{
 "ietf-restconf:errors": {
  "error": [
   {
    "error-type":"rpc",
    "error-tag":"operation-failed",
    "error-app-tag":"general-error",
    "error-message":"JSON encoding not yet supported",
    "error-info": {
     "error-number":412
    }
   }
  ]
 }
}

Confirmed Commit with RESTCONF

The confirmed commit procedure in NETCONF allows an edit transaction to be automatically rolled back unless confirmed within a specific time period. This is useful for applying edits across multiple devices, where a rollback is needed if any device fails.

RESTCONF does not define confirmed commit, but netconfd-pro supports it using query parameters on data resource edits. For more details on the NETCONF confirmed commit capability, see :confirmed-commit.

Confirmed Commit (Start)

Use the following query parameters on POST, PUT, PATCH, or DELETE:

  • confirmed=1: required to initiate the confirmed commit procedure

  • confirm-timeout=N: optional; number of seconds before rollback (default 300)

  • persist=string: required; token used to confirm or cancel

POST /restconf/data?confirmed=1&confirm-timeout=30&persist=abcde HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json

{ "test:uint8.1" : 42 }

Confirming Commit

The confirming commit invokes the NETCONF <commit> operation as a RESTCONF operation resource. Do not include the "confirmed" parameter or the server will treat it as another confirmed commit.

The persist-id parameter must match the persist token from the confirmed commit request.

POST /restconf/operations/ietf-netconf:commit HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json

{ "input" : {
    "persist-id" : "abcde"
  }
}

Canceling a Confirmed Commit

If the confirmed commit is not confirmed before the timeout, it is rolled back automatically. A confirmed commit can also be canceled explicitly:

POST /restconf/operations/ietf-netconf:cancel-commit HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json

{ "input" : {
    "persist-id" : "abcde"
  }
}

Using YANG Actions in RESTCONF

The YANG 'action' is handled a little differently than an RPC operation.

The RESTCONF POST method is used to send the action request and the parameters.

  • The action node is specified like a data resource in RESTCONF

    • /restconf/operations/rpc-name

    • /restconf/data/data-nodes/action-name

Example YANG Module

list list1 {
   key idx;
   leaf idx { type uint8; }
   action reset {
     input {
       leaf full-reset {
         type boolean;
         default false;
       }
     }
   }
}

Example NETCONF YANG action Request

A NETCONF action request may be sent as follows:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="3"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <action xmlns="urn:ietf:params:xml:ns:yang:1">
  <list1 xmlns="urn:yumaworks:params:xml:ns:yang:action1">
   <idx>11</idx>
   <reset>
    <full-reset>true</full-reset>
   </reset>
  </list1>
 </action>
</rpc>

Converting the NETCONF Action Request for RESTCONF

  • The 'rpc' node is removed

  • The ancestor data nodes are removed and encoded in the target resource instead.

  • The namespace declaration is moved to the 'reset' node.

  • The 'reset' node name is changed to 'input'

<?xml version="1.0" encoding="UTF-8"?>
<input xmlns="urn:yumaworks:params:xml:ns:yang:action1">
  <full-reset>true</full-reset>
</input>

Example RESTCONF Action Request Using curl

  • The 'input' parameters are saved in a file (e.g. 'reset1.xml')

  • The proper 'Content-Type is shown although 'text/xml' will also be accepted

curl -H "Content-Type: application/yang-data+xml" --data @reset1.xml localhost/restconf/data/action1:list1=11/reset

The curl program simply returns because the server does not return any data. It returns '204 No Content' in this case.

Status: 204 No Content
Cache-Control: no-cache
Pragma: no-cache

RESTCONF Curl Examples

This section outlines how to use 'curl' to perform RESTCONF operations. The examples in this section include GET, POST, PUT, PATCH, and DELETE requests, as well as RESTCONF notifications and TLS transport.

The data can be requested or submitted in either XML or JSON formats.

GET Request

To retrieve data from a RESTCONF server, send a GET request. The following 'curl' command requests data in XML format:

curl http://restconf-dev/restconf/data/restconf-state/capabilities \
  -H "Accept:application/yang-data+xml"

Response (XML format):

<?xml version="1.0" encoding="UTF-8"?>
<capabilities xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
  <capability>urn:ietf:params:restconf:capability:depth:1.0</capability>
  <capability>urn:ietf:params:restconf:capability:with-defaults:1.0</capability>
  <capability>urn:ietf:params:restconf:capability:defaults:1.0?basic-mode=explicit</capability>
  <capability>urn:ietf:params:restconf:capability:fields:1.0</capability>
  <capability>urn:ietf:params:restconf:capability:replay:1.0</capability>
  <capability>urn:ietf:params:restconf:capability:filter:1.0</capability>
  <capability>urn:ietf:params:restconf:capability:yang-patch:1.0</capability>
</capabilities>

Retrieving Data in JSON Format

To retrieve data in JSON format, use the Accept header with the value application/yang-data+json:

curl http://restconf-dev/restconf/data/restconf-state/capabilities \
  -H "Accept:application/yang-data+json"

Response (JSON format):

{
  "capabilities": {
    "capability": [
      "urn:ietf:params:restconf:capability:depth:1.0",
      "urn:ietf:params:restconf:capability:with-defaults:1.0",
      "urn:ietf:params:restconf:capability:defaults:1.0?basic-mode=explicit",
      "urn:ietf:params:restconf:capability:fields:1.0",
      "urn:ietf:params:restconf:capability:replay:1.0",
      "urn:ietf:params:restconf:capability:filter:1.0",
      "urn:ietf:params:restconf:capability:yang-patch:1.0"
    ]
  }
}

NETCONF Equivalent Command

RESTCONF request demonstrated in the previous sections have an equivalent operation in NETCONF. The operation can be executed using yangcli-pro as follows:

sget /restconf-state/capabilities

This command will produce the following RPC request to the server:

<rpc message-id="3"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <get>
  <filter type="subtree">
   <restconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
    <capabilities/>
   </restconf-state>
  </filter>
 </get>
</rpc>

GET Request with Query Parameters

The RESTCONF supports query parameters, such as Depth Query Parameter, to control the level of detail in the data. For example, the following command retrieves data with a depth of 1:

curl http://restconf-dev/restconf/data/restconf-state/capabilities?depth=1

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<capabilities xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"/>

NETCONF Equivalent Command

RESTCONF request demonstrated in the previous sections have an equivalent operation in NETCONF. The operation can be executed using yangcli-pro as follows:

sget /restconf-state/capabilities depth=1

This command will produce the following RPC request to the server:

<rpc message-id="4" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <get>
  <depth xmlns="http://yumaworks.com/ns/yumaworks-system">1</depth>
  <filter type="subtree">
   <restconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
    <capabilities/>
   </restconf-state>
  </filter>
 </get>
</rpc>

GET Request Using TLS Transport

To secure communication with the RESTCONF server using TLS, use the following 'curl' command, providing the client certificate, key, and CA certificate:

curl --cert /ssl/client.crt:password \
  --key /ssl/clients.key \
  --cacert /ssl/ca.crt \
  https://restconf-dev/restconf/yang-library-version

Response:

{
 "yang-library-version":"2016-06-21"
}

GET Request to Subscribe to RESTCONF Notifications

To receive event-based notifications from the RESTCONF server, subscribe to an event stream using a GET request:

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

Response (Notification Data):

data:
data:   <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
data:     <eventTime>2016-04-21T21:04:51Z</eventTime>
data:     <netconf-config-change xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
data:       <changed-by>
data:         <username>yumaworks</username>
data:         <session-id>4</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>create</operation>
data:       </edit>
data:     </netconf-config-change>
data:   </notification>

POST Requests

To send data to a RESTCONF server, such as creating a new entry, a POST request can be used. The following command creates a new leaf "leaf1":

curl -i \
  -H "Accept:application/yang-data+json" \
  -H "Content-Type:application/json" \
  -X POST -d '{"leaf1":16}' \
  http://restconf-dev/restconf/data

Example response headers:

HTTP/1.1 201 Created
Date: Thu, 21 Apr 2016 21:22:23 GMT
Server: Apache/2.4.7 (Ubuntu)
Cache-Control: no-cache
Pragma: no-cache
Location: http://restconf-dev/restconf/data/uint16.1
Last-Modified: Thu, 21 Apr 2016 21:22:24 GMT
ETag: 57472
Content-Length: 0

NETCONF Equivalent Command

RESTCONF request demonstrated in the previous sections have an equivalent operation in NETCONF. The operation can be executed using yangcli-pro as follows:

create /leaf1 value=16

This command will produce the following RPC request to the server:

<rpc message-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <edit-config>
  <target>
   <candidate/>
  </target>
  <default-operation>merge</default-operation>
  <test-option>set</test-option>
  <config>
   <leaf1 xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
    nc:operation="create"
    xmlns="http://netconfcentral.org/ns/test">16</leaf1>
  </config>
 </edit-config>
</rpc>

Editing with JSON or XML Encoding

The Content-Type header must match the encoding used for edits.

JSON Example (POST)

To create a new "artist" resource within the "library" resource, send a JSON encoded request:

POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json

{
  "example-jukebox:artist": {
    "name": "Foo Fighters"
  }
}

XML Example (PATCH)

To modify multiple data nodes in one request, send a PATCH to the datastore resource using XML encoding:

PATCH /restconf/data HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml

<data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
  <jukebox xmlns="http://example.com/ns/example-jukebox">
    <library>
      <artist>
        <name>Foo Fighters</name>
        <album>
          <name>Wasting Light</name>
          <year>2011</year>
        </album>
      </artist>
      <artist>
        <name>Nick Cave</name>
        <album>
          <name>Tender Prey</name>
          <year>1988</year>
        </album>
      </artist>
    </library>
  </jukebox>
</data>

PUT Requests

To create or update data using the PUT method, the following command can be used.

This example sends the contents of input.json to create an entry:

curl -vX PUT -d @$HOME/input.json \
  -H "Content-Type:application/yang-data+json" \
  http://restconf-dev/restconf/data/ietf-interfaces:interfaces/interface=test2

Where input.json contains:

{
    "interface": [
        {
            "name": "test1",
            "type": "iana-if-type:l2vlan"
        }
    ]
}

NETCONF Equivalent Command

RESTCONF request demonstrated in the previous sections have an equivalent operation in NETCONF. The operation can be executed using yangcli-pro as follows:

merge /interfaces/interface[name='test1']/type value=iana-if-type:l2vlan

This command will produce the following RPC request to the server:

<rpc message-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <edit-config>
  <target>
   <candidate/>
  </target>
  <default-operation>merge</default-operation>
  <test-option>set</test-option>
  <config>
   <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
    <interface>
     <name>test1</name>
     <type xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
      nc:operation="merge"
      xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:l2vlan</type>
    </interface>
   </interfaces>
  </config>
 </edit-config>
</rpc>

PUT on the Datastore Resource

The PUT method is supported for data and datastore resources. A PUT on the datastore resource replaces the entire contents of the datastore. Any child nodes not present in the request but present in the server datastore are deleted.

Warning

This operation replaces the WHOLE contents of the datastore. Any existing data not present in the request is removed.

Example: Replace the entire datastore contents using XML encoding:

PUT /restconf/data HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml

<data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
  <jukebox xmlns="http://example.com/ns/example-jukebox">
    <library>
      <artist>
        <name>Foo Fighters</name>
        <album>
          <name>One by One</name>
          <year>2012</year>
        </album>
      </artist>
      <artist>
        <name>Nick Cave and the Bad Seeds</name>
        <album>
          <name>Tender Prey</name>
          <year>1988</year>
        </album>
      </artist>
    </library>
  </jukebox>
</data>

Example: Remove all configuration data by replacing the datastore with an empty <data> container:

PUT /restconf/data HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml

<data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
</data>

PATCH Requests

Similarly, to modify an existing entry using the PATCH method, use the following command:

curl -vX PATCH -d @$HOME/mode.json \
  -H "Content-Type:application/yang-data+json" \
  http://localhost/restconf/data/ietf-interfaces:interfaces

Where mode.json contains:

{
    "interfaces" : {
        "interface": [
            {
                "name": "test1",
                "type": "iana-if-type:other"
            }
        ]
    }
}

NETCONF Equivalent Command

RESTCONF request demonstrated in the previous sections have an equivalent operation in NETCONF. The operation can be executed using yangcli-pro as follows:

merge /interfaces/interface[name='test1']/type value=iana-if-type:other

This command will produce the following RPC request to the server:

<rpc message-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <edit-config>
  <target>
   <candidate/>
  </target>
  <default-operation>merge</default-operation>
  <test-option>set</test-option>
  <config>
   <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
    <interface>
     <name>test1</name>
     <type xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
      nc:operation="merge"
      xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:other</type>
    </interface>
   </interfaces>
  </config>
 </edit-config>
</rpc>

YANG Patch

YANG Patch (RFC 8072) provides an ordered edit list, giving RESTCONF clients more precise control than a plain PATCH or POST.

Compared to the plain PATCH mechanism in RFC 8040, YANG Patch adds:

  • Multiple sub-resources in a single PATCH request

  • A more precise set of edit operations

  • An ordered edit list with explicit processing order and clearer error handling

YANG Patch is invoked with a PATCH Requests using one of the following media types, and the message-body is required:

  • application/yang-patch+xml

  • application/yang-patch+json

The message-body representing the YANG Patch input parameters MUST be present.

The server returns the "Accept-Patch" header in an OPTIONS response to advertise YANG Patch formats:

Accept-Patch: application/yang-patch+xml,application/yang-patch+json

YANG Patch can only edit data resources. The PATCH method cannot be used to replace the datastore resource. The YANG Patch "patch-id" is included in audit records and can help with debugging. YANG Patch can be encoded in XML or JSON and can be used with content defined in YANG 1.0 or YANG 1.1.

Each edit specifies one edit operation on the target data node. The set of operations aligns with NETCONF edit operations and adds insert and move.

YANG Patch Edit Operations

Operation

Description

create

Create a new data resource if it does not exist; otherwise error

delete

Delete a data resource if it exists; otherwise error

insert

Insert a new user-ordered data resource

merge

Merge the edit value; create if it does not exist

move

Reorder the target data resource

replace

Replace the target data resource with the edit value

remove

Remove a data resource if it exists

YANG Patch Examples

Add Resources (Success)

The following example adds two songs to an existing album. Both edits succeed and new sub-resources are created.

Request:

PATCH /restconf/data/example-jukebox:jukebox/library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
Accept: application/yang-data+json
Content-Type: application/yang-patch+json

{
  "ietf-yang-patch:yang-patch": {
    "patch-id": "add-songs-patch-2",
    "edit": [
      {
        "edit-id": "edit1",
        "operation": "create",
        "target": "/song=Rope",
        "value": {
          "song": [
            {
              "name": "Rope",
              "location": "/media/rope.mp3",
              "format": "MP3",
              "length": 259
            }
          ]
        }
      },
      {
        "edit-id": "edit2",
        "operation": "create",
        "target": "/song=Dear%20Rosemary",
        "value": {
          "song": [
            {
              "name": "Dear Rosemary",
              "location": "/media/dear_rosemary.mp3",
              "format": "MP3",
              "length": 269
            }
          ]
        }
      }
    ]
  }
}

Response:

HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json

{
  "ietf-yang-patch:yang-patch-status": {
    "patch-id": "add-songs-patch-2",
    "ok": [null]
  }
}

Add Resources (Error)

In this example, the first song already exists. The server returns an error for that edit and does not attempt the remaining edits.

Request:

PATCH /restconf/data/example-jukebox:jukebox/library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
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-songs-patch</patch-id>
  <edit>
    <edit-id>edit1</edit-id>
    <operation>create</operation>
    <target>/song=Bridge%20Burning</target>
    <value>
      <song xmlns="http://example.com/ns/example-jukebox">
        <name>Bridge Burning</name>
        <location>/media/bridge_burning.mp3</location>
        <format>MP3</format>
        <length>288</length>
      </song>
    </value>
  </edit>
  <edit>
    <edit-id>edit2</edit-id>
    <operation>create</operation>
    <target>/song=Rope</target>
    <value>
      <song xmlns="http://example.com/ns/example-jukebox">
        <name>Rope</name>
        <location>/media/rope.mp3</location>
        <format>MP3</format>
        <length>259</length>
      </song>
    </value>
  </edit>
  <edit>
    <edit-id>edit3</edit-id>
    <operation>create</operation>
    <target>/song=Dear%20Rosemary</target>
    <value>
      <song xmlns="http://example.com/ns/example-jukebox">
        <name>Dear Rosemary</name>
        <location>/media/dear_rosemary.mp3</location>
        <format>MP3</format>
        <length>269</length>
      </song>
    </value>
  </edit>
</yang-patch>

Response:

HTTP/1.1 409 Conflict
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+xml

<yang-patch-status xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
  <patch-id>add-songs-patch</patch-id>
  <edit-status>
    <edit>
      <edit-id>edit1</edit-id>
      <errors>
        <error>
          <error-type>application</error-type>
          <error-tag>data-exists</error-tag>
          <error-path xmlns:jb="http://example.com/ns/example-jukebox">
            /jb:jukebox/jb:library
            /jb:artist[jb:name='Foo Fighters']
            /jb:album[jb:name='Wasting Light']
            /jb:song[jb:name='Bridge Burning']
          </error-path>
          <error-message>
            Data already exists; cannot be created
          </error-message>
        </error>
      </errors>
    </edit>
  </edit-status>
</yang-patch-status>

DELETE Requests

To delete data using the DELETE method, the following command can be used.

curl -i \
  -H "Accept:application/yang-data+json" \
  -H "Content-Type:application/json" \
  -X DELETE \
  http://restconf-dev/restconf/data/ietf-interfaces:interfaces

Example response headers:

HTTP/1.1 204 No Content

NETCONF Equivalent Command

RESTCONF request demonstrated in the previous sections have an equivalent operation in NETCONF. The operation can be executed using yangcli-pro as follows:

delete /interfaces

This command will produce the following RPC request to the server:

<rpc message-id="7" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <edit-config>
  <target>
   <candidate/>
  </target>
  <default-operation>merge</default-operation>
  <test-option>set</test-option>
  <config>
   <interfaces
    xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
    nc:operation="delete"
    xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"/>
  </config>
 </edit-config>
</rpc>