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.
Retrieves details of all active topologies.
The GET request takes no parameters. It returns data for all active topologies in the system.
The GET request returns the following response:
Successful requests return an array of JSON objects containing the following:
Name | Type | Description |
|---|---|---|
| String | Name of the topology. |
| String | Description of the topology. |
| Boolean | Whether the topology is active ( |
The following examples demonstrate making a GET request to the /topologies endpoint.
Example cURL GET request to return details for all active topologies:
curl -X GET 'https://example.com/api/v1/topologies' -u phil:password123
Example response returning the active topology details:
[
{
"name": "host",
"description": "Host-based topology",
"active": true
},
{
"name": "location",
"description": "Location-based topology",
"active": true
}
]
Creates one or more topologies.
The POST request takes the following request payload:
Name | Type | Required | Description |
|---|---|---|---|
| String | Yes | Name of the topology. Must be less than 256 characters. |
| String | No | Description of the topology. Must be less than 1001 characters. |
| Boolean | No | Whether the topology is active ( |
The POST request returns the following response:
Successful requests return an array of JSON objects containing the following:
Name | Type | Description |
|---|---|---|
| String | Name of the topology. |
| String | Description of the topology. |
| Boolean | Whether the topology is active ( |
If you send an existing name in the request, it will be ignored and returned in the response.
The following examples demonstrate making a POST request to the /topologies endpoint.
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}]'
Updates one or more topologies.
The PUT request takes the following request payload:
Name | Type | Required | Description |
|---|---|---|---|
| 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. |
| String | No | Description of the topology. Must be less than 1001 characters. |
| Boolean | No | Whether the topology is active ( You cannot set a topology to inactive if it's being used to filter a Recipe. |
The PUT request returns the following response:
Successful requests return an array of JSON objects containing the following:
Name | Type | Description |
|---|---|---|
| String | Name of the topology. |
| String | Description of the topology. |
| Boolean | Whether the topology is active ( |
The following examples demonstrate making a PUT request to the /topologies endpoint.
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}]'