/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.

Name

Type

Required

Description

name

String

Yes

Replace: Name of the replacing topology.

Rename: The topology to rename.

active

Boolean

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:

Type	Description
HTTP Code	HTTP status or error code indicating request success or failure. See HTTP status code definitions for more information.

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
    }
]

In this section: