Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Managing Clusters Using REST APIs

The management console provides REST APIs that you can use to programmatically access much of the console’s functionality. Among the operations that you can request with the REST APIs are operations related to managing clusters. This includes creating, removing and getting information about a cluster as well as starting, stopping, and restarting applications in a cluster.

See Using the Management Console APIs for an overview of the REST APIs, including a basic example of use, and a summary of returned status codes and error handling codes.

This page provides a brief description of each REST API for cluster management, an HTTP method to invoke the API, and a usage example. The examples show how to invoke the API using cURL, the command line HTTP tool. The notation \{mmc base} refers to the console base address.

Note: The notation \{mmc base} refers to the console base address. The console base address used in the examples is http://localhost:8080/mmc and configured with the default username and password (admin:admin).

The table below summarizes the REST APIs for cluster management:

Task Resource Description HTTP Invocation Method

Get Clusters

\{mmc base}/api/clusters

Returns a list of all clusters

GET

Get information About a Cluster

\{mmc base}/api/clusters/<cluster>

Returns information about a specific cluster

GET

Create a Cluster

\{mmc base}/api/clusters

Creates a cluster comprised of the specified servers

POST

Stop a Cluster

\{mmc base}/api/clusters/<cluster>/stop

Stops a cluster

POST

Restart a Cluster

\{mmc base}/api/clusters/<cluster>/restart

Restarts a cluster

POST

Disband a Cluster

\{mmc base}/api/clusters/<cluster>

Disband a cluster

DELETE

List Applications in a Cluster

\{mmc base}/api/clusters/<cluster>/applications

Lists the applications running in a cluster

GET

Start an Application in a Cluster

\{mmc base}/api/clusters/<cluster>/applications/<application>/start

Starts an application in a cluster

POST

Stop an Application in a Cluster

\{mmc base}/api/clusters/<cluster>/applications/<application>/stop

Stops an application in a cluster

POST

Restart an Application in a Cluster

\{mmc base}/api/clusters/<cluster>/applications/<application>/restart

Restarts an application in a cluster

POST

Get Clusters

Returns a list of all the clusters.

HTTP Method:

GET

URL:


         
      
1
http://{mmc base}/api/clusters

Example:

Request:


         
      
1
curl --basic -u admin:admin http://localhost:8080/mmc/api/clusters

Response:


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "data": [
        {
            "clusterStatus": "OK",
            "deployments": [],
            "groupIds": [],
            "id": "6ab68dd4-1777-4681-ab22-e1f2e291b2d5",
            "lastRestarted": 1314980993138,
            "location": "N/A",
            "name": "rel",
            "nodeServerIds": [
                "local$cf6e2ba3-eb96-4d93-822a-9314acf36d32",
                "local$af7dbb22-bad8-4334-9f65-e42b597c23fb"
            ],
            "nodesUpCount": 2,
            "pausedServices": 0,
            "runningServices": 0,
            "status": "2 of 2 nodes online",
            "stoppedServices": 0,
            "totalServices": 0,
            "version": "1"
        }
    ],
    "total": 1
}

Get Information About a Cluster

Returns information about a specific cluster.

HTTP Method:

GET

URL:


         
      
1
http://{mmc base}/api/clusters/<cluster>

Parameters:

cluster: The specified cluster ID or name.

Example:

Request:


         
      
1
curl --basic -u admin:admin http://localhost:8080/mmc/api/clusters/rel

or


         
      
1
curl --basic -u admin:admin http://localhost:8080/mmc/api/clusters/'6ab68dd4-1777-4681-ab22-e1f2e291b2d5'

