Overview

RESTCONF is a network configuration management protocol that uses HTTP methods, including OPTIONS, HEAD, GET, POST, PATCH, PUT and DELETE, to provide a set of Create, Read, Update, Delete (CRUD) operations on YANG-defined datastore to manage network devices.

RESTCONF is developed based on the integration of NETCONF and HTTP protocols, which can be implemented on a device that supports the NETCONF protocol.

RESTCONF provides a programming interface in line with the popular RESTful style, providing users with the ability to efficiently develop Web-based operation and maintenance tools.

RESTCONF Components

As shown in Figure 1, the RESTCONF protocol consists of two parts: RESTCONF Client and Server.

RESTCONF Client

The client utilizes the RESTCONF protocol for system management of network devices. The client sends HTTP requests to the server to create, delete, modify or query one or more data, encoded in XML or JSON format.

RESTCONF Server

The server device is used to maintain the information data of the managed devices. When receiving a HTTP request from the RESTCONF client, the server parses and processes the request message, and then returns a response to the client.

Figure 1. RESTCONF Components

The information that the client obtains from the running server includes configuration data and status data.

The client can query the status data and the configuration data.
The client can modify the configuration data and manipulate it to achieve the desired state of the server.
The client cannot modify the status data, which mainly includes the running status and statistical information of the server.

Advantage

RESTCONF provides RESTful style programming interface to support Web development.
Adopting XML or JSON encoding.
Standardized interface, compatible with devices from multiple manufacturers, can reduce development and maintenance costs.
Good extensibility, different manufacturer devices can define their own protocol operation.

YANG Model

Same as NETCONF, RESTCONF also works based on YANG.

Most YANG files independent of the device type are placed in the following path:

/pica/etc/common/data-models.

root@PICOS:/pica/etc/common/data-models# ls -lt *.yang
-rw-r--r-- 1 root root 178165 May 19  2023 bgp.yang
-rw-r--r-- 1 root root   4487 May 12  2023 arp.yang
-rw-r--r-- 1 root root  56906 May  5  2023 ospfv2.yang
-rw-r--r-- 1 root root  22047 May  5  2023 ospfv3.yang
-rw-r--r-- 1 root root  16808 Apr 12  2023 bfd.yang
-rw-r--r-- 1 root root   7163 Apr 12  2023 cos-with-pfc.yang
-rw-r--r-- 1 root root   8350 Apr 12  2023 dhcp.yang
-rw-r--r-- 1 root root  23978 Apr 12  2023 firewall-no-icmp-type-code.yang
-rw-r--r-- 1 root root  24752 Apr 12  2023 firewall.yang
-rw-r--r-- 1 root root   2416 Apr 12  2023 igmp.yang
-rw-r--r-- 1 root root   8168 Apr 12  2023 igmpsnooping.yang
-rw-r--r-- 1 root root   4244 Apr 12  2023 lacp.yang
-rw-r--r-- 1 root root   5081 Apr 12  2023 mlag.yang
-rw-r--r-- 1 root root  26129 Apr 12  2023 mstp.yang
-rw-r--r-- 1 root root   5118 Apr 12  2023 ovsdb.yang
-rw-r--r-- 1 root root   7986 Apr 12  2023 pim.yang
-rw-r--r-- 1 root root  58523 Apr 12  2023 routing.yang
-rw-r--r-- 1 root root   5240 Apr 12  2023 sflow.yang
-rw-r--r-- 1 root root  10446 Apr 12  2023 snmp.yang
-rw-r--r-- 1 root root  13186 Apr 12  2023 static-routes.yang
-rw-r--r-- 1 root root  17509 Apr 12  2023 vlan-interface.yang
-rw-r--r-- 1 root root   8591 Apr 12  2023 vlans.yang
-rw-r--r-- 1 root root  11408 Apr 12  2023 vrrp.yang
-rw-r--r-- 1 root root   9920 Apr 12  2023 vxlans.yang
-rw-r--r-- 1 root root   5173 Aug 24  2022 dot1x.yang
-rw-r--r-- 1 root root   6062 Aug 12  2022 cos-without-pfc.yang
-rw-r--r-- 1 root root  16760 Aug 12  2022 ietf-inet-types.yang
-rw-r--r-- 1 root root  18034 Aug 12  2022 ietf-yang-types.yang
-rw-r--r-- 1 root root   5475 Aug 12  2022 ipfix.yang
-rw-r--r-- 1 root root   6944 Aug 12  2022 lldp.yang
-rw-r--r-- 1 root root   1411 Aug 12  2022 mfea.yang
-rw-r--r-- 1 root root   1629 Aug 12  2022 mpls.yang
-rw-r--r-- 1 root root   4825 Aug 12  2022 neighbour.yang
-rw-r--r-- 1 root root   8833 Aug 12  2022 policy.yang
-rw-r--r-- 1 root root   4592 Aug 12  2022 rip.yang
-rw-r--r-- 1 root root   3669 Aug 12  2022 ripng.yang
-rw-r--r-- 1 root root  50887 Aug 12  2022 system.yang
-rw-r--r-- 1 root root   4126 Aug 12  2022 udld.yang
-rw-r--r-- 1 root root    871 Aug 12  2022 version.yang
-rw-r--r-- 1 root root   4515 Aug 12  2022 xovs.yang

