Introduction of RESTCONF
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:
Example 2: Input a non-exist path when using PATCH method causes error: "error-type": "protocol".
The response result is:
Example 3: No data was provided when using PUT method causes error: "error-type": "rpc".
The response result is:
Copyright © 2024 Pica8 Inc. All Rights Reserved.