Traffic Ops API

The Traffic Ops API provides programmatic access to read and write Traffic Control data which allows for the monitoring of CDN performance and configuration of Traffic Control settings and parameters.

API Routes

How to Read this Documentation

Each endpoint is on its own page, titled with the request path. The request paths shown on each endpoint’s page are - unless otherwise noted - only usable by being appended to the request path prefix /api/<version>/ where <version> is the API version being requested. The API versions officially supported as of the time of this writing are 1.1, 1.2, 1.3, 1.4. All endpoints are documented as though they were being used in version 1.4. If an endpoint or request method of an endpoint is only available after a specific version, that will be noted next to the method or endpoint name. If changes were made to the structure of an endpoint’s input or output, the version number and nature of the change will be noted.

Every endpoint is documented with a section for each method, containing the subsections “Request Structure” and “Response Structure” which identify all properties and structure of the Request to and Response from the endpoint. Before these subsections, three key pieces of information will be provided:

Auth. Required
This will either be ‘Yes’ to indicate that a user must be authenticated (or “logged-in”) via e.g. user/login to use this method of the endpoint, or ‘No’ to indicate that this is not required.
Roles Required
Any permissions roles that are allowed to use this method of the endpoint will be listed here. Users with roles not listed here will be unable to properly use these endpoints
Response Type
Unless otherwise noted, all responses are JSON objects. See Response Structure for more information.

The methods of endpoints that require/accept data payloads - unless otherwise noted - always interpret the content of the payload as a JSON object, regardless of the request’s Content-Type header. Because of this, all payloads are - unless otherwise noted - JSON objects. The Request Structure and Response Structure subsections will contain explanations of the fields before any examples like e.g.

foo:

A constant field that always contains “foo”

bar:

An array of objects that each represent a “bar” object

name:The bar’s name
value:The bar’s value (an integer)

All fields are mandatory in a request payload, or always present in a response payload unless otherwise noted in the field description.

In most cases, JSON objects have been “pretty-printed” by inserting line breaks and indentation. This means that the Content-Length HTTP header does not, in general, accurately portray the length of the content displayed in Request Examples and Response Examples. Also, the Traffic Ops endpoints will ignore any content negotiation, meaning that the Content-Type header of a request is totally meaningless. A utility may choose to pass the data as e.g. application/x-www-form-urlencoded (cURL’s default Content-Type) when constructing a Request Example, but the example itself will most often show application/json in order for syntax highlighting to properly work.

Response Structure

Unless otherwise noted, all response payloads come as JSON objects.

#498 Response 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 endpoints may return other top-level objects (most commonly the "alerts" object). The field definitions listed in the Response Structure subsection of an endpoint method are the elements of this object. Sometimes the response object is a string, sometimes it’s an object that maps keys to values, sometimes it’s an array that contains many arbitrary objects, and sometimes it isn’t present at all. For ease of reading, the field lists delegate the distinction to be made by the Response Type field directly under the request method heading.

Response Type Meanings

Array
The fields in the field list refer to the keys of the objects in the response array.
Object
The fields in the field list refer to the keys of the response object.
undefined
No response object is present in the response payload. Unless the format is otherwise noted, this means that there should be no field list in the “Response Structure” subsection.

Using API Endpoints

  1. Authenticate with valid Traffic Control user account credentials (the same used by Traffic Portal).

  2. Upon successful user authentication, note the Mojolicious cookie value in the response headers[1].

    Note

    Many tools have methods for doing this without manual intervention - a web browser for instance will automatically remember and properly handle cookies. Another common tool, cURL, has command line switches that will also accomplish this. Most high-level programming language libraries will implement a cookie-handling method as well.

  3. Pass the Mojolicious cookie value, along with any subsequent calls to an authenticated API endpoint.

Note

Many endpoints support a .json suffix. This should be avoided at all costs, because there’s no real consistency regarding when it may be used, and the output of API endpoints, in general, are not capable of representing POSIX-compliant files (as a ‘file extension’ might imply).

Example Session

A user makes a request to the /api/1.1/asns endpoint.

GET /api/1.1/asns HTTP/1.1
Accept: application/json
Host: trafficops.infra.ciab.test
User-Agent: example

The response JSON indicates an authentication error.

HTTP/1.1 401 UNAUTHORIZED
Content-Length: 68
Content-Type: application/json
Date: Tue, 02 Oct 2018 13:12:30 GMT

{ "alerts": [
        {
                "level":"error",
                "text":"Unauthorized, please log in."
        }
]}

To authenticate, the user sends a POST request containing their login information to the /api/1.3/user/login endpoint.

POST /api/1.1/user/login HTTP/1.1
User-Agent: example
Host: trafficops.infra.ciab.test
Accept: application/json
Content-Length: 32
Content-Type: application/x-www-form-urlencoded

Traffic Ops responds with a Mojolicious cookie to be used for future requests, and a message indicating the success or failure (in this case success) of the login operation.

