CloudEngine 16800 V300R024C10 Configuration Guide - System Management

Understanding RESTCONF

RESTCONF Fundamentals
RESTCONF Message Formats
RESTCONF Error Codes

RESTCONF Fundamentals

RESTCONF Network Architecture

Figure 2-91 shows the basic RESTCONF network architecture. The main elements in the RESTCONF network architecture are as follows:

RESTCONF client:

The RESTCONF client uses RESTCONF to manage network devices, and it sends a request to the server to create, delete, modify, or query one or more data records.

RESTCONF server:

The device functions as the RESTCONF server to maintain the data of the managed network devices, respond to client requests, and report requested data to the client. After receiving a request sent by the client, the server parses and processes the request, and then sends a response to the client.

Figure 2-91 RESTCONF network architecture

The RESTCONF client obtains both configuration and status data from a running RESTCONF server.

The RESTCONF client can query the status data and configuration data.
The RESTCONF client can modify and operate configuration data, allowing the status of the RESTCONF server to migrate to a user-expected status.
The RESTCONF client cannot modify status data, which includes the running status and statistics of the RESTCONF server.

RESTCONF Modeling Language

RESTCONF uses YANG as its modeling language. YANG is a data modeling language used to model both the configuration and status data in RESTCONF.

The YANG data model is a machine-oriented model interface, which defines data structures and constraints to provide more flexible and complete data description.

Related Concepts

The RESTCONF client and server run HTTP to establish a secure and connection-oriented session. The client sends a request to the server. After processing the user request, the server replies with a response to the client. The request and response messages are coded in either XML or JSON format.

Message coding

XML encoding

XML, the encoding format used by RESTCONF, enables the use of a text file to represent complex hierarchical data. A traditional text tool or XML-specific compilation tool can be used to read, save, and operate configuration data.

XML-based network management uses XML to describe managed data and management operations so that management information becomes a database comprehensible to computers. XML-based network management helps computers efficiently process network management data, improving network management capabilities.

XML encoding

XML, the encoding format used by RESTCONF, enables the use of a text file to represent complex hierarchical data. A traditional text tool or XML-specific compilation tool can be used to read, save, and operate configuration data.

XML-based network management uses XML to describe managed data and management operations so that management information becomes a database comprehensible to computers. XML-based network management helps computers efficiently process network management data, improving network management capabilities.
The XML encoding format file header is <?xml version="1.0" encoding="UTF-8"?>, where:
- <?: indicates the start of an instruction.
- xml: indicates an XML file.
- version="1.0": indicates the XML1.0 standard version.
- encoding: indicates a character set encoding format. Only UTF-8 encoding is supported.
- ?>: indicates the end of an instruction.
JSON encoding

JSON is a lightweight text data exchange format. JSON uses JavaScript syntax to describe data objects, but JSON is still independent of languages and platforms, making it easier to understand.

JSON is similar to XML, but JSON is shorter, faster, and easier to parse than XML.
JSON syntax rules are as follows:
- Data is in name:value pairs.
- Data is separated by commas (,).
- An object is saved in braces ({}).
- An array is saved in brackets ([]).
The JSON format is as follows:
- JSON name:value pair. For example:
```
"Name": "Apple"
```
- JSON value. The value can be a number, string, logical value, array, object, or null. For example:
```
"Price": 3.99
```
- JSON object. An object is an unordered collection of name:value pairs. An object starts with a left brace ({) and ends with a right brace (}). Each name is followed by a colon (:), and name:value pairs are separated by commas (,). For example:
```
{ "firstName": "Brett", "lastName":"McLaughlin", "email": "aaaa" }
```
- JSON array. An array is an ordered list of values. An array starts with a left bracket ([) and ends with a right bracket (]). Arrays are separated by commas (,). For example:
```
{ "people": [
      { "firstName": "Brett", "lastName":"McLaughlin", "email": "aaaa" }, 
	  { "firstName": "Jason", "lastName":"Hunter", "email": "bbbb"}  
	  ]
}
```

RESTCONF capability

In addition to a group of basic operations, RESTCONF also provides extended capabilities supported by the device. The capability set is used to declare that the device supports these extended capabilities. Each capability set is identified by a uniform resource identifier (URI).

Table 2-88 describes the standard capability sets supported by RESTCONF.

Table 2-88 Capability set description

Name	URI	Description of Capability Set Operations
depth	urn:ietf:params:xml:restconf:capability:depth:1.0	A device supports the "depth" query parameter of version 1.0. This capability indicates that the device supports a specified maximum number of data query times.
fields	urn:ietf:params:xml:restconf:capability:fields:1.0	The device supports the "fields" query parameter of version 1.0. This capability indicates that a device can obtain the subset of the target data content.
with-defaults	urn:ietf:params:xml:restconf:capability:with-defaults:1.0	The device supports the "with-defaults" query parameter of version 1.0. This capability indicates that a device is capable of specifying how information about default data nodes should be returned.
defaults	urn:ietf:params:restconf:capability:defaults:1.0	This capability indicates the default value of the "with-defaults" query parameter. NOTE: If the "with-defaults" query parameter is not specified in the request URI, the default value is report-all (to query all nodes).

RESTCONF Message Formats

RESTCONF is an HTTP-based protocol. Messages transmitted between a client and a server are HTTP packets, including request and response messages.

Request message

A request is sent by a RESTCONF client to a RESTCONF server. It contains three parts: request line, request header, and request body, as shown in Figure 2-92.

Figure 2-92 Request format

Figure 2-93 URI format

Table 2-89 Request fields

