RESTCONF Protocol

This chapter describes how to configure the HTTP-based Representational State Transfer Configuration
Protocol (RESTCONF). RESTCONF provides a programmatic interface based on standard mechanisms for
accessing configuration data, state data, data-model-specific Remote Procedure Call (RPC) operations and
events, defined in the YANG model.
• Prerequisites for the RESTCONF Protocol, on page 1
• Restrictions for the RESTCONF Protocol, on page 1
• Information About RESTCONF Programmable Interface, on page 2
• How to Configure RESTCONF Programmable Interface, on page 4
• Configuration Examples for RESTCONF Programmable Interface, on page 9
• Additional References for the RESTCONF Protocol, on page 12
• Feature Information for the RESTCONF Protocol, on page 13

Prerequisites for the RESTCONF Protocol

• Enable the Cisco IOS-HTTP services for RESTCONF. For more information, see Examples for
RESTCONF RPCs

Restrictions for the RESTCONF Protocol

The following restrictions apply to the RESTCONF protocol:
• Notifications and event streams
• YANG patch
• Optional query parameters, such as, filter, start-time, stop-time, replay, and action
• The RESTCONF feature is not supported on a device running dual IOSd configuration or software
redundancy.

RESTCONF Protocol
1
 RESTCONF Protocol
Information About RESTCONF Programmable Interface

Information About RESTCONF Programmable Interface

Overview of RESTCONF
This section describes the protocols and modelling languages that enable a programmatic way of writing
configurations to a network device.
• RESTCONF—Uses structured data (XML or JSON) and YANG to provide a REST-like APIs, enabling
you to programmatically access different network devices. RESTCONF APIs use HTTPs methods.
• YANG—A data modelling language that is used to model configuration and operational features . YANG
determines the scope and the kind of functions that can be performed by NETCONF and RESTCONF
APIs.

In releases prior to Cisco IOS XE Fuji 16.8.1, an operational data manager (based on polling) was enabled
separately. In Cisco IOS XE Fuji 16.8.1 and later releases, operational data works on platforms running
NETCONF (similar to how configuration data works), and is enabled by default. For more information on
the components that are enabled for operational data queries or streaming, see the GitHub respository, and
view *-oper in the naming convention.

HTTPs Methods
The HTTPS-based RESTCONF protocol (RFC 8040), is a stateless protocol that uses secure HTTP methods
to provide CREATE, READ, UPDATE, and DELETE (CRUD) operations on a conceptual datastore containing
YANG-defined data, which is compatible with a server that implements NETCONF datastores.
The following table shows how the RESTCONF operations relate to NETCONF protocol operations:

OPTIONS SUPPORTED METHODS

GET Read

PATCH Update

PUT Create or Replace

POST Create or Operations (reload, default)

DELETE Deletes the targeted resource

HEAD Header metadata (no response body)

RESTCONF Root Resource

• A RESTCONF device determines the root of the RESTCONF API through the link element:
/.well-known/host-meta resource that contains the RESTCONF attribute.
• A RESTCONF device uses the RESTCONF API root resource as the initial part of the path in the request
URI.

RESTCONF Protocol
2
 RESTCONF Protocol
RESTCONF API Resource

Example:
Example returning /restconf:

The client might send the following:

GET /.well-known/host-meta HTTP/1.1

Host: [Link]
Accept: application/xrd+xml

The server might respond as follows:

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

<XRD xmlns='[Link]
<Link rel='restconf' href='/restconf'/>
</XRD>

Example of URIs:
• GigabitEthernet0/0/2 -
[Link]
• fields=name –
[Link]
• depth=1 -
[Link]
• Name and IP -
[Link]
• MTU (fields) -
[Link]
• MTU -
[Link]
• Port-Channel -
[Link]
• “Char” to “Hex” conversion chart: [Link]

RESTCONF API Resource

The API resource is the top-level resource located at +restconf. It supports the following media types:

Note Media is the type of YANG formated RPC that is sent to the RESCONF server (XML or JSON).

• Application/YANG-Data+XML OR Application/YANG-Data+JSON
• The API resource contains the RESTCONF root resource for the RESTCONF DATASTORE and
OPERATION resources. For example:

RESTCONF Protocol
3
 RESTCONF Protocol
Methods

The client may then retrieve the top-level API resource, using the
root resource "/restconf".

GET /restconf HTTP/1.1

Host: [Link]
Accept: application/yang-data+json

The server might respond as follows:

HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 [Link] GMT
Server: example-server
Content-Type: application/yang-data+json

{
"ietf-restconf:restconf" : {
"data" : {},
"operations" : {},
"yang-library-version" : "2016-06-21"
}
}

For more information, refer to RFC 3986

Methods
Methods are HTTPS operations (GET/PATCH/POST/DELETE/OPTIONS/PUT) performed on a target
resource. A YANG-formated RPC invokes a particular method on a given resource that pertains to a target
YANG model residing in the RESTCONF server. The uniform resource identifier (URI) acts as a location
identification for a given resource, so that the client RESTCONF method can locate that particular resource
to take an action specified by an HTTPS method or property.
For more information, see RFC 8040 - RESTCONF Protocol

How to Configure RESTCONF Programmable Interface

Authentication of NETCONF/RESTCONF Using AAA
Before you begin
NETCONF and RESTCONF connections must be authenticated using authentication, authorization, and
accounting (AAA). As a result, RADIUS or TACACS+ users defined with privilege level 15 access are
allowed access into the system.

SUMMARY STEPS
1. enable
2. configure terminal
3. aaa new-model
4. aaa group server radius server-name
5. server-private ip-address key key-name
6. ip vrf forwarding vrf-name

RESTCONF Protocol
4
 RESTCONF Protocol
Authentication of NETCONF/RESTCONF Using AAA

7. exit
8. aaa authentication login default group group-name local
9. aaa authentication login list-name none
10. aaa authorization exec default group group-name local
11. aaa session-id common
12. line console number
13. login authentication authentication-list
14. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode
Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 aaa new-model Enables AAA.

Example:
Device(config)# aaa new-model

Step 4 aaa group server radius server-name Adds the RADIUS server and enters server group RADIUS
configuration mode.
Example:
Device(config)# aaa group server radius ISE • The server-name argument specifies the RADIUS
server group name.

Step 5 server-private ip-address key key-name Configures a IP address and encryption key for a private
RADIUS server.
Example:
Device(config-sg-radius)# server-private
[Link] key Cisco123

Step 6 ip vrf forwarding vrf-name Configures the virtual routing and forwarding (VRF)
reference of a AAA RADIUS or TACACS+ server group.
Example:
Device(config-sg-radius)# ip vrf forwarding
Mgmt-intf

Step 7 exit Exits server group RADIUS configuration mode and

returns to global configuration mode.
Example:
Device(config-sg-radius)# exit

Step 8 aaa authentication login default group group-name local Sets the specified group name as the default local AAA
authentication during login.
Example:

RESTCONF Protocol
5
 RESTCONF Protocol
Enabling Cisco IOS HTTP Services for RESTCONF

Command or Action Purpose

Device(config)# aaa authentication login default
group ISE local

Step 9 aaa authentication login list-name none Specifies that no authentication is required while logging
into a system.
Example:
Device(config)# aaa authentication login NOAUTH
none

Step 10 aaa authorization exec default group group-name local Runs authorization to determine if an user is allowed to
run an EXEC shell.
Example:
Device(config)# aaa authorization exec default
group ISE local

Step 11 aaa session-id common Ensures that session identification (ID) information that
is sent out for a given call will be made identical.
Example:
Device(config)# aaa session-id common

Step 12 line console number Identifies a specific line for configuration and enter line
configuration mode.
Example:
Device(config)# line console 0

Step 13 login authentication authentication-list Enables AAA authentication for logins.

