topologies

GET

Retrieves Topologies.

Auth. Required:

Yes

Roles Required:

“read-only”

Permissions Required:

TOPOLOGY:READ, CACHE-GROUP:READ

Response Type:

Array

Request Structure

Table 435 Request Query Parameters

Name

Required

Description

name

no

Return the Topology with this name

#1057 Request Example
GET /api/4.0/topologies HTTP/1.1
User-Agent: python-requests/2.23.0
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...

Response Structure

description:

A short sentence that describes the Topology.

lastUpdated:

The date and time at which this Topology was last updated, in ISO-like format

name:

The name of the Topology. This can only be letters, numbers, and dashes.

nodes:

An array of nodes in the Topology

cachegroup:

The name of a Cache Group

parents:

The indices of the parents of this node in the nodes array, 0-indexed.

#1058 Response Example
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Encoding: gzip
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 13 Apr 2020 18:22:32 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: lF4MCJCinuQWz0flLAAZBrzbuPVsHrNn2BtTozRZojEjGpm76IsXBQK5QOwSwBoHac+D0C1Z3p7M8kdjcfgIIg==
X-Server-Name: traffic_ops_golang/
Date: Mon, 13 Apr 2020 17:22:32 GMT
Content-Length: 205

{
    "response": [
        {
            "description": "This is my topology",
            "name": "my-topology",
            "nodes": [
                {
                    "cachegroup": "edge1",
                    "parents": [
                        7
                    ]
                },
                {
                    "cachegroup": "edge2",
                    "parents": [
                        7,
                        8
                    ]
                },
                {
                    "cachegroup": "edge3",
                    "parents": [
                        8,
                        9
                    ]
                },
                {
                    "cachegroup": "edge4",
                    "parents": [
                        9
                    ]
                },
                {
                    "cachegroup": "mid1",
                    "parents": []
                },
                {
                    "cachegroup": "mid2",
                    "parents": [
                        4
                    ]
                },
                {
                    "cachegroup": "mid3",
                    "parents": [
                        4
                    ]
                },
                {
                    "cachegroup": "mid4",
                    "parents": [
                        5
                    ]
                },
                {
                    "cachegroup": "mid5",
                    "parents": [
                        5,
                        6
                    ]
                },
                {
                    "cachegroup": "mid6",
                    "parents": [
                        6
                    ]
                }
            ],
            "lastUpdated": "2020-04-13 17:12:34+00"
        }
    ]
}

POST

Create a new Topology.

Auth. Required:

Yes

Roles Required:

“admin” or “operations”

Permissions Required:

TOPOLOGY:CREATE, TOPOLOGY:READ, CACHE-GROUP:READ

Response Type:

Object

Request Structure

description:

A short sentence that describes the topology.

name:

The name of the topology. This can only be letters, numbers, and dashes.

nodes:

An array of nodes in the Topology

cachegroup:

The name of a Cache Group with at least 1 server in it

parents:

The indices of the parents of this node in the nodes array, 0-indexed.

#1059 Request Example
POST /api/4.0/topologies HTTP/1.1
User-Agent: python-requests/2.23.0
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...
Content-Length: 924
Content-Type: application/json

{
    "name": "my-topology",
    "description": "This is my topology",
    "nodes": [
        {
            "cachegroup": "edge1",
            "parents": [
                7
            ]
        },
        {
            "cachegroup": "edge2",
            "parents": [
                7,
                8
            ]
        },
        {
            "cachegroup": "edge3",
            "parents": [
                8,
                9
            ]
        },
        {
            "cachegroup": "edge4",
            "parents": [
                9
            ]
        },
        {
            "cachegroup": "mid1",
            "parents": []
        },
        {
            "cachegroup": "mid2",
            "parents": [
                4
            ]
        },
        {
            "cachegroup": "mid3",
            "parents": [
                4
            ]
        },
        {
            "cachegroup": "mid4",
            "parents": [
                5
            ]
        },
        {
            "cachegroup": "mid5",
            "parents": [
                5,
                6
            ]
        },
        {
            "cachegroup": "mid6",
            "parents": [
                6
            ]
        }
    ]
}

Response Structure

description:

A short sentence that describes the topology.

lastUpdated:

The date and time at which this Topology was last updated, in ISO-like format

name:

The name of the topology. This can only be letters, numbers, and dashes.

nodes:

An array of nodes in the Topology

cachegroup:

The name of a Cache Group

parents:

The indices of the parents of this node in the nodes array, 0-indexed.

#1060 Response Example
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Encoding: gzip
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 13 Apr 2020 18:12:34 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: ftNcDRjYCDMkQM+o/szayKZriQZHGpcT0vNY0HpKgy88i0pXeEEeLGbUPh6LXtK7TvL76EgGECTzvCkcm+2LVA==
X-Server-Name: traffic_ops_golang/
Date: Mon, 13 Apr 2020 17:12:34 GMT
Content-Length: 239

