| .. |
| .. |
| .. Licensed under the Apache License, Version 2.0 (the "License"); |
| .. you may not use this file except in compliance with the License. |
| .. You may obtain a copy of the License at |
| .. |
| .. http://www.apache.org/licenses/LICENSE-2.0 |
| .. |
| .. Unless required by applicable law or agreed to in writing, software |
| .. distributed under the License is distributed on an "AS IS" BASIS, |
| .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| .. See the License for the specific language governing permissions and |
| .. limitations under the License. |
| .. |
| |
| 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 |
| ------------------- |
| 1. Authenticate with your Traffic Portal or Traffic Ops user account credentials. |
| 2. Upon successful user authentication, note the mojolicious cookie value in the response headers. |
| 3. 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 |