Example:
Device(config-line)# login authentication NOAUTH

Step 14 end Exits line configuration mode and returns to privileged

EXEC mode.
Example:
Device(config-line)# end

Enabling Cisco IOS HTTP Services for RESTCONF

Perform this task to use the RESTCONF interface.

SUMMARY STEPS
1. enable
2. configure terminal
3. restconf
4. ip http secure-server
5. end

DETAILED STEPS

Command or Action Purpose

Step 1 enable Enables privileged EXEC mode.

RESTCONF Protocol
6
 RESTCONF Protocol
Verifying RESTCONF Configuration

Command or Action Purpose

Example: • Enter your password if prompted.
Device> enable

Step 2 configure terminal Enters global configuration mode.

Example:
Device# configure terminal

Step 3 restconf Enables the RESTCONF interface on your network device.

Example:
Device(config)# restconf

Step 4 ip http secure-server Enables a secure HTTP (HTTPS) server.

Example:
Device(config)# ip http secure-server

Step 5 end Exits global configuration mode and enters privileged EXEC
mode
Example:
Device(config)# end

Verifying RESTCONF Configuration

When a device boots up with the startup configuration, the nginx process will be running. However; DMI
proceses are not enabled.
The following sample output from the show platform software yang-management process monitor command
shows that the nginx process is running:
Device# show platform software yang-management process monitor

COMMAND PID S VSZ RSS %CPU %MEM ELAPSED

nginx 27026 S 332356 18428 0.0 0.4 01:34
nginx 27032 S 337852 13600 0.0 0.3 01:34

NGINX is an internal webserver that acts as a proxy webserver. It provides Transport Layer Security
(TLS)-based HTTPS. RESTCONF request sent via HTTPS is first received by the NGINX proxy web serve,r
and the request is transferred to the confd web server for further syntax/semantics check.
The following sample output from the show platform software yang-management process command shows
the status of the all processes when a device is booted with the startup-configuration:

Device# show platform software yang-management process

confd : Not Running

nesd : Not Running
syncfd : Not Running
ncsshd : Not Running
dmiauthd : Not Running
nginx : Running
ndbmand : Not Running

RESTCONF Protocol
7
 RESTCONF Protocol
Verifying RESTCONF Configuration

pubd : Not Running

The nginx process gets restrated and DMI process are started, when the restconf command is configured.
The following sample output from the show platform software yang-management process command shows
that the nginx process and DMI processes are up and running:
Device# show platform software yang-management process

confd : Running
nesd : Running
syncfd : Running
ncsshd : Not Running ! NETCONF-YANG is not configured, hence ncsshd process is
in not running.
dmiauthd : Running
vtyserverutild : Running
opdatamgrd : Running
nginx : Running ! nginx process is up due to the HTTP configuration, and it is
restarted when RESTCONF is enabled.
ndbmand : Running

The following sample output from the show platform software yang-management process monitor command
displays detailed information about all processes:
Device#show platform software yang-management process monitor
COMMAND PID S VSZ RSS %CPU %MEM ELAPSED
confd 28728 S 860396 168496 42.2 4.2 00:12
confd-startup.s 28448 S 19664 4496 0.2 0.1 00:12
dmiauthd 29499 S 275356 23340 0.2 0.5 00:10
ndbmand 29321 S 567232 65564 2.1 1.6 00:11
nesd 29029 S 189952 14224 0.1 0.3 00:11
nginx 29711 S 332288 18420 0.6 0.4 00:09
nginx 29717 S 337636 12216 0.0 0.3 00:09
pubd 28237 S 631848 68624 2.1 1.7 00:13
syncfd 28776 S 189656 16744 0.2 0.4 00:12

After AAA and the RESTCONF interface is configured, and nginx process and relevant DMI processes are
running; the device is ready to receive RESTCONF requests.
Use the show netconf-yang sessions command to view the status of NETCONF/RESTCONF sessions:
Device# show netconf-yang sessions

R: Global-lock on running datastore

