Representational State Transfer Configuration Protocol (RESTCONF) Fundamentals

Representational State Transfer Configuration Protocol (RESTCONF) is a next generation northbound interface that provides an additional way to configure and monitor the switch. RESTCONF is an HTTP-based protocol that provides a programmatic interface to access data defined in a YANG model using the datastore concepts defined in NETCONF. RESTCONF uses a client-server model. The server acts as an entry point to a datastore, a conceptual place to store and access information. Clients use HTTP or HTTPS to interface with the server to configure and monitor devices.

RESTCONF Client and Server

A typical RESTCONF interaction consists of an HTTP/HTTPS request sent by a RESTCONF client and an HTTP/HTTPS response sent by the server. The HTTP/HTTPS request and response contain a required set of expected HTTP headers and can also contain a request or response message body. The message body is encoded in JSON.

An HTTP request consists of the HTTP method (such as GET or POST) identifier, resource identifier, HTTP protocol version, HTTP headers, and HTTP body. The HTTP resource identifier is the string that identifies a service or resource that the server makes available to the client. The RESTCONF request contains the Universal Resource Identifier or URI which starts with /rest/restconf/data/ or /rest/restconf/operations/.

YANG Model

YANG is the data modeling language used for modeling configuration and state data for manipulation by using remote procedure calls (RPCs). The RESTCONF interface is generated with YANG Data Model. The YANG model is based on Open config model, which is a non vendor specific model that captures the key components found in multiple vendor solutions. RESTCONF is described by the Internet Engineering Task Force (IETF) in RFC 8040.

RESTCONF Authentication

RESTCONF uses the CLI user account and supports both local and remote authentication. Local authentication uses the local CLI user account while remote authentication can use either a RADIUS or TACACS+ server.

You can only use a CLI account with the RWA access level.

With RADIUS or TACACS+ enabled, if the remote server is not available, authentication falls back to local authentication and uses the local CLI user on the switch.

When the RESTCONF client posts for authentication, the HTTP server validates the login username and password if you have not enabled CLI remote authentication. If the remote server is not reachable, the HTTP server uses the local user for login validation.

For HTTPS access to the RESTCONF server, you must enable TLS and install a certificate. For the certificate, first you need to create a leaf certificate in .pem format and convert the private key to PKCS8 format. Then you need to create a .pem container that contains both the leaf certificate and the PCKS8 private key. The container will be used in the RESTCONF configuration and will have the following format:

----BEGIN CERTIFICATE----
----END CERTIFICATE----
----BEGIN PRIVATE KEY----
----END PRIVATE KEY----

To install the certificate, copy your certificate and private key into the container between the appropriate BEGIN and END lines.

RESTCONF APIs

You can access the RESTCONF API documentation on your switch using the following URL:

http(s)://<IP>:<tcp-port>/apps/restconfdoc/

Replace <IP> with the management IP address of your switch and <tcp-port> with the TCP port configured for RESTCONF. For example, http://192.0.2.16:8080/apps/restconfdoc/.

The on-switch URL works only if you enable the RESTCONF feature on the switch.

You can also access the RESTCONF API documentation online through the Developer Center (https://www.extremenetworks.com/support/documentation-api/).

Server Support

The RESTCONF server in the network operating system (NOS) supports the following actions:

HTTP Action

VOSS Instrumentation

GET

Corresponds to SHOW

POST

Corresponds to SET for creation

PATCH

Corresponds to SET for modification

DELETE

Corresponds to SET for deletion

The following table details modules supported by RESTCONF:

Modules

OpenConfig

Extreme Network Service

OpenConfig

Relay Agent (DHCP support)

OpenConfig

Interfaces Port: POE, port attributes, such as auto-sense, default-vlan-id, flex-uni, qos, untag-port-default-vlan

OpenConfig

Interfaces LAG: attributes, such as flex-uni

OpenConfig

Platform: ports, CPU, fans, power supply, optical devices - GET operations only

OpenConfig

Network Instance: VLAN interface - VRF association, CVLAN I-SID, IS-IS redistribute direct, IPVPN, I-SID, and IP DHCP relay forward path)

OpenConfig

STP: STP global information and port interface bpduguard state, RSTP global and port level information, MSTP global, MST instance level state - GET operations only

OpenConfig

System (aaa)

OpenConfig

LLDP

OpenConfig

VLAN

The RESTCONF feature is disabled by default. The RESTCONF server uses the same management IP address as the other applications and TCP port. The default TCP port that RESTCONF server listens to is port 8080. The TCP port delivers the message to the HTTP server for RESTCONF.