The yang files related to the device type are placed in the following path. This path contains a soft link to the yang file above, use an ellipsis instead.

root@PICOS:/pica/etc/as5712_54x/data-models# ls -lt *.yang
……
-rw-r--r-- 1 root root 58741 Apr 12  2023 interface.yang
-rw-r--r-- 1 root root  2211 Aug 12  2022 stm.yang

Authentication

RESTCONF supports setting authorization to “Basic Auth”, the username and password should be set to the same as the accounts used for authentication of the RESTCONF server.

In the HTTPs request message sent by the client, you need to fill in the authentication information correctly to ensure that the connection between the RESTCONF client and server can be established successfully.

HTTP Status Code

RESTCONF uses the Status-Line part of an HTTP response message to inform clients of their request’s result. HTTP defines these standard status codes that can be used to convey the results of a client’s request.

Table 1. HTTP status codes

Status Code	Description
200 OK	Indicates that the request has succeeded.
201 Created	Indicates that the request has succeeded and a new resource has been created as a result.
204 No Content	The server has fulfilled the request but does not need to return a response body. The server may return the updated meta information.
400 Bad Request	The request could not be understood by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications.
401 Unauthorized	Indicates that the request requires user authentication information. The client MAY repeat the request with a suitable Authorization header field
403 Forbidden	Unauthorized request. The client does not have access rights to the content. Unlike 401, the client’s identity is known to the server.
404 Not Found	The server cannot find the requested resource.
405 Method Not Allowed	The request HTTP method is known by the server but has been disabled and cannot be used for that resource.
408 Request Timeout	Indicates that the server did not receive a complete request from the client within the server’s allotted timeout period.
409 Conflict	The request could not be completed due to a conflict with the current state of the resource.
410 Gone	The requested resource is no longer available at the server.
412 Precondition Failed	The client has indicated preconditions in its headers which the server does not meet.
413 Request Entity Too Large	Request entity is larger than limits defined by server.
414 Request-URI Too Long	The URI requested by the client is longer than the server can interpret.
415 Unsupported Media Type	The media-type in Content-type of the request is not supported by the server.
500 Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.
501 Not Implemented	The HTTP method is not supported by the server and cannot be handled.

RESTCONF Error Codes

The tree of YANG model <errors> is defined as follows:

+---- errors
      +---- error*
         +---- error-type       enumeration
         +---- error-tag        string
         +---- error-app-tag?   string
         +---- error-path?      instance-identifier
         +---- error-message?   string
         +---- error-info?

When an error occurs, the server returns a response message carried with above error information.

error-type

The value of error-type can be：

Value	Description
transport	Transport Layer
tpc	RPC Layer
protocol	Operation Layer
application	Application Layer

error-tag

<error-tag>	Error description	Status code
in-use	The requested resource is already in use	409
invalid-value	The parameter value in the request is incorrect	400, 404 or 406
too-big	Request or reply messages are too large to process	413 or 400
missing-attribute	Missing attribute on element node	400
bad-attribute	Attribute error on element node	400
unknown-attribute	Unknown attribute on element node	400
bad-element	The element node value is incorrect	400
unknown-element	Unrecognized elements	400
unknown-namespace	Unrecognized namespaces	400
access-denied	Access denied	401 or 403
lock-denied	The configuration process is locked	409
resource-denied	Insufficient resources to complete the request	409
rollback-failed	Rollback failure	500
data-exists	The data already exists and POST creates a duplicate record	409
data-missing	Deleting a non-existent object returns this error	409
operation-not-supported	The operation is not supported. For example, POST and DELETE operations are not supported for current container nodes	405 or 501
operation-failed	Operation execution failed	412 or 500
partial-operation	Some operations failed	500
malformed-message	The message format is incorrect	400

error-app-tag: Indicates a specific error type.
error-path: Represents the location where the error occurred.
error-message: Indicates detailed error information.
error-info: Indicates the description of error parameters.

For example,

Example 1: Input an error path when using GET method causes error: "error-type": "application".

The response result is:

400 Bad Request
{
    "ietf-restconf:errors": {
        "error": {
            "error-type": "application",
            "error-tag": "unknown-element",
            "error-info": {
                "bad-element": "vlan"
            },
            "error-severity": "error",
            "error-message": "No such yang module prefix"
        }
    }
}

Example 2: Input a non-exist path when using PATCH method causes error: "error-type": "protocol".

The response result is:

400 Bad Request
{
    "ietf-restconf:errors": {
        "error": {
            "error-type": "protocol",
            "error-tag": "invalid-value",
            "error-severity": "error",
            "error-message": "API-resource type"
        }
    }
}

Example 3: No data was provided when using PUT method causes error: "error-type": "rpc".

The response result is:

400 Bad Request
{
    "ietf-restconf:errors": {
        "error": {
            "error-type": "rpc",
            "error-tag": "malformed-message",
            "error-severity": "error",
            "error-message": "The message-body MUST contain exactly one instance of the expected data resource"
        }
    }
}

PICOS-4.4.4_Configuration_Guide

Introduction of RESTCONF

Overview

Figure 1. RESTCONF Components

YANG Model

Authentication

HTTP Status Code

RESTCONF Error Codes