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
.
Other attributes of the default certificate can also be customized by specifying appropriate values for the following properties in /opt/traffic_router/conf/https.properties
. These properties are listed below:
Name |
Description |
Default |
---|---|---|
https.certificate.location |
The location of the certificate key store |
|
https.password |
The password for the certificate key store |
|
https.key.size |
The size for the HTTPS keys |
2048 |
https.signature.algorithm |
The HTTPS signing algorithm to be used |
SHA1WithRSA |
https.validity.years |
The amount of time (in years) for which the cert is valid |
3 |
https.certificate.country |
The country of the certificate |
US |
https.certificate.state |
The state of the certificate |
CO |
https.certificate.locality |
The locality of the certificate |
Denver |
https.certificate.organization |
The organization of the certificate |
Apache Traffic Control |
https.certificate.organizational.unit |
The organizational unit of the certificate |
Apache Foundation, Hosted by Traffic Control, CDNDefault |
Traffic Router API endpoints only respond to GET
requests.
/crs/stats
General stats.
Request Structure
GET /crs/stats HTTP/1.1
Host: trafficrouter.infra.ciab.test
User-Agent: curl/7.52.1
Accept: */*
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1214
Date: Mon, 04 Nov 2019 19:48:04 GMT
{ "app": {
"buildTimestamp": "2019-11-04",
"name": "traffic_router",
"deploy-dir": "/opt/traffic_router",
"git-revision": "eabc2b82e",
"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": 1572895915703,
"averageDnsTime": 0,
"averageHttpTime": 1572895947202,
"updateTracker": {
"lastHttpsCertificatesCheck": 1572896852436,
"lastGeolocationDatabaseUpdaterUpdate": 1572895942543,
"lastCacheStateCheck": 1572896884465,
"lastCacheStateChange": 1572895951089,
"lastNetworkUpdaterUpdate": 1572895941407,
"lastHttpsCertificatesUpdate": 1572896854512,
"lastSteeringWatcherUpdate": 1572896007369,
"lastConfigCheck": 1572896881213,
"lastConfigChange": 1572895947297,
"lastNetworkUpdaterCheck": 1572895941392,
"lastGeolocationDatabaseUpdaterCheck": 1572895942533,
"lastFederationsWatcherUpdate": 1572895947336,
"lastHttpsCertificatesFetchSuccess": 1572896852506,
"lastSteeringWatcherCheck": 1572896848090,
"lastFederationsWatcherCheck": 1572896848067,
"lastHttpsCertificatesFetchAttempt": 1572896852436
}
}}
/crs/stats/ip/{{IP}}
Geolocation information for an IPv4 or IPv6 address.
Request Structure
Name |
Description |
---|---|
IP |
The IP address for which statics will be returned. May be IPv4 or IPv6 |
GET /crs/stats/ip/255.255.255.255 HTTP/1.1
Host: trafficrouter.infra.ciab.test
User-Agent: curl/7.52.1
Accept: */*
Response Structure
HTTP/1.1 200 OK
Content-Disposition: inline;filename=f.txt
Content-Type: application/json;charset=UTF-8
Content-Length: 131
Date: Mon, 04 Nov 2019 19:48:04 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
GET /crs/locations HTTP/1.1
Host: trafficrouter.infra.ciab.test
User-Agent: curl/7.52.1
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
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 35
Date: Mon, 04 Nov 2019 19:48:04 GMT
{ "locations": [
"CDN_in_a_Box_Edge"
]}
/crs/locations/caches
A mapping of caches to cache groups and their current health state.
Request Structure
GET /crs/locations/caches HTTP/1.1
Host: trafficrouter.infra.ciab.test
User-Agent: curl/7.52.1
Accept: */*
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 278
Date: Mon, 04 Nov 2019 19:48:04 GMT
{ "locations": {
"CDN_in_a_Box_Edge": [
{
"cacheId": "edge",
"fqdn": "edge.infra.ciab.test",
"ipAddresses": [
"172.16.239.4",
"fc01:9400:1000:8:0:0:0:4"
],
"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
Name |
Description |
---|---|
cachegroup |
The Name of a Cache Group of which a list of constituent cache servers will be retrieved |
GET /crs/locations/CDN_in_a_Box_Edge/caches HTTP/1.1
Host: trafficrouter.infra.ciab.test
User-Agent: curl/7.52.1
Accept: */*
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 253
Date: Mon, 04 Nov 2019 19:48:04 GMT
{ "caches": [
{
"cacheId": "edge",
"fqdn": "edge.infra.ciab.test",
"ipAddresses": [
"172.16.239.4",
"fc01:9400:1000:8:0:0:0:4"
],
"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
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
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
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
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? |
GET /crs/consistenthash/deliveryservice?deliveryServiceId=demo1&requestPath=/ HTTP/1.1
Host: trafficrouter.infra.ciab.test
User-Agent: curl/7.52.1
Accept: */*
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 828
Date: Mon, 04 Nov 2019 19:48:04 GMT
{ "id": "demo1",
"coverageZoneOnly": false,
"geoRedirectUrl": null,
"geoRedirectFile": null,
"geoRedirectUrlType": "INVALID_URL",
"routingName": "video",
"missLocation": {
"latitude": 42.0,
"longitude": -88.0,
"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",
"consistentHashRegex": "",
"consistentHashQueryParams": [
"abc",
"zyx",
"xxx",
"pdq"
],
"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
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
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
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
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 |
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.52.1
Accept: */*
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 137
Date: Mon, 04 Nov 2019 19:48:04 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
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 |
GET /crs/consistenthash/patternbased/deliveryservice?deliveryServiceId=demo1&requestPath=%2Fsometext1234%2Fstream_name%2Fasset_name.m3u8 HTTP/1.1
Host: localhost:3333
User-Agent: curl/7.52.1
Accept: */*
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 163
Date: Mon, 04 Nov 2019 19:48:04 GMT
{ "resultingPathToConsistentHash": "/sometext1234/stream_name/asset_name.m3u8",
"deliveryServiceId": "demo1",
"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
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