/topologies/{topologyName}/nodes

The /topologies/{topologyName}/nodes endpoint allows you to create, retrieve, update and delete one or more topology nodes.

To retrieve a single node for a topology, see /topologies/{topologyName}/nodes/{nodeName}.

Back to Topologies API Endpoint Reference.

GET

Retrieves details of all nodes for a specified topology.

Path parameters

The GET request takes the following path parameter:

Name

Type

Required

Description

 topologyName

String

Yes

Name of the topology. You can obtain all topology names by executing a GET request to /topologies.

Response

The GET request returns the following response:

Successful requests return an array of JSON objects containing the following:

Name

Type

Description

name

String

Name of the node.

description

String

Description of the node.

Example

The following example demonstrates making a GET request to the /topologies/{topologyName}/nodes endpoint.

Request example

Example cURL GET request to return node details for the "host" topology:

curl -X GET 'https://example.com/api/v1/topologies/host/nodes' -u phil:password123

Response example

Example response returning the topology's node details:

[
    {
        "name": "node1",
        "description": "First node"
    },
    {
        "name": "node2",
        "description": "Second node"
    }
]

POST

Creates one or more nodes in a topology.

Request arguments

The POST request takes the following request payload:

Name

Type

Required

Description

name

String

Yes

Name of the node.

description

String

No

Description of the node.

Response

The POST request returns the following response:

Successful requests return an array of JSON objects containing the following:

Name

Type

Description

name

String

Name of the node.

description

String

Description of the node.

If you send an existing name in the request, it will be ignored and returned in the response.

Example

The following example demonstrates making a POST request to the /topologies/{topologyName}/nodes endpoint.

Request example

Example cURL POST request to create two nodes in the "host" topology:

curl -X POST 'https://example.com/api/v1/topologies/host/nodes' \
--header 'Content-Type: application/json; charset=UTF-8' \
-u phil:password123 \
-d '[{"name":"node1","description":"First node"},{"name":"node2","description":"Second node"}]'

Response example

Example response returning the new topologies:

[
    {
        "name": "node1",
        "description: "First node"
    },
    {
        "name": "node2",
        "description: "Second node"
    }
]

PUT

Updates one or more nodes in a topology. You can only update node descriptions, not node names.

Request arguments

The PUT request takes the following request payload:

Name

Type

Required

Description

name

String

Yes

Name of the topology.

description

String

No

Description of the topology.

Response

The PUT request returns the following response:

Successful requests return an array of JSON objects containing the following:

Name

Type

Description

name

String

Name of the node.

description

String

Description of the node.

Example

The following example demonstrates making a PUT request to the /topologies/{topologyName}/nodes endpoint.

Request example

Example cURL PUT request to update two nodes in the "host" topology named "node1" and "node2":

curl -X PUT 'https://example.com/api/v1/topologies/host/nodes' \
--header 'Content-Type: application/json; charset=UTF-8' \
-u phil:password123 \
-d '[{"name":"node1","description":"Primary node"},{"name":"node2","description":"Secondary node"}]'

Response example

Example response returning the new nodes:

[
    {
        "name": "node1",
        "description: "Primary node"
    },
    {
        "name": "node2",
        "description: "Secondary node"
    }
]

DELETE

Deletes one or more nodes in a topology.

Request arguments

The DELETE request takes the following request payload:

Name

Type

Required

Description

names

Array of Strings

Yes

One or more node names in the format ["nodename1","nodename2"].

Response

The DELETE request returns the following response:

Example

The following example demonstrates making a DELETE request to the /topologies/{topologyName}/nodes endpoint.

Request example

Example cURL request to delete the "node1" and "node2" nodes in the "host" topology:

curl -X DELETE 'https://example.com/api/v1/topologies/host/nodes' \
-H 'Content-Type: application/json' \
-d ["node1","node2"] \
-u phil:password123

Response example