{
    "alerts": [
        {
            "text": "topology was created.",
            "level": "success"
        }
    ],
    "response": {
        "description": "This is my topology",
        "name": "my-topology",
        "nodes": [
            {
                "cachegroup": "edge1",
                "parents": [
                    7
                ]
            },
            {
                "cachegroup": "edge2",
                "parents": [
                    7,
                    8
                ]
            },
            {
                "cachegroup": "edge3",
                "parents": [
                    8,
                    9
                ]
            },
            {
                "cachegroup": "edge4",
                "parents": [
                    9
                ]
            },
            {
                "cachegroup": "mid1",
                "parents": []
            },
            {
                "cachegroup": "mid2",
                "parents": [
                    4
                ]
            },
            {
                "cachegroup": "mid3",
                "parents": [
                    4
                ]
            },
            {
                "cachegroup": "mid4",
                "parents": [
                    5
                ]
            },
            {
                "cachegroup": "mid5",
                "parents": [
                    5,
                    6
                ]
            },
            {
                "cachegroup": "mid6",
                "parents": [
                    6
                ]
            }
        ],
        "lastUpdated": "2020-04-13 17:12:34+00"
    }
}

PUT

Updates a specific Topology.

Auth. Required:

Yes

Roles Required:

“admin” or “operations”

Permissions Required:

TOPOLOGY:UPDATE, TOPOLOGY:READ, CACHE-GROUP:READ

Response Type:

Object

Request Structure

Table 436 Request Query Parameters

Name

Required

Description

name

yes

The name of the Topology to be updated

description:

A short sentence that describes the Topology.

name:

The name of the Topology. This can only be letters, numbers, and dashes.

nodes:

An array of nodes in the Topology

cachegroup:

The name of a Cache Group with at least 1 server in it

parents:

The indices of the parents of this node in the nodes array, 0-indexed.

#1061 Request Example
PUT /api/4.0/topologies?name=my-topology HTTP/1.1
User-Agent: python-requests/2.23.0
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...
Content-Length: 853
Content-Type: application/json

{
    "name": "my-topology",
    "description": "The description is updated, too",
    "nodes": [
        {
            "cachegroup": "edge1",
            "parents": [
                6
            ]
        },
        {
            "cachegroup": "edge2",
            "parents": [
                6,
                7
            ]
        },
        {
            "cachegroup": "edge3",
            "parents": [
                7,
                8
            ]
        },
        {
            "cachegroup": "edge4",
            "parents": [
                8
            ]
        },
        {
            "cachegroup": "mid2",
            "parents": []
        },
        {
            "cachegroup": "mid3",
            "parents": []
        },
        {
            "cachegroup": "mid4",
            "parents": [
                4
            ]
        },
        {
            "cachegroup": "mid5",
            "parents": [
                4,
                5
            ]
        },
        {
            "cachegroup": "mid6",
            "parents": [
                5
            ]
        }
    ]
}

Response Structure

description:

A short sentence that describes the Topology.

lastUpdated:

The date and time at which this Topology was last updated, in ISO-like format

name:

The name of the Topology. This can only be letters, numbers, and dashes.

nodes:

An array of nodes in the Topology

cachegroup:

The name of a Cache Group

parents:

The indices of the parents of this node in the nodes array, 0-indexed.

#1062 Response Example
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Encoding: gzip
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 13 Apr 2020 18:33:13 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: WVOtsoOVrEWcVjWM2TmT5DXy/a5Q0ygTZEQRhbkHHUmz9dgVLK1F5Joc9jtKA8gZu8/eM5+Tqqguh3mzrhAy/Q==
X-Server-Name: traffic_ops_golang/
Date: Mon, 13 Apr 2020 17:33:13 GMT
Content-Length: 237

{
    "alerts": [
        {
            "text": "topology was updated.",
            "level": "success"
        }
    ],
    "response": {
        "description": "The description is updated, too",
        "name": "my-topology",
        "nodes": [
            {
                "cachegroup": "edge1",
                "parents": [
                    6
                ]
            },
            {
                "cachegroup": "edge2",
                "parents": [
                    6,
                    7
                ]
            },
            {
                "cachegroup": "edge3",
                "parents": [
                    7,
                    8
                ]
            },
            {
                "cachegroup": "edge4",
                "parents": [
                    8
                ]
            },
            {
                "cachegroup": "mid2",
                "parents": []
            },
            {
                "cachegroup": "mid3",
                "parents": []
            },
            {
                "cachegroup": "mid4",
                "parents": [
                    4
                ]
            },
            {
                "cachegroup": "mid5",
                "parents": [
                    4,
                    5
                ]
            },
            {
                "cachegroup": "mid6",
                "parents": [
                    5
                ]
            }
        ],
        "lastUpdated": "2020-04-13 17:33:13+00"
    }
}

DELETE

Deletes a specific Topology.

Auth. Required:

Yes

Roles Required:

“admin” or “operations”

Permissions Required:

TOPOLOGY:DELETE, TOPOLOGY:READ, CACHE-GROUP:READ

Response Type:

undefined

Request Structure

Table 437 Request Query Parameters

Name

Required

Description

name

yes

The name of the Topology to be deleted

#1063 Request Example
DELETE /api/4.0/topologies?name=my-topology HTTP/1.1
User-Agent: python-requests/2.23.0
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...
Content-Length: 0

Response Structure

#1064 Response Example
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Encoding: gzip
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 13 Apr 2020 18:35:32 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: yErJobzG9IA0khvqZQK+Yi7X4pFVvOqxn6PjrdzN5DnKVm/K8Kka3REul1XmKJnMXVRY8RayoEVGDm16mBFe4Q==
X-Server-Name: traffic_ops_golang/
Date: Mon, 13 Apr 2020 17:35:32 GMT
Content-Length: 87

{
    "alerts": [
        {
            "text": "topology was deleted.",
            "level": "success"
        }
    ]
}