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.

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.

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.

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.

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`