Response:


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "clusterStatus": "OK",
    "deployments": [],
    "groupIds": [],
    "id": "6ab68dd4-1777-4681-ab22-e1f2e291b2d5",
    "lastRestarted": 1314980993138,
    "location": "N/A",
    "name": "rel",
    "nodeServerIds": [
        "local$cf6e2ba3-eb96-4d93-822a-9314acf36d32",
        "local$af7dbb22-bad8-4334-9f65-e42b597c23fb"
    ],
    "nodesUpCount": 2,
    "pausedServices": 0,
    "runningServices": 0,
    "status": "2 of 2 nodes online",
    "stoppedServices": 0,
    "totalServices": 0,
    "version": "1"
}

Create a Cluster

Creates a cluster comprised of the specified servers.

HTTP Method:

POST

URL:


         
      
1
http://{mmc base}/api/clusters

Parameters:

name: The name of the new cluster.
version: The version number of the new cluster.
nodes: The list of nodes to be integrated by the new cluster.

Input Fields (JSON):

name: Name of the cluster to be created.
nodes: List of server IDs that will be assigned to the new cluster. This filed requires at least one valid server ID, otherwise a message error will be displayed. If the ID does not exist, the operation will return an error message with the invalid ID.
version: version number of the cluster.

Example:

Request:


         
      
1
curl --basic -u admin:admin -d '{"name":"rel","version":"1","nodes":["local$cf6e2ba3-eb96-4d93-822a-9314acf36d32", "local$af7dbb22-bad8-4334-9f65-e42b597c23fb"]}' --header 'Content-Type: application/json' http://localhost:8080/mmc/api/clusters

Stop or Restart a Cluster

Stops or restarts the specified cluster.

HTTP Method:

POST

URL:


         
      
1
http://{mmc base}/api/clusters/<cluster>/stop

or


         
      
1
http://{mmc base}/api/clusters/<cluster>/restart

Parameters

cluster: The name or ID of the cluster to be stopped or restarted.

Example:

Request:


         
      
1
curl --basic -u admin:admin -X POST http://localhost:8080/mmc/api/clusters/rel/stop

or


         
      
1
curl --basic -u admin:admin -X POST http://localhost:8080/mmc/api/clusters/rel/restart

Disband a Cluster

HTTP Method:

DELETE

URL:


         
      
1
http://{mmc base}/api/clusters/<cluster>

Parameters:

cluster: The name or ID of the cluster.

Example:

Request:


         
      
1
curl --basic -u admin:admin -X DELETE  http://localhost:8080/mmc/api/clusters/rel

Response:

No response.

List the Applications in a Cluster

Lists all the applications in the specified cluster and their status.

HTTP Method:

GET

URL:


         
      
1
http://{mmc base}/api/clusters/<cluster>/applications

Example:

Request:


         
      
1
curl --basic -u admin:admin http://localhost:8080/mmc/api/clusters/rel/applications

Response:


         
      
1
2
3
4
5
6
7
8
9
{
    "data": [
        {
            "name": "test-app",
            "status": "STOPPED"
        }
    ],
    "total": 1
}

Start, Stop, or Restart an Application in a Cluster

HTTP Method:

POST

URL:

To Start:


         
      
1
http://{mmc base}/api/clusters/<cluster>/applications/<application>/start

To Stop:


         
      
1
http://{mmc base}/api/clusters/<cluster>/applications/<application>/stop

To Restart:


         
      
1
http://{mmc base}/api/clusters/<cluster>/applications/<application>/restart

Parameters:

cluster: The name or ID of the cluster.

application: The name of the application.

Example (similar for starting and restarting):

Request:


         
      
1
curl --basic -u admin:admin -X POST  http://localhost:8080/mmc/api/clusters/Mule/applications/test-app/stop

Response:


         
      
1
2
3
4
5
6
{
    "data": [
        "test-app"
    ],
    "total": 1
}

To check the actual status:

Request:


         
      
1
curl --basic -u admin:admin http://localhost:8080/mmc/api/clusters/Mule/applications

Response:


         
      
1
2
3
4
5
6
7
8
9
{
    "data": [
        {
            "name": "test-app",
            "status": "STOPPED"
        }
    ],
    "total": 1
}