HTTP/1.1 200 OK
Connection: keep-alive
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept
Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 02 Oct 2018 19:03:18 GMT; HttpOnly
Content-Type: application/json
Date: Tue, 02 Oct 2018 12:53:32 GMT
Access-Control-Allow-Credentials: true
Content-Length: 81
X-Server-Name: traffic_ops_golang/

{ "alerts": [
        {
                "level": "success",
                "text": "Successfully logged in."
        }
]}

Using this cookie, the user can now access their original target - the /api/1.1/asns endpoint…

GET /api/1.1/asns HTTP/1.1
Accept: application/json
Cookie: mojolicious=...;
Host: trafficops.infra.ciab.test
User-Agent: Example

… and the Traffic Ops server will now happily service this request.

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: *
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 48
Content-Type: application/json
Date: Tue, 02 Oct 2018 12:55:57 GMT
Set-Cookie: mojolicious=...; Path=/; HttpOnly
Whole-Content-SHA512: u+Q5X7z/DMTc/VzRGaFlJBA8btA8EC…dnA85HCYTm8vVwsQCvle+uVc1nA==
X-Server-Name: traffic_ops_golang/

{ "response": {
        "asns": [
                {
                        "lastUpdated": "2012-09-17 21:41:22",
                        "id": 27,
                        "asn": 7015,
                        "cachegroup": "us-ma-woburn",
                        "cachegroupId": 2
                },
                {
                        "lastUpdated": "2012-09-17 21:41:22",
                        "id": 28,
                        "asn": 7016,
                        "cachegroup": "us-pa-pittsburgh",
                        "cachegroupID": 3
                }
        ]
}}

API Errors

If an API endpoint has something to say besides the actual response (usually an error message), it will add a top-level object to the response JSON with the key "alerts". This will be an array of objects that represent messages from the server, each with the following string fields:

level:"success", "info", "warning" or "error" as appropriate
text:The alert’s actual message

The most common errors returned by Traffic Ops are:

401 Unauthorized

When a “mojolicious” cookie is supplied that is invalid or expired, or the login credentials are incorrect the server responds with a 401 UNAUTHORIZED response code.

#499 Example of a Response to a Login Request with Bad Credentials
HTTP/1.1 401 Unauthorized
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
Whole-Content-Sha512: xRKu2Q7Yj07UA6A6SyxMNmcBpuBcW2/bzuKO5eTZ2y4V27rXfP/5bSkNPesomJbiOO+xSmiybDsHlcL3P+pzpg==
X-Server-Name: traffic_ops_golang/
Date: Tue, 02 Oct 2018 13:28:30 GMT
Content-Length: 69

{ "alerts": [
        {
                "text": "Invalid username or password.",
                "level": "error"
        }
]}
404 Not Found

When the requested resource (path) doesn’t exist, Traffic Ops returns a 404 NOT FOUND response code.

#500 Example Response to GET /not/an/api/path HTTP/1.1 with Proper Cookies
HTTP/1.1 404 Not Found
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Type: text/html;charset=UTF-8
Date: Tue, 02 Oct 2018 13:58:56 GMT
Server: Mojolicious (Perl)
Set-Cookie: mojolicious=...; expires=Tue, 02 Oct 2018 17:58:56 GMT; path=/; HttpOnly
Vary: Accept-Encoding
Whole-Content-Sha512: Ff5hO8ZUNUMbwCW0mBuUlsvrSmm/Giijpq7O3uLivLZ6VOu6eGom4Jag6UqlBbbDBnP6AG7l1Szdt74TT6NidA==
Transfer-Encoding: chunked

The content of this response will be the Legacy UI login page (which is omitted because it's huge)
500 Internal Server Error

When a server-side error occurs, the Perl API will return a 500 INTERNAL SERVER ERROR response (the below example request will result in a 400 BAD REQUEST response if using the v1.3 API instead - as this will use the Go server’s API)

#501 Example Response to GET /api/1.1/servers/hostname/jj/details.json (‘jj’ doesn’t exist)
HTTP/1.1 500 Internal Server Error
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: 93
Content-Type: application/json
Date: Tue, 02 Oct 2018 17:29:42 GMT
Server: Mojolicious (Perl)
Set-Cookie: mojolicious=..; expires=Sun, 19 Apr 2015 00:45:06 GMT; path=/; HttpOnly
Vary: Accept-Encoding
Whole-Content-Sha512: gFa4NYFmofCbV7YqgwyFRzKk90+KNgoZu6p2Nx98J4Gy7/2j55tYknvk53WXuMdMKKrgYMop4uiYOla1k1ozQQ==

{ "alerts": [
        {
                "level": "error",
                "text": "An error occurred. Please contact your administrator."
        }
]}

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

TrafficOps Native Client Libraries

TrafficOps client libraries are available in Java, Go and Python. You can read (very little) more about them in the client README.

[1]A cookie obtained by logging in through Traffic Portal can be used to access API endpoints under the Traffic Portal domain name - since it will proxy such requests back to Traffic Ops. This is not recommended in actual deployments, however, because it will involve an extra network connection which could be avoided by simply using the Traffic Ops domain itself.