Login
- Released At: 04-09-2025
- Page Views:
- Downloads:
- Table of Contents
- Related Documents
-
H3C Access Controllers
REST API Developers Guide
Copyright © 2025 New H3C Technologies Co., Ltd. All rights reserved.
No part of this manual may be reproduced or transmitted in any form or by any means without prior written consent of New H3C Technologies Co., Ltd.
Except for the trademarks of New H3C Technologies Co., Ltd., any trademarks that may be mentioned in this document are the property of their respective owners.
This document provides generic technical information, some of which might not be applicable to your products.
Preface
This guide is intended for network administrators and operators to configure and manage Comware-based devices from a RESTful client.
This preface includes the following topics about the documentation:
· Audience
This documentation is intended for:
· Network planners that have knowledge of XML and REST development.
· Network administrators or maintainer familiar with XML and REST APIs.
Command conventions
|
Convention |
Description |
|
Boldface |
Bold text represents commands and keywords that you enter literally as shown. |
|
Italic |
Italic text represents arguments that you replace with actual values. |
|
[ ] |
Square brackets enclose syntax choices (keywords or arguments) that are optional. |
|
{ x | y | ... } |
Braces enclose a set of required syntax choices separated by vertical bars, from which you select one. |
|
[ x | y | ... ] |
Square brackets enclose a set of optional syntax choices separated by vertical bars, from which you select one or none. |
|
{ x | y | ... } * |
Asterisk marked braces enclose a set of required syntax choices separated by vertical bars, from which you select a minimum of one. |
|
[ x | y | ... ] * |
Asterisk marked square brackets enclose optional syntax choices separated by vertical bars, from which you select one choice, multiple choices, or none. |
|
&<1-n> |
The argument or keyword and argument combination before the ampersand (&) sign can be entered 1 to n times. |
|
# |
A line that starts with a pound (#) sign is comments. |
Symbols
|
Convention |
Description |
|
|
An alert that calls attention to important information that if not understood or followed can result in personal injury. |
|
|
An alert that calls attention to important information that if not understood or followed can result in data loss, data corruption, or damage to hardware or software. |
|
|
An alert that calls attention to essential information. |
|
NOTE: |
An alert that contains additional or supplementary information. |
|
|
An alert that provides helpful information. |
Network topology icons
|
|
Represents a generic network device, such as a router, switch, or firewall. |
|
|
Represents a routing-capable device, such as a router or Layer 3 switch. |
|
|
Represents a generic switch, such as a Layer 2 or Layer 3 switch, or a router that supports Layer 2 forwarding and other Layer 2 features. |
|
|
Represents an access controller, a unified wired-WLAN module, or the access controller engine on a unified wired-WLAN switch. |
|
|
Represents an access point. |
|
|
Represents a wireless terminator unit. |
|
|
Represents a wireless terminator. |
|
|
Represents a mesh access point. |
|
|
Represents omnidirectional signals. |
|
|
Represents directional signals. |
|
|
Represents a security product, such as a firewall, UTM, multiservice security gateway, or load balancing device. |
|
|
Represents a security module, such as a firewall, load balancing, NetStream, SSL VPN, IPS, or ACG module. |
Examples provided in this document
Configuration examples provided in this documentation are for illustration only. They might differ depending on the hardware model, software version, and configuration. Examples in this document might use devices that differ from your device in hardware model, configuration, or software version.
The interface numbers in this document are for illustration only. They might differ from the interface numbers available on your device.
You can e-mail your comments about product documentation to E-mail: [email protected].
We appreciate your comments.
Contents
Configuring and managing the device from REST APIs
Generic procedure for device configuration and management from REST APIs
Configuring RESTful access over HTTP
Configuring RESTful over HTTPS
Assigning access permissions to a RESTful user on the device
About RESTful user access permissions
Configuring user role rules for a RESTful client
Using REST API references to construct RESTful requests
Connecting to the device from a RESTful client
Integrating the validated request into the client script or program
Disconnecting the RESTful client from the device
Request concurrency over one session
Maximum number of NETCONF sessions
RESTful operations supported in Comware
Summary of RESTful operations supported in Comware
Examples: Using Postman for REST-based device configuration and management
Example: Developing a client in Python
Example: Logging in to the device
Example: Performing a GET operation
Example: Performing a POST operation
Example: Performing a PUT operation
Example: Performing a DELETE operation
About REST
Representational State Transfer (REST) is a lightweight, platform-agnostic, and language-independent architecture for building resource-oriented applications. It offers a clear structure, easy management, and scalability. Comware devices are available with REST APIs for administrators to configure and manage the devices from an external application system.
This document is intended for network administrators and operators to configure and manage Comware-based devices from a RESTful client.
Operating mechanism of REST
As shown in Figure 1, REST APIs are based on a client/server model. The RESTful client is a program or script developed in a programming language such as Python, Ruby, or Java. The RESTful server is deployed on a network device. A RESTful client configures and manage a network device as follows:
1. The client sends an HTTP or HTTPS request to have the server operate on the resources at the specified REST API. The operation to perform is specified by the HTTP method included in the request, which can be GET, PUT, POST, or DELETE.
2. The server executes the REST API call when it receives the HTTP or HTTPS request, and then returns the result in an HTTP or HTTPS response to the client.
In HTTP/HTTPS request and response messages, data is encoded in JSON format.
Figure 1 Basic REST architecture
RESTful message format
RESTful architecture uses HTTP or HTTPS for communication between the client and server, with requests and responses adhering to the standard HTTP format.
|
|
NOTE: The REST APIs support UTF-8 encoding for data transmission. |
Request format
An HTTP/HTTPS request message consists of a request line, request headers, and a request body.
· Request line: Consists of the operation method, URL, and HTTP version.
¡ Operation method: Set the value to GET, PUT, POST, or DELETE.
¡ URL: Specify the URL at which the resource to be operated on is located. With HTTP, the URL format is http://ip-address:port/api/v1/resource-locator?parameter.
Table 1 URL field description
|
Field |
Description |
|
http |
Protocol type of the request message. Set the value to HTTP or HTTPS. |
|
ip-address:port |
IP address and port number of the server. If you use the default port number for HTTP or HTTPS, omit the port number. |
|
api/v1 |
Fixed field. |
|
resource-locator |
Location of the resource to operate on. To obtain the URIs of resources for a feature, see the REST API reference for that feature. For more information about the REST API reference, see "About REST API references." |
|
?parameter |
The parameters sent with the request. The supported parameters include index, filter-condition, select-fields, and getbulk-count. You can omit parameters in a URL. For more information about parameters, see "About data filters." |
· Request headers: Standard HTTP request headers, including the compression method, authentication header, content type, and content length.
· Request body: Encode the request data in JSON format and encapsulate it in the request body.
The following is an example of RESTful requests:
POST http://192.168.100.91/api/v1/Syslog/LogHosts HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001b81dbfc50884818f45b686fd81ceaa
Content-Type: application/json
Content-Length: 78
Host: 192.168.100.91
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
{
"Address": "1.1.1.3",
"VRF": "b",
"Port": 518,
"Facility": 184
}
Response format
An HTTP/HTTPS response message consists of a status line, response headers, and a response body.
· Status line: Consists of the HTTP version, status code, and reason phrase. The status code identifies whether the operation has succeeded. Codes 200 to 299 indicate a success, while codes 400 and above indicate a failure. For information about common status codes, see Table 2.
|
Status code |
Description |
|
200 |
Success. |
|
201 |
Creation succeeded. |
|
204 |
No content. The server has successfully fulfilled the request and its response body does not contain additional content. |
|
401 |
Authentication failed. |
|
404 |
The requested resource does not exist. |
|
405 |
Method not allowed. This code indicates that the operation is not supported on the resource. |
|
406 |
The data encoding formats used by the RESTful client and server do not match. |
|
500 |
Internal server error. |
|
501 |
Not implemented. The RESTful server does not support the requested method, for example, CONNECT. |
· Response header: Standard HTTP response header. The header contains fields such as the content type and response time.
· Response body: The response data uses JSON format encoding and is encapsulated in the response body.
The following example shows a response message indicating a successful operation.
HTTP/1.1 201 Created
Content-Type: application/json charset=UTF-8
Location: http://192.168.100.91/api/v1/Syslog/LogHosts?index=Address%3D1.1.1.3%3BVRF%3Db
Server: HTTPD
Date: Fri, 12 Jun 2015 14:46:33 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
X-XSS-Protection: 1;mode-block
X-Content-Type-Options: nosniff
The following example shows a response message indicating a failed operation.
HTTP/1.1 409 Conflict
Content-Type: application/json charset=UTF-8
Server: HTTPD
Date: Sat, 16 Jul 2022 09:49:09 GMT
Connection: close
X-XSS-Protection: 1;mode-block
X-Content-Type-Options: nosniff
{"errors":[{"error":{"error-type":"rpc","error-tag":"bad-element","error-path":"Port","error-message":"The value must be less than or equal to 65535."}}]}
Configuring and managing the device from REST APIs
Generic procedure for device configuration and management from REST APIs
To configure and manage the device from REST APIs:
Comware devices support both HTTP and HTTPS for RESTful access. The configuration procedure differs by protocol.
2. Assigning access permissions to a RESTful user on the device
Authorize the client to use the required network service:
¡ To establish HTTP sessions, authorize the client to use the HTTP service.
¡ To establish HTTPS sessions, authorize the client to use the HTTPS service.
3. Set up the RESTful client
Choose an existing RESTful client or develop a RESTful client software, program, or script in a programming language such as Python, Ruby, or Java.
4. Constructing RESTful requests
Construct the RESTful requests to a feature based on the API documentation for that module.
5. Connecting to the device from a RESTful client
Send requests from the RESTful client to establish HTTP or HTTPS connections with the device.
6. Integrating the validated request into the client script or program
Integrate the validated script into the client program. For example, replace the placeholders with your program variables.
7. Disconnecting the RESTful client from the device
Configuring RESTful access
Configuring RESTful access over HTTP
1. Enter system view.
system-view
2. (Optional.) Specify the service port number for RESTful access over HTTP.
restful http port port-number
By default, the service port number for RESTful access over HTTP is 80.
3. Enable RESTful over HTTP.
restful http enable
By default, RESTful over HTTP is disabled.
4. (Optional.) Configure an ACL to control TCP connections from HTTP clients.
IPv4:
http acl { advanced-acl-number | basic-acl-number }
IPv6:
http ipv6 acl { advanced-acl-number | basic-acl-number }
By default, any HTTP clients can establish TCP connections to the device.
Configuring RESTful over HTTPS
1. Enter system view.
system-view
2. (Optional.) Specify the service port number for RESTful access over HTTPS.
restful https port port-number
By default, the service port number for RESTful access over HTTPS is 443.
3. Enable RESTful over HTTPS.
restful https enable
By default, RESTful over HTTPS is disabled.
4. (Optional.) Configure an ACL to control TCP connections from HTTPS clients.
IPv4:
https acl { advanced-acl-number | basic-acl-number }
IPv6:
https ipv6 acl { advanced-acl-number | basic-acl-number }
By default, any HTTPS clients can establish TCP connections to the device.
Assigning access permissions to a RESTful user on the device
To configure and maintain the device from a RESTful client, make sure the user account used by the RESTful client has the required operation permissions.
About RESTful user access permissions
Comware uses the role-based access control model (RBAC) to control access to the system by user role.
The REST APIs are built on top of NETCONF. You must assign access permissions to RESTful clients through the role-based access control (RBAC) module based on the NETCONF requirements. For the device to execute a RESTful request, make sure the client has sufficient access permissions at the following levels.
· Protocol level permission—Controls the privilege to execute RPC operations. Table 3 shows the mappings between RESTful operations and NETCONF RPC operations.
Table 3 RESTful operations and NETCONF RPC mappings
|
RESTful operations |
NETCONF RPC operations |
Required access to the path |
|
GET |
rpc/get |
read |
|
POST |
rpc/edit-config: create |
write |
|
POST |
rpc/action |
execute |
|
PUT |
rpc/edit-config: merge |
write |
|
DELETE |
rpc/edit-config: delete |
write |
· Module level permission—Controls access to modules and their tables, rows, groups, and columns. For example, to assign a client read, write, and execute access to the resources of the interface module, execute the rule number permit read write execute xml-element ifmgr/ command.
· Instance level permission—Controls access to instances of an object, such as a interface, or VLAN.
For the device to execute a request, make sure the client has sufficient access permissions at the protocol, module, and instance levels.
For example, assign a RESTful client the following permissions:
· Protocol level—Write access to the rpc/edit-config/config/top path.
· Module level—Write access to the Ifmgr/Interfaces/Interface table.
· Instance level—Write access to the interface with an interface index of 3.
#
role name restful
rule 1 permit write xml-element rpc/edit-config/config/top
rule 2 permit write xml-element ifmgr/interfaces/interface
interface policy deny
permit interface GigabitEthernet2/0/1
#
Comware 7 predefines a set of user roles. The following are the most commonly used ones:
· Predefined user roles network-admin have full access to all features and resources on the device, except for the display security-logfile summary, info-center security-logfile directory, and security-logfile save commands for security log file management.
· By default, predefined user roles network-operator have read access to all features and execute access to some of the features on the device. You can manually assign other permissions to these user roles as needed.
· You can also use other predefined user roles and configure custom user roles for granular functionality and resource access control.
Configure access permissions for user roles as needed and assign user roles to users to control their access to the device.
Configuring user role rules for a RESTful client
1. Enter system view.
system-view
2. Create a user role and enter its user role view.
role name role-name
3. Enable access to specified <rpc> elements in XML.
rule number permit { execute | read | write } * xml-element rpc/
To view the list of supported RPC operations, execute the rule number permit { execute | read | write } * xml-element rpc/? command. If you do not specify an operation, the rule permits all RPC operations.
4. Configure access to a module or table in XML elements.
rule number { deny | permit } { execute | read | write } * xml-element [ module-xpath ]
To view the list of modules, execute the rule number { deny | permit } { execute | read | write } * xml-element ? command. To view the list of tables in a module, execute the rule number { deny | permit } { execute | read | write } * xml-element module-name/? command. If you do not specify a module or table, the rule applies to all modules or tables in a module, respectively.
5. Configure resource access policies.
¡ Execute the following commands in sequence to configure the interface policy.
interface policy deny
By default, the interface policy of the user role permits access to all interfaces.
|
|
CAUTION: This command denies the user role access to any interfaces if you do not specify accessible interfaces by using the permit interface command. |
permit interface interface-list
By default, a user role does not have access to any interfaces.
Repeat this step to add accessible interfaces.
¡ Execute the following commands in sequence to configure the VLAN policy.
vlan policy deny
By default, the VLAN policy of the user role permits access to all VLANs.
|
|
CAUTION: This command denies the user role access to any VLANs if you do not specify accessible VLANs by using the permit vlan command. |
permit vlan vlan-id-list
By default, no accessible VLANs are configured in VLAN policy view.
Repeat this step to add additional accessible VLANs.
Configuring a RESTful user
About this task
In the user account for a RESTful client, configure the following settings:
· Enable network services for the user account depending on the RESTful access method. To run RESTful over HTTP, enable HTTP service. To run RESTful over HTTPS, enable HTTPS service.
· Assign the user role or user roles to the client.
The following information uses local authentication for example to describe the configuration procedure. For information about the configuration procedure for remote authentication, see AAA configuration in the set of configuration guides for the software release running on the device.
Procedure
1. Enter system view.
system-view
2. Create a local device management user account and enter its view.
local-user user-name class manage
3. Set a password for the user.
password [ { hash | simple } string ]
By default the password setting is optional..
4. Assign services to the user.
service-type { http | https } *
By default, none of the services are available for a local user.
5. Assign a user role to the user.
authorization-attribute user-role role-name
Constructing RESTful requests
About REST API references
Every REST-capable feature has an API reference named in Comware XXX REST API Reference format, where XXX represents the module name.
The REST API reference for a module contains the following sections:
· Resource summary for the module. As shown in Figure 2, the resource summary table provides high-level information about the module's resources, including its resource names, base URLs, and supported methods (operations).
Figure 2 Example of the resource summary for a feature module
· Detailed information about a resource, including its resource description and properties table.
¡ Resource description: Provides a brief description of the resource and its global constraints, as shown in Figure 3.
Figure 3 Example of a resource description
¡ Properties table: Provides detailed information about each property of the resource, including their column names, descriptions, data types, and constraints, as shown in Figure 4.
Figure 4 Example of a properties table
|
|
NOTE: · Unless otherwise stated, the column names in GET operation results match those in the properties tables for each module. · Comware REST API references provide information about the complete set of modules and resources. Support for these modules and resources varies by device model. |
Using REST API references to construct RESTful requests
A RESTful request message (HTTP/HTTPS request) consists of a request line, request headers, and a request body (HTTP Body). Construct the following parts of a request message in compliance with the REST API references and follow the HTTP standard to construct the remaining parts.
· The value for the resource-locator argument in the api/v1/resource-locator segment of the URL represents the base URL of the target resource.
· Construct the request data in the request body based on the properties tables in the applicable REST API reference.
To construct a RESTful request:
1. Identify the module to which the target resource belongs, and then locate the REST API reference for that module.
2. In the REST API reference, identify the base URL for the target resource in the resource summary for the module. Construct the RESTful request URL with the base URL. For example, to create a VLAN on device 10.1.1.1 via HTTP, send the request to the URL at http://10.1.1.1/api/v1/VLAN/VLANs.
3. In the REST API reference, identify the
properties table for the target resource. Construct the request data based on
the columns in this table. Encode the data in JSON format and include it in the
request body.
For example, to create VLAN 10 with a description of VLAN10 on the
interface at index 1000 on the device, use the following request body:
{
"ID": "10",
"Description": "VLAN 10"
"AccessPortList": "1000"
}
4. Construct a RESTful request message by using the URL address, request body, and HTTP standard headers.
Connecting to the device from a RESTful client
After you set up the device, configure the client to send RESTful requests with a JSON payload to the device at the URL in http://deviceIP:[portNum]/api/v1/ or https://deviceIP:portNum/api/v1/ format. For example, if the device address is 192.168.1.1, the request destination URL will be one of the following:
· In HTTP: http://192.168.1.1/api/v1/
· In HTTPS: https://192.168.1.1:443/api/v1/
|
|
NOTE: · When you specify the HTTP or HTTPS URL, you must retain the ending forward slash (/). · By default, the service port is 80 and 443 for REST service over HTTP and REST service over HTTPS, respectively. To change the port number, see "Configuring RESTful access." |
When a RESTful client sends a login request to establish a connection with the device, use the following format for the login request message:
POST http://192.168.100.91/api/v1/tokens HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: Basic dGVzdDp0ZXN0
Content-Type: application/json
Content-Length: 0
Host: 192.168.100.91
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
The following is a sample response message from the device:
HTTP/1.1 201 Created
Content-Type: application/json charset=UTF-8
Server: HTTPD
Date: Fri, 12 Jun 2015 11:43:38 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
{
"token-id": "40000142841c72b5d700bc67a55ae1f2567e",
"link": "http://192.168.100.91/api/v1/tokens/40000142841c72b5d700bc67a55ae1f2567e",
"expiry-time": "11:43:44"
}
In the request message above, the value in the Authorization field is calculated by using the standard HTTP basic authentication method.
This method calculates a value for authorization as follows:
1. Add a colon (:) between the username and password.
2. Encode the resulting character string in Base64.
For example, the username is Aladdin and the password is open sesame. The system combines them into the Aladdin:open sesame string, and then encode the combined string in Base64 to get an authorization value of QWxhZGRpbjpvcGVuIHNlc2FtZQ==.
The client must obtain the token ID from the response and then send subsequent requests with the token-id in the X-Auth-Token header. The following is a sample request to retrieve the configuration for the LogHosts resource:
GET http://192.168.100.91/api/v1/Syslog/LogHosts?index=Address%3D1.1.1.1%3BVRF%3Da HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001b81dbfc50884818f45b686fd81ceaa
Host: 192.168.100.91
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
The following is the sample response message for the above request:
HTTP/1.1 200 OK
Content-Type: application/json charset=UTF-8
Server: HTTPD
Date: Fri, 12 Jun 2015 13:28:24 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
{"LogHosts":[{"Address":"192.168.1.1","VRF":"","Port":514,"Facility":184}]}
|
|
NOTE: Client developers must provide mechanisms for recovery from response exceptions in situations such as loss of connectivity and server unresponsiveness. |
Integrating the validated request into the client script or program
After you verify that a RESTful request is correct, integrate that request into the client script or program. If the client is an unattended program, design mechanisms to handle anomalies such as timeout and loss of connectivity so the program can operate correctly unattended for a long time.
Disconnecting the RESTful client from the device
Disconnect the RESTful client from the device to free up resources if the connection is no longer needed for device management.
To disconnect the RESTful client from the device, send a DELETE request to the current token's URL at api/v1/tokens/token-id.
To disconnect from the device, configure the RESTful client to send a request in the following format:
DELETE http://192.168.100.91/api/v1/tokens/400001b81dbfc50884818f45b686fd81ceaa HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001b81dbfc50884818f45b686fd81ceaa
Host: 192.168.100.91
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
The following is the sample response message for the above request:
HTTP/1.1 204 No Content
Content-Type: application/json charset=UTF-8
Server: HTTPD
Date: Fri, 12 Jun 2015 15:00:33 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
About RESTful sessions
Lifecycle of sessions
A RESTful session is created when a client sends a login request to the device. This session remains active until after the client sends a DELETE request to delete the token resource or the session times out due to inactivity.
During the lifetime of a session, one TCP connection is open for every request sent over the session. The server closes the TCP connection for a request after it sends a response for that request.
After the client receives the authentication token, the client must send every request with this authentication token to identify their source.
The session automatically closes after 10 minutes of idle time since the most recent request.
To maintain the session, configure the client to periodically send a token request identified by the token-id to the server. The server will return a response that is the same as the login response sent over the session.
Request concurrency over one session
A RESTful client can use multiple threads to send requests with the same token concurrently over one session. However the number of concurrent requests is limited. As a best practice, do not use this method for concurrency.
Maximum number of NETCONF sessions
The maximum number of RESTful sessions depends on the AAA session limit.
RESTful operations supported in Comware
Summary of RESTful operations supported in Comware
Table 4 lists the RESTful operations supported in Comware.
Table 4 RESTful operations supported in Comware
|
Category |
Operation |
Purpose |
|
Data retrieval |
GET |
Retrieves data from the device. |
|
Data creation |
POST |
Creates configuration data that does not exist in the system. |
|
Data update |
PUT |
Modifies the configuration data in the system. The system creates the data if it does not exist. |
|
Data deletion |
DELETE |
Delete configuration data from the system. You can only delete resources that have been created. |
About data filters
To perform a RESTful operation only on data of interest, filter data by specifying parameters in the URL. Supported parameters include index, filter-condition, select-fields, and getbulk-count.
· Set the index parameter in index=Indexname=Value format. You must specify all index columns.
· Set the filter-condition parameter in filter-condition=condition:Name=Value format. You can enter either an indexed column or a regular column for this parameter. However, do not repeat any column listed in the index parameter.
· Set the select-fields parameter in select-fields=Name format.
· Set the getbulk-count parameter in getbulk-count=Value format. The Value field represents the number of data entries to retrieve.
Separate two indexes or filter conditions with a semicolon (;). Separate two parameters with an ampersand (&). Always include an equal sign (=) even if an index or filter condition is empty. The following is a sample data filter:
index=Indexname1=value1;indexname2=&filter-condition=Name3=Value3
GET operations
About GET operations
Use the GET operation to retrieve configuration and operational state data from the system.
The GET operation does not support specifying indexes or content filters in the HTTP body. To filter data, include the index or filter conditions as HTTP parameters in the URL.
The GET operation supports data filtering and column selection. The server returns only requested property data in the current resource.
· To filter data, use the URL parameter filter-condition to determine the matching method, such as more, notMore, less, or notLess. The default value is equal.
· To select columns, use the URL parameter select-fields.
Encode the parameter content with a method such as encodeURI. For example, the index=Address=1.1.1.1;VRF=a string might be encoded into the index=Address%3D1.1.1.1%3BVRF%3Da string. In the encoded string, the %3D substring represents an equal sign (=) and the %3B substring represents a semicolon (;).
GET operation examples
Filtering data based on indexes
Specify the index parameter in the URL to filter GET operation results. The GET operation returns only data matching the index parameter.
If an object has multiple indexes, separate each index name-value pair with a semicolon (;) in the URL, in index=index_column1=value1;index_column2=value2 format.
For example, to retrieve all columns of data for interface at index 1281 (IfIndex=1281), the client sends a request in the following format:
GET http://192.168.56.120/api/v1/Ifmgr/Interfaces?index=IfIndex%3D1281 HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001d534ee6ba9b7d4e26e65e0bfa1df9f
Host: 192.168.56.120
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
When the device receives the request, the device sends the requested data for interface at index 1281 to the client in a response in the following format:
HTTP/1.1 200 OK
Content-Type: application/json charset=UTF-8
Server: HTTPD
Date: Mon, 31 May 2021 15:48:36 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
X-XSS-Protection: 1;mode-block
X-Content-Type-Options: nosniff
{"IfIndex":1281,"Name":"M-GigabitEthernet0\/0\/0","AbbreviatedName":"MGE0\/0\/0","PortIndex":1281,"ifTypeExt":"28","ifType":"6","Description":"manage","AdminStatus":1,"OperStatus":1,"ConfigSpeed":1,"ActualSpeed":1000000,"ConfigDuplex":3,"ActualDuplex":1,"PortLayer":2,"InetAddressIPV4":"192.168.56.120","InetAddressIPV4Mask":"255.255.0.0","MAC":"78-81-C4-32-01-01","ForwardingAttributes":17,"ConfigMTU":1500,"ActualMTU":1500,"ActualBandwidth":1000000,"SubPort":false,"Interval":300,"LastChange":"0Day4Hour36Minute23Second","Actual64Bandwidth":1000000,"IPv4ProtocolStatus":1,"IPv6ProtocolStatus":0}
Retrieving specified columns of data
Specify the select-fields parameter in the
URL to make the device return only the selected columns.
To return multiple columns, separate each column with a semicolons (;), in select-fields=column1;column2;column3
format.
|
|
NOTE: Whether or not you specify index columns using the select-fields parameter, GET operations always include index columns in the returned data. |
The following information provides an example of using the select-fields parameter.
In this example, the client sends a request in the following format to retrieve the full names, abbreviated names, and indexes of all interfaces:
GET http://192.168.56.120/api/v1/Ifmgr/Interfaces?select-fields=Name%3BAbbreviatedName%3BPortIndex HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001d534ee6ba9b7d4e26e65e0bfa1df9f
Host: 192.168.56.120
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
When the device receives the request, the device sends the index, full name, and abbreviated name of each interface to the client. The following is a sample response:
HTTP/1.1 200 OK
Content-Type: application/json charset=UTF-8
Server: HTTPD
Date: Mon, 31 May 2021 15:45:15 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
X-XSS-Protection: 1;mode-block
X-Content-Type-Options: nosniff
{"Interfaces":[{"IfIndex":1281,"Name":"M-GigabitEthernet0\/0\/0","AbbreviatedName":"MGE0\/0\/0","PortIndex":1281},{"IfIndex":1409,"Name":"NULL0","AbbreviatedName":"NULL0"},{"IfIndex":1410,"Name":"InLoopBack0","AbbreviatedName":"InLoop0"},{"IfIndex":1536,"Name":"LoopBack2","AbbreviatedName":"Loop2"},{"IfIndex":1537,"Name":"LoopBack0","AbbreviatedName":"Loop0"},{"IfIndex":1601,"Name":"LoopBack1","AbbreviatedName":"Loop1"}]}
Filtering data based on columns
You can perform column-based filtering by doing an exact match, regular expression match, or conditional match.
If you use multiple types of filters together, only one of them takes effect. The device selects the filter to apply in order of exact match, regular expression match, and conditional match.
To perform column-based filtering, specify the filter-condition parameter in the URL.
· Exact match for column data filtering
To perform exact match for column
filtering, specify the filter-condition parameter in the URL.
To identify one column of interest, set the parameter in filter-condition=column_name=value
format.
To identify multiple columns of interest, separate each column name and value
pair with a semicolons (;), in filter-condition=column1=value1;column2=value2 format.
For example, to retrieve data for interface M-GigabitEthernet0/0/0, configure the client to send a request in the following format, with the filter-condition=Name=M-GigabitEthernet0/0/0 parameter included in the URL:
GET http://192.168.56.120/api/v1/Ifmgr/Interfaces?filter-condition=Name%3DM-GigabitEthernet0%2F0%2F0 HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001d534ee6ba9b7d4e26e65e0bfa1df9f
Host: 192.168.56.120
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
When the device receives the request, the device sends the data for interface M-GigabitEthernet0/0/0 to the client. The following is a sample response:
HTTP/1.1 200 OK
Content-Type: application/json charset=UTF-8
Server: HTTPD
Date: Mon, 31 May 2021 15:47:47 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
X-XSS-Protection: 1;mode-block
X-Content-Type-Options: nosniff
{"Interfaces":[{"IfIndex":1281,"Name":"M-GigabitEthernet0\/0\/0"}]}
|
|
NOTE: In this example, the URL in the request does not include the select-fields parameter. Then, the returned interface data only includes the index columns and the column specified by the filter-condition parameter, which is the Name column that contains interface name data. |
· Regular expression match for column data filtering
To filter table columns based on a
regular expression match, specify a regular expression filter in filter-condition=regExp:column_name=regex format in the URL.
To filter multiple columns based on multiple regular expressions, separate each
regular expression with a semicolon (;), in filter-condition=regExp:column1=regex1;regex:column2=regex2; format.
The following information provides an example of filtering column data with a regular expression.
In this example, the client retrieves information about interfaces with only digits and letters in their descriptions by sending a request in the following format:
GET http://192.168.56.120/api/v1/Ifmgr/Interfaces?filter-condition=regExp%3ADescription%3D%5E%5Ba-zA-Z0-9%5D*%24 HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001d534ee6ba9b7d4e26e65e0bfa1df9f
Host: 192.168.56.120
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
When the device receives the request, the device returns the interface data matching the regular expression to the client. The following is a sample response:
HTTP/1.1 200 OK
Content-Type: application/json charset=UTF-8
Server: HTTPD
Date: Mon, 31 May 2021 15:51:43 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
X-XSS-Protection: 1;mode-block
X-Content-Type-Options: nosniff
{"Interfaces":[{"IfIndex":1281,"Description":"manage"},{"IfIndex":1409,"Description":"N0U0L0L"}]}
· Conditional match for column data filtering
Regular expressions are intended for character string matching. To filter data based on logical operations on numbers, use conditional match. .
To filter column data based on a conditional match, add the condition in filter-condition=condition_command:column_name=condition_value format. If you use multiple conditions, separate each condition with a semicolons (;), in filter-condition=command1:column1=value1;command2:column2=value2 format.
Table 5 shows the conditional match commands supported for RESTful operations.
Table 5 Conditional match commands for RESTful operations
|
Greater than |
filter -condition=more:column=value |
Matches column values higher than the specified value. The specified value can be a DateTime, numeric, or string data type. |
|
Less than |
filter -condition=less:column=value |
Matches column values less than the specified value. The specified value can be a DateTime, numeric, or string data type. |
|
Not less than |
filter -condition=notLess:column=value |
Matches column values equal to or higher than the specified value. The specified value can be a DateTime, numeric, or string data type. |
|
Not greater than |
filter -condition=notMore:column=value |
Matches column values less than or equal to the specified value. The specified value can be a DateTime, numeric, or string data type. |
|
Equal to |
filter -condition=equal:column=value |
Matches column values equal to the specified value. The specified value can be a DateTime, numeric, string, OID, or BOOL data type. |
|
Not equal to |
filter -condition=notEqual:column=value |
Matches column values not equal to the specified value. The specified value can be a DateTime, numeric, string, OID, or BOOL data type. |
|
Include |
filter -condition=include:column=value |
Matches column values that contain the specified string. The specified string can be any string data type. |
|
Exclude |
filter -condition=exclude:column=value |
Matches column values that do not contain the specified string. The specified string can be any string data type. |
|
Begin with |
filter -condition=startWith:column=value |
Matches column values that start with the specified string. The specified string can be the OID or any string data type. |
|
End with |
filter -condition=endWith:column=value |
Matches column values that end with the specified string. The specified string can be any string data type. |
For example, to retrieve the names of all interfaces at an index greater than 1281, send a request in the following format from the client, with the filter-condition=more:IfIndex=1281 and select-fields=Name parameters:
GET http://192.168.56.120/api/v1/Ifmgr/Interfaces?select-fields=Name&filter-condition=more%3AIfIndex%3D1281%3B HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001d534ee6ba9b7d4e26e65e0bfa1df9f
Host: 192.168.56.120
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
When the device receives the request, the device sends the names of all interfaces with index values greater than 1281 to the client. The following is a sample response:
HTTP/1.1 200 OK
Content-Type: application/json charset=UTF-8
Server: HTTPD
Date: Mon, 31 May 2021 15:39:57 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
X-XSS-Protection: 1;mode-block
X-Content-Type-Options: nosniff
{"Interfaces":[{"IfIndex":1409,"Name":"NULL0"},{"IfIndex":1410,"Name":"InLoopBack0"},{"IfIndex":1536,"Name":"LoopBack2"},{"IfIndex":1537,"Name":"LoopBack0"},{"IfIndex":1601,"Name":"LoopBack1"}]}
Example: Using multiple parameters to filter data
In RESTful GET operations, specify the index, select-fields, and filter-condition parameters together to do multiple condition filtering.
Send the following message from the client to retrieve information about interfaces that meets the following conditions:
· The interface index value is 1281.
· The interface description contains only digits and letters.
· The device must return interface names in the response.
GET http://192.168.56.120/api/v1/Ifmgr/Interfaces?index=IfIndex%3D%201281&select-fields=Name%3B&filter-condition=regExp%3ADescription%3D%5E%5Ba-zA-Z0-9%5D*%24 HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001f430ff4fda0c5485a17934edf035e8
Host: 192.168.56.120
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
When the device receives the request, the device sends the matching interface data to the client. The following is a sample response:
HTTP/1.1 200 OK
Content-Type: application/json charset=UTF-8
Server: HTTPD
Date: Mon, 31 May 2021 15:27:05 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
X-XSS-Protection: 1;mode-block
X-Content-Type-Options: nosniff
{"IfIndex":1281,"Name":"M-GigabitEthernet0\/0\/0","Description":"manage"}
Retrieving multiple rows of data
To retrieve multiple rows of data, perform a RESTful GET operation with the getbulk-count parameter.
For example, send the following request from the client to retrieve information about three VLANs:
GET http://192.168.56.120/api/v1/VLAN/VLANs?getbulk-count=3 HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001d534ee6ba9b7d4e26e65e0bfa1df9f
Host: 192.168.56.120
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
When the device receives the request, the device sends information about VLAN 1, VLAN 2, and VLAN 3 to the client. The following is a sample response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Server: HTTPD
Date: Wed, 11 May 2022 06:56:22 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1;mode-block
X-Content-Type-Options: nosniff
{"VLANs":[{"ID":1,"Description":"VLAN 0001","Name":"VLAN 0001","Shared":false},{"ID":2,"Description":"VLAN 0002","Name":"VLAN 0002","AccessPortList":"","Shared":false},{"ID":3,"Description":"VLAN 0003","Name":"VLAN 0003","AccessPortList":"","Shared":false}]}
POST operations
About POST operations
Use a POST operation to create the specified resource. This action is equivalent to the create option for the <edit-config> operation in NETCONF.
Place the POST request content in the HTTP Body. Do not include the index parameter in the URL.
If a request is successfully executed, the server returns status code 201.
You can also use POST operations to send action requests, which are equivalent to the action operations in NETCONF. To send an action request, a RESTful client must prefix the resource URL with the /api/v1/action/ string.
You can perform a POST operation to deliver multiple rows of data.
|
|
NOTE: You cannot create global resources via POST operations. |
POST operation examples
Adding a log host for the information center
Send the following message from the client to add the log host at 1.1.1.3 to the information center on the device. Assign the log host to VPN instance b, set its service port number to 518, and set its logging facility to local7.
POST http://192.168.100.91/api/v1/Syslog/LogHosts HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001b81dbfc50884818f45b686fd81ceaa
Content-Type: application/json
Content-Length: 78
Host: 192.168.100.91
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
{
"Address": "1.1.1.3",
"VRF": "b",
"Port": 518,
"Facility": 184
}
After the device executes the request successfully, the device sends the following message to notify the client of successful creation of the log host:
HTTP/1.1 201 Created
Content-Type: application/json charset=UTF-8
Location: http://192.168.100.91/api/v1/Syslog/LogHosts?index=Address%3D1.1.1.3%3BVRF%3Db
Server: HTTPD
Date: Fri, 12 Jun 2015 14:46:33 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
Creating a VLAN
Send the following message from the client to create VLAN 2 on the device:
POST http://192.168.100.91/api/v1/VLAN/VLANs HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001b81dbfc50884818f45b686fd81ceaa
Content-Type: application/json
Content-Length: 44
Host: 192.168.100.91
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
{
"ID": "2",
"Description": "VLAN 2"
}
After the device executes the request successfully, the device sends the following message to notify the client that the VLAN has been successfully created:
HTTP/1.1 201 Created
Content-Type: application/json charset=UTF-8
Location: http://192.168.100.91/api/v1/VLAN/VLANs?index=ID%3D2
Server: HTTPD
Date: Fri, 12 Jun 2015 14:49:21 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
Clearing interface data through an action request
Send the following message from the client to clear data on the interface at index 1281:
POST http://192.168.79.167/api/v1/action/Ifmgr/Interfaces HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001fb4b7abc838fe880ad66f6b06c8bf3
Content-Type: application/json
Content-Length: 36
Host: 192.168.79.167
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
{
"IfIndex":"1281",
"Clear": ""
}
|
|
NOTE: If the HTTP body contains columns that do not require values, send them in "ColumnName": "" format, such as "Clear": "" in this example. |
After the device executes the request successfully, the device sends the following message to notify the client that it has cleared the interface data:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Location: http://192.168.79.167/api/v1/Ifmgr/Interfaces?index=IfIndex%3D1281
Server: HTTPD
Date: Fri, 17 May 2019 06:29:31 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
X-Frame-Options: SAMEORIGIN
Creating a list of VLANs through an action request
Send the following message from the client to create a VLAN list that contains VLAN 34 on the device:
POST http://192.168.79.167/api/v1/action/VLAN/BatchVlans HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001ffb29850dbb0763f29851bb4efa97a
Content-Type: application/json
Content-Length: 54
Host: 192.168.79.167
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
{
"CreateVlanList": "34"
}
After the device executes the request successfully, the device sends the following message to notify the client that it has successfully created the VLAN list:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Server: HTTPD
Date: Fri, 17 May 2019 06:51:20 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
X-Frame-Options: SAMEORIGIN
{ "CreateVlanList":"34" }
Adding log hosts in bulk to the information center
Send a message from the client to add the following two log hosts on the device:
· Log host 1 is located at 1.1.1.5 in VPN instance aaa, and it uses logging facility local7 to receive logs at service port 515.
· Log host 1 is located at 1.1.1.6 in VPN instance aaa, and it uses logging facility local7 to receive logs at service port 515.
POST http://192.168.56.101/api/v1/Syslog/LogHosts HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 4000019cb383a71c5781ce33cc2feaf8e4d1
Content-Type: application/json;charset=UTF-8
Content-Length: 223
Host: 192.168.56.101
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
{"LogHosts": [
{
"Address": "1.1.1.5",
"VRF": "aaa",
"Port": 515,
"Facility": 184
},
{
"Address": "1.1.1.6",
"VRF": "aaa",
"Port": 515,
"Facility": 184
}
]}
After the device executes the request successfully, the device sends the following message to notify the client that both log hosts have been successfully created:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Server: HTTPD
Date: Thu, 09 Dec 2021 05:26:18 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
X-Frame-Options: SAMEORIGIN
{"LogHosts":[{"Address":"1.1.1.5","VRF":"aaa","Port":515,"Facility":184,"Format":0},{"Address":"1.1.1.6","VRF":"aaa","Port":515,"Facility":184,"Format":0}]}
PUT operations
About PUT operations
Use the PUT operation to modify an existing resource, which is equivalent to the merge action in the NETCONF edit-config operation.
If the specified resource exists, the operation modifies it. If the resource does not exist, the operation creates it.
After successfully executing the PUT operation, the device returns a 204 response.
When you perform a PUT operation, use the following restrictions and guidelines:
· Specify index columns in the index parameter of the URL and make sure their values match the index column values in the HTTP Body.
· Specify the index parameter in a PUT operation in index=Indexname1=value1;indexname2=value2 format, which is the same as in a GET operation. Encode the parameter content by using encodeURI or any other valid method.
PUT operation examples
Creating or changing log host information in the information center
Send the following message from the client to create a log host on the device or modify existing log host information:
PUT http://192.168.1.1:80/api/v1/Syslog/LogHosts
X-Auth-Token: 1000028562945fa49b19199a71a01f33d609
{
“Loghosts”:[
{“Address”:”1.1.1.1”, “VFR”:””, “Port “:514, “Facility”: 192 },
]}
After the device executes the request successfully, the device sends the following message to notify the client that the operation has succeeded. In this example, the log host did not exist on the device, so the device created it.
204 No Content
Modifying the description of an interface
Send the following message from the client to modify the description of the interface at index 3 on the device:
PUT http://192.168.100.91/api/v1/Ifmgr/Interfaces?index=IfIndex%3D3 HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001b81dbfc50884818f45b686fd81ceaa
Content-Type: application/json
Content-Length: 51
Host: 192.168.100.91
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
{
"IfIndex":3,
"Description": "Interface 3"
}
|
|
NOTE: The index parameter in the URL must match the value of the index column in the HTTP body. In this example, both values are 3. |
After the device executes the request successfully, the device sends the following message to notify the client that the interface description has been successfully modified:
HTTP/1.1 204 No Content
Content-Type: application/json charset=UTF-8
Server: HTTPD
Date: Fri, 12 Jun 2015 14:26:10 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
DELETE operations
About DELETE operations
Use the DELETE operation to remove specified resources. It is equivalent to the <edit-config> operation performed with the delete option in NETCONF.
Do not include an HTTP body in DELETE requests.
Do not execute DELETE operations on non-creatable resources. The system returns a 405 Method Not Allowed error if you attempt to delete such resources.
When you execute a DELETE operation on a creatable resource, specify the index of the target resource in the URL's index parameter. The device deletes all properties of the resource at the specified index upon receiving the DELETE request. If the resource does not exist or cannot be deleted, the device returns a 409 Conflict error.
Specify the index parameter in a DELETE operation in index=Indexname1=value1;indexname2=value2 format, which is the same as in a GET operation. Encode the parameter content by using encodeURI or any other valid method.
DELETE operation examples
Take the Syslog/LogHosts resource for example. To delete the log host at 1.1.1.1 in a VPN instance, send the following request from the client:
DELETE http://192.168.100.91/api/v1/Syslog/LogHosts?index=Address%3D1.1.1.1%3BVRF%3Da HTTP/1.1
Accept-Encoding: gzip,deflate
X-Auth-Token: 400001b81dbfc50884818f45b686fd81ceaa
Host: 192.168.100.91
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
After the device executes the request successfully, the device sends the following message to notify the client that the log host has been deleted:
HTTP/1.1 204 No Content
Content-Type: application/json charset=UTF-8
Server: HTTPD
Date: Fri, 12 Jun 2015 14:07:50 GMT
Connection: Keep-Alive
Transfer-Encoding: chunked
Examples: Using Postman for REST-based device configuration and management
Postman is a widely used API testing tool. You can use Postman as a RESTful client to configure and manage Comware devices. The following information provides examples to show how to use Postman as a RESTful client for configuration and management of Comware devices.
Logging in to the device
Use Postman as a RESTful client to log in to the Comware device at 192.168.32.100:
1. Select File > New > HTTP Request to create a RESTful request.
Figure 5 Creating a RESTful request
2. Select the POST method and enter the target URL (in this example, http://192.168.32.100/api/v1/tokens).
Figure 6 Setting the operation method and URL for a RESTful request
3. Click the Authorization tab. Select Basic Auth for the Type field, and then enter the RESTful client's username and password in the Username and Password fields.
Figure 7 Configuring authentication parameters for a RESTful request
4. Click Send to send the RESTful request. If the device returns data as shown in Figure 8, the RESTful client has successfully logged in to the device.
Figure 8 Sending a RESTful request to log in to the device
GET operations
To execute a GET operation from Postman:
1. Select the GET method and enter the target URL. This example accesses the URL at http://192.168.32.100/api/v1/Ifmgr/Interfaces to retrieve interface data.
Figure 9 Constructing a RESTful GET request
2. Add the X-Auth-Token header and its value to the Headers field. Set the value to the token-id received upon a successful login to the device.
Figure 10 Setting the X-Auth-Token header
3. Click Send to send the RESTful request for interface data retrieval.
Figure 11 Retrieving interface data
POST operations
To execute a POST operation from Postman:
1. Select the POST method and enter the target URL. This example accesses the URL at http://192.168.32.100/api/v1/Syslog/LogHosts to add a log host to the information center on the device.
Figure 12 Constructing a RESTful POST request
2. Add the X-Auth-Token header and its value to the Headers field. Set the value to the token-id received upon a successful login to the device. Add the Content-Type header in the Headers field and select application/json as its value.
Figure 13 Setting the headers field for a RESTful request
3. On the Body tab, set the parameters to create a log host.
Figure 14 Set the log host parameters in the body of the RESTful request.
4. Click Send to send the RESTful request for log host creation.
Figure 15 Creating a log host
PUT operations
To execute a PUT operation from Postman:
1. Select the PUT method and enter the target URL. This example accesses the URL at http://192.168.32.100/api/v1/Ifmgr/Interfaces?index=IfIndex%3DM-GigabitEthernet0%2F0%2F0 to change the description of the specified interface.
Figure 16 Constructing a RESTful PUT request
2. Add the X-Auth-Token header and its value to the Headers field. Set the value to the token-id received upon a successful login to the device. Add the Content-Type header in the Headers field and select application/json as its value.
3. On the Body tab, set the parameters to change the description of the specified interface.
Figure 17 Setting the parameters for modifying the interface description in the body of the RESTful request
4. Click Send to send the RESTful request for modifying the interface description.
Figure 18 Modifying the description of an interface
DELETE operations
To execute a DELETE operation from Postman:
1. Select the DELETE method and enter the target URL. This example accesses the URL at http://192.168.32.100/api/v1/Syslog/LogHosts?index=Address%3D1.1.1.3%3BVRF%3Db to delete the log host created on the device in the previous example.
Figure 19 Constructing a RESTful DELETE request
2. Add the X-Auth-Token header and its value to the Headers field. Set the value to the token-id received upon a successful login to the device.
3. Click Send to send the RESTful request to delete the log host.
Figure 20 Deleting an existing log host
Example: Developing a client in Python
Prerequisites
Python is a widely used scripting language. The following information describes how to develop a RESTful client program in Python. The provided code examples cover basic RESTful operations.
To develop a RESTful client program in Python, make sure you have the following expertise and skills:
· REST basics.
· HTTP basics.
· Python programming language.
Example: Logging in to the device
The following coding example uses the requests module in Python for logging in to a Comware device as a RESTful client:
def restful_login():
"""
Log in to the REST API URL for the device to obtain a token ID.
"""
url = 'http://192.168.32.100/api/v1/tokens'
"""
Fill in the HTTP headers field with the Authorization header set to standard HTTP Basic authentication.
"""
headers = {"Authorization":"Basic YWRtaW46YWRtaW4=","Content-type":"application/json","Accept": "application/json"}
"""
Log in to the device
"""
req = requests.post(url, headers=headers)
"""
Output the results in JSON format
"""
return req.json()
After the RESTful client executes the login
code to send a request to the Comware device, the RESTful client will receive
the token ID returned by the device.
In subsequent requests, the RESTful client must include this token ID in the
X-Auth-Token header.
Example: Performing a GET operation
The following Python code example performs a GET operation to retrieve interface data:
def restful_get():
"""
The URL at which interface data of interest is located
"""
url = 'http://192.168.32.100:/api/v1/Ifmgr/Interfaces'
tokenJson = restful_login()
"""
Retrieve the token ID from the login response data
"""
for key,value in tokenJson.items():
if key == 'token-id':
token = value
"""
Set the value for the X-Auth-Token header in the Headers field to the token ID from the login response data
"""
headers = {"X-Auth-Token":token,"Content-type":"application/json","Accept": "application/json"}
"""
Retrieve interface data
"""
req = requests.get(url, headers=headers)
print(req.json())
Example: Performing a POST operation
The following Python code example performs a POST operation to create a log host:
def restful_post():
"""
URL for creation of a log host
"""
url = 'http://192.168.32.100:/api/v1/Syslog/LogHosts '
"""
JSON-encoded parameters contained in the body for log host creation
"""
values = {"Address": "1.1.1.3","VRF": "b","Port": 518,"Facility": 184}
"""
Use the JSON module to convert data into a standard JSON string and extract the token ID from the login response
"""
param = json.dumps(values)
tokenJson = restful_login()
for key,value in tokenJson.items():
if key == 'token-id':
token = value
"""
Set the value for the X-Auth-Token header in the Headers field to the token ID from the login response data
"""
headers = {"X-Auth-Token":token,"Content-type":"application/json","Accept": "application/json"}
"""
Create the log host
"""
req = requests.post(url, data=param, headers=headers)
print(req.status_code)
Example: Performing a PUT operation
The following Python code example performs a PUT operation to edit the interface description:
def restful_put():
"""
URL at which the interface description to be edited is located. Make sure you include the index in the URL
"""
url = 'http://192.168.32.100:/api/v1/Ifmgr/Interfaces?index=IfIndex%3DM-GigabitEthernet0%2F0%2F0'
"""
JSON-encoded new interface description in the request body
"""
values = {"IfIndex": "M-GigabitEthernet0/0/0", "Description": "ll"}
"""
Use the JSON module to convert data into a standard JSON string and extract the token ID from the login response
"""
param = json.dumps(values)
tokenJson = restful_login()
for key,value in tokenJson.items():
if key == 'token-id':
token = value
"""
Set the value for the X-Auth-Token header in the Headers field to the token ID from the login response data
"""
headers = {"X-Auth-Token":token,"Content-type":"application/json","Accept": "application/json"}
"""
Modify the interface description
"""
req = requests.put(url, data=param, headers=headers)
print(req.status_code)
Example: Performing a DELETE operation
The following Python code example performs a DELETE operation to delete an existing log host:
def restful_delete():
"""
URL at which the log host to be deleted is located
"""
url = 'http://192.168.32.100:/api/v1/Syslog/LogHosts?index=Address%3D1.1.1.1%3BVRF%3Da '
tokenJson = restful_login()
"""
Retrieve the token ID from the login response data
"""
for key,value in tokenJson.items():
if key == 'token-id':
token = value
"""
Set the value for the X-Auth-Token header in the Headers field to the token ID from the login response data
"""
headers = {"X-Auth-Token":token,"Content-type":"application/json","Accept": "application/json"}
"""
Delete the loghost
"""
req = requests.delete(url, headers=headers)
print(req.status_code)