topologies

GET

Retrieves Topologies.

Auth. Required

Yes

Roles Required

“read-only”

Permissions Required

TOPOLOGY:READ, CACHE-GROUP:READ

Response Type

Array

Request Structure

Table 430 Request Query Parameters

Name

Required

Description

name

no

Return the Topology with this name

#1042 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. 2 parents max

#1043 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. 2 parents max

#1044 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. 2 parents max

#1045 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 431 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. 2 parents max

#1046 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. 2 parents max

#1047 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 432 Request Query Parameters

Name

Required

Description

name

yes

The name of the Topology to be deleted

#1048 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

#1049 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"
        }
    ]
}