/topologies/{topologyName}/replace

The /topologies/{topologyName}/replace endpoint allows you to replace an existing topology with another topology. This process deletes the original topology. You can use the clone and replace topologies endpoints to update a copy of an existing topology and then replace a topology with the updated version.

You can also use this endpoint to rename a topology.

Back to Topologies API Endpoint Reference.

PUT

Replaces an existing topology with another topology, or renames a topology. Provide the {topologyName} in the endpoint according to the desired function:

  • Replace: The name of the existing topology to replace.

  • Rename: The new topology name.

When a topology is replaced:

  • The original topology and its nodes and links are deleted.

  • Alerts that reference the original topology are updated to reference the replacement topology.

  • If the replacement topology is active, its processing state in the database is set to outdated. This triggers the graph analyser process to run as part of the Housekeeper Moolet. See Topology Overview for more information.

Request arguments

The PUT request takes the following request payload:

Name

Type

Required

Description

name

String

Yes

Replace: Name of the replacing topology.

Rename: The topology to rename.

active

Boolean

No

Sets the replaced or renamed topology to active (true) or inactive (false). Replaced topologies take the active status of the replacing topology by default.

Response

The PUT request returns the following response:

The request fails if any of the following are true:

  • name is being used to filter a Recipe, or does not exist.

  • {topologyName} is being used to filter a Recipe and you are trying to make it inactive.

Successful requests return a JSON object containing the following:

Name

Type

Description

name

String

Name of the topology.

description

String

Description of the topology.

active

Boolean

Whether the topology is active (true) or inactive (false).

Example

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

Request example

Example cURL PUT request to replace the "host" topology with the "host_new" topology and set its status to active:

curl -X PUT 'https://example.com/api/v1/topologies/host/replace' \
--header 'Content-Type: application/json; charset=UTF-8' \
-u phil:password123 \
-d '{"name":"host_new","active":true}'

In this example, if there is no topology named "host" the "host_new" topology is renamed "host".

Response example

Example response returning the newly replaced topology:

[
    {
        "name": "host_new",
        "description": "Host-based topology",
        "active": true
    }
]