C: Global-lock on candidate datastore
S: Global-lock on startup datastore

Number of sessions : 1

session-id transport username source-host global-lock

--------------------------------------------------------------------------------
19 netconf-ssh admin [Link] None

Use the show netconf-yang sessions detail command to view detailed information about
NETCONF/RESTCONF sessions:
Device# show netconf-yang sessions detail

RESTCONF Protocol
8
 RESTCONF Protocol
Configuration Examples for RESTCONF Programmable Interface

R: Global-lock on running datastore

C: Global-lock on candidate datastore
S: Global-lock on startup datastore

Number of sessions : 1

session-id : 19
transport : netconf-ssh
username : admin
source-host : [Link]
login-time : 2018-10-26T[Link]+00:00
in-rpcs : 0
in-bad-rpcs : 0
out-rpc-errors : 0
out-notifications : 0
global-lock : None

ConfigurationExamplesforRESTCONFProgrammableInterface
Example: Configuring the RESTCONF Protocol
RESTCONF Requests (HTTPS Verbs):
The following is a sample RESTCONF request that shows the HTTPS verbs allowed on a targeted resource.
In this example, the logging monitor command is used..

root:~# curl -i -k -X "OPTIONS"

"[Link]
\
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin'
HTTP/1.1 200 OK
Server: nginx
Date: Mon, 23 Apr 2018 [Link] GMT
Content-Type: text/html
Content-Length: 0
Connection: keep-alive
Allow: DELETE, GET, HEAD, PATCH, POST, PUT, OPTIONS >>>>>>>>>>> Allowed methods
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Accept-Patch: application/yang-data+xml, application/yang-data+json
Pragma: no-cache

root:~#

POST (Create) Request

The POST operation creates a configuration which is not present in the targeted device.

Note Ensure that the logging monitor command is not availabel in the running configuration.

The following sample POST request uses the logging monitor alerts command.

RESTCONF Protocol
9
 RESTCONF Protocol
Example: Configuring the RESTCONF Protocol

Device:~# curl -i -k -X "POST"

"[Link] \
> -H 'Content-Type: application/yang-data+json' \
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin' \
> -d $'{
> "severity": "alerts"
> }'
HTTP/1.1 201 Created
Server: nginx
Date: Mon, 23 Apr 2018 [Link] GMT
Content-Type: text/html
Content-Length: 0
Location:
[Link]
Connection: keep-alive
Last-Modified: Mon, 23 Apr 2018 [Link] GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1524-495231-97239
Pragma: no-cache

Device:~#

PUT: (Create or Replace) Request:

If the specified command is not present on the device, the POST request creates it ; however, if it is
already present in the running configuration, the command will be replaced by this request.
The following sample PUT request uses the logging monitor warnings command.
Device:~# curl -i -k -X "PUT"
"[Link]
\
> -H 'Content-Type: application/yang-data+json' \
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin' \
> -d $'{
> "severity": "warnings"
> }'
HTTP/1.1 204 No Content
Server: nginx
Date: Mon, 23 Apr 2018 [Link] GMT
Content-Type: text/html
Content-Length: 0
Connection: keep-alive
Last-Modified: Mon, 23 Apr 2018 [Link] GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1524-495466-326956
Pragma: no-cache

Device:~#

PATCH: (Update) Request

The following sample PATCH request uses the logging monitor informational command.
Device:~# curl -i -k -X "PATCH"
"[Link] \
> -H 'Content-Type: application/yang-data+json' \
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin' \

RESTCONF Protocol
10
RESTCONF Protocol
Example: Configuring the RESTCONF Protocol

> -d $'{
> "native": {
> "logging": {
> "monitor": {
> "severity": "informational"
> }
> }
> }
> }'
HTTP/1.1 204 No Content
Server: nginx
Date: Mon, 23 Apr 2018 [Link] GMT
Content-Type: text/html
Content-Length: 0
Connection: keep-alive
Last-Modified: Mon, 23 Apr 2018 [Link] GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1524-496076-273016
Pragma: no-cache
Device:~#

