knutsel closed pull request #2175: Move API docs to top level URL: https://github.com/apache/incubator-trafficcontrol/pull/2175
This is a PR merged from a forked repository. As GitHub hides the original diff on merge, it is displayed below for the sake of provenance: As this is a foreign pull request (from a fork), the diff is supplied below (as it won't show otherwise due to GitHub magic): diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst new file mode 100644 index 000000000..cd619bce1 --- /dev/null +++ b/docs/source/api/index.rst @@ -0,0 +1,27 @@ +.. +.. +.. 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. +.. + +APIs +**** +A guide to external RESTful APIs for Traffic Ops + +.. toctree:: + :maxdepth: 2 + + traffic_ops_api + routes + v11/index + v12/index + diff --git a/docs/source/development/traffic_ops_api/routes.rst b/docs/source/api/routes.rst similarity index 100% rename from docs/source/development/traffic_ops_api/routes.rst rename to docs/source/api/routes.rst diff --git a/docs/source/api/traffic_ops_api.rst b/docs/source/api/traffic_ops_api.rst new file mode 100644 index 000000000..2ae61d3cc --- /dev/null +++ b/docs/source/api/traffic_ops_api.rst @@ -0,0 +1,192 @@ +.. +.. +.. 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. + diff --git a/docs/source/development/traffic_ops_api/v11/asn.rst b/docs/source/api/v11/asn.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/asn.rst rename to docs/source/api/v11/asn.rst diff --git a/docs/source/development/traffic_ops_api/v11/cachegroup.rst b/docs/source/api/v11/cachegroup.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/cachegroup.rst rename to docs/source/api/v11/cachegroup.rst diff --git a/docs/source/development/traffic_ops_api/v11/cdn.rst b/docs/source/api/v11/cdn.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/cdn.rst rename to docs/source/api/v11/cdn.rst diff --git a/docs/source/development/traffic_ops_api/v11/changelog.rst b/docs/source/api/v11/changelog.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/changelog.rst rename to docs/source/api/v11/changelog.rst diff --git a/docs/source/development/traffic_ops_api/v11/deliveryservice.rst b/docs/source/api/v11/deliveryservice.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/deliveryservice.rst rename to docs/source/api/v11/deliveryservice.rst diff --git a/docs/source/development/traffic_ops_api/v11/hwinfo.rst b/docs/source/api/v11/hwinfo.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/hwinfo.rst rename to docs/source/api/v11/hwinfo.rst diff --git a/docs/source/api/v11/index.rst b/docs/source/api/v11/index.rst new file mode 100644 index 000000000..bb50b2222 --- /dev/null +++ b/docs/source/api/v11/index.rst @@ -0,0 +1,40 @@ +.. +.. +.. 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 1.1 Reference +***************** +Traffic Ops v1.1 API Documentation + +.. toctree:: + :maxdepth: 1 + + asn + cachegroup + cdn + changelog + deliveryservice + hwinfo + parameter + phys_location + profile + region + role + server + static_dns + status + system + to_extension + type + user diff --git a/docs/source/development/traffic_ops_api/v11/parameter.rst b/docs/source/api/v11/parameter.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/parameter.rst rename to docs/source/api/v11/parameter.rst diff --git a/docs/source/development/traffic_ops_api/v11/phys_location.rst b/docs/source/api/v11/phys_location.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/phys_location.rst rename to docs/source/api/v11/phys_location.rst diff --git a/docs/source/development/traffic_ops_api/v11/profile.rst b/docs/source/api/v11/profile.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/profile.rst rename to docs/source/api/v11/profile.rst diff --git a/docs/source/development/traffic_ops_api/v11/region.rst b/docs/source/api/v11/region.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/region.rst rename to docs/source/api/v11/region.rst diff --git a/docs/source/development/traffic_ops_api/v11/role.rst b/docs/source/api/v11/role.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/role.rst rename to docs/source/api/v11/role.rst diff --git a/docs/source/development/traffic_ops_api/v11/server.rst b/docs/source/api/v11/server.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/server.rst rename to docs/source/api/v11/server.rst diff --git a/docs/source/development/traffic_ops_api/v11/static_dns.rst b/docs/source/api/v11/static_dns.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/static_dns.rst rename to docs/source/api/v11/static_dns.rst diff --git a/docs/source/development/traffic_ops_api/v11/status.rst b/docs/source/api/v11/status.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/status.rst rename to docs/source/api/v11/status.rst diff --git a/docs/source/development/traffic_ops_api/v11/system.rst b/docs/source/api/v11/system.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/system.rst rename to docs/source/api/v11/system.rst diff --git a/docs/source/development/traffic_ops_api/v11/to_extension.rst b/docs/source/api/v11/to_extension.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/to_extension.rst rename to docs/source/api/v11/to_extension.rst diff --git a/docs/source/development/traffic_ops_api/v11/type.rst b/docs/source/api/v11/type.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/type.rst rename to docs/source/api/v11/type.rst diff --git a/docs/source/development/traffic_ops_api/v11/user.rst b/docs/source/api/v11/user.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v11/user.rst rename to docs/source/api/v11/user.rst diff --git a/docs/source/development/traffic_ops_api/v12/api_capability.rst b/docs/source/api/v12/api_capability.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/api_capability.rst rename to docs/source/api/v12/api_capability.rst diff --git a/docs/source/development/traffic_ops_api/v12/asn.rst b/docs/source/api/v12/asn.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/asn.rst rename to docs/source/api/v12/asn.rst diff --git a/docs/source/development/traffic_ops_api/v12/cache.rst b/docs/source/api/v12/cache.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/cache.rst rename to docs/source/api/v12/cache.rst diff --git a/docs/source/development/traffic_ops_api/v12/cache_stats.rst b/docs/source/api/v12/cache_stats.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/cache_stats.rst rename to docs/source/api/v12/cache_stats.rst diff --git a/docs/source/development/traffic_ops_api/v12/cachegroup.rst b/docs/source/api/v12/cachegroup.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/cachegroup.rst rename to docs/source/api/v12/cachegroup.rst diff --git a/docs/source/development/traffic_ops_api/v12/cachegroup_parameter.rst b/docs/source/api/v12/cachegroup_parameter.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/cachegroup_parameter.rst rename to docs/source/api/v12/cachegroup_parameter.rst diff --git a/docs/source/development/traffic_ops_api/v12/capability.rst b/docs/source/api/v12/capability.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/capability.rst rename to docs/source/api/v12/capability.rst diff --git a/docs/source/development/traffic_ops_api/v12/cdn.rst b/docs/source/api/v12/cdn.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/cdn.rst rename to docs/source/api/v12/cdn.rst diff --git a/docs/source/development/traffic_ops_api/v12/changelog.rst b/docs/source/api/v12/changelog.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/changelog.rst rename to docs/source/api/v12/changelog.rst diff --git a/docs/source/development/traffic_ops_api/v12/configfiles_ats.rst b/docs/source/api/v12/configfiles_ats.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/configfiles_ats.rst rename to docs/source/api/v12/configfiles_ats.rst diff --git a/docs/source/development/traffic_ops_api/v12/deliveryservice.rst b/docs/source/api/v12/deliveryservice.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/deliveryservice.rst rename to docs/source/api/v12/deliveryservice.rst diff --git a/docs/source/development/traffic_ops_api/v12/deliveryservice_regex.rst b/docs/source/api/v12/deliveryservice_regex.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/deliveryservice_regex.rst rename to docs/source/api/v12/deliveryservice_regex.rst diff --git a/docs/source/development/traffic_ops_api/v12/deliveryservice_stats.rst b/docs/source/api/v12/deliveryservice_stats.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/deliveryservice_stats.rst rename to docs/source/api/v12/deliveryservice_stats.rst diff --git a/docs/source/development/traffic_ops_api/v12/division.rst b/docs/source/api/v12/division.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/division.rst rename to docs/source/api/v12/division.rst diff --git a/docs/source/development/traffic_ops_api/v12/federation.rst b/docs/source/api/v12/federation.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/federation.rst rename to docs/source/api/v12/federation.rst diff --git a/docs/source/development/traffic_ops_api/v12/federation_deliveryservice.rst b/docs/source/api/v12/federation_deliveryservice.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/federation_deliveryservice.rst rename to docs/source/api/v12/federation_deliveryservice.rst diff --git a/docs/source/development/traffic_ops_api/v12/federation_federationresolver.rst b/docs/source/api/v12/federation_federationresolver.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/federation_federationresolver.rst rename to docs/source/api/v12/federation_federationresolver.rst diff --git a/docs/source/development/traffic_ops_api/v12/federation_resolver.rst b/docs/source/api/v12/federation_resolver.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/federation_resolver.rst rename to docs/source/api/v12/federation_resolver.rst diff --git a/docs/source/development/traffic_ops_api/v12/federation_user.rst b/docs/source/api/v12/federation_user.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/federation_user.rst rename to docs/source/api/v12/federation_user.rst diff --git a/docs/source/development/traffic_ops_api/v12/hwinfo.rst b/docs/source/api/v12/hwinfo.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/hwinfo.rst rename to docs/source/api/v12/hwinfo.rst diff --git a/docs/source/api/v12/index.rst b/docs/source/api/v12/index.rst new file mode 100644 index 000000000..15e839c88 --- /dev/null +++ b/docs/source/api/v12/index.rst @@ -0,0 +1,62 @@ +.. +.. +.. 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 1.2 Reference +***************** +Traffic Ops API V1.2 + +.. toctree:: + :maxdepth: 1 + + api_capability + asn + cache + cachegroup + cachegroup_parameter + cache_stats + capability + cdn + changelog + configfiles_ats + deliveryservice + deliveryservice_regex + deliveryservice_stats + division + federation + federation_deliveryservice + federation_federationresolver + federation_resolver + federation_user + hwinfo + iso + job + parameter + phys_location + profile + profile_parameter + influxdb + region + role + server + static_dns + status + steering_target + system + tenant + to_extension + type + user + topology diff --git a/docs/source/development/traffic_ops_api/v12/influxdb.rst b/docs/source/api/v12/influxdb.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/influxdb.rst rename to docs/source/api/v12/influxdb.rst diff --git a/docs/source/development/traffic_ops_api/v12/iso.rst b/docs/source/api/v12/iso.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/iso.rst rename to docs/source/api/v12/iso.rst diff --git a/docs/source/development/traffic_ops_api/v12/job.rst b/docs/source/api/v12/job.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/job.rst rename to docs/source/api/v12/job.rst diff --git a/docs/source/development/traffic_ops_api/v12/parameter.rst b/docs/source/api/v12/parameter.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/parameter.rst rename to docs/source/api/v12/parameter.rst diff --git a/docs/source/development/traffic_ops_api/v12/phys_location.rst b/docs/source/api/v12/phys_location.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/phys_location.rst rename to docs/source/api/v12/phys_location.rst diff --git a/docs/source/development/traffic_ops_api/v12/profile.rst b/docs/source/api/v12/profile.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/profile.rst rename to docs/source/api/v12/profile.rst diff --git a/docs/source/development/traffic_ops_api/v12/profile_parameter.rst b/docs/source/api/v12/profile_parameter.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/profile_parameter.rst rename to docs/source/api/v12/profile_parameter.rst diff --git a/docs/source/development/traffic_ops_api/v12/region.rst b/docs/source/api/v12/region.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/region.rst rename to docs/source/api/v12/region.rst diff --git a/docs/source/development/traffic_ops_api/v12/role.rst b/docs/source/api/v12/role.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/role.rst rename to docs/source/api/v12/role.rst diff --git a/docs/source/development/traffic_ops_api/v12/server.rst b/docs/source/api/v12/server.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/server.rst rename to docs/source/api/v12/server.rst diff --git a/docs/source/development/traffic_ops_api/v12/static_dns.rst b/docs/source/api/v12/static_dns.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/static_dns.rst rename to docs/source/api/v12/static_dns.rst diff --git a/docs/source/development/traffic_ops_api/v12/status.rst b/docs/source/api/v12/status.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/status.rst rename to docs/source/api/v12/status.rst diff --git a/docs/source/development/traffic_ops_api/v12/steering_target.rst b/docs/source/api/v12/steering_target.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/steering_target.rst rename to docs/source/api/v12/steering_target.rst diff --git a/docs/source/development/traffic_ops_api/v12/system.rst b/docs/source/api/v12/system.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/system.rst rename to docs/source/api/v12/system.rst diff --git a/docs/source/development/traffic_ops_api/v12/tenant.rst b/docs/source/api/v12/tenant.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/tenant.rst rename to docs/source/api/v12/tenant.rst diff --git a/docs/source/development/traffic_ops_api/v12/to_extension.rst b/docs/source/api/v12/to_extension.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/to_extension.rst rename to docs/source/api/v12/to_extension.rst diff --git a/docs/source/development/traffic_ops_api/v12/topology.rst b/docs/source/api/v12/topology.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/topology.rst rename to docs/source/api/v12/topology.rst diff --git a/docs/source/development/traffic_ops_api/v12/type.rst b/docs/source/api/v12/type.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/type.rst rename to docs/source/api/v12/type.rst diff --git a/docs/source/development/traffic_ops_api/v12/user.rst b/docs/source/api/v12/user.rst similarity index 100% rename from docs/source/development/traffic_ops_api/v12/user.rst rename to docs/source/api/v12/user.rst diff --git a/docs/source/development/traffic_ops.rst b/docs/source/development/traffic_ops.rst index 03e2f91d5..cb4333059 100644 --- a/docs/source/development/traffic_ops.rst +++ b/docs/source/development/traffic_ops.rst @@ -367,264 +367,3 @@ Traffic Ops accesses each extension through the addition of a URL route as a cus Development Configuration -------------------------- To incorporate any custom Extensions during development set your PERL5LIB with any number of directories with the understanding that the PERL5LIB search order will come into play, so keep in mind that top-down is how your code will be located. Once Perl locates your custom route or Perl package/class it 'pins' on that class or Mojo Route and doesn't look any further, which allows for the developer to *override* Traffic Ops functionality. - -API -=== -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. - -Traffic Ops API Routes ----------------------- - -.. toctree:: - :maxdepth: 1 - - traffic_ops_api/routes - -API 1.1 Reference ------------------ - -.. toctree:: - :maxdepth: 1 - - traffic_ops_api/v11/asn - traffic_ops_api/v11/cachegroup - traffic_ops_api/v11/cdn - traffic_ops_api/v11/changelog - traffic_ops_api/v11/deliveryservice - traffic_ops_api/v11/hwinfo - traffic_ops_api/v11/parameter - traffic_ops_api/v11/phys_location - traffic_ops_api/v11/profile - traffic_ops_api/v11/region - traffic_ops_api/v11/role - traffic_ops_api/v11/server - traffic_ops_api/v11/static_dns - traffic_ops_api/v11/status - traffic_ops_api/v11/system - traffic_ops_api/v11/to_extension - traffic_ops_api/v11/type - traffic_ops_api/v11/user - -API 1.2 Reference ------------------ - -.. toctree:: - :maxdepth: 1 - - traffic_ops_api/v12/api_capability - traffic_ops_api/v12/asn - traffic_ops_api/v12/cache - traffic_ops_api/v12/cachegroup - traffic_ops_api/v12/cachegroup_parameter - traffic_ops_api/v12/cache_stats - traffic_ops_api/v12/capability - traffic_ops_api/v12/cdn - traffic_ops_api/v12/changelog - traffic_ops_api/v12/configfiles_ats - traffic_ops_api/v12/deliveryservice - traffic_ops_api/v12/deliveryservice_regex - traffic_ops_api/v12/deliveryservice_stats - traffic_ops_api/v12/division - traffic_ops_api/v12/federation - traffic_ops_api/v12/federation_deliveryservice - traffic_ops_api/v12/federation_federationresolver - traffic_ops_api/v12/federation_resolver - traffic_ops_api/v12/federation_user - traffic_ops_api/v12/hwinfo - traffic_ops_api/v12/iso - traffic_ops_api/v12/job - traffic_ops_api/v12/parameter - traffic_ops_api/v12/phys_location - traffic_ops_api/v12/profile - traffic_ops_api/v12/profile_parameter - traffic_ops_api/v12/influxdb - traffic_ops_api/v12/region - traffic_ops_api/v12/role - traffic_ops_api/v12/server - traffic_ops_api/v12/static_dns - traffic_ops_api/v12/status - traffic_ops_api/v12/steering_target - traffic_ops_api/v12/system - traffic_ops_api/v12/tenant - traffic_ops_api/v12/to_extension - traffic_ops_api/v12/type - traffic_ops_api/v12/user - traffic_ops_api/v12/topology - - - - - diff --git a/docs/source/index.rst b/docs/source/index.rst index 50b604b9f..4f9782547 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -60,6 +60,14 @@ A guide to the various internal and external APIs, and an introduction for the T development/index +APIs +==== +A guide to external RESTful APIs for Traffic Ops + +.. toctree:: + :maxdepth: 3 + + api/index FAQ === ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
