API Overview¶

The Traffic Ops API provides programmatic access to read and write CDN data providing authorized API consumers with the ability to monitor CDN performance and configure CDN settings and parameters.

Response Structure¶

All successful responses have the following structure:

{
  "response": <JSON object with main response>,
}

To make the documentation easier to read, only the <JSON object with main response> is documented, even though the response and version fields are always present.

Using API Endpoints¶

Authenticate with your Traffic Portal or Traffic Ops user account credentials.
Upon successful user authentication, note the mojolicious cookie value in the response headers.
Pass the mojolicious cookie value, along with any subsequent calls to an authenticated API endpoint.

Example:

[jvd@laika ~]$ curl -H "Accept: application/json" http://localhost:3000/api/1.1/usage/asns.json
{"alerts":[{"level":"error","text":"Unauthorized, please log in."}]}
[jvd@laika ~]$
[jvd@laika ~]$ curl -v -H "Accept: application/json" -v -X POST --data '{ "u":"admin", "p":"secret_passwd" }' http://localhost:3000/api/1.1/user/login
* Hostname was NOT found in DNS cache
*   Trying ::1...
* connect to ::1 port 3000 failed: Connection refused
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 3000 (#0)
> POST /api/1.1/user/login HTTP/1.1
> User-Agent: curl/7.37.1
> Host: localhost:3000
> Accept: application/json
> Content-Length: 32
> Content-Type: application/x-www-form-urlencoded
>
* upload completely sent off: 32 out of 32 bytes
< HTTP/1.1 200 OK
< Connection: keep-alive
< Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
< Access-Control-Allow-Origin: http://localhost:8080
< Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept
< Set-Cookie: mojolicious=eyJleHBpcmVzIjoxNDI5NDAyMjAxLCJhdXRoX2RhdGEiOiJhZG1pbiJ9--f990d03b7180b1ece97c3bb5ca69803cd6a79862; expires=Sun, 19 Apr 2015 00:10:01 GMT; path=/; HttpOnly
< Content-Type: application/json
< Date: Sat, 18 Apr 2015 20:10:01 GMT
< Access-Control-Allow-Credentials: true
< Content-Length: 81
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
* Server Mojolicious (Perl) is not blacklisted
< Server: Mojolicious (Perl)
<
* Connection #0 to host localhost left intact
{"alerts":[{"level":"success","text":"Successfully logged in."}]}
[jvd@laika ~]$

[jvd@laika ~]$ curl -H'Cookie: mojolicious=eyJleHBpcmVzIjoxNDI5NDAyMjAxLCJhdXRoX2RhdGEiOiJhZG1pbiJ9--f990d03b7180b1ece97c3bb5ca69803cd6a79862;' -H "Accept: application/json" http://localhost:3000/api/1.1/asns.json
{"response":{"asns":[{"lastUpdated":"2012-09-17 15:41:22", .. asn data deleted ..   ,}
[jvd@laika ~]$

API Errors¶

Response Properties

Parameter	Type	Description
`alerts`	array	A collection of alert messages.
`>level`	string	Success, info, warning or error.
`>text`	string	Alert message.

The 3 most common errors returned by Traffic Ops are:

401 Unauthorized

When you don’t supply the right cookie, this is the response.

[jvd@laika ~]$ curl -v -H "Accept: application/json" http://localhost:3000/api/1.1/usage/asns.json
* Hostname was NOT found in DNS cache
*   Trying ::1...
* connect to ::1 port 3000 failed: Connection refused
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 3000 (#0)
> GET /api/1.1/usage/asns.json HTTP/1.1
> User-Agent: curl/7.37.1
> Host: localhost:3000
> Accept: application/json
>
< HTTP/1.1 401 Unauthorized
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Content-Length: 84
* Server Mojolicious (Perl) is not blacklisted
< Server: Mojolicious (Perl)
< Connection: keep-alive
< Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
< Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept
< Access-Control-Allow-Origin: http://localhost:8080
< Date: Sat, 18 Apr 2015 20:36:12 GMT
< Content-Type: application/json
< Access-Control-Allow-Credentials: true
<
* Connection #0 to host localhost left intact
{"alerts":[{"level":"error","text":"Unauthorized, please log in."}]}
[jvd@laika ~]$

404 Not Found

When the resource (path) is non existent Traffic Ops returns a 404:

[jvd@laika ~]$ curl -v -H'Cookie: mojolicious=eyJleHBpcmVzIjoxNDI5NDAyMjAxLCJhdXRoX2RhdGEiOiJhZG1pbiJ9--f990d03b7180b1ece97c3bb5ca69803cd6a79862;' -H "Accept: application/json" http://localhost:3000/api/1.1/asnsjj.json
* Hostname was NOT found in DNS cache
*   Trying ::1...
* connect to ::1 port 3000 failed: Connection refused
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 3000 (#0)
> GET /api/1.1/asnsjj.json HTTP/1.1
> User-Agent: curl/7.37.1
> Host: localhost:3000
> Cookie: mojolicious=eyJleHBpcmVzIjoxNDI5NDAyMjAxLCJhdXRoX2RhdGEiOiJhZG1pbiJ9--f990d03b7180b1ece97c3bb5ca69803cd6a79862;
> Accept: application/json
>
< HTTP/1.1 404 Not Found
* Server Mojolicious (Perl) is not blacklisted
< Server: Mojolicious (Perl)
< Content-Length: 75
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Content-Type: application/json
< Date: Sat, 18 Apr 2015 20:37:43 GMT
< Access-Control-Allow-Credentials: true
< Set-Cookie: mojolicious=eyJleHBpcmVzIjoxNDI5NDAzODYzLCJhdXRoX2RhdGEiOiJhZG1pbiJ9--8a5a61b91473bc785d4073fe711de8d2c63f02dd; expires=Sun, 19 Apr 2015 00:37:43 GMT; path=/; HttpOnly
< Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
< Connection: keep-alive
< Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept
< Access-Control-Allow-Origin: http://localhost:8080
<
* Connection #0 to host localhost left intact
{"alerts":[{"text":"Resource not found.","level":"error"}]}
[jvd@laika ~]$

500 Internal Server Error

When you are asking for a correct path, but the database doesn’t match, it returns a 500:

[jvd@laika ~]$ curl -v -H'Cookie: mojolicious=eyJleHBpcmVzIjoxNDI5NDAyMjAxLCJhdXRoX2RhdGEiOiJhZG1pbiJ9--f990d03b7180b1ece97c3bb5ca69803cd6a79862;' -H "Accept: application/json" http://localhost:3000/api/1.1/servers/hostname/jj/details.json
* Hostname was NOT found in DNS cache
*   Trying ::1...
* connect to ::1 port 3000 failed: Connection refused
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 3000 (#0)
> GET /api/1.1/servers/hostname/jj/details.json HTTP/1.1
> User-Agent: curl/7.37.1
> Host: localhost:3000
> Cookie: mojolicious=eyJleHBpcmVzIjoxNDI5NDAyMjAxLCJhdXRoX2RhdGEiOiJhZG1pbiJ9--f990d03b7180b1ece97c3bb5ca69803cd6a79862;
> Accept: application/json
>
< HTTP/1.1 500 Internal Server Error
* Server Mojolicious (Perl) is not blacklisted
< Server: Mojolicious (Perl)
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Content-Length: 93
< Set-Cookie: mojolicious=eyJhdXRoX2RhdGEiOiJhZG1pbiIsImV4cGlyZXMiOjE0Mjk0MDQzMDZ9--1b08977e91f8f68b0ff5d5e5f6481c76ddfd0853; expires=Sun, 19 Apr 2015 00:45:06 GMT; path=/; HttpOnly
< Content-Type: application/json
< Date: Sat, 18 Apr 2015 20:45:06 GMT
< Access-Control-Allow-Credentials: true
< Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
< Connection: keep-alive
< Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept
< Access-Control-Allow-Origin: http://localhost:8080
<
* Connection #0 to host localhost left intact
{"alerts":[{"level":"error","text":"An error occurred. Please contact your administrator."}]}
[jvd@laika ~]$

The rest of the API documentation will only document the 200 OK case, where no errors have occured.

TrafficOps Native Client Libraries¶

TrafficOps client libraries are available in both Golang and Python. You can read more about them at https://github.com/apache/incubator-trafficcontrol/tree/master/traffic_control/clients