Skip to content

Topology REST interface

Get metadata about nodes

Retrieve information about all the nodes managed in WombatOAM.

Definition

1
GET /api/topo/node

Example request

1
curl -X GET "http://127.0.0.1:8080/api/topo/node"

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
[
  {
    "id": "298548c9-f5f8-464d-9a2c-07d494c3ecd4",
    "name": "wombat@127.0.0.1",
    "node_family_id": "01a85d4a-7af3-43bd-b96e-21f0ffbc2e3b",
    "host": "undefined",
    "cookie": "wombat",
    "domain_id": "undefined",
    "state": "UP",
    "tref": "undefined",
    "deleted": false,
    "plugins_opts": []
  },
  {...},
  {...}
]

Arguments

None.

Returns

An array of node objects.

Get metadata about node families

Retrieve information about all the managed families of nodes in WombatOAM.

Definition

1
GET /api/topo/node-family

Example request

1
curl -X GET "http://127.0.0.1:8080/api/topo/node-family"

Example 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
[
  {
    "id": "823f293e-ba72-43b0-a4cf-e8be08d68f22",
    "name": "OTP  APN 181 01 R16B03-1",
    "description": [],
    "node_selection": "random",
    "bootstrap_strategy": [
      "wo_bootstrap_strategy",
      "none",
      []
    ],
    "bootstrap_strategy_opts": [],
    "neighbors": [],
    "nodes": [
      "95b12f74-0c45-4b38-827f-59db5e88e56c",
      "f3e198ae-aace-4755-a8c1-68dc9610a904",
      "bf1641d1-b50c-4bb0-8c1e-387713b9323f",
      "19c61bb9-9f32-4c29-9e87-cbbac74ba489"
    ],
    "plugins_opts": [],
    "deleted": false
  },
  {...},
  {...}
]

Arguments

None.

Returns

An array of node family objects.

Get more information about a node

Definition

1
GET /api/topo/node/NODE_ID

Example request

1
curl -X GET "http://10.211.55.14:8080/api/topo/node/298548c9-f5f8-464d-9a2c-07d494c3ecd4"

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "id": "298548c9-f5f8-464d-9a2c-07d494c3ecd4",
  "name": "wombat@127.0.0.1",
  "node_family_id": "01a85d4a-7af3-43bd-b96e-21f0ffbc2e3b",
  "host": "undefined",
  "cookie": "wombat",
  "domain_id": "undefined",
  "state": "UP",
  "tref": "undefined",
  "deleted": false,
  "plugins_opts": []
}

Arguments

Argument Description
node ID Required. The identifier of the node to be retrieved.

Returns

A node object if a valid identifier was provided. When requesting the identifier of a node that has been deleted, the "deleted" property will be true.

Get more information about a family

Retrieve details of a specified node family.

Definition

1
GET /api/topo/node-family/NODE_FAMILY_ID

Example request

1
curl -X GET "http://10.211.55.14:8080/api/topo/node-family/01a85d4a-7af3-43bd-b96e-21f0ffbc2e3b"

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "id": "01a85d4a-7af3-43bd-b96e-21f0ffbc2e3b",
  "name": "wombat pre-0.9.0",
  "description": [],
  "node_selection": "random",
  "bootstrap_strategy": [
    "wo_bootstrap_strategy",
    "none",
    []
  ],
  "bootstrap_strategy_opts": [],
  "neighbors": [],
  "nodes": [
    "298548c9-f5f8-464d-9a2c-07d494c3ecd4"
  ],
  "plugins_opts": [],
  "deleted": false
}

Arguments

Argument Description
node family ID Required. The identifier of the node family to be retrieved.

Returns

A node family object. When requesting the identifier of a node family that has been deleted, the "deleted" property will be true.

Add new node

Add a managed node.

Definition

1
POST /api/topo/action/add-node

Data

1
2
3
4
{
  "name": "NEW_NODE_NAME",
  "cookie": "NEW_NODE_COOKIE"
}

Example request

1
2
3
curl -X POST "http://127.0.0.1:8080/api/topo/action/add-node" \
     -H "Content-Type: application/json" \
     -d "{\"name\":\"wo_test_1@127.0.0.1\", \"cookie\":\"cookietest\"}"

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "id": "c2d750f5-b4eb-40d6-b15c-9226577c0c4d",
  "name": "wo_test_1@127.0.0.1",
  "node_family_id": "823f293e-ba72-43b0-a4cf-e8be08d68f22",
  "host": "undefined",
  "cookie": "cookietest",
  "domain_id": "undefined",
  "state": "STOPPED",
  "tref": "undefined",
  "deleted": false,
  "plugins_opts": []
}

Arguments

Argument Description
name Required. The name of the node to be added.
cookie Required. The cookie for the node to be added.

Returns

The node object. Note that, right after adding the node, the "state" may be STOPPED or DOWN.

Add new node and discover connected nodes

Add a new managed node, and discover and automatically add other nodes connected to it.

Definition

1
POST /api/topo/action/add-node-and-disc

Data

1
2
3
4
{
  "name": "NEW_NODE_NAME",
  "cookie": "NEW_NODE_COOKIE"
}

Example request

1
2
3
curl -X POST "http://127.0.0.1:8080/api/topo/action/add-node-and-disc" \
     -H "Content-Type: application/json" \
     -d "{\"name\": \"wo_test_1@127.0.0.1\", \"cookie\": \"cookietest\"}"

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
[
  {
    "id": "a2df05ae-75ba-49aa-a993-b3cfcd63a120",
    "name": "wo_test_3@127.0.0.1",
    "node_family_id": "93be4f01-dae6-49b0-9608-4552f841a720",
    "host": "undefined",
    "cookie": "cookietest",
    "domain_id": "undefined",
    "state": "STOPPED",
    "tref": "undefined",
    "deleted": false,
    "plugins_opts": []
  },
  {...},
  {...}
]

Arguments

Argument Description
name Required. The name of the node to be added.
cookie Required. The cookie for the node to be added.

Returns

The node objects for the discovered nodes. Note that, right after adding the nodes, the "state" may be STOPPED or DOWN.

Add new family

Add a node family.

Definition

1
POST /api/topo/node-family

Data

1
2
3
4
5
6
{
  "name": "NEW_FAMILY_NAME",
  "bootstrap_node_selection": "SELECTION",
  "bootstrap_strategy": "STRATEGY",
  "bootstrap_strategy_opts": [ ]
}

Example request

1
2
3
curl -X POST "http://127.0.0.1:8080/api/topo/node-family" \
     -H "Content-Type: application/json" \
     -d "{\"name\":\"new_family_name\", \"bootstrap_node_selection\":\"selection\", \"bootstrap_strategy\":\"strategy\", \"bootstrap_strategy_opts\":[]}"

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "id": "0db17632-5264-48e0-9282-7cb2db3983d6",
  "name": "new_family_name",
  "description": [],
  "node_selection": "selection",
  "bootstrap_strategy": "strategy",
  "bootstrap_strategy_opts": [],
  "neighbors": [],
  "nodes": [],
  "plugins_opts": [],
  "deleted": false
}

Arguments

Argument Description
name Required. A custom string with which to identify the node family.
bootstrap_node_selection Required. Defines how another node is selected when a new node joins the cluster. Currently the only option is random.
bootstrap_strategy Required. Determines what WombatOAM should do when it deploys a new node to the node family. The options are Distributed Erlang (WombatOAM only makes sure that the nodes are connected with each other via Erlang Distribution), and Custom (you can specify a script to be executed in bootstrap_strategy_opts).
bootstrap_strategy_opts Required. A list containing details of what should happen when a new node is deployed into the node family, for example the execution of a specified script. The list may be empty.

Returns

A node family object.

Remove node

Remove a specified node from being managed in WombatOAM.

Definition

1
DELETE /api/topo/node/NODE_ID

Example request

1
2
curl -X DELETE "http://127.0.0.1:8080/api/topo/node/a2df05ae-75ba-49aa-a993-b3cfcd63a12" \
     -H "Content-Type: application/json"

Example response

204 No Content

Arguments

Argument Description
node family ID Required. The identifier of the node to be removed.

Returns

Only the HTTP response code.

Remove family

Remove a specified node family from being managed in WombatOAM.

Definition

1
DELETE /api/topo/node-family/NODE_FAMILY_ID/force

Example request

1
curl -X DELETE "http://127.0.0.1:8080/api/topo/node_families/823f293e-ba72-43b0-a4cf-e8be08d68f22/force"

Example response

204 No Content

Arguments

Argument Description
node family ID Required. The identifier of the node family to be removed.

Returns