Field	Description
Method	RESTCONF method, performed on the resource identified by the request URI. For details, see RESTCONF Operation Methods.
URI	As shown in Figure 2-93, URI fields are as follows: restconf: resource's root path, which is obtained from the well-known URI (/.well-known/host-meta). The content obtained from /.well-known/host-meta contains the URL: http://docs.oasis-open.org/ns/xri/xrd-1.0. path: resource's relative path, which is specified by the YANG model. query: query parameters. For details, see Query Parameters.
HTTP/Version-number	HTTP protocol version.
Connection: value1	Used to manage HTTP/HTTPS connections. The options are as follows: keep-alive: The HTTP connection remains alive for a period. Setting this parameter to keep-alive or close does not affect functions but affects only the number of connection setup times. close: The connection to the server is torn down each time an HTTP request is sent.
Host: value2	IP address of the HTTP server.
Accept: value3	Response data format of HTTP response packets. Currently, the following formats are supported: application/yang-data+json application/yang-data+xml
Content-Type: value4	Request data format. If the request data in an HTTP/HTTPS packet is empty, this parameter is optional or left empty. Currently, the following formats are supported: application/yang-data+json application/yang-data+xml
Content-Length: value5	Actual length of the request data, in bytes. If there is no data, the value is 0.
Authorization: value6 value7	Authentication information. value6: authentication parameters. Currently, only Basic is supported. The username and password are used for authentication. value7: authentication data, which complies with the HTTP protocol and is generated through Base64 encoding.
Optional request body	Request message body.

Response message

A response is returned by a RESTCONF server to a RESTCONF client in response to the client's request. A response also contains three parts: response line, response header, and response body, as shown in Figure 2-94.

Figure 2-94 Response format

Table 2-90 Response fields

Field	Description
HTTP/Version-number	HTTP protocol version.
Status code	HTTP status code. For details, see Table 3 HTTP status code.
Message	HTTP status message.
Date: value1	Date and time when the HTTP response packet is generated. Example: Wed, 18 Apr 2024 12:00:00 GMT.
Content-Length: value2	Actual length of the response data, in bytes.
Content-Type: value3	Response data format. Currently, the following formats are supported: application/yang-data+json application/yang-data+xml
Optional response body	Response message body.

Table 2-91 HTTP status code

Status Code	Description
200 OK	The operation is successful, and the reply message body exists.
201 Created	A resource is successfully created, and the URI of the newly created resource exists in the location field.
204 No Content	The operation is successful, but the reply message body does not exist.
400 Bad Request	The request message body is incorrect. It carries error information, such as incorrect field values, missing required attributes, incorrect attributes, error elements, error namespaces, or malformed packets.
401 Unauthorized	The certificate authentication fails. The SSL certificate that the client sends to the server does not match the one that is required for logging in to the server. An HTTP session expires.
403 Forbidden	Access is forbidden. The possible causes are as follows: A user attempts to perform unauthorized operations. The username or password for login is incorrect.
404 Not Found	The requested resource cannot be found.
405 Method Not Allowed	The request method specified in the request cannot be used to request the resource.
409 Conflict	A conflict occurs. The possible causes are as follows: Multiple users modify the same data concurrently, causing a conflict. A user attempts to establish a resource that already exists during the POST operation.
412 Precondition Failed	The prerequisite is not met.
413 Request Entity Too Large	The server refuses to process the request because the entity data size of the request exceeds the processing capability of the server.
414 Request-URI Too Long	The server refuses to provide services for the request because the URI length of the request exceeds the length that can be parsed by the server.
415 Unsupported Media Type	The media type is not supported.
500 Internal Server Error	The request cannot be executed due to an internal server error. The user needs to resend the request later.
501 Not Implemented	The function has not been implemented.

RESTCONF Error Codes

The <errors> tree diagram is described as follows in the YANG model.

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

If an error occurs, the server returns a response message carrying the preceding error information.

error-type
The error-type value can be:
- transport
- rpc
- protocol
- application

error-tag

The following table lists error-tag values and mappings between these values and status codes.

Table 2-92 Error-tag values and mappings between error-tag values and status codes

<error-tag>	Error Description	Status Code
in-use	The requested resource is in use.	409
invalid-value	The value of a parameter in the request is incorrect.	400, 404, or 406
too-big	The request or response message is too large to process.	413 or 400
missing-attribute	The element node does not have an attribute.	400
bad-attribute	The attribute of the element node is incorrect.	400
unknown-attribute	The attribute of the element node is unknown.	400
bad-element	The value of the element node is incorrect.	400
unknown-element	The element cannot be identified.	400
unknown-namespace	The namespace cannot be identified.	400
access-denied	The access is denied.	401 or 403
lock-denied	The configuration is locked.	409
resource-denied	The request cannot be processed due to insufficient resources.	409
rollback-failed	The rollback fails.	500
data-exists	The data already exists, and the POST operation creates a duplicate record.	409
data-missing	The data is missing. This error is returned when an object that does not exist is deleted.	409
operation-not-supported	The operation is not supported. For example, the POST or DELETE operation cannot be performed on the container node.	405 or 501
operation-failed	An error occurs during operation execution.	412 or 500
partial-operation	Some operations succeed or fail.	500
malformed-message	The message is malformed.	400

error-app-tag: indicates the error type.
error-path: indicates the location where an error occurs.
error-message: indicates detailed error information.
error-info: contains error-paras/error-para, which is a description of parameters.

For example:

Error response (XML format):

HTTP/1.1 400 Bad Request
Date: Thu, 26 Jan 2024 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+xml

<errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
  <error>
    <error-type>application</error-type>
    <error-tag>invalid-value</error-tag>
  </error>
</errors>

RESTCONF Fundamentals
RESTCONF Message Formats
RESTCONF Error Codes

Translation

Favorite

Download

Update Date：2025-04-23

Document ID：EDOC1100463937

Downloads：15

Average rating：0.0Points

Related Version

Digital Signature File

digtal sigature tool