Cisco IOS XE RESTCONF Protocol User Guide: Configuration and API Reference

Restrictions for the RESTCONF Protocol

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 the RESTCONF Protocol, on page 2 How to Configure the RESTCONF Protocol, on page 22 Configuration Examples for the RESTCONF Protocol, on page 27 Additional References for the RESTCONF Protocol, on page 30 Feature Information for the RESTCONF Protocol, on page 31 Prerequisites for the RESTCONF Protocol • Enable the Cisco IOS-HTTP services for RESTCONF. 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

Page 1

RESTCONF Root Resource

Information About the RESTCONF Protocol 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: 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 Information About the RESTCONF Protocol 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 Protocol 2

Page 2

Displaying Version Information

Example: Example returning /restconf: The client might send the following: GET /.well-known/host-meta HTTP/1.1 Host: example.com Accept: application/xrd+xml The server might respond as follows: HTTP/1.1 200 OK Content-Type: application/xrd+xml Content-Length: nnn xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'> rel='restconf' href='/restconf'/> Example of URIs:

• GigabitEthernet0/0/2 - https://10.104.50.97/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=0%2F0%2F2 • fields=name – https://10.104.50.97/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=0%2F0%2F2?fields=name • depth=1 - https://10.85.116.59/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet?depth=1 • Name and IP - https://10.85.116.59/restconf/data/Cisco-IOS-XE-native:native/interface?fields=GigabitEthernet/ip/address/primary;name • MTU (fields) - https://10.104.50.97/restconf/data/Cisco-IOS-XE-native:native/interface?fields=GigabitEthernet(mtu) • MTU - https://10.85.116.59/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=3/mtu • Port-Channel - https://10.85.116.59/restconf/data/Cisco-IOS-XE-native:native/interface/Port-channel • “Char” to “Hex” conversion chart:

http://www.columbia.edu/kermit/ascii.html Displaying Version Information The Cisco-IOS-XE-install-oper module that has various nodes to display the version information. The following sample RPC shows the some of the supported nodes of the Cisco-IOS-XE-install-oper module and the response from the host that contains the major and minor release version: xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="urn:uuid:7d0908d8-0d5f-4521-9d7b-380b81304776"> xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-install-oper"> RESTCONF Protocol Displaying Version Information RESTCONF Protocol 3

Page 3

Displaying Version Information

## Received message from host xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="urn:uuid:7d0908d8-0d5f-4521-9d7b-380b81304776"> xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-install-oper"> 17.06.04.0.3870 1651661105 install-version-state-present 17.09.01.0.158212 1651125381 install-version-state-present 17.10.01.0.158658 1651754624 install-version-state-present /bootflash/c8000v-universalk9nic.2022-05-05_18.13.SSA.bin 17.10.01.0.160585 1656581638 install-version-state-provisioned-committed /bootflash/c8000v-universalk9.2022-06-30_15.03.SSA.bin 17.10.01.0.162616 1657120419 install-version-state-present /bootflash/c8000v-universalk9.BLD_POLARIS_DEV_LATEST_20220706_ 143733.SSA.bin When using the protocol, gNMI, NETCONF, or RESTCONF, the Cisco-IOS-XE-native:version module only displays the major release version.

RESTCONF Protocol Displaying Version Information RESTCONF Protocol 4

Page 4