Skip to main content

/topologies

The /topologies endpoint allows you to create, retrieve and update one or more topologies.

To retrieve and delete a single existing topology, see /topologies/{topologyName}.

Back to Topologies API Endpoint Reference.

GET

Retrieves details of all active topologies.

Path parameters

The GET request takes no parameters. It returns data for all active topologies in the system.

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

description

String

Description of the topology.

active

Boolean

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

Examples

The following examples demonstrate making a GET request to the /topologies endpoint.

Request example

Example cURL GET request to return details for all active topologies:

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

Response example

Example response returning the active topology details:

[
    {
        "name": "host",
        "description": "Host-based topology",
        "active": true
    },
    {
        "name": "location",
        "description": "Location-based topology",
        "active": true
    }
]

POST

Creates one or more topologies.

Request arguments

The POST request takes the following request payload:

Name

Type

Required

Description

name

String

Yes

Name of the topology. Must be less than 256 characters.

description

String

No

Description of the topology. Must be less than 1001 characters.

active

Boolean

No

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

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

description

String

Description of the topology.

active

Boolean

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

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

Examples

The following examples demonstrate making a POST request to the /topologies endpoint.

Request example

Example cURL POST request to create two topologies named "host" and "location":

curl -X POST 'https://example.com/api/v1/topologies' \
--header 'Content-Type: application/json; charset=UTF-8' \
-u phil:password123 \
-d '[{"name":"host","description":"Host-based topology","active":true},{"name":"location","description":"Location-based topology","active":true}]'

Response example

PUT

Updates one or more topologies.

Request arguments

The PUT request takes the following request payload:

Name

Type

Required

Description

name

String

Yes

Name of the topology. Must be less than 256 characters.

You cannot update the topology name. To rename a topology use the /topologies/{topologyName}/replace endpoint.

description

String

No

Description of the topology. Must be less than 1001 characters.

active

Boolean

No

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

You cannot set a topology to inactive if it's being used to filter a Recipe.

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

description

String

Description of the topology.

active

Boolean

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

Examples

The following examples demonstrate making a PUT request to the /topologies endpoint.

Request example

Example cURL PUT request to update the descriptions of two topologies named "host" and "location":

curl -X PUT 'https://example.com/api/v1/topologies' \
--header 'Content-Type: application/json; charset=UTF-8' \
-u phil:password123 \
-d '[{"name":"host","description":"Host-based network topology","active":false},{"name":"location","description":"Location-based network topology","active":false}]'

Response example