December 5th, 2024

Machine translation is used partially for this article. See the Japanese version for the original article.

Introduction

In EXPRESSCLUSTER X 4.2 and later, in addition to the traditional GUI and CUI, a RESTful API is provided. By using the RESTful API, it becomes possible to easily perform operations such as getting the state, starting, stopping, and failover of the EXPRESSCLUSTER HA cluster from other applications.

As an introduction to using the RESTful API, this article explains the steps to enable the RESTful API of EXPRESSCLUSTER and simple methods to verify it. For a description of how to get and use the sample application as an example of using the RESTful API, please refer to “Part 2”.

Contents

1. About RESTful API

A RESTful API is an Application Programming Interface designed according to the principles of REST (Representational State Transfer) for web systems. RESTful API is accessible via the HTTP protocol, and has the advantage of being able to use these functions from any language such as commands and Node.js. Also, because it can specify operations and their targets via URI, commands or codes can be simplified.

The RESTful API provided by EXPRESSCLUSTER has different available features depending on the version. The RESTful API in EXPRESSCLUSTER X 5.2 provides the following features.

For details on the available APIs, please refer to the appropriate documentation for the version of EXPRESSCLUSTER X you are using.

2. Procedure to Enable RESTful API

In the default settings of EXPRESSCLUSTER, the RESTful API is disabled. Therefore, to use it, you need to install Node.js on each server that constitutes the HA cluster and then enable the RESTful API.

2.1 Installing Node.js

Download the Node.js that is compatible with the OS you are using from the following link.

For the Node.js versions that have been tested to work with EXPRESSCLUSTER, please refer to the documentation corresponding to the version of EXPRESSCLUSTER you are using. Also, if you use a newer version of Node.js that belongs to the same major version as the tested Node.js, it is expected to work. However, please ensure to verify its operation before use.

■ Windows
This time, we will use "node-v20.10.0-x64.msi". After running the installer, follow the instructions of the installation wizard. We keep the default settings for options such as the installation destination. After completing the installation of Node.js, reboot the OS.

■ Linux
This time, to use Node v20.10.0, download "node-v20.10.0-linux-x64.tar.xz" from the Node.js previous versions page and extract it to a desired location (in this article, /opt).

When installing Node.js using tar packages or nvm, make sure that the node command is accessible from the following paths. If the paths are not set correctly, the node command execution from EXPRESSCLUSTER will fail.

If the path is not set, create a symbolic link to the node command in /usr/bin/ manually. Rebooting the OS is not necessary.

Instead of installing a specific version of Node.js as mentioned above, you can use the Node.js distributed by the distribution and install it using the package management command. For example, on Red Hat Enterprise Linux, Node.js is installed using the dnf command.

2.2 Enabling RESTful API settings

After connecting to the Cluster WebUI, open "Cluster Properties" from the configuration mode and click on the "API" tab.

Turn on [Enable API Service] checkbox.
Select either HTTP or HTTPS for the [Communication Method].
In this article, we choose HTTPS. HTTPS is recommended when accessing RESTful API because it uses username and password authentication.
When choosing HTTPS for [Communication Method], it is necessary to specify the certificate file and the private key file, etc. in the "Encryption" tab. For settings in the "Encryption" tab, please refer to the past article "How to Connect to Cluster WebUI with HTTPS Using OpenSSL 3.0/3.1(Windows/Linux)".

■ Windows

Larger view

■ Linux

Larger view

After the setup is complete, apply the settings.

3. Checking the Operation

We will confirm the connection to the RESTful API using the curl command. In the case of Windows, there are two types of curl commands: curl.exe and the PowerShell version of curl. This time, we will use the curl.exe command, which can use the same options as the Linux curl command. When using the curl.exe command, you can run it from the command prompt, or explicitly specify curl.exe to run it. In the following examples, we will use curl.exe by running it from the command prompt.

3.1 Getting Server Status

For example, to get server information, run the following command:

An example of a curl.exe command corresponding to this API is as follows.

Specify the OS user and password for <user> and <password>. For <server>, specify the IP address or hostname of the server running EXPRESSCLUSTER with the API service enabled. For <port>, specify the port number on which the API service is listening (default is 29009). The option "-w '\nStatus: %{http_code}\n'" outputs the Status Code of the HTTP request response to the standard output (optional). The option "-k" skips certificate signing verification, which is unnecessary for official certificates.
Upon success, the response (in JSON format) and Status Code 200 will be output as follows. Additionally, the response "code" (the result of the API execution) will be 0, and the server names and server statuses will be set in the "servers" section.

In the event of errors such as authentication failure or invalid request URL, the Status Code at the end will be something other than 200. Additionally, the response "code" will be something other than 0, and the error message will be set in the "message".

3.2 Getting Group Resource Information

Let's try to get information about a specific group resource. The API is as follows.

An example of a curl.exe command corresponding to this API is as follows.

Similar to the previous getting server information command, the URL for calling the API is slightly different. You specify the resource name you want to get in <resource name>.
Upon success, the response (in JSON format) and Status Code 200 will be output as follows. Additionally, the response "code" (the result of the API execution) will be 0, and the "resources" will contain information such as the resource name and resource status. "type" will be the resource type, "current" will be the server on which the resource is running, and "group" will be the group to which the resource belongs.

3.3 Moving Group

We will try to execute the group move. The API is as follows.

An example of a curl.exe command corresponding to this API is as follows.

When getting information, we specified GET with the -X option, but since group movement is an operation, we specify POST. The URL for calling the API is also for group movement, and specify the group name you want to move to in <group name>. This API allows you to specify the destination by setting "target" value <target server> as the destination server in the request parameter. The request parameters are described in JSON format with the -d option. If the request parameter "target" is omitted, it will move to the next failover policy server.
When successful, the group movement starts, and the response (in JSON format) will be output as well as the Status Code 200 at the end. Also, the response "code" (API execution result) will be 0.

To confirm whether the group movement has been completed successfully, execute the command of getting group information.
The API is as follows.

An example of a curl.exe command corresponding to this API is as follows.

If the "status" of the "groups" section is "Offline Pending" or "Online Pending", it means they are in the process of moving. Once the "status" becomes "Online" and the "name" changes to the destination server's name, the group movement is complete.

3.4 Rebooting the Cluster

Finally, We will try rebooting the cluster. The API is as follows.

An example of a curl.exe command corresponding to this API is as follows.

Confirm that the cluster reboot begins upon successful completion. The execution result will output a response (in JSON format) and the Status Code 200 at the end.

Conclusion

This time, we introduced the steps to enable the RESTful API of EXPRESSCLUSTER. By using the RESTful API, you can monitor and control the cluster state in a way that is different from using the Cluster WebUI or EXPRESSCLUSTER commands. Please make use of it if you find it useful.
In “Part 2”, we introduce a sample application that utilizes a RESTful API.

If you consider introducing the configuration described in this article, you can perform a validation with the trial module of EXPRESSCLUSTER. Please do not hesitate to contact us if you have any questions.