Only the HTTP response code.

Move a node to another family

Move a specified node to a specified node family.

Definition

1
POST /api/topo/action/move-node

Example request 1

1
2
3
curl -X POST "http://127.0.0.1:8080/api/topo/action/move-node" \
     -H "Content-Type: application/json" \
     -d "{\"node\":\"d1a4c84f-754a-4d44-9ba2-4932faf65004\", \"family\":\"33c14e1f-5e56-415f-9b2c-32ff9ed653ff\"}"

Example response 1

1
2
3
{
  "success": true
}

Example request 2

1
2
3
curl -X POST "http://127.0.0.1:8080/api/topo/action/move-node" \
     -H "Content-Type: application/json" \
     -d "{\"node\":\"d35345f-754a-4d44-9ba2-4932fgvi73y\", \"family\":\"334533f-5e56-415f-9b2c-32ff9vjhebff\"}"

Example response 2

1
2
3
4
{
  "success": false,
  "reason": "node_or_family_not_found"
}

Arguments

Argument Description
node ID Required. The identifier of the node.
node family ID Required. The identifier of the node family to move the node to.

Returns

returns an object showing the success or failure.

Rename a family

Rename a family.

Definition

1
POST /api/topo/node-family/:FamilyID/update

Example request 1

1
2
3
curl -X POST "http://127.0.0.1:8080/api/topo/node-family/:FamilyID/update" \
     -H "Content-Type: application/json" \
     -d "{\"name\":\"NewName\"}"

Example response 1

1
2
3
{
  "success": true
}

Arguments

Argument Description
node ID Required. The identifier of the node.
New Name Required. The new name of the family.

Returns

returns an object showing the success or failure.

Analyse reachability of a node

Analyse the possibility of reaching the node via Distributed Erlang.

Definition

1
POST /api/topo/action/analyse-reachability

Data

1
2
3
{
  "name": "NODE_NAME"
}

Example request 1

1
2
3
curl -X POST "http://127.0.0.1:8080/api/topo/action/analyse-reachability" \
     -H "Content-Type: application/json" \
     -d "{\"name\":\"wo_test_1@127.0.0.1\"}"

Example response 1

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "reachability": "should be reachable",
  "details": [
    {
      "checksPerformed": [
        "check_node_format",
        "check_name_type",
        "check_host_resolution",
        "check_epmd_port",
        "check_node_in_epmd",
        "check_node_dist_port"
      ]
    }
  ],
  "description": "",
  "hints": [
    "The Erlang node may have a different cookie from the one specified.",
    "The Erlang node may have been registered addressing the host in a different way than specified."
  ]
}

Example request 2

1
2
3
curl -X POST "http://127.0.0.1:8080/api/topo/action/analyse-reachability" \
     -H "Content-Type: application/json" \
     -d "{\"name\":\"name@\"}"

Example response 2

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "reachability": "is not reachable",
  "details": [
    {
      "reasonCode": "bad_node_format"
    },
    {
      "reasonDetails": "[{node,name@}]"
    }
  ],
  "description": "The node name specified name@ does not comply with the name@host format.",
  "hints": [
    "Specify a node name compliant to the name@host format."
  ]
}

Arguments

Argument Description
name Required. The name of the node to be analysed.

Returns

An object describing the reachability of the node, including the checks performed, the reason why the node might not be reachable, (if relevant), and steps the user could take (under “hints”) concerning the management of the node. The fields number_of_crashlogs_this_hour and number_of_new_alarms_raised_this_hour show the number updates on those counters between the beginning of the current hour and the current time.

Get node statistics

Return statistical information about the entire cluster.

Definition

1
GET /api/topo/node-stat

Example request

1
curl -X GET "http://10.211.55.14:8080/api/topo/node-stat"

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "number_of_nodes": 2,
  "number_of_up_nodes": 2,
  "number_of_families": 1,
  "number_of_crashlogs_this_hour": 22,
  "number_of_new_alarms_raised_this_hour": 57,
  "number_of_active_alarms": 0,
  "family_stats": [
    {
      "id": "c0dce081-89ae-458d-8465-0533a29c4037",
      "number_of_nodes": 2,
      "number_of_up_nodes": 2
    }
  ]
}

Arguments

Argument Description

Returns

Returns information about the managed nodes, containing information about the number of nodes, running nodes, managed node families, number of alarms and number of crash logs in the last one hour.