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 268 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 nth 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 Group1

fallbackToClosest

A boolean value that defines the Fallback to Closest behavior of this Cache Group1

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 Fallbacks1

fallbackToClosest

A boolean that sets the Fallback to Closest behavior of the Cache Group1

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 Group2

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 Group2

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 Group1

fallbackToClosest

A boolean value that defines the Fallback to Closest behavior of this Cache Group1

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.