`cachegroups`

`GET`

Extract information about Cache Groups.

Auth. Required: Yes
Roles Required: None
Permissions Required: CACHE-GROUP:READ, TYPE:READ
Response Type: Array

Request Structure

Table 267 Request Query Parameters
Name	Required	Description
id	no	Return the only Cache Group that has this id
name	no	Return only the Cache Group identified by this Name
type	no	Return only Cache Groups that are of the Type identified by this integral, unique identifier
topology	no	Return only Cache Groups that are used in the Topology identified by this unique identifier
orderby	no	Choose the ordering of the results - must be the name of one of the fields of the objects in the `response` array
sortOrder	no	Changes the order of sorting. Either ascending (default or “asc”) or descending (“desc”)
limit	no	Choose the maximum number of results to return
offset	no	The number of results to skip before beginning to return results. Must use in conjunction with limit
page	no	Return the n^th page of results, where “n” is the value of this parameter, pages are `limit` long and the first page is 1. If `offset` was defined, this query parameter has no effect. `limit` must be defined to make use of `page`.

#644 Request Example

GET /api/4.0/cachegroups?type=23 HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*
Cookie: mojolicious=...

Response Structure

fallbacks: An array of strings that are Cache Group names that are registered as Fallbacks for this Cache Group 1
fallbackToClosest: A boolean value that defines the Fallback to Closest behavior of this Cache Group 1
id: An integer that is the ID of the Cache Group
lastUpdated: The time and date at which this entry was last updated in Traffic Ops’s Custom Date/Time Format
latitude: A floating-point Latitude for the Cache Group
localizationMethods: An array of Localization Methods as strings
longitude: A floating-point Longitude for the Cache Group
name: A string containing the Name of the Cache Group
parentCachegroupId: An integer that is the ID of this Cache Group’s Parent - or null if it doesn’t have a Parent
parentCachegroupName: A string containing the Name of this Cache Group’s Parent - or null if it doesn’t have a Parent
secondaryParentCachegroupId: An integer that is the ID of this Cache Group’s Secondary Parent - or null if it doesn’t have a Secondary Parent
secondaryParentCachegroupName: A string containing the Name of this Cache Group’s Secondary Parent Cache Group - or null if it doesn’t have a Secondary Parent
shortName: A string containing the Short Name of the Cache Group
typeId: An integral, unique identifier for the ‘Type’ of the Cache Group
typeName: A string that names the Type of this Cache Group

Note

The default value of fallbackToClosest is ‘true’, and if it is ‘null’ Traffic Control components will still interpret it as ‘true’.

#645 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-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: oV6ifEgoFy+v049tVjSsRdWQf4bxjrUvIYfDdgpUtlxiC7gzCv31m5bXQ8EUBW4eg2hfYM+BsGvJpnNDZB7pUg==
X-Server-Name: traffic_ops_golang/
Date: Wed, 07 Nov 2018 19:46:36 GMT
Content-Length: 379

{ "response": [
    {
        "id": 7,
        "name": "CDN_in_a_Box_Edge",
        "shortName": "ciabEdge",
        "latitude": 38.897663,
        "longitude": -77.036574,
        "parentCachegroupName": "CDN_in_a_Box_Mid",
        "parentCachegroupId": 6,
        "secondaryParentCachegroupName": null,
        "secondaryParentCachegroupId": null,
        "fallbackToClosest": [],
        "localizationMethods": [],
        "typeName": "EDGE_LOC",
        "typeId": 23,
        "lastUpdated": "2018-11-07 14:45:43+00",
        "fallbacks": []
    }
]}

`POST`

Creates a Cache Group

Auth. Required: Yes
Roles Required: “admin” or “operations”
Permissions Required: CACHE-GROUP:CREATE, CACHE-GROUP:READ, TYPE:READ
Response Type: Object

Request Structure

fallbacks: An optional field which, when present, should contain an array of strings that are the Names of other Cache Groups which will be the Fallbacks 1
fallbackToClosest: A boolean that sets the Fallback to Closest behavior of the Cache Group 1

Note