GET Request (To Read)

The following sample GET request uses the logging monitor informational command.
Device:~# curl -i -k -X "GET"
"[Link]
\
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin'
HTTP/1.1 200 OK
Server: nginx
Date: Mon, 23 Apr 2018 [Link] GMT
Content-Type: application/yang-data+json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Pragma: no-cache

{
"Cisco-IOS-XE-native:severity": "informational"
}
Device:~#

DELETE Request (To Delete the Configuration)

Device:~# curl -i -k -X "DELETE"

"[Link]
\
> -H 'Content-Type: application/yang-data+json' \
> -H 'Accept: application/yang-data+json' \
> -u 'admin:admin'
HTTP/1.1 204 No Content
Server: nginx
Date: Mon, 23 Apr 2018 [Link] GMT
Content-Type: text/html
Content-Length: 0

RESTCONF Protocol
11
 RESTCONF Protocol
Additional References for the RESTCONF Protocol

Connection: keep-alive
Last-Modified: Mon, 23 Apr 2018 [Link] GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1524-497165-473206
Pragma: no-cache

linux_host:~#

Additional References for the RESTCONF Protocol

Related Documents

Related Topic Document Title

YANG data models for various releases To access Cisco YANG models in a developer-friendly way, please
of IOS XE, IOS XR, and NX-OS clone the GitHub repository, and navigate to the
platforms vendor/ciscosubdirectory. Models for various releases of IOS-XE,
IOS-XR, and NX-OS platforms are available here.

Standards and RFCs

Standard/RFC Title

RFC 6020 YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)

RFC 8040 Representational State Transfer Configuration Protocol (RESTCONF)

Technical Assistance

Description Link

The Cisco Support website provides extensive online [Link]

resources, including documentation and tools for
troubleshooting and resolving technical issues with Cisco
products and technologies.
To receive security and technical information about your
products, you can subscribe to various services, such as
the Product Alert Tool (accessed from Field Notices), the
Cisco Technical Services Newsletter, and Really Simple
Syndication (RSS) Feeds.
Access to most tools on the Cisco Support website
requires a [Link] user ID and password.

RESTCONF Protocol
12
 RESTCONF Protocol
Feature Information for the RESTCONF Protocol

Feature Information for the RESTCONF Protocol

The following table provides release information about the feature or features described in this module. This
table lists only the software release that introduced support for a given feature in a given software release
train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to [Link]/go/cfn. An account on [Link] is not required.

Table 1: Feature Information for RESTCONF Network Management Interface

Feature Name Releases Feature Information

RESTCONF Cisco IOS XE This chapter describes how to set-up and configure an HTTP-based
Network Everest 16.6.1 protocol- Representational State Transfer Configuration Protocol
Management (RESTCONF). RESTCONF provides a programmatic interface based
Interface on standard mechanisms for accessing configuration data, state data,
data-model-specific Remote Procedure Call (RPC) operations and
event notifications defined in the YANG model.
This feature was introduced on the ASR 1000 Aggregation Services
Routers-ASR1001-HX and ASR1002-HX, CSR 1000v Series Cloud
Services Router, and Cisco 4000 Series Integrated Services Routers
(ISRs).
The following commands were introduced or modified: ip http server
and restconf

Cisco IOS XE Fuji This feature was implemented on the following platforms:
16.8.1a
• Cisco Catalyst 3650 Series Switches
• Cisco Catalyst 3850 Series Switches
• Cisco Catalyst 9300 Series Switches
• Cisco Catalyst 9400 Series Switches
• Cisco Catalyst 9500 Series Switches

Cisco IOS XE Fuji This feature was implemented on the following platforms:
16.9.2
• Cisco Catalyst 9200 Series Switches

RESTCONF Protocol
13
 RESTCONF Protocol
Feature Information for the RESTCONF Protocol

RESTCONF Protocol
14