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.