The default value of fallbackToClosest is true, and if it is null Traffic Control components will still interpret it as though it were true.
latitude: An optional field which, if present, should be a floating-point number that will define the Latitude for the Cache Group 2
localizationMethods: Array of Localization Methods (as strings)

Tip

This field has no defined meaning if the Type identified by typeId is not “EDGE_LOC”.
longitude: An optional field which, if present, should be a floating-point number that will define the Longitude for the Cache Group 2
name: The Name of the Cache Group
parentCachegroupId: An optional field which, if present, should be an integer that is the ID of a Parent for this Cache Group.
secondaryParentCachegroupId: An optional field which, if present, should be an integral, unique identifier for this Cache Group’s secondary parent
shortName: An abbreviation of the name
typeId: An integral, unique identifier for the Cache Group’s Type

Note

The actual, integral, unique identifiers for these Types must first be obtained, generally via types.

#646 Request Example

POST /api/4.0/cachegroups HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*
Cookie: mojolicious=...
Content-Length: 252
Content-Type: application/json

{
    "name": "test",
    "shortName": "test",
    "latitude": 0,
    "longitude": 0,
    "fallbackToClosest": true,
    "localizationMethods": [
        "DEEP_CZ",
        "CZ",
        "GEO"
    ],
    "typeId": 23,
}

Response Structure

fallbacks: An array of strings that are Cache Group names that are registered as Fallbacks for this Cache Group 1
fallbackToClosest: A boolean value that defines the Fallback to Closest behavior of this Cache Group 1
id: An integer that is the ID of the Cache Group
lastUpdated: The time and date at which this entry was last updated in Traffic Ops’s Custom Date/Time Format
latitude: A floating-point Latitude for the Cache Group
localizationMethods: An array of Localization Methods as strings
longitude: A floating-point Longitude for the Cache Group
name: A string containing the Name of the Cache Group
parentCachegroupId: An integer that is the ID of this Cache Group’s Parent - or null if it doesn’t have a Parent
parentCachegroupName: A string containing the Name of this Cache Group’s Parent - or null if it doesn’t have a Parent
secondaryParentCachegroupId: An integer that is the ID of this Cache Group’s Secondary Parent - or null if it doesn’t have a Secondary Parent
secondaryParentCachegroupName: A string containing the Name of this Cache Group’s Secondary Parent Cache Group - or null if it doesn’t have a Secondary Parent
shortName: A string containing the Short Name of the Cache Group
typeId: An integral, unique identifier for the ‘Type’ of the Cache Group
typeName: A string that names the Type of this Cache Group

#647 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-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: YvZlh3rpfl3nBq6SbNVhbkt3IvckbB9amqGW2JhLxWK9K3cxjBq5J2sIHBUhrLKUhE9afpxtvaYrLRxjt1/YMQ==
X-Server-Name: traffic_ops_golang/
Date: Wed, 07 Nov 2018 22:11:50 GMT
Content-Length: 379

{ "alerts": [
    {
        "text": "cachegroup was created.",
        "level": "success"
    }
],
"response": {
    "id": 8,
    "name": "test",
    "shortName": "test",
    "latitude": 0,
    "longitude": 0,
    "parentCachegroupName": null,
    "parentCachegroupId": null,
    "secondaryParentCachegroupName": null,
    "secondaryParentCachegroupId": null,
    "fallbackToClosest": true,
    "localizationMethods": [
        "DEEP_CZ",
        "CZ",
        "GEO"
    ],
    "typeName": "EDGE_LOC",
    "typeId": 23,
    "lastUpdated": "2019-12-02 22:21:08+00",
    "fallbacks": []
}}

1(1,2,3,4,5,6): Traffic Router will first check for a fallbacks array and, when that is empty/unset/all the Cache Groups in it are also unavailable, will subsequently check for fallbackToClosest. If that is true, then it falls back to the geographically closest Cache Group capable of serving the same content or, when it is false/no such Cache Group exists/said Cache Group is also unavailable, will respond to clients with a failure response indicating the problem.
2(1,2): While these fields are technically optional, note that if they are not specified many things may break. For this reason, Traffic Portal requires them when creating or editing Cache Groups.

cachegroups

GET

Request Structure

Response Structure

POST

Request Structure

Response Structure

`cachegroups`

`GET`

`POST`