Traffic Router API

By default, Traffic Router serves its API via HTTP (not HTTPS) on port 3333. This can be configured in /opt/traffic_router/conf/server.xml or by setting a Parameter with the Name “api.port”, and the Config File “server.xml” on the Traffic Router’s Profile.

The API can be configured via HTTPS on port 3443 in /opt/traffic_router/conf/server.xml or by setting a Parameter named secure.api.port with configFile server.xml on the Traffic Router’s Profile. The post install script will generate self signed certificates at /opt/traffic_router/conf/, create a new Java Keystore named /opt/traffic_router/conf/keyStore.jks, and add the new certificate to the Keystore. The password for the Java Keystore and the Keystore location are stored in /opt/traffic_router/conf/https.properties. To override the self signed certificates with new ones from a certificate authority, update the properties for the Keystore location and password at /opt/traffic_router/conf/https.properties.

The API can be configured via HTTPS on port 3443 in /opt/traffic_router/conf/server.xml or by setting a Parameter named secure.api.port with configFile server.xml on the Traffic Router’s Profile. When systemctl start traffic_router is run, it will generate self signed certificates at /opt/traffic_router/conf/, create a new Java Keystore named /opt/traffic_router/conf/keyStore.jks, and add the new certificate to the Keystore. The password for the Java Keystore and the Keystore location are stored in /opt/traffic_router/conf/https.properties. To override the self signed certificates with new ones from a certificate authority, either replace the Java Keystore in the default location or update the properties for the new Keystore location and password at /opt/traffic_router/conf/https.properties and then restart the Traffic Router using systemctl.

Traffic Router API endpoints only respond to GET requests.

/crs/stats

General stats.

Request Structure

#148 Request Example
GET /crs/stats HTTP/1.1
Host: trafficrouter.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*

Response Structure

#149 Response Example
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 15 Jan 2019 21:02:09 GMT

{ "app": {
    "buildTimestamp": "2019-01-10",
    "name": "traffic_router",
    "deploy-dir": "/opt/traffic_router",
    "git-revision": "437e9df81",
    "version": "3.0.0"
},
"stats": {
    "dnsMap": {},
    "httpMap": {
        "video.demo1.mycdn.ciab.test": {
            "czCount": 0,
            "geoCount": 0,
            "deepCzCount": 0,
            "missCount": 0,
            "dsrCount": 0,
            "errCount": 0,
            "staticRouteCount": 0,
            "fedCount": 0,
            "regionalDeniedCount": 0,
            "regionalAlternateCount": 0
        }
    },
    "totalDnsCount": 0,
    "totalHttpCount": 1,
    "totalDsMissCount": 0,
    "appStartTime": 1547584831677,
    "averageDnsTime": 0,
    "averageHttpTime": 1547584863270,
    "updateTracker": {
        "lastHttpsCertificatesCheck": 1547586068932,
        "lastGeolocationDatabaseUpdaterUpdate": 1547584858917,
        "lastCacheStateCheck": 1547586128932,
        "lastCacheStateChange": 1547584867102,
        "lastNetworkUpdaterUpdate": 1547584857484,
        "lastHttpsCertificatesUpdate": 1547586071079,
        "lastSteeringWatcherUpdate": 1547584923514,
        "lastConfigCheck": 1547586127344,
        "lastConfigChange": 1547584863406,
        "lastNetworkUpdaterCheck": 1547584857465,
        "lastGeolocationDatabaseUpdaterCheck": 1547584858906,
        "lastFederationsWatcherUpdate": 1547584863433,
        "lastHttpsCertificatesFetchSuccess": 1547586069070,
        "lastSteeringWatcherCheck": 1547586124630,
        "lastFederationsWatcherCheck": 1547586124584,
        "lastHttpsCertificatesFetchAttempt": 1547586068932
    }
}}

/crs/stats/ip/{{IP}}

Geolocation information for an IPv4 or IPv6 address.

Request Structure

Table 83 Request Path Parameters

Name

Description

IP

The IP address for which statics will be returned. May be IPv4 or IPv6
#150 Request Example
GET /crs/stats/ip/255.255.255.255 HTTP/1.1
Host: trafficrouter.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*

Response Structure

#151 Response Example
HTTP/1.1 200 OK
Content-Disposition: inline;filename=f.txt
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 15 Jan 2019 21:06:09 GMT

{ "locationByGeo": {
    "city": "Woodridge",
    "countryCode": "US",
    "latitude": "41.7518",
    "postalCode": "60517",
    "countryName": "United States",
    "longitude": "-88.0489"
},
"locationByFederation": "not found",
"requestIp": "69.241.118.34",
"locationByCoverageZone": "not found",
"locationByDeepCoverageZone": "not found"
}

/crs/locations

A list of configured Cache Groups to which the Traffic Router is capable of routing client traffic.

Request Structure

#152 Request Example
GET /crs/locations HTTP/1.1
Host: trafficrouter.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*

Response Structure

locations

An array of strings that are the Names of Cache Groups to which this Traffic Router is capable of routing client traffic

#153 Response Example
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 15 Jan 2019 21:12:17 GMT

{ "locations": [
    "CDN_in_a_Box_Edge"
]}

/crs/locations/caches

A mapping of caches to cache groups and their current health state.

Request Structure

#154 Request Example
GET /crs/locations/caches HTTP/1.1
Host: trafficrouter.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*

Response Structure

#155 Response Example
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 15 Jan 2019 21:15:53 GMT

{ "locations": {
    "CDN_in_a_Box_Edge": [
        {
            "cacheId": "edge",
            "fqdn": "edge.infra.ciab.test",
            "ipAddresses": [
                "172.16.239.100",
                "fc01:9400:1000:8:0:0:0:100"
            ],
            "port": 0,
            "adminStatus": null,
            "lastUpdateHealthy": false,
            "lastUpdateTime": 0,
            "connections": 0,
            "currentBW": 0,
            "availBW": 0,
            "cacheOnline": true
        }
    ]
}}

/crs/locations/{{cachegroup}}/caches

A list of cache servers for this Cache Group only.

Request Structure

Table 84 Request Path Parameters

Name

Description

cachegroup

The Name of a Cache Group of which a list of constituent cache servers will be retrieved
#156 Request Example
GET /crs/locations/CDN_in_a_Box_Edge/caches HTTP/1.1
Host: trafficrouter.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*

Response Structure

#157 Response Example
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 15 Jan 2019 21:18:25 GMT

{ "caches": [
    {
        "cacheId": "edge",
        "fqdn": "edge.infra.ciab.test",
        "ipAddresses": [
            "172.16.239.100",
            "fc01:9400:1000:8:0:0:0:100"
        ],
        "port": 0,
        "adminStatus": null,
        "lastUpdateHealthy": false,
        "lastUpdateTime": 0,
        "connections": 0,
        "currentBW": 0,
        "availBW": 0,
        "cacheOnline": true
    }
]}

/crs/consistenthash/cache/coveragezone

The resulting cache of the consistent hash using coverage zone file for a given client IP, Delivery Service, and request path.

Request Structure

Table 85 Request Query Parameters

Name

Required

Description

ip

yes

The IP address of a potential client

deliveryServiceId

yes

The integral, unique identifier?/’xml_id’?/name? of a Delivery Service served by this Traffic Router

requestPath

yes

The… request path?

Response Structure

TBD

/crs/consistenthash/cache/deep/coveragezone

The resulting cache of the consistent hash using deep coverage zone file (deep caching) for a given client IP, Delivery Service, and request path.

Request Structure

Table 86 Request Query Parameters

Name

Required

Description

ip

yes

The IP address of a potential client

deliveryServiceId

yes

The integral, unique identifier?/’xml_id’?/name? of a Delivery Service served by this Traffic Router

requestPath

yes

The… request path?

Response Structure

TBD

/crs/consistenthash/cache/geolocation

The resulting cache of the consistent hash using geographic location for a given client IP, Delivery Service, and request path.

Request Structure

Table 87 Request Query Parameters

Name

Required

Description

ip

yes

The IP address of a potential client

deliveryServiceId

yes

The integral, unique identifier?/’xml_id’?/name? of a Delivery Service served by this Traffic Router

requestPath

yes

The… request path?

Response Structure

TBD

/crs/consistenthash/deliveryservice/

The resulting Delivery Service of the consistent hash for a given Delivery Service and request path – used to test STEERING Delivery Services.

Request Structure

Table 88 Request Query Parameters

Name

Required

Description

deliveryServiceId

yes

The integral, unique identifier?/’xml_id’?/name? of a Delivery Service served by this Traffic Router

requestPath

yes

The… request path?
#158 Request Example
GET /crs/consistenthash/deliveryservice?deliveryServiceId=demo1&requestPath=/ HTTP/1.1
Host: trafficrouter.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*

Response Structure

#159 Response Example
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 15 Jan 2019 21:40:51 GMT

{ "id": "demo1",
"coverageZoneOnly": false,
"geoRedirectUrl": null,
"geoRedirectFile": null,
"geoRedirectUrlType": "INVALID_URL",
"routingName": "video",
"missLocation": {
    "latitude": 42,
    "longitude": -88,
    "postalCode": null,
    "city": null,
    "countryCode": null,
    "countryName": null,
    "defaultLocation": false,
    "properties": {
        "city": null,
        "countryCode": null,
        "latitude": "42.0",
        "postalCode": null,
        "countryName": null,
        "longitude": "-88.0"
    }
},
"dispersion": {
    "limit": 1,
    "shuffled": true
},
"ip6RoutingEnabled": true,
"responseHeaders": {},
"requestHeaders": [],
"regionalGeoEnabled": false,
"geolocationProvider": "maxmindGeolocationService",
"anonymousIpEnabled": false,
"sslEnabled": true,
"acceptHttp": true,
"deepCache": "NEVER",
"dns": false,
"locationLimit": 0,
"maxDnsIps": 0,
"sslReady": true,
"available": true
}

/crs/coveragezone/caches

A list of caches for a given Delivery Service and Cache Group.

Request Structure

Table 89 Request Query Parameters

Name

Required

Description

deliveryServiceId

yes

The integral, unique identifier?/’xml_id’?/name? of a Delivery Service served by this Traffic Router

cacheLocationId

yes

The Name of a Cache Group to which this Traffic Router is capable of routing client traffic

Response Structure

TBD

/crs/coveragezone/cachelocation

The resulting Cache Group for a given client IP and Delivery Service.

Request Structure

Table 90 Request Query Parameters

Name

Required

Description

ip

yes

The IP address of a potential client

deliveryServiceId

yes

The integral, unique identifier?/’xml_id’?/name? of a Delivery Service served by this Traffic Router

Response Structure

TBD

/crs/deepcoveragezone/cachelocation

The resulting Cache Group using the Deep Coverage Zone File (deep caching) for a given client IP and Delivery Service.

Request Structure

Table 91 Request Query Parameters

Name

Required

Description

ip

yes

The IP address of a potential client

deliveryServiceId

yes

The integral, unique identifier?/’xml_id’?/name? of a Delivery Service served by this Traffic Router

Response Structure

TBD

/crs/consistenthash/patternbased/regex

The resulting path that will be used for consistent hashing when the given regex is applied to the given request path.

Request Structure

Table 92 Request Query Parameters

Name

Required

Description

regex

yes

The (URI encoded) regular expression to be used to test pattern based consistent hashing

requestPath

yes

The (URI encoded) request path to use to test pattern based consistent hashing
#160 Request Example
GET /crs/consistenthash/patternbased/regex?regex=%2F.*%3F%28%2F.*%3F%2F%29.*%3F%28%5C.m3u8%29&requestPath=%2Ftext1234%2Fname%2Fasset.m3u8 HTTP/1.1
Host: localhost:3333
User-Agent: curl/7.54.0
Accept: */*

Response Structure

#161 Response Example
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 15 Feb 2019 22:06:53 GMT

{
"resultingPathToConsistentHash":"/name/.m3u8",
"consistentHashRegex":"/.*?(/.*?/).*?(\\.m3u8)",
"requestPath":"/text1234/name/asset.m3u8"
}

/crs/consistenthash/patternbased/deliveryservice

The resulting path that will be used for consistent hashing for the given delivery service and the given request path.

Request Structure

Table 93 Request Query Parameters

Name

Required

Description

requestPath

yes

The (URI encoded) request path to use to test pattern based consistent hashing

deliveryServiceId

yes

The integral, unique identifier?/’xml_id’?/name? of a Delivery Service served by this Traffic Router
#162 Request Example
GET /crs/consistenthash/patternbased/deliveryservice?deliveryServiceId=asdf&requestPath=%2Fsometext1234%2Fstream_name%2Fasset_name.m3u8 HTTP/1.1
Host: localhost:3333
User-Agent: curl/7.54.0
Accept: */*

Response Structure

#163 Response Example
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 15 Feb 2019 22:12:38 GMT

{
"resultingPathToConsistentHash":"/sometext1234/stream_name/asset_name.m3u8",
"deliveryServiceId":"asdf",
"requestPath":"/sometext1234/stream_name/asset_name.m3u8"
}

/crs/consistenthash/cache/coveragezone/steering

The resulting cache of the consistent hash using coverage zone for a given client IP, delivery service and, request path – used to test cache selection for steering delivery services.

Request Structure

Table 94 Request Query Parameters

Name

Required

Description

requestPath

yes

The (URI encoded) request path to use to test pattern based consistent hashing

deliveryServiceId

yes

The integral, unique identifier?/’xml_id’?/name? of a Delivery Service served by this Traffic Router

ip

yes

The IP address of a potential client

Response Structure

TBD