/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 |
|---|---|---|
| String | Name of the topology. |
| String | Description of the topology. |
| Boolean | Whether the topology is active ( |
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 |
|---|---|---|---|
| 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 ( |
Response
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.
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 |
|---|---|---|---|
| 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. |
Response
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 ( |
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}]'