1. Preface

1.1. Who Should Use This Guide

"EXPRESSCLUSTER® X RESTful API Reference Guide" is intended for administrators who need to configure RESTful API (hereafter referred as REST API) provided by "EXPRESSCLUSTER X", and describes the essential points on your first settings before go-live. Use this guide as a reference when you need information on REST API settings and operation.

1.2. How This Guide is Organized

  • 2. About REST API : Describes operational requirements and settings.

  • 3. API Reference : Describes REST API on getting each cluster information and operating each cluster.

  • 4. Troubleshooting : Describes troubles and solutions on installation or settings.

1.3. EXPRESSCLUSTER Documentation Set

The EXPRESSCLUSTER manuals consist of the following seven guides. The title and purpose of each guide is described below.

EXPRESSCLUSTER X Getting Started Guide

This guide is intended for all users. The guide covers topics such as product overview, system requirements, and known problems.

EXPRESSCLUSTER X Installation and Configuration Guide

This guide is intended for system engineers and administrators who want to build, operate, and maintain a cluster system. Instructions for designing, installing, and configuring a cluster system with EXPRESSCLUSTER are covered in this guide.

EXPRESSCLUSTER X Reference Guide

This guide is intended for system administrators. The guide covers topics such as how to operate EXPRESSCLUSTER, function of each module and troubleshooting. The guide is complement to the Installation and Configuration Guide.

EXPRESSCLUSTER X Maintenance Guide

This guide is intended for administrators and for system administrators who want to build, operate, and maintain EXPRESSCLUSTER-based cluster systems. The guide describes maintenance-related topics for EXPRESSCLUSTER.

EXPRESSCLUSTER X Hardware Feature Guide

This guide is intended for administrators and for system engineers who want to build EXPRESSCLUSTER-based cluster systems. The guide describes features to work with specific hardware, serving as a supplement to the Installation and Configuration Guide.

EXPRESSCLUSTER X Legacy Feature Guide

This guide is intended for administrators and for system engineers who want to build EXPRESSCLUSTER-based cluster systems. The guide describes EXPRESSCLUSTER X 4.0 WebManager, Builder, and EXPRESSCLUSTER Ver 8.0 compatible commands.

EXPRESSCLUSTER X RESTful API Reference Guide

This guide is intended for administrators and for system engineers who want to build EXPRESSCLUSTER-based cluster systems. The guide describes information on EXPRESSCLUSTER X 4.2 REST API.

1.4. Conventions

In this guide, Note, Important, Related Information are used as follows:

Note

Used when the information given is important, but not related to the data loss and damage to the system and machine.

Important

Used when the information given is necessary to avoid the data loss and damage to the system and machine.

See also

Used to describe the location of the information given at the reference destination.

The following conventions are used in this guide.

Convention

Usage

Example

Bold

Indicates graphical objects, such as fields, list boxes, menu selections, buttons, labels, icons, etc.

In User Name, type your name.
On the File menu, click Open Database.

Angled bracket within the command line

Indicates that the value specified inside of the angled bracket can be omitted.

clpstat -s [-h host_name ]

Monospace

Indicates path names, commands, system output (message, prompt, etc.), directory, file names, functions and parameters.

curl -u user:password http://10.0.0.1:29009/api/v1/cluster

bold

Indicates the value that a user actually enters from a command line.

Enter the following:
http://<IP address>:<port>/api/v1

italic

Indicates that users should replace italicized part with values that they are actually working with.

http://<IP address>:<port>/api/v1

1.5. Contacting NEC

For the latest product information, visit our website below:

https://www.nec.com/global/prod/expresscluster/

2. About REST API

2.1. Introduction

This chapter describes how to use REST API provided by "EXPRESSCLUSTER X".

Important

REST API is supported with EXPRESSCLUSTER X 4.2 or later version. Confirm your EXPRESSCLUSTER version is 4.2 or later before you use (other EXPRESSCLUSTER versions do not support REST API).

2.2. Setting Environments

REST API works on a Node.js environment. To perform REST API, EXPRESSCLUSTER API service settings are required and Node.js must be installed in all the servers composing a cluster. Before the EXPRESSCLUSTER API service is set, install Node.js in all the servers composing a cluster.

The REST API works in the following environments:

Runtime environment

Node.js 10.16.0

Node.js 10.21.0

The relationship between EXPRESSCLUSTER X and REST API versions is as follows.

EXPRESSCLUSTER X for Windows

REST API

12.20

v1.0

12.22

v1.1

12.30

v1.2

EXPRESSCLUSTER X for Linux

REST API

4.2.0-1

v1.0

4.2.2-1

v1.1

4.3.0-1

v1.2

For EXPRESSCLUSTER API service settings, refer to "EXPRESSCLUSTER X Reference Guide" > "Parameter details" > "Parameter settings ("Cluster properties")" > "API tab" and "Encryption tab".

2.3. Performing REST API

REST API provides methods to get various types of EXPRESSCLUSER status and perform cluster operation for other applications on a client. REST API works based on http requests (required request types described later) sent by other applications on a client.

EXPRESSCLUSTER API reacts on the sent requests and responds with the results or status information (JSON format). Refer to "3. API Reference" for details.

Important

To perform this REST API, a user name and password, which can be authenticated by a server with cluster configuration, are required. Refer to the "2. Authentication" below for details.

  1. Endpoint

    A base URI of the REST API endpoint is the following:

    http://<IP address>:<port>/api/v1

    IP address

    Specify an IP address of a server with EXPRESSCLUSTER Server installed.

    port

    Specify the same API HTTP port number specified on the installation (default: 29009).

    (e.g.) http://10.0.0.1:29009/api/v1

    See also

    To enable encrypted communication for accessing EXPRESSCLUSTER Server, refer to "EXPRESSCLUSTER X Reference Guide" > "Parameter details" > "Cluster properties " > "Encryption tab". Use the following example for encrypted communication.

    https://10.0.0.1:29009/api/v1

    Specify each endpoint path in the base URI described above according to "3. API Reference" in this guide.

    (e.g.) If you need to get cluster status:

    http://10.0.0.1:29009/api/v1/cluster

    Sending parameters to the specified endpoint with the GET or POST method enables you to operate each resource described in "3. API Reference" of this guide.

  2. Authentication

    With REST API, EXPRESSCLUSTER access requires the authentication. Specify a user name and password, which can be authenticated by a server with EXPRESSCLUSTER Server installed, when performing REST API.

    (e.g.) If you use curl to perform REST API:

    curl http://10.0.0.1:29009/api/v1/cluster -u user:password

    Important

    To use REST API, HTTPS is recommended for communication method, which can be configured in API service settings (HTTP is not recommended for this interface as it has weaker security protection).

2.4. Notes and Restrictions

Notes and restrictions of the REST API are as follows:

  • In REST API, the maximum number of connections is 64 per EXPRESSCLUSTER Server node.

  • If you perform REST API to operate EXPRESSCLUSTER, do not wait for the completion. You need to get the requested result of cluster operation accordingly using API for getting its status.

  • REST API cannot be canceled once performed.

  • Parallel API operations for EXPRESSCLUSTER cannot be performed. After you get the previous response, perform the next REST API.

  • If authentication failure count exceeds a configured threshold, the same connection source, user name and password cannot be used for a certain time.

  • Specify request parameters in the JSON format when you use REST API.

3. API Reference

This chapter describes two types of REST APIs for: getting each cluster information and operating each cluster.

Both of REST APIs can be performed in parallel.

In REST API, the maximum number of connections is 64 per EXPRESSCLUSTER Server node.

3.1. Getting Cluster Information with REST API

3.1.1. Getting status

Description

Get status information of a cluster.

Synopsis
GET /api/v1/cluster
Query parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

cluster

object

Cluster information

name

string

Cluster name

status

string

Cluster status

Request example (http communication, curl command)
curl -u user:password http://10.0.0.1:29009/api/v1/cluster
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        },
        "cluster": {
            "name": "cluster",
            "status": "Normal"
        }
    }
    
  • Error

    {
        "result": {
            "code": 1,
            "message": ""
        },
        "cluster": {
            "name": "",
            "status": ""
        }
    }
    

3.1.2. Getting timeout ratio

Description
Get information on the cluster timeout ratio.
It can be used in REST API v1.2 or later
Synopsis
GET /api/v1/cluster/toratio
Query parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

cluster

object

Cluster information

toratio

integer

Cluster timeout ratio

Request example (http communication, curl command)
curl -u user:password http://10.0.0.1:29009/api/v1/cluster/toratio
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        },
        "cluster": {
            "toratio": 2
        }
    }
    
  • Error

    {
        "result": {
            "code": 1,
            "message": ""
        },
        "cluster": {
            "toratio": 0
        }
    }
    

3.2. Getting Server Information with REST API

3.2.1. Getting status

Description
Get each server status.
Use the {servername} option to filter servers.
Synopsis
GET /api/v1/servers
GET /api/v1/servers/{servername}
Query parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

servers

array

Server information

name

string

Server name

status

string

Server status

Request example (http communication, curl command)
curl -u user:password http://10.0.0.1:29009/api/v1/servers
curl -u user:password http://10.0.0.1:29009/api/v1/servers/server1
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        },
        "servers": [
            {
                "name": "server1",
                "status": "Online"
            },
            {
                "name": "server2",
                "status": "Offline"
            }
        ]
    }
    
  • Error

    {
        "result": {
            "code": 1,
            "message": ""
        },
        "servers": [{
            "names": "",
            "status": ""
        }]
    }
    

3.2.2. Getting name list

Description

Get a server name list.

Synopsis
GET /api/v1/servers
Query parameter

Parameter

Type

Specified value

Description

select

string

name

filters by name

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

servers

array

Server information

name

string

Server name

Request example (http communication, curl command)
curl -u user:password http://10.0.0.1:29009/api/v1/servers?select=name
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        },
        "servers": [
            {
                "name": "server1"
            },
            {
                "name": "server2"
            }
        ]
    }
    
  • Error

    {
        "result": {
            "code": 1,
            "message": ""
        },
        "servers": [
            {
                "names": ""
            }
        ]
    }
    

3.3. Getting Group Information with REST API

3.3.1. Getting status

Description
Get each group status.
Use the {groupname} option to filter groups.
A list of names of group resources which belong in the group can be obtained in REST API v1.1 or later.
Synopsis
GET /api/v1/groups
GET /api/v1/groups/{groupname}
Query parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

groups

array

Group information

name

string

Group name

status

string

Group status

current

string

Started server name

resources

array

A list of names of group resources which belong in the group (It can be used in REST API v1.1 or later)

Request example (http communication, curl command)
curl -u user:password http://10.0.0.1:29009/api/v1/groups
curl -u user:password http://10.0.0.1:29009/api/v1/groups/failover1
REST API v1.0 Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        },
        "groups": [
            {
                "name": "failover1",
                "status": "Online",
                "current": "server1"
            },
            {
                "name": "failover2",
                "status": "Online",
                "current": "server2"
            }
        ]
    }
    
  • Error

    {
        "result": {
            "code": 1,
            "message": ""
        },
        "groups": [
             {
                "name": "",
                "status": "",
                "current": ""
             }
        ]
    }
    
REST API v1.1 Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        },
        "groups": [
            {
                "name": "failover1",
                "status": "Online",
                "current": "server1",
                "resources": [
                    {
                        "name": "fip1"
                    },
                    {
                        "name": "script1"
                    }
                ]
            },
            {
                "name": "failover2",
                "status": "Online",
                "current": "server2",
                "resources": [
                    {
                        "name": "fip2"
                    },
                    {
                        "name": "script2"
                    }
                ]
            }
        ]
    }
    
  • Error

    {
        "result": {
            "code": 1,
            "message": ""
        },
        "groups": [
             {
                "name": "",
                "status": "",
                "current": "",
                "resources": []
             }
        ]
    }
    

3.3.2. Getting name list

Description
Get a group name list.
The {groupname} is required only if the {resources} query parameter is specified.
The {resources} query parameter can be used in REST API v1.1 or later.
Synopsis
GET /api/v1/groups
GET /api/v1/groups/{groupname}
Query parameter

Parameter

Type

Specified value

Description

select

string

name

filters by name

select

string

resources

filters by a list of names of group resources which belong in the group (It can be used in REST API v1.1 or later)

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

groups

array

Group Information

name

string

Group name

resources

string

A list of names of group resources which belong in the group (It can be used in REST API v1.1 or later)

Request example (http communication, curl command)
curl -u user:password http://10.0.0.1:29009/api/v1/groups?select=name
curl -u user:password http://10.0.0.1:29009/api/v1/groups/failover1?select=resources
An example of a JSON response data when specifying the {name} query parameter
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        },
        "groups": [
            {
                "name": "failover1"
            },
            {
                "name": "failover2"
            }
        ]
    }
    
  • Error

    {
        "result": {
            "code": 1,
            "message": ""
        },
        "servers": [
            {
                "names": ""
            }
        ]
    }
    
An example of a JSON response data when specifying the {resources} query parameter
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        },
        "groups": [
            {
                "resources": [
                    {
                        "name": "fip1"
                    },
                    {
                        "name": "script1"
                    }
                ]
            }
        ]
    }
    
  • Error

    {
        "result": {
            "code": 1,
            "message": ""
        },
        "groups": [
            {
                "resources": []
            }
        ]
    }
    

3.4. Getting Group Resource Information with REST API

3.4.1. Getting status

Description
Get each group resource status.
Use the {resourcename} option to filter resources.
A name of a group in which group resources belong can be obtained in REST API v1.1 or later.
Synopsis
GET /api/v1/resources
GET /api/v1/resources/{resourcename}
Query parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

resources

array

Group Resource information

name

string

Group Resource name

type

string

Group Resource type

status

string

Group Resource status

current

string

Started server name

group

string

A name of a group in which group resources belong (It can be used in REST API v1.1 or later)

Request example (http communication, curl command)
curl -u user:password http://10.0.0.1:29009/api/v1/resources
curl -u user:password http://10.0.0.1:29009/api/v1/resources/fip1
REST API v1.0 Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        },
        "resources": [
            {
                "name": "fip1",
                "type": "fip",
                "status": "Online",
                "current": "server1"
            },
            {
                "name": "fip2",
                "type": "fip",
                "status": "Online",
                "current":"server2"
             }
        ]
    }
    
  • Error

    {
        "result": {
            "code": 1,
            "message": ""
        },
        "resources": [
            {
                "name": "",
                "type": "",
                "status": "",
                "current": ""
            }
        ]
    }
    
REST API v1.1 Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        },
        "resources": [
            {
                "name": "fip1",
                "type": "fip",
                "status": "Online",
                "current": "server1",
                "group": "failover1"
            },
            {
                "name": "fip2",
                "type": "fip",
                "status": "Online",
                "current":"server2",
                "group": "failover2"
             }
        ]
    }
    
  • Error

    {
        "result": {
            "code": 1,
            "message": ""
        },
        "resources": [
            {
                "name": "",
                "type": "",
                "status": "",
                "current": "",
                "group": ""
            }
        ]
    }
    

3.4.2. Getting name list

Description

Get a list of each group resource name.

Synopsis
GET /api/v1/resources
Query parameter

Parameter

Type

Specified value

Description

select

string

name

filters by name

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

resources

array

Group Resource information

name

string

Group Resource name

Request example (http communication, curl command)
curl -u user:password http://10.0.0.1:29009/api/v1/resources?select=name
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        },
        "resources": [
            {
                "name": "fip1"
            },
            {
                "name": "fip2"
             }
        ]
    }
    
  • Error

    {
        "result": {
            "code": 1,
            "message": ""
        },
        "resources": [
            {
                "name": ""
            }
        ]
    }
    

3.5. Getting Monitor Resource Information with REST API

3.5.1. Getting status

Description
Get each monitor resource status.
Use the {monitorname} option to filter monitors .
Synopsis
GET /api/v1/monitors
GET /api/v1/monitors/{monitorname}
Query parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

monitors

array

Monitor Resourceinformation

name

string

Monitor Resource name

type

string

Monitor Resource type

status

string

Monitor Resource status

servers

array

Server information

name

string

Server name

status

string

Monitor Resource status on a target server

Request example (http communication, curl command)
curl -u user:password http://10.0.0.1:29009/api/v1/monitors
curl -u user:password http://10.0.0.1:29009/api/v1/monitors/fipw1
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        },
        "monitors": [
            {
                "name": "fipw1",
                "type": "fip",
                "status": "Normal",
                "servers": [
                    {
                        "name": "server1",
                        "status": "Normal"
                    },
                    {
                        "name": "server2",
                        "status": "Normal"
                    }
                ]
            }
        ]
    }
    
  • Error

    {
        "result": {
            "code": 1,
            "message": ""
        },
        "monitors": [
            {
                "name": "",
                "type": "",
                "status": "",
                "servers": []
            }
        ]
    }
    

3.5.2. Getting name list

Description

Get a list of each monitor resource name.

Synopsis
GET /api/v1/monitors
Query parameter

Parameter

Type

Specified value

Description

select

string

name

filters by name

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

monitors

array

Monitor Resource information

name

string

Monitor Resource name

Request example (http communication, curl command)
curl -u user:password http://10.0.0.1:29009/api/v1/monitors?select=name
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        },
        "monitors": [
            {
               "name": "fipw1"
            },
            {
               "name": "fipw2"
            }
        ]
    }
    
  • Error

    {
        "result": {
            "code": 1,
            "message": ""
        },
        "monitors": [
            {
               "name": ""
            }
        ]
    }
    

3.6. Operating Cluster with REST API

3.6.1. Starting

Description

Start a cluster.

Synopsis
POST /api/v1/cluster/start
Request parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/start
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.6.2. Stopping

Description

Stop a cluster.

Synopsis
POST /api/v1/cluster/stop
Request parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/stop
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.6.3. Restarting

Description

Restart a cluster.

Synopsis
POST /api/v1/cluster/reboot
Request parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/reboot
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.6.4. Shutting down

Description

Shut down a cluster.

Synopsis
POST /api/v1/cluster/shutdown
Request parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/shutdown
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.6.5. Suspending

Description

Suspend a cluster.

Synopsis
POST /api/v1/cluster/suspend
Request parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/suspend
Resopnse (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.6.6. Resuming

Description

Resume a cluster.

Synopsis
POST /api/v1/cluster/resume
Request parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/resume
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.6.7. Temporarily adjusting timeout value

Description

Temporarily extend each of the following timeout values on all servers in a cluster:

  • monitor resource

  • heartbeat resource 1

  • disk agent

  • Alert synchronous service

  • Webmanager service

It can be used in REST API v1.2 or later

1

Not yet supported for kernel mode LAN heartbeat resources for Windows.

Synopsis
POST /api/v1/cluster/toratio/set
Request parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/toratio/reset
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.6.8. Initializing timeout value

Description
Reset changed timeout values to the defaults .
It can be used in REST API v1.2 or later
Synopsis
POST /api/v1/cluster/toratio/reset
Request parameter

Parameter

Type

Description

ratio

integer

Timeout ratio (1 to 10000)

If the ratio is 1, the changed timeout ratios are reset to the defaults.

time

string

Specified the extension period in minutes (m), hours (h), and days (d) (up to 30 days); e.g., 2m, 3h, 4d

This value cannot be specified if the ratio is 1.

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/cluster/toratio/set -d '{ "ratio" : 2, "time" : "3d"}'
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.7. Operating Server with REST API

3.7.1. Starting server service

Description

Start a server service

Synopsis
POST /api/v1/servers/{servername}/start
Request parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/servers/server1/start
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.7.2. Stopping server service

Description

Stop a server service.

Synopsis
POST /api/v1/servers/{servername}/stop
Request parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/servers/server1/stop
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.7.3. Restarting

Description

Restart a server.

Synopsis
POST /api/v1/servers/{servername}/reboot
Request parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/servers/server1/reboot
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.7.4. Shutting down

Description

Shut down a server.

Synopsis
POST /api/v1/servers/{servername}/shutdown
Request parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/servers/server1/shutdown
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.8. Operating Group with REST API

3.8.1. Starting

Description

Start a group.

Synopsis
POST /api/v1/groups/start
POST /api/v1/groups/{groupname}/start
Request parameter

Parameter

Type

Description

target

string

Server name where groups will be started

If {groupname} is not specified, all groups which can be started on the specified server will be started.

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/groups/start -d '{ "target" : "server1" }'
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/groups/failover1/start -d '{ "target" : "server1" }'
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.8.2. Stopping

Description

Stop a group.

Synopsis
POST /api/v1/groups/stop
POST /api/v1/groups/{groupname}/stop
Request parameter

Parameter

Type

Description

target

string

Server name where groups are started

If {groupname} is specified, it can be omitted.

If {groupname} is not specified, all groups which can be stopped on the specified server will be stopped.

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/groups/stop -d '{ "target" : "server1" }'
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/groups/failover1/stop
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.8.3. Moving

Description

Move a group.

Synopsis
POST /api/v1/groups/{groupname}/move
Request parameter

Parameter

Type

Description

target

string

Server name to which groups will move (option)

If the server name is specified, groups will move to the server.

If it is not specified, groups will move to a server based on failover policy.

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/groups/failover1/move
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/groups/failover1/move -d '{ "target" : "server1" }'
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.9. Operating Group Resource with REST API

3.9.1. Starting

Description
Start a group resource.
If the resource has group resource dependencies and some of which are stopped, they will be also started.
Synopsis
POST /api/v1/resources/{resourcename}/start
Request parameter

Parameter

Type

Description

target

string

Server name where group resources will be started.

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/resources/fip1/start -d '{ "target" : "server1" }'
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.9.2. Stopping

Description

Stop a group resource.

Synopsis
POST /api/v1/resources/{resourcename}/stop
Request parameter

None

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result Information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/resources/exec1/stop
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.10. Operation Monitor Resource with REST API

3.10.1. Resuming

Description

Resume a monitor resource.

Synopsis
POST /api/v1/monitors/{monitorname}/resume
Request parameter

Parameter

Type

Description

target

string

Server name on which a monitor resource will be resumed

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/monitors/fipw1/resume -d '{ "target" : "server1" }'
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.10.2. Suspending

Description

Suspend a monitor resource.

Synopsis
POST /api/v1/monitors/{monitorname}/suspend
Request parameter

Parameter

Type

Description

target

string

Server name on which a monitor resource will be suspended .

Status code

Successful

200

Failed

Other than 200

Response parameter

Parametetr

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/monitors/fipw1/suspend -d '{ "target" : "server1" }'
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

3.11. Requesting Script Execution with REST API

3.11.1. Requesting script operation

Description
Request script operation.
It can be used in REST API v1.2 or later
Synopsis
POST /api/v1/scripts/run
Query parameter

Parameter

Type

Description

script

string

Name of a script to be executed

The script needs to be placed in the work/trnreq directory with Windows or the work/rexec directory with Linux, below the EXPRESSCLUSTER installation directory on a target server.

target

string

IP address of the EXPRESSCLUSTER server that executes the script

timeout

integer

Timeout value of the API (optional)

Unless you specify this value, 180 (in seconds) is set.

logdir

string

File path where a detailed log for one execution request is outputted (optional)

Unless you specify this path, nothing is outputted.

Status code

Successful

200

Failed

Other than 200

Response parameter

Parameter

Type

Description

result

object

Result information

code

integer

Code information

message

string

Message information

Request example (http communication, curl command)
curl -u user:password -X POST http://10.0.0.1:29009/api/v1/scripts/run -d '{ "script" : "script.bat", "target" : "10.0.0.2", "timeout" : 60, "logdir" : "C:\tmp\script.log" }'
Response (JSON) example
  • Normal

    {
        "result": {
            "code": 0,
            "message": ""
        }
    }
    
  • Error

    {
        "result": {
            "code": 0,
            "message": "xxxxxxx."
        }
    }
    

4. Troubleshooting

Error response list for REST API

HTTP status

Message

Solution

400

The requested URL has an error.

The requested URL has an error .
Correct the specified URL and perform the API again.

401

Authentication failed.

Authentication failed.
The specified user name or password in the REST API request has an error.
Correct the user name or password and perform the API again.

403

The request has not been allowed.

The request has not been allowed.
The specified user name or password in the REST API request needs to be changed to the ones authenticated by the server specified in the REST API and perform the API again.

405

The request has an error.

The request method has an error.
Check if the specified communication method in URL is the same as the configured one, and also check if any HTTP method other than GET or POST is specified before performing the API again.

500

An error occurred while sending the request.

An error occurred while sending the request.
EXPRESSCLUSTER Server might have a problem.
Check the EXPRESSCLUSTER Server and perform the API again.

500

An error occurred while processing the request.

An error occurred while processing the request.
EXPRESSCLUSTER Server might have a problem.
Check the EXPRESSCLUSTER Server and perform the API again.

500

An error occurred while analyzing the response data.

An error occurred while analyzing the response data.
Wait for a while and perform the API again.