You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficcontrol.apache.org by ne...@apache.org on 2018/12/14 17:15:27 UTC
[trafficcontrol] branch master updated: API documentation overhaul
(#3078)
This is an automated email from the ASF dual-hosted git repository.
neuman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git
The following commit(s) were added to refs/heads/master by this push:
new 5bf0792 API documentation overhaul (#3078)
5bf0792 is described below
commit 5bf0792a5a04d180fa9b64a34e9271bae949bbdd
Author: ocket8888 <oc...@gmail.com>
AuthorDate: Fri Dec 14 10:15:21 2018 -0700
API documentation overhaul (#3078)
* Moved API overview to the Index page
* Consistent formatting, acurate build system listing, footnotes and helpful links
* Formatting consistency; added helpful links; grammar fixes
* syntax highlighting
* Moved route listing into main API page - replaces ToC
* Fixed footnote reference issue
* Added libpq dependency listing, added admonition warning that TO tests don't matter and the points don't count
* Added TO Golang documentation page (stub atm)
* Steps now numbered
* Began migrating endpoints to single-documentation form
* Moved cache statistics endpoints to new file structure
* Moved cachegroups into the new file structure
* Finished moving cachegroups endpoints out of the old file structure
* Moved cachegroup_fallbacks endpoint ouf of old file structure
* Finished moving cachegroupparameters endpoint to new file structure
* Moved capabilities out of old file structure
* Added note about API response differences between v1.1 and v1.2
* WIP - Moving cdns/* endpoints to new file structure
* WIP - pulled deliveryservices endpoint out of cdns endpoint
* Finished moving cdns logic out of old file structure
* Moved logs endpoints out of old file structure
* Pulled configuration file endpoints out of old file structure
* Added implementation note for logs/newcount
Also fixed a typo in a directive name for logs/{{days}}/days
* Pulled coordinates out of old file structure
* started working on deliveryservice stuff
* Moved api/1.x/cdns/{{name}}/dnsseckeys/ksk/generate out of old file structure
* Fixed incorrect documentation from Rob's PR
* Fixed more dnsseckeys stuff, more ds work
* more DS stuff
* more work on stuff
* Adding some HTTP responses
* More HTTP examples
* Removed '/api/1.x/' common prefix
* Fixed label duplication
* Fixed missing syntax name in code block
* Title formatting fixed for compliance
* Line breaks shouldn't occur in URLs, so we're back to monospace for API paths
* another HTTP example"
* More HTTP examples
* Pulled out more deliveryservice stuff and added more http examples
* Pulled more things out of the Delivery Service files
* Pulled out more of Delivery Services
* More HTTP examples
* A LOT more HTTP examples
* Pulled more stuff out of Delivery Services, added forward-compatible globbing to the index, and removed the big, ugly, inaccurate, incomplete, incomprehensible table
* fixed the "Traffic Ops API" page heading being monospaced
* Finally finished converting examples for previously-extracted, testable, working routes from json to full http
* A couple of missed HTTP examples, pulled more stuff out of deliveryservices
* Started working on deliveryservices POST
* Finished the request format spec for Deliveryservices POST
* Pulled out 'safe' DS endpoint
* Finished pulling the v1.1 Delivery Services page into the new layout system
* Added version change notes to deliveryservice representation endpoints, pulled deliveryservices/xml_id/servers into new file structure
* Finished pulling things out of v1.2/deliveryservice (deliveryservices/xml_id/urisignkeys not done yet)
* Added documentation for 1.4 DNSSEC key refresh endpoint
* Began pulling out deliveryservices.*regexes, removed now-broken references from index files
* Finished ds regexes endpoints
* Moved deliveryservice_stats to new structure - also removed entries from version-specific index
* Moved ds regex endpoint to appropriate filename
* Moved divisions endpoints into new file structure
* Fixed bad route name, non-http example, missing request example
* Removed reference to now non-existent v12/divisions document
* Started working with federations - CIAB cannot handle atm
* Moved hwinfo endpoint into new file structure
* started working on the iso endpoints
* Moved traffic_monitor/stats into new structure
* Moved isos endpoint into the new structure
* started working on federations and jobs
* Fixed a broken foot ref, temporarily disabled ref to unknown source
* Fixed typo in page label and code block argument
* Changed from HTTP to JSON syntax highlighting - will change back once CIAB supports endpoints
* Fixed typo in code-block optional directive
* Fixed now-broken references to API-version-specific hwinfo endpoints
* Removed reference to old structure 'influxdb' page
* pulled v12/federation.rst into new structure (not done with federation endpoints, some refs broken)
* Moved v12/federation_deliveryservice.rst into new structure
Still not quite done with federations, so some references remain broken
* moved v12/federation_federationresolver.rst into new structure
STILL not done with federations - some references remain broken.
* Moved v12/federation_resolver.rst into new structure
**STILL** not done with federations - some references remain broken...
* Moved v12/federation_user into new structure
federations are now done - they still need proper examples, and a v14 route is missing
* All federation endpoints now have full HTTP examples
* Moved jobs endpoints to new structure
Examples aren't done yet - I'm rebuilding CIAB
* Pulled v11/parameter.rst and v12/parameter.rst apart into constituent routes
* Moved phys_locations endpoints into new structure
* Added missing query params, added deprecation notice to GET divisions/{{id}}
* fixed formatting error
* Made minor improvements to deprecation formatting notice
* Added missing query parameter and added a deprecation notice
* Fixed copy/paste typo
* Moved region endpoints into new structure
* Fixed a spelling error
* Pulled v11/profile.rst and v12/profile.rst into new structure
* Pulled v12/profile_parameter into new structure
* Moved v1x/role.rst into the new structure
* Moved servers endpoints into new structure
* Various syntax error fixes
* Moved staticdnsentries endpoint into new structure
* Moved statuses endpoints into new structure
* Pulled steering endpoints into new structure
* Moved last 1.3 endpoint (origins) into new structure
* moved system info endpoint into new file structure
I may need to add more keys to the definition - CIAB has quite a few less than production environments, but I don't understand all of the nuances there
* Moved tenants endpoints into new structure
* WIP - pulling to_extensions into new structure
* Pulled Traffic Ops extensions endpoints into new structure
* Moved snapshot endpoints into new structure
* Moved types endpoints into new structure
* Pulled users endpoints into new structure
---
docs/source/api/api_capabilities.rst | 182 +
docs/source/api/api_capabilities_id.rst | 239 ++
docs/source/api/asns.rst | 142 +
docs/source/api/asns_id.rst | 188 ++
docs/source/api/cache_stats.rst | 123 +
docs/source/api/cachegroup_fallbacks.rst | 286 ++
.../api/cachegroup_parameterID_parameter.rst | 85 +
docs/source/api/cachegroupparameters.rst | 135 +
.../api/cachegroupparameters_id_parameterID.rst | 75 +
docs/source/api/cachegroups.rst | 216 ++
docs/source/api/cachegroups_id.rst | 266 ++
.../source/api/cachegroups_id_deliveryservices.rst | 91 +
docs/source/api/cachegroups_id_parameters.rst | 77 +
docs/source/api/cachegroups_id_queue_updates.rst | 90 +
.../api/cachegroups_id_unassigned_parameters.rst | 87 +
...cachegroups_parameterID_parameter_available.rst | 61 +
docs/source/api/cachegroups_trimmed.rst | 78 +
docs/source/api/caches_stats.rst | 80 +
docs/source/api/capabilities.rst | 132 +
docs/source/api/capabilities_name.rst | 184 ++
docs/source/api/cdns.rst | 136 +
docs/source/api/cdns_capacity.rst | 51 +
.../api/cdns_cdn_configfiles_ats_filename.rst | 54 +
docs/source/api/cdns_configs.rst | 44 +
docs/source/api/cdns_dnsseckeys_refresh.rst | 55 +
docs/source/api/cdns_domains.rst | 53 +
docs/source/api/cdns_health.rst | 59 +
docs/source/api/cdns_id.rst | 187 ++
docs/source/api/cdns_id_queue_update.rst | 78 +
docs/source/api/cdns_id_snapshot.rst | 66 +
..._types_metric_start_date_start_end_date_end.rst | 94 +
docs/source/api/cdns_name_configs_monitoring.rst | 228 ++
docs/source/api/cdns_name_configs_routing.rst | 161 +
.../api/cdns_name_dnsseckeys_ksk_generate.rst | 57 +
docs/source/api/cdns_name_federations.rst | 174 +
docs/source/api/cdns_name_federations_id.rst | 232 ++
docs/source/api/cdns_name_health.rst | 78 +
docs/source/api/cdns_name_name.rst | 114 +
docs/source/api/cdns_name_name_dnsseckeys.rst | 116 +
.../api/cdns_name_name_dnsseckeys_delete.rst | 48 +
docs/source/api/cdns_name_name_sslkeys.rst | 67 +
docs/source/api/cdns_name_snapshot.rst | 540 +++
docs/source/api/cdns_name_snapshot_new.rst | 543 +++
docs/source/api/cdns_routing.rst | 71 +
docs/source/api/cdns_usage_overview.rst | 55 +
docs/source/api/coordinates.rst | 295 ++
.../api/deliveryservice_server_dsid_serverid.rst | 68 +
docs/source/api/deliveryservice_stats.rst | 176 +
docs/source/api/deliveryservice_user.rst | 83 +
.../api/deliveryservice_user_dsid_userid.rst | 66 +
docs/source/api/deliveryservices.rst | 685 ++++
.../api/deliveryservices_dnsseckeys_generate.rst | 50 +
.../api/deliveryservices_hostname_name_sslkeys.rst | 89 +
docs/source/api/deliveryservices_id.rst | 556 ++++
docs/source/api/deliveryservices_id_capacity.rst | 73 +
docs/source/api/deliveryservices_id_health.rst | 83 +
docs/source/api/deliveryservices_id_regexes.rst | 164 +
.../source/api/deliveryservices_id_regexes_rid.rst | 224 ++
docs/source/api/deliveryservices_id_routing.rst | 91 +
docs/source/api/deliveryservices_id_safe.rst | 317 ++
..._metric_types_start_date_start_end_date_end.rst | 128 +
docs/source/api/deliveryservices_id_servers.rst | 156 +
.../api/deliveryservices_id_servers_eligible.rst | 143 +
.../api/deliveryservices_id_servers_unassigned.rst | 136 +
docs/source/api/deliveryservices_id_state.rst | 86 +
docs/source/api/deliveryservices_regex.rst | 72 +
docs/source/api/deliveryservices_request.rst | 134 +
docs/source/api/deliveryservices_sslkeys_add.rst | 71 +
.../api/deliveryservices_sslkeys_generate.rst | 69 +
docs/source/api/deliveryservices_xmlid_servers.rst | 84 +
.../api/deliveryservices_xmlid_urisignkeys.rst | 213 ++
.../api/deliveryservices_xmlid_xmlid_sslkeys.rst | 99 +
...deliveryservices_xmlid_xmlid_sslkeys_delete.rst | 51 +
.../api/deliveryservices_xmlid_xmlid_urlkeys.rst | 68 +
...d_xmlid_urlkeys_copyfromxmlid_copyfromxmlid.rst | 49 +
...liveryservices_xmlid_xmlid_urlkeys_generate.rst | 49 +
docs/source/api/deliveryserviceserver.rst | 161 +
docs/source/api/divisions.rst | 133 +
docs/source/api/divisions_id.rst | 146 +
docs/source/api/divisions_name_regions.rst | 88 +
docs/source/api/federation_resolvers.rst | 94 +
docs/source/api/federation_resolvers_id.rst | 74 +
docs/source/api/federations.rst | 231 ++
.../source/api/federations_id_deliveryservices.rst | 153 +
.../api/federations_id_deliveryservices_id.rst | 75 +
.../api/federations_id_federation_resolvers.rst | 157 +
docs/source/api/federations_id_user_id.rst | 75 +
docs/source/api/federations_id_users.rst | 142 +
docs/source/api/hwinfo.rst | 77 +
docs/source/api/index.rst | 256 +-
docs/source/api/isos.rst | 124 +
docs/source/api/jobs.rst | 98 +
docs/source/api/jobs_id.rst | 67 +
docs/source/api/logs.rst | 96 +
docs/source/api/logs_days_days.rst | 104 +
docs/source/api/logs_newcount.rst | 60 +
docs/source/api/origins.rst | 410 +++
docs/source/api/osversions.rst | 58 +
docs/source/api/parameterprofile.rst | 88 +
docs/source/api/parameters.rst | 193 ++
docs/source/api/parameters_id.rst | 223 ++
docs/source/api/parameters_id_profiles.rst | 92 +
.../api/parameters_id_unassigned_profiles.rst | 105 +
docs/source/api/parameters_profile_name.rst | 109 +
docs/source/api/parameters_validate.rst | 122 +
docs/source/api/phys_locations.rst | 207 ++
docs/source/api/phys_locations_id.rst | 265 ++
docs/source/api/phys_locations_trimmed.rst | 60 +
docs/source/api/profileparameter.rst | 88 +
docs/source/api/profileparameters.rst | 173 +
.../profileparameters_profileID_parameterID.rst | 73 +
docs/source/api/profiles.rst | 168 +
docs/source/api/profiles_id.rst | 259 ++
docs/source/api/profiles_id_parameters.rst | 246 ++
.../api/profiles_id_unassigned_parameters.rst | 94 +
docs/source/api/profiles_name_name_copy_copy.rst | 88 +
docs/source/api/profiles_name_name_parameters.rst | 245 ++
.../profiles_profile_configfiles_ats_filename.rst | 76 +
docs/source/api/profiles_trimmed.rst | 66 +
docs/source/api/regions.rst | 154 +
docs/source/api/regions_id.rst | 169 +
docs/source/api/regions_name_phys_locations.rst | 126 +
docs/source/api/roles.rst | 66 +
docs/source/api/routes.rst | 98 -
docs/source/api/servercheck.rst | 69 +
docs/source/api/servers.rst | 404 +++
docs/source/api/servers_hostname_name_details.rst | 144 +
docs/source/api/servers_id.rst | 454 +++
docs/source/api/servers_id_deliveryservices.rst | 263 ++
docs/source/api/servers_id_queue_update.rst | 97 +
docs/source/api/servers_id_status.rst | 85 +
docs/source/api/servers_server_configfiles_ats.rst | 192 ++
.../servers_server_configfiles_ats_filename.rst | 75 +
docs/source/api/servers_totals.rst | 97 +
docs/source/api/snapshot_name.rst | 64 +
docs/source/api/staticdnsentries.rst | 367 +++
docs/source/api/statuses.rst | 82 +
docs/source/api/statuses_id.rst | 80 +
docs/source/api/steering_id_targets.rst | 172 +
docs/source/api/steering_id_targets_targetID.rst | 222 ++
docs/source/api/system_info.rst | 84 +
docs/source/api/tenants.rst | 153 +
docs/source/api/tenants_id.rst | 213 ++
docs/source/api/to_extensions.rst | 187 ++
docs/source/api/to_extensions_id_delete.rst | 75 +
docs/source/api/traffic_monitor_stats.rst | 68 +
docs/source/api/traffic_ops_api.rst | 239 --
docs/source/api/types.rst | 84 +
docs/source/api/types_id.rst | 81 +
docs/source/api/types_trimmed.rst | 66 +
docs/source/api/user_current.rst | 217 ++
docs/source/api/user_current_jobs.rst | 191 ++
docs/source/api/user_current_update.rst | 111 +
.../api/user_id_deliveryservices_available.rst | 74 +
docs/source/api/user_login.rst | 73 +
docs/source/api/user_login_token.rst | 74 +
docs/source/api/user_logout.rst | 58 +
docs/source/api/user_reset_password.rst | 73 +
docs/source/api/users.rst | 277 ++
docs/source/api/users_id.rst | 265 ++
docs/source/api/users_id_deliveryservices.rst | 264 ++
docs/source/api/users_register.rst | 83 +
docs/source/api/v11/asn.rst | 82 -
docs/source/api/v11/cachegroup.rst | 372 ---
docs/source/api/v11/cdn.rst | 1109 -------
docs/source/api/v11/changelog.rst | 154 -
docs/source/api/v11/deliveryservice.rst | 1286 --------
docs/source/api/v11/hwinfo.rst | 67 -
docs/source/api/v11/index.rst | 40 -
docs/source/api/v11/parameter.rst | 136 -
docs/source/api/v11/phys_location.rst | 449 ---
docs/source/api/v11/profile.rst | 129 -
docs/source/api/v11/region.rst | 235 --
docs/source/api/v11/role.rst | 58 -
docs/source/api/v11/server.rst | 630 ----
docs/source/api/v11/static_dns.rst | 63 -
docs/source/api/v11/status.rst | 127 -
docs/source/api/v11/system.rst | 79 -
docs/source/api/v11/to_extension.rst | 210 --
docs/source/api/v11/type.rst | 151 -
docs/source/api/v11/user.rst | 778 -----
docs/source/api/v12/api_capability.rst | 320 --
docs/source/api/v12/asn.rst | 200 --
docs/source/api/v12/cache.rst | 84 -
docs/source/api/v12/cache_stats.rst | 134 -
docs/source/api/v12/cachegroup.rst | 905 -----
docs/source/api/v12/cachegroup_fallbacks.rst | 288 --
docs/source/api/v12/cachegroup_parameter.rst | 177 -
docs/source/api/v12/capability.rst | 271 --
docs/source/api/v12/cdn.rst | 1413 --------
docs/source/api/v12/changelog.rst | 164 -
docs/source/api/v12/configfiles_ats.rst | 193 --
docs/source/api/v12/deliveryservice.rst | 3486 --------------------
docs/source/api/v12/deliveryservice_regex.rst | 374 ---
docs/source/api/v12/deliveryservice_stats.rst | 155 -
docs/source/api/v12/division.rst | 203 --
docs/source/api/v12/federation.rst | 449 ---
docs/source/api/v12/federation_deliveryservice.rst | 155 -
.../api/v12/federation_federationresolver.rst | 118 -
docs/source/api/v12/federation_resolver.rst | 110 -
docs/source/api/v12/federation_user.rst | 161 -
docs/source/api/v12/hwinfo.rst | 68 -
docs/source/api/v12/index.rst | 63 -
docs/source/api/v12/influxdb.rst | 65 -
docs/source/api/v12/iso.rst | 134 -
docs/source/api/v12/job.rst | 136 -
docs/source/api/v12/parameter.rst | 691 ----
docs/source/api/v12/phys_location.rst | 456 ---
docs/source/api/v12/profile.rst | 415 ---
docs/source/api/v12/profile_parameter.rst | 573 ----
docs/source/api/v12/region.rst | 244 --
docs/source/api/v12/role.rst | 59 -
docs/source/api/v12/server.rst | 1496 ---------
docs/source/api/v12/static_dns.rst | 66 -
docs/source/api/v12/status.rst | 127 -
docs/source/api/v12/steering_target.rst | 333 --
docs/source/api/v12/system.rst | 80 -
docs/source/api/v12/tenant.rst | 255 --
docs/source/api/v12/to_extension.rst | 206 --
docs/source/api/v12/topology.rst | 152 -
docs/source/api/v12/type.rst | 151 -
docs/source/api/v12/user.rst | 1262 -------
docs/source/api/v13/coordinate.rst | 272 --
docs/source/api/v13/index.rst | 26 -
docs/source/api/v13/origin.rst | 474 ---
docs/source/api/v13/staticdnsentry.rst | 317 --
docs/source/api/v14/cdn.rst | 198 --
docs/source/api/v14/index.rst | 24 -
docs/source/api/v14/user.rst | 1374 --------
docs/source/basics/cache_revalidation.rst | 5 +-
docs/source/development/building.rst | 58 +-
docs/source/development/index.rst | 1 +
docs/source/development/traffic_ops.rst | 3 +
docs/source/development/traffic_ops_golang.rst | 25 +
docs/source/development/traffic_portal.rst | 24 +-
docs/source/docutils.conf | 8 +
236 files changed, 22953 insertions(+), 25618 deletions(-)
diff --git a/docs/source/api/api_capabilities.rst b/docs/source/api/api_capabilities.rst
new file mode 100644
index 0000000..9d7bdf4
--- /dev/null
+++ b/docs/source/api/api_capabilities.rst
@@ -0,0 +1,182 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-api_capability:
+
+********************
+``api_capabilities``
+********************
+Deals with the capabilities that may be associated with API endpoints and methods. These capabilities are assigned to "roles", of which a user may have one or more. Capabilities support "wildcarding" or "globbing" using asterisks to group multiple routes into a single capability
+
+``GET``
+=======
+Get all API-capability mappings.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +----------------+----------+--------+------------------------------------+
+ | Name | Required | Type | Description |
+ +================+==========+========+====================================+
+ | capability | no | string | Capability name |
+ +----------------+----------+--------+------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.1/api_capabilities?capability=types-write HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:capability: Capability name
+:httpMethod: An HTTP request method, practically one of:
+
+ - ``GET``
+ - ``POST``
+ - ``PUT``
+ - ``PATCH``
+ - ``DELETE``
+
+:httpRoute: The request route for which this capability applies - relative to the Traffic Ops server's URL
+:id: An integer which uniquely identifies this capability
+:lastUpdated: The time at which this capability was last updated, in ISO format
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Thu, 01 Nov 2018 14:45:24 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 01 Nov 2018 18:45:24 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: wptErtIop/AfTTQ+1MZdA2YpPXEOuLFfrPQvvaHqO/uX5fRruOVYW+7p8JTrtH1xg1WN+x6FnjQnSHuWwcpyJg==
+ Content-Length: 393
+
+ { "response": [
+ {
+ "httpMethod": "POST",
+ "lastUpdated": "2018-11-01 14:10:22.794114+00",
+ "httpRoute": "types",
+ "id": 261,
+ "capability": "types-write"
+ },
+ {
+ "httpMethod": "PUT",
+ "lastUpdated": "2018-11-01 14:10:22.795917+00",
+ "httpRoute": "types/*",
+ "id": 262,
+ "capability": "types-write"
+ },
+ {
+ "httpMethod": "DELETE",
+ "lastUpdated": "2018-11-01 14:10:22.799748+00",
+ "httpRoute": "types/*",
+ "id": 263,
+ "capability": "types-write"
+ }
+ ]}
+
+``POST``
+========
+Create an API-capability mapping.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+:capability: Capability name
+:httpMethod: An HTTP request method, one of: 'GET', 'POST', 'PUT', 'PATCH', 'DELETE'
+:httpRoute: The API endpoint for which to create capabilities
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.1/api_capabilities HTTP/1.1
+ Host: ipcdn-cache-51.cdnlab.comcast.net:6443
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 94
+ Content-Type: application/x-www-form-urlencoded
+
+ {
+ "capability": "types-write",
+ "httpRoute": "/api/1.1/api_capabilities",
+ "httpMethod": "PATCH"
+ }
+
+Response Structure
+------------------
+:capability: Capability name
+:httpMethod: An HTTP request method, practically one of:
+
+ - ``GET``
+ - ``POST``
+ - ``PUT``
+ - ``PATCH``
+ - ``DELETE``
+
+:httpRoute: The request route for which this capability applies - relative to the Traffic Ops server's URL
+:id: An integer which uniquely identifies this capability
+:lastUpdated: The time at which this capability was last updated, in ISO format
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Thu, 01 Nov 2018 14:53:58 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 01 Nov 2018 18:53:58 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: CDz5DUJFoL5DgfnCcvitPmnKJAG5VENhNN6wz2YNqqW1n5HQzSci+NsU5SqfhKnTwnKfSy7PYl9hQhrUKO6KCQ==
+ Content-Length: 209
+
+ { "alerts": [
+ {
+ "level": "success",
+ "text": "API-Capability mapping was created."
+ }
+ ],
+ "response": {
+ "httpMethod": "PATCH",
+ "lastUpdated": null,
+ "httpRoute": "/api/1.1/api_capabilities",
+ "id": 273,
+ "capability": "types-write"
+ }}
+
diff --git a/docs/source/api/api_capabilities_id.rst b/docs/source/api/api_capabilities_id.rst
new file mode 100644
index 0000000..f72216c
--- /dev/null
+++ b/docs/source/api/api_capabilities_id.rst
@@ -0,0 +1,239 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-api_capabilities_id:
+
+***************************
+``api_capabilities/{{ID}}``
+***************************
+Manages a specific API capability.
+
+``GET``
+=======
+Get an API-capability mapping by id.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +-------------+----------+---------+-----------------------------------------+
+ | Name | Required | Type | Description |
+ +=============+==========+=========+=========================================+
+ | ID | yes | integer | A unique identifier for this capability |
+ +-------------+----------+---------+-----------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.1/api_capabilities/273 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+
+Response Structure
+------------------
+:capability: Capability name
+:httpMethod: An HTTP request method, practically one of:
+
+ * ``GET``
+ * ``POST``
+ * ``PUT``
+ * ``PATCH``
+ * ``DELETE``
+
+:httpRoute: The request route for which this capability applies - relative to the Traffic Ops server's URL
+:id: An integer which uniquely identifies this capability
+:lastUpdated: The time at which this capability was last updated, in an ISO-like format
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Thu, 01 Nov 2018 16:14:09 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 01 Nov 2018 20:14:09 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: SMSFHOcD6VvfJKmcHmHBQcN+jkRRCmFzx1jyBWhJeyPg04YHPSvUcjZzslWlJqyjwWeoXeNVwxhRkBwl8TQX/g==
+ Content-Length: 162
+
+ { "response": [
+ {
+ "httpMethod": "PATCH",
+ "lastUpdated": "2018-11-01 14:53:58.853356+00",
+ "httpRoute": "/api/1.1/api_capabilities",
+ "id": 273,
+ "capability": "types-write"
+ }
+ ]}
+
+``PUT``
+=======
+Edit an API-capability mapping.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+:capability: Capability name
+:httpMethod: An HTTP request method, practically one of:
+
+ * ``GET``
+ * ``POST``
+ * ``PUT``
+ * ``PATCH``
+ * ``DELETE``
+
+:httpRoute: The request route for which this capability applies - relative to the Traffic Ops server's URL
+
+.. table:: Request Path Parameters
+
+ +-------------+----------+---------+-----------------------------------------+
+ | Name | Required | Type | Description |
+ +=============+==========+=========+=========================================+
+ | id | yes | integer | A unique identifier for this capability |
+ +-------------+----------+---------+-----------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/1.1/api_capabilities/273 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 98
+ Content-Type: application/x-www-form-urlencoded
+
+ {
+ "capability": "types-write",
+ "httpRoute": "/api/1.1/api_capabilities/*",
+ "httpMethod": "PATCH"
+ }
+
+Response Structure
+------------------
+:capability: Capability name
+:httpMethod: An HTTP request method, practically one of:
+
+ * ``GET``
+ * ``POST``
+ * ``PUT``
+ * ``PATCH``
+ * ``DELETE``
+
+:httpRoute: The request route for which this capability applies - relative to the Traffic Ops server's URL
+:id: An integer which uniquely identifies this capability
+:lastUpdated: The time at which this capability was last updated, in ISO format
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Thu, 01 Nov 2018 18:28:38 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 01 Nov 2018 22:28:38 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: zQuDrqpJt02Fh2fNZ6K7/XmVJ49ZqGTnSbsaR7nOyoxbkmLM17XJV1rtef/SAows2M4j4YjcDbEP4WM/hjCFtw==
+ Content-Length: 241
+
+ {
+ "alerts": [
+ {
+ "level": "success",
+ "text": "API-Capability mapping was updated."
+ }
+ ],
+ "response": {
+ "httpMethod": "PATCH",
+ "lastUpdated": "2018-11-01 18:28:10.38317+00",
+ "httpRoute": "/api/1.1/api_capabilities/*",
+ "id": 273,
+ "capability": "types-write"
+ }
+ }
+
+DELETE
+======
+Delete a capability.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: ``undefined``
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +-------------+----------+---------+-----------------------------------------+
+ | Name | Required | Type | Description |
+ +=============+==========+=========+=========================================+
+ | id | yes | integer | A unique identifier for this capability |
+ +-------------+----------+---------+-----------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ DELETE /api/1.1/api_capabilities/273 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 07 Nov 2018 15:44:14 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Wed, 07 Nov 2018 19:44:14 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: eTFJkB2Bh8SCT2A29e21e8qoEdNzFGfuT5a3tDG7u8vwz/JHntQRRR8554a1i65733uWojlWKM65bLSDNmmNqQ==
+ Content-Length: 73
+
+ { "alerts": [
+ {
+ "level": "success",
+ "text": "API-capability mapping deleted."
+ }
+ ]}
diff --git a/docs/source/api/asns.rst b/docs/source/api/asns.rst
new file mode 100644
index 0000000..8c9b84a
--- /dev/null
+++ b/docs/source/api/asns.rst
@@ -0,0 +1,142 @@
+..
+..
+.. 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.
+..
+
+
+.. _to-api-asns:
+
+********
+``asns``
+********
+.. seealso:: `The Autonomous System Wikipedia page <https://en.wikipedia.org/wiki/Autonomous_system_%28Internet%29>` for an explanation of what an ASN actually is.
+
+``GET``
+=======
+List all Autonomous System Numbers (ASNs).
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +----------------+----------+-----------------------------------------------------------------------------------------------------+
+ | Parameter | Required | Description |
+ +================+==========+=====================================================================================================+
+ | cachegroup | no | An integral, unique identifier for a Cache Group - only ANSs for this Cache Group will be returned. |
+ +----------------+----------+-----------------------------------------------------------------------------------------------------+
+
+Response Structure
+------------------
+:lastUpdated: The Time / Date this server entry was last updated in ISO format
+:id: An integer which uniquely identifies the ASN
+:asn: Autonomous System Numbers per APNIC for identifying a service provider
+:cachegroup: Related Cache Group name
+:cachegroupId: Related Cache Group ID
+
+.. versionchanged:: 1.2
+ Used to contain the array in the ``response.asns`` object, changed so that ``response`` is an actual array
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: 2zeWYI/dGyCzi0ZUWXuuycLFPyL9M5nDJchC7nJMQPW3cwXTaTwf0qI3mP3G1ArZlJTk/ju6/jbUVCNcVIXX1Q==
+ X-Server-Name: traffic_ops_golang/
+ Date: Thu, 01 Nov 2018 18:56:38 GMT
+ Content-Length: 129
+
+ { "response": [
+ {
+ "asn": 1,
+ "cachegroup": "TRAFFIC_ANALYTICS",
+ "cachegroupId": 1,
+ "id": 1,
+ "lastUpdated": "2018-11-01 18:55:39+00"
+ }
+ ]}
+
+
+``POST``
+========
+Creates a new Autonomous System Number (ASN).
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+:asn: The value of the new ASN
+:cachegroupId: The integral, unique identifier of a Cache Group to which this ASN will be assigned
+:cachegroup: An optional field which, if present, specifies the name of a Cache Group to which this ASN will be assigned
+
+.. note:: While this endpoint accepts the ``cachegroup`` field, sending this in the request payload has no effect except that the response will (erroneously) name the Cache Group to which the ASN was assigned. Any subsequent requests will reveal that, in fact, the Cache Group name is set by the ``cachegroupId`` field.
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.1/asns HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 60
+ Content-Type: application/x-www-form-urlencoded
+
+ {"asn": 1, "cachegroupId": 1}
+
+Response Structure
+------------------
+:lastUpdated: The Time / Date this server entry was last updated in ISO format
+:id: An integer which uniquely identifies the ASN
+:asn: Autonomous System Numbers per APNIC for identifying a service provider
+:cachegroup: Related Cache Group name
+:cachegroupId: Related Cache Group ID
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: DnM8HexH7LFkVNH8UYFe6uBQ445Ic8lRLDlOSDIuo4gjokMafxh5Ebr+CsSixNt//OxP0hoWZ+DKymSC5Hdi9Q==
+ X-Server-Name: traffic_ops_golang/
+ Date: Thu, 01 Nov 2018 18:57:08 GMT
+ Content-Length: 175
+
+ { "alerts": [
+ {
+ "text": "asn was created.",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "asn": 1,
+ "cachegroup": "TRAFFIC_ANALYTICS",
+ "cachegroupId": 1,
+ "id": 2,
+ "lastUpdated": "2018-11-01 18:57:08+00"
+ }}
diff --git a/docs/source/api/asns_id.rst b/docs/source/api/asns_id.rst
new file mode 100644
index 0000000..e513efc
--- /dev/null
+++ b/docs/source/api/asns_id.rst
@@ -0,0 +1,188 @@
+..
+..
+.. 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.
+..
+
+
+.. _to-api-asns-id:
+
+***************
+``asns/{{id}}``
+***************
+.. seealso:: `The Autonomous System Wikipedia page <https://en.wikipedia.org/wiki/Autonomous_system_%28Internet%29>` for an explanation of what an ASN actually is.
+
+``GET``
+=======
+Deal with a specific Autonomous System Number (ASN).
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +-------------------+----------+----------------------------------------------------+
+ | Name | Required | Description |
+ +===================+==========+====================================================+
+ | id | yes | The integral, unique identifier of the desired ASN |
+ +-------------------+----------+----------------------------------------------------+
+
+Response Structure
+------------------
+:asn: Autonomous System Numbers per APNIC for identifying a service provider
+:cachegroup: Related Cache Group name
+:cachegroupId: Related Cache Group ID
+:id: An integer which uniquely identifies the ASN
+:lastUpdated: The time and date at which this server entry was last updated in an ISO-like format
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: oeifOX6ImU1KVyCmyswh4uddhbNPZqxliMuNw+lNea1q/SJOYKXpaKnYqVjRm9QqJ7gH3vqeBxCftMLtb3sAWg==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 07 Nov 2018 18:44:31 GMT
+ Content-Length: 120
+
+ { "response": [
+ {
+ "lastUpdated": "2012-09-17 21:41:22",
+ "id": "28",
+ "asn": "7016",
+ "cachegroup": "us-pa-pittsburgh",
+ "cachegroupId": "13"
+ }
+ ]}
+
+``PUT``
+=======
+Allows user to edit an existing Autonomous System Number (ASN).
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+:asn: The value of the new ASN
+:cachegroupId: The integral, unique identifier of a Cache Group to which this ASN will be assigned
+:cachegroup: An optional field which, if present, specifies the name of a Cache Group to which this ASN will be assigned
+
+.. note:: While this endpoint accepts the ``cachegroup`` field, sending this in the request payload has no effect except that the response will (erroneously) name the Cache Group to which the ASN was assigned. Any subsequent requests will reveal that, in fact, the Cache Group name is set by the ``cachegroupId`` field.
+
+.. table:: Request Path Parameters
+
+ +-------------------+----------+----------------------------------------------------+
+ | Name | Required | Description |
+ +===================+==========+====================================================+
+ | id | yes | The integral, unique identifier of the desired ASN |
+ +-------------------+----------+----------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/1.1/asns/1 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 29
+ Content-Type: application/x-www-form-urlencoded
+
+ {"asn": 2, "cachegroupId": 1}
+
+Response Structure
+------------------
+:asn: Autonomous System Numbers per APNIC for identifying a service provider
+:cachegroup: Related Cache Group name
+:cachegroupId: Related Cache Group ID
+:id: An integer which uniquely identifies the ASN
+:lastUpdated: The date and time at which this server entry was last updated in an ISO-like format
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: /83P4LJVsrQx9BKHFxo5pbhQMlB4o3a9v3PpkspyOJcpNx1S/GJhCPpiANBki547sbY+0vTq76IriHZ4GYp8bA==
+ X-Server-Name: traffic_ops_golang/
+ Date: Thu, 08 Nov 2018 14:37:39 GMT
+ Content-Length: 160
+
+ { "alerts": [
+ {
+ "text": "asn was updated.",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "asn": 2,
+ "cachegroup": null,
+ "cachegroupId": 1,
+ "id": 1,
+ "lastUpdated": "2018-11-08 14:37:39+00"
+ }}
+
+``DELETE``
+==========
+Deletes an Autonomous System Number (ASN).
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: ``undefined``
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+----------+----------------------------------------------------+
+ | Name | Required | Description |
+ +======+==========+====================================================+
+ | id | yes | The integral, unique identifier of the desired ASN |
+ +------+----------+----------------------------------------------------+
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: 6t3WA+DOcfPJB5UnvDpzEVx5ySfmJgEV9wgkO71U5k32L1VXpxcaTdDVLNGgDDl9sdNftmYnKXf5jpfWUuFYJQ==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 07 Nov 2018 19:14:08 GMT
+ Content-Length: 58
+
+ { "alerts": [
+ {
+ "text": "asn was deleted.",
+ "level": "success"
+ }
+ ]}
diff --git a/docs/source/api/cache_stats.rst b/docs/source/api/cache_stats.rst
new file mode 100644
index 0000000..4cc610b
--- /dev/null
+++ b/docs/source/api/cache_stats.rst
@@ -0,0 +1,123 @@
+..
+..
+.. 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.
+..
+
+
+.. _to-api-cache_stats:
+
+***************
+``cache_stats``
+***************
+.. caution:: This page is a stub! Much of it may be missing or just downright wrong - it needs a lot of love from people with the domain knowledge required to update it.
+
+Retrieves detailed, aggregated statistics for caches configured in Traffic Ops.
+
+.. versionadded:: 1.2
+
+.. seealso:: This gives an aggregate of statistics for *all caches* within a particular CDN and time range. For statistics basic statistics from all caches regardless of CDN and at the current time, use :ref:`to-api-caches_stats`.
+
+``GET``
+-------
+Retrieves statistics about the caches within the CDN
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +============+==========+===================================================================================================================+
+ | cdnName | yes | The name of a CDN. Results will represent caches within this CDN |
+ +------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | metricType | yes | The metric type (valid metric types: 'ats.proxy.process.http.current_client_connections', 'bandwidth', 'maxKbps') |
+ +------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | startDate | yes | The begin date for data aggregation in ISO format, e.g. '2015-08-11T12:30:00-06:00' |
+ +------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | endDate | yes | The end date for data aggregation in ISO format, e.g. '2015-08-12T12:30:00-06:00' |
+ +------------+----------+-------------------------------------------------------------------------------------------------------------------+
+
+Response Structure
+------------------
+:series: A collection of tabular data and its descriptors
+
+ :columns: An array of names, in order, of the columns of the table. The first is a label for the first entry in each "value", and so on.
+ :count: The total number of data points in the "values" array
+ :name: The name of the metric which was aggregated
+ :values: An array of the actual data points. Each of which is itself an array of properties, which are labeled by the "columns" array. This can be thought of as the data's rows
+
+ :time: The time in ISO format at which this datum was collected
+ :value: The value of the datum. Its meaning is dependent upon "name" - and by extension the ``metricType`` request query parameter
+
+:summary: A summary of the data contained in the "series" object
+
+ :average: The arithmetic mean across all data point values
+ :count: The total number of data points in the "series.values" array
+ :fifthPercentile: The right-hand threshold value for the 5\ :sup:`th` percentile
+ :max: The maximum of the requested metric values
+ :min: The minimum of the requested metric values
+ :ninetyEighthPercentile: The right-hand threshold value for the 98\ :sup:`th` percentile
+ :ninetyFifthPercentile: The right-hand threshold value for the 95\ :sup:`th` percentile
+
+
+.. code-block:: json
+ :caption: Response Example
+
+ { "response": {
+ "series": {
+ "columns": [
+ "time",
+ ""
+ ],
+ "count": 29,
+ "name": "bandwidth",
+ "tags": {
+ "cdn": "over-the-top"
+ },
+ "values": [
+ [
+ "2015-08-10T22:40:00Z",
+ 229340299720
+ ],
+ [
+ "2015-08-10T22:41:00Z",
+ 224309221713.334
+ ],
+ [
+ "2015-08-10T22:42:00Z",
+ 229551834168.334
+ ],
+ [
+ "2015-08-10T22:43:00Z",
+ 225179658876.667
+ ],
+ [
+ "2015-08-10T22:44:00Z",
+ 230443968275
+ ]
+ ]
+ },
+ "summary": {
+ "average": 970410.295,
+ "count": 1376041798,
+ "fifthPercentile": 202.03,
+ "max": 3875441.02,
+ "min": 0,
+ "ninetyEighthPercentile": 2957940.93,
+ "ninetyFifthPercentile": 2366728.63
+ }
+ }}
diff --git a/docs/source/api/cachegroup_fallbacks.rst b/docs/source/api/cachegroup_fallbacks.rst
new file mode 100644
index 0000000..c2f21d6
--- /dev/null
+++ b/docs/source/api/cachegroup_fallbacks.rst
@@ -0,0 +1,286 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cachegroup_fallbacks:
+
+************************
+``cachegroup_fallbacks``
+************************
+
+``GET``
+=======
+Retrieve fallback-related configurations for a Cache Group.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +--------------+----------+---------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +==============+==========+===================================================================================================+
+ | cacheGroupId |yes\ [1]_ | The integral, unique identifier of a Cache Group whose fallback configurations shall be retrieved |
+ +--------------+----------+---------------------------------------------------------------------------------------------------+
+ | fallbackId |yes\ [1]_ | The integral, unique identifier of a fallback Cache Group |
+ +--------------+----------+---------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.3/cachegroup_fallbacks?cacheGroupId=11&fallbackId=7 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:cacheGroupId: The integral, unique identifier of the Cache Group described by this entry
+:cacheGroupName: The name of the Cache Group described by this entry
+:fallbackId: The integral, unique identifier of the Cache Group on which the Cache Group described by this entry will fall back
+:fallbackName: The name of the Cache Group on which the Cache Group described by this entry will fall back
+:fallbackOrder: The order of the fallback described by "fallbackId" and "fallbackName" in the list of fallbacks for the Cache Group described by this entry
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 15:40:34 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Wed, 14 Nov 2018 19:40:34 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: 9kauJ9tA4Ca5ElMHZk0fIJpQr+Wcx6NHiqWrnZJvyupRIOBQiUec3UW/fI9HdtE98xkrthz1daXKmdUkDhon8Q==
+ Content-Length: 125
+
+ { "response": [
+ {
+ "cacheGroupId": 11,
+ "fallbackOrder": 1,
+ "fallbackName": "CDN_in_a_Box_Edge",
+ "fallbackId": 7,
+ "cacheGroupName": "test"
+ }
+ ]}
+
+
+.. [1] At least one of these must be provided, not necessarily both (though both is perfectly valid).
+
+``POST``
+========
+Creates fallback configuration for a Cache Group.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Array
+
+Request Structure
+-----------------
+The request payload for this endpoint **must** be an array, even if only one fallback relationship is being created.
+
+:cacheGroupId: Integral, unique identifier of a Cache Group to which to assign a fallback
+:fallbackId: Integral, unique identifier of a Cache Group on which the Cache Group identified by ``cacheGroupId`` will fall back
+:fallbackOrder: The order of this fallback for the Cache Group identified by ``cacheGroupId``
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.3/cachegroup_fallbacks HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 59
+ Content-Type: application/x-www-form-urlencoded
+
+ [{"cacheGroupId": 11, "fallbackId": 7, "fallbackOrder": 1}]
+
+Response Structure
+------------------
+:cacheGroupId: The integral, unique identifier of the Cache Group to which this fallback was assigned
+:cacheGroupName: The name of the Cache Group to which this fallback was assigned
+:fallbackId: The integral, unique identifier of the Cache Group on which this entries Cache Group will fall back
+:fallbackName: The name of the Cache Group on which this entries Cache Group will fall back
+:fallbackOrder: The order of the fallback described by "fallbackId" and "fallbackName" in the list of fallbacks for the Cache Group described by this entry
+
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Thu, 08 Nov 2018 14:59:46 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 08 Nov 2018 18:59:46 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: 0twD50R5e7V2DtVrALQxzr2DmeHPPu8rTY8aGU4dFkx4XnOzjeRK5z+SYCrZEZ9Mh8QnWha3yZ2PtlxVTZt1YA==
+ Content-Length: 225
+
+ { "alerts": [
+ {
+ "level": "success",
+ "text": "Backup configuration CREATE for cache group 11 successful."
+ }
+ ],
+ "response": [
+ {
+ "cacheGroupId": 11,
+ "fallbackName": "CDN_in_a_Box_Edge",
+ "fallbackOrder": 1,
+ "fallbackId": 7,
+ "cacheGroupName": "test"
+ }
+ ]}
+
+
+``PUT``
+=======
+Updates an existing fallback configuration for one or more Cache Groups.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Array
+
+Request Structure
+-----------------
+The request payload for this endpoint **must** be an array, even if only one fallback relationship is being updated.
+:cacheGroupId: Integral, unique identifier of a Cache Group to which to assign a fallback
+:fallbackId: Integral, unique identifier of a Cache Group on which the Cache Group identified by ``cacheGroupId`` will fall back
+:fallbackOrder: The order of this fallback for the Cache Group identified by ``cacheGroupId``
+
+.. note:: The request data should be an array of these objects (and any number can be submitted per request), see the example
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/1.1/cachegroup_fallbacks HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 59
+ Content-Type: application/x-www-form-urlencoded
+
+ [{"cacheGroupId": 11, "fallbackId": 7, "fallbackOrder": 2}]
+
+Response Structure
+------------------
+:cacheGroupId: The integral, unique identifier of the Cache Group to which this fallback was assigned
+:cacheGroupName: The name of the Cache Group to which this fallback was assigned
+:fallbackId: The integral, unique identifier of the Cache Group on which this entries Cache Group will fall back
+:fallbackName: The name of the Cache Group on which this entries Cache Group will fall back
+:fallbackOrder: The order of the fallback described by "fallbackId" and "fallbackName" in the list of fallbacks for the Cache Group described by this entry
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Thu, 08 Nov 2018 15:07:06 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 08 Nov 2018 19:07:06 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: 7QQpwDEmSpSPn6E3FAjxNw3E7xKP3TOBdnvZiBHQwOLmOH6Eiaq58f3eMPYAuK4qMSAKBj9Y2R//Fpa59YCMRw==
+ Content-Length: 225
+
+ { "alerts": [
+ {
+ "level": "success",
+ "text": "Backup configuration UPDATE for cache group 11 successful."
+ }
+ ],
+ "response": [
+ {
+ "cacheGroupId": 11,
+ "fallbackName": "CDN_in_a_Box_Edge",
+ "fallbackOrder": 2,
+ "fallbackId": 7,
+ "cacheGroupName": "test"
+ }
+ ]}
+
+``DELETE``
+==========
+Delete fallback list assigned to a Cache Group
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object (string)
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +--------------+----------+---------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +==============+==========+===================================================================================================+
+ | cacheGroupId |yes\ [2]_ | The integral, unique identifier of a Cache Group whose fallback configurations shall be retrieved |
+ +--------------+----------+---------------------------------------------------------------------------------------------------+
+ | fallbackId |yes\ [2]_ | The integral, unique identifier of a fallback Cache Group |
+ +--------------+----------+---------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ DELETE /api/1.2/cachegroup_fallbacks?cacheGroupId=11&fallbackId=7 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Thu, 08 Nov 2018 15:48:56 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 08 Nov 2018 19:48:56 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: MG2FNZ18EyAvy/IgdUPX4XRjJXYclXtp0e/kCMfimx9C427LNwjvL1seXkvu9crT2o68i0H2q1efshDJHO81IQ==
+ Content-Length: 76
+
+ {
+ "response": "Backup Cachegroup 7 DELETED from cachegroup 11 fallback list"
+ }
+
+
+.. [2] At least one of "cacheGroupId" or "fallbackId" must be sent with the request. If both are sent, a single fallback relationship is deleted, whereas using only "cacheGroupId" will result in all fallbacks being removed from the Cache Group identified by that integral, unique identifier, and using only "fallbackId" will remove the Cache Group identified by *that* integral, unique identifier from all other Cache Groups' fallback lists.
diff --git a/docs/source/api/cachegroup_parameterID_parameter.rst b/docs/source/api/cachegroup_parameterID_parameter.rst
new file mode 100644
index 0000000..eabeee6
--- /dev/null
+++ b/docs/source/api/cachegroup_parameterID_parameter.rst
@@ -0,0 +1,85 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cachegroup-parameterID-parameter:
+
+*****************************************
+``cachegroup/{{parameter ID}}/parameter``
+*****************************************
+.. deprecated:: 1.1
+ Use :ref:`to-api-cachegroupparameters` instead
+
+.. caution:: This endpoint does not appear to work, and thus its use is strongly discouraged!
+
+``GET``
+=======
+Extract identifying information about all cachegroups with a specific parameter
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------------------+----------+------------------------------------------------+
+ | Name | Required | Description |
+ +==================+==========+================================================+
+ | parameter_ID | yes | An integral, unique identifier for a parameter |
+ +------------------+----------+------------------------------------------------+
+
+Response Structure
+------------------
+:cachegroups: An array of all Cache Groups with an associated parameter identifiable by the ``parameter_id`` request path parameter
+
+ :id: The numeric ID of the Cache Group
+ :name: The human-readable name of the Cache Group
+
+.. code-block:: json
+ :caption: Response Example
+
+ { "response": {
+ "cachegroups": [
+ {
+ "name": "CDN_in_a_Box_Edge",
+ "id": 7
+ },
+ {
+ "name": "CDN_in_a_Box_Mid",
+ "id": 6
+ },
+ {
+ "name": "TRAFFIC_ANALYTICS",
+ "id": 1
+ },
+ {
+ "name": "TRAFFIC_OPS",
+ "id": 2
+ },
+ {
+ "name": "TRAFFIC_OPS_DB",
+ "id": 3
+ },
+ {
+ "name": "TRAFFIC_PORTAL",
+ "id": 4
+ },
+ {
+ "name": "TRAFFIC_STATS",
+ "id": 5
+ }
+ ]
+ }}
diff --git a/docs/source/api/cachegroupparameters.rst b/docs/source/api/cachegroupparameters.rst
new file mode 100644
index 0000000..f2842a9
--- /dev/null
+++ b/docs/source/api/cachegroupparameters.rst
@@ -0,0 +1,135 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cachegroupparameters:
+
+************************
+``cachegroupparameters``
+************************
+
+``GET``
+=======
+Extract information about parameters associated with Cache Groups
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Object
+
+Response Structure
+------------------
+No available parameters
+
+Response Structure
+------------------
+:cachegroupParameters: An array of identifying information for parameters assigned to Cache Group profiles
+
+ :parameter: Numeric ID of the parameter
+ :last_updated: Date and time of last modification in ISO format
+ :cachegroup: Name of the Cache Group
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 18:24:12 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Wed, 14 Nov 2018 22:24:12 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: PZyh09NeYYy4sXSv+Bfov0v32EuEk/1y7/B+4fyvhbcPxWQ650NXBDpAe8IsmYZQYVRB03xlBtc33bo3Ixunbg==
+ Content-Length: 124
+
+ { "response": {
+ "cachegroupParameters": [
+ {
+ "parameter": 124,
+ "last_updated": "2018-11-14 18:23:40.488853+00",
+ "cachegroup": "test"
+ }
+ ]
+ }}
+
+``POST``
+========
+Assign parameter(s) to Cache Group(s).
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Array
+
+Request Structure
+-----------------
+The request data can take the form of either a single object or an array of one or more objects.
+
+:cacheGroupId: Integral, unique identifier for the Cache Group to which a parameter is being assigned
+:parameterId: Integral, unique identifier for the Parameter being assigned
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.1/cachegroupparameters HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 39
+ Content-Type: application/json
+
+ {
+ "cachegroupId": 8,
+ "parameterId": 124
+ }
+
+Response Structure
+------------------
+:parameter: Numeric ID of the parameter
+:last_updated: Date and time of last modification in ISO format
+:cachegroup: Name of the Cache Group
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 15:47:49 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Wed, 14 Nov 2018 19:47:49 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: wCv388wFaSjgFLCnI9dchlcyGxaVr8IhBAG25F+rpI2/azCswEYTcVBSlYOg6NxTQRzGkluMvn67jI6rV+vNsQ==
+ Content-Length: 136
+
+ { "alerts": [
+ {
+ "level": "success",
+ "text": "Profile parameter associations were created."
+ }
+ ],
+ "response": [
+ {
+ "cacheGroupId": 8,
+ "parameterId": 124
+ }
+ ]}
+
diff --git a/docs/source/api/cachegroupparameters_id_parameterID.rst b/docs/source/api/cachegroupparameters_id_parameterID.rst
new file mode 100644
index 0000000..8f51c57
--- /dev/null
+++ b/docs/source/api/cachegroupparameters_id_parameterID.rst
@@ -0,0 +1,75 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cachegroupparameters-id-parameterID:
+
+***********************************************
+``cachegroupparameters/{{ID}}/{{parameterID}}``
+***********************************************
+
+``DELETE``
+==========
+De-associate a parameter with a Cache Group
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: ``undefined``
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +-------------+-----------------------------------------------------------------------------------------+
+ | Name | Description |
+ +=============+=========================================================================================+
+ | ID | Unique identifier for the Cache Group which will have the parameter association deleted |
+ +-------------+-----------------------------------------------------------------------------------------+
+ | parameterID | Unique identifier for the parameter which will be removed from a Cache Group |
+ +-------------+-----------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ DELETE /api/1.1/cachegroupparameters/8/124 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 18:26:40 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Wed, 14 Nov 2018 22:26:40 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: Cuj+ZPAKsDLp4FpbJDcwsWY0yVQAi1Um1CWraeTIQEMlyJSBEm17oKQWDjzTrvqqV8Prhu3gzlcHoVPzEpbQ1Q==
+ Content-Length: 84
+
+ { "alerts": [
+ {
+ "level": "success",
+ "text": "Profile parameter association was deleted."
+ }
+ ]}
diff --git a/docs/source/api/cachegroups.rst b/docs/source/api/cachegroups.rst
new file mode 100644
index 0000000..765c01c
--- /dev/null
+++ b/docs/source/api/cachegroups.rst
@@ -0,0 +1,216 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cachegroups:
+
+***************
+``cachegroups``
+***************
+
+``GET``
+=======
+Extract information about all Cache Groups.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +------+----------+----------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +======+==========+==============================================================================================+
+ | type | no | Return only Cache Groups that are of the type identified by this integral, unique identifier |
+ +------+----------+----------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.3/cachegroups?type=23 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+
+Response Structure
+------------------
+:fallbackToClosest: If ``true``, Traffic Router will direct clients to peers of this Cache Group in the event that it becomes unavailable.
+:id: A numeric, unique identifier for the Cache Group
+:lastUpdated: The time and date at which this entry was last updated in ISO format
+:latitude: Latitude for the Cache Group
+:longitude: Longitude for the Cache Group
+:name: The name of the Cache Group entry
+:parentCachegroupId: ID of this Cache Group's parent Cache Group (if any)
+:parentCachegroupName: Name of this Cache Group's parent Cache Group (if any)
+:secondaryParentCachegroupId: ID of this Cache Group's secondary parent Cache Group (if any)
+:secondaryParentCachegroupName: Name of this Cache Group's secondary parent Cache Group (if any)
+:shortName: Abbreviation of the Cache Group name
+:typeId: Unique identifier for the 'Type' of Cache Group entry
+:typeName: The name of the type of Cache Group entry
+
+.. note:: The default value of ``fallbackToClosest`` is 'true', and if it is 'null' Traffic Control components will still interpret it as 'true'.
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: oV6ifEgoFy+v049tVjSsRdWQf4bxjrUvIYfDdgpUtlxiC7gzCv31m5bXQ8EUBW4eg2hfYM+BsGvJpnNDZB7pUg==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 07 Nov 2018 19:46:36 GMT
+ Content-Length: 379
+
+ { "response": [
+ {
+ "id": 7,
+ "name": "CDN_in_a_Box_Edge",
+ "shortName": "ciabEdge",
+ "latitude": 38.897663,
+ "longitude": -77.036574,
+ "parentCachegroupName": "CDN_in_a_Box_Mid",
+ "parentCachegroupId": 6,
+ "secondaryParentCachegroupName": null,
+ "secondaryParentCachegroupId": null,
+ "fallbackToClosest": null,
+ "localizationMethods": null,
+ "typeName": "EDGE_LOC",
+ "typeId": 23,
+ "lastUpdated": "2018-11-07 14:45:43+00"
+ }
+ ]}
+
+
+``POST``
+========
+Creates a cache group
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+:fallbackToClosest: If ``true``, the Traffic Router will fall back on the 'closest' Cache Group to this one, when this one fails
+
+ .. note:: The default value of ``fallbackToClosest`` is 'true', and if it is 'null' Traffic Control components will still interpret it as 'true'.
+
+:latitude: An optional field which, if present, will define the latitude for the Cache Group to ISO-standard double specification\ [1]_
+:localizationMethods: Array of enabled localization methods (as strings)
+:longitude: An optional field which, if present, will define the longitude for the Cache Group to ISO-standard double specification\ [1]_
+:name: The name of the Cache Group
+:parentCachegroupId: An optional field which, if present, should be an integral, unique identifier for this Cache Group's primary parent
+:secondaryParentCachegroupId: An optional field which, if present, should be an integral, unique identifier for this Cache Group's secondary parent
+:shortName: An abbreviation of the ``name``
+:typeId: An integral, unique identifier for the type of Cache Group; one of:
+
+ EDGE_LOC
+ Indicates a group of Edge-tier caches
+ MID_LOC
+ Indicates a group of Mid-tier caches
+ ORG_LOC
+ Indicates a group of origin servers (though only one server will typically be in any given ORG_LOC)
+
+ .. note:: The actual, integral, unique identifiers for these types must first be obtained, generally via :ref:`to-api-types`.
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.1/cachegroups HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 252
+ Content-Type: application/x-www-form-urlencoded
+
+ {
+ "fallbackToClosest": false,
+ "latitude": 0,
+ "longitude": 0,
+ "localizationMethods": [],
+ "name": "test",
+ "parentCachegroupId": 7,
+ "shortName": "test",
+ "typeId": 23
+ }
+
+Response Structure
+------------------
+:fallbackToClosest: If ``true``, Traffic Router will direct clients to peers of this Cache Group in the event that it becomes unavailable.
+:id: A numeric, unique identifier for the Cache Group
+:lastUpdated: The time and date at which this entry was last updated in ISO format
+:latitude: Latitude for the Cache Group
+:longitude: Longitude for the Cache Group
+:name: The name of the Cache Group entry
+:parentCachegroupId: ID of this Cache Group's parent Cache Group (if any)
+:parentCachegroupName: Name of this Cache Group's parent Cache Group (if any)
+:secondaryParentCachegroupId: ID of this Cache Group's secondary parent Cache Group (if any)
+:secondaryParentCachegroupName: Name of this Cache Group's secondary parent Cache Group (if any)
+:shortName: Abbreviation of the Cache Group name
+:typeId: Unique identifier for the 'Type' of Cache Group entry
+:typeName: The name of the type of Cache Group entry
+
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: YvZlh3rpfl3nBq6SbNVhbkt3IvckbB9amqGW2JhLxWK9K3cxjBq5J2sIHBUhrLKUhE9afpxtvaYrLRxjt1/YMQ==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 07 Nov 2018 22:11:50 GMT
+ Content-Length: 379
+
+ { "alerts": [
+ {
+ "text": "cg was created.",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "id": 10,
+ "name": "test",
+ "shortName": "test",
+ "latitude": 0,
+ "longitude": 0,
+ "parentCachegroupName": null,
+ "parentCachegroupId": 7,
+ "secondaryParentCachegroupName": null,
+ "secondaryParentCachegroupId": null,
+ "fallbackToClosest": false,
+ "localizationMethods": [],
+ "typeName": null,
+ "typeId": 23,
+ "lastUpdated": "2018-11-07 22:11:50+00"
+ }}
+
+.. [1] While these fields are technically optional, note that if they are not specified many things may break. For this reason, Traffic Portal requires them when creating or editing Cache Groups.
+
+.. This doesn't appear to exist anymore - can't reproduce in CIAB nor production
+.. ``/api/1.1/cachegroups/:parameter_id/parameter/available``
+.. ==========================================================
diff --git a/docs/source/api/cachegroups_id.rst b/docs/source/api/cachegroups_id.rst
new file mode 100644
index 0000000..0a4d34f
--- /dev/null
+++ b/docs/source/api/cachegroups_id.rst
@@ -0,0 +1,266 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cachegroups_id:
+
+**********************
+``cachegroups/{{ID}}``
+**********************
+Extracts information about a single Cache Group
+
+``GET``
+=======
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +--------------+---------------------------------------------------------------+
+ | Parameter | Description |
+ +==============+===============================================================+
+ | ID | The integral, unique identifier of a Cache Group |
+ +--------------+---------------------------------------------------------------+
+
+Response Structure
+------------------
+:fallbackToClosest: If ``true``, Traffic Router will direct clients to peers of this Cache Group in the event that it becomes unavailable
+:id: Integral, unique identifier for the Cache Group
+:lastUpdated: The date and time at which this Cache Group was last updated, in an ISO-like format
+:latitude: Latitude of the Cache Group
+:localizationMethods: An array of strings that name the localization methods enabled for this Cache Group. Each of the three available localization methods may be present, with the following meanings:
+
+ CZ
+ Lookup in the Traffic Router's "Coverage Zone" file is enabled
+ DEEP_CZ
+ Lookup in the Traffic Router's "Deep Coverage Zone" file is enabled
+ GEO
+ Use of a geographical location-to-IP mapping database is enabled
+
+:longitude: Longitude of the Cache Group
+:name: The name of the Cache Group
+:parentCachegroupId: Integral, unique identifier of the Cache Group that is this Cache Group's parent
+:parentCachegroupName: The name of the Cache Group that is this Cache Group's parent
+:secondaryParentCachegroupId: Integral, unique identifier of the Cache Group that is this Cache Group's secondary parent
+:secondaryParentCachegroupName: The name of the Cache Group that is this Cache Group's secondary parent
+:shortName: Abbreviation of the Cache Group Name
+:typeId: The integral, unique identifier for the 'Type' of Cache Group
+:typeName: The name of the type of this Cache Group
+
+.. note:: The default value of ``fallbackToClosest`` is 'true', and if it is 'null' Traffic Control components will still interpret it as 'true'.
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: EXO+TK1CIwQ5lzTXQGqlLDzU641pLLCQbyqz5Z8QUYSPAjjn5cqC9W3c0ioDiCdK9bUWvHP3E4/ERBzkBTi06g==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 18:35:53 GMT
+ Content-Length: 357
+
+ { "response": [
+ {
+ "id": 8,
+ "name": "test",
+ "shortName": "test",
+ "latitude": 0,
+ "longitude": 0,
+ "parentCachegroupName": "CDN_in_a_Box_Mid",
+ "parentCachegroupId": 6,
+ "secondaryParentCachegroupName": null,
+ "secondaryParentCachegroupId": null,
+ "fallbackToClosest": null,
+ "localizationMethods": [
+ "DEEP_CZ",
+ "CZ"
+ ],
+ "typeName": "EDGE_LOC",
+ "typeId": 23,
+ "lastUpdated": "2018-11-14 18:23:33+00"
+ }
+ ]}
+
+
+``PUT``
+=======
+Update Cache Group
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +--------------+---------------------------------------------------------------+
+ | Parameter | Description |
+ +==============+===============================================================+
+ | ID | The integral, unique identifier of a Cache Group |
+ +--------------+---------------------------------------------------------------+
+
+:fallbackToClosest: An optional field which, if present and ``true``, will cause Traffic Router to direct clients to peers of this Cache Group in the event that it becomes unavailable
+
+ .. note:: The default value of ``fallbackToClosest`` is ``true``, and if it is ``null`` or ``undefined`` Traffic Control components will still interpret it as ``true``.
+
+:latitude: An optional field which, if specified, will set the latitude of the new Cache Group\ [1]_
+:localizationMethods: An optional array of strings that name the localization methods enabled for this Cache Group. Each of the three available localization methods may be present, with the following meanings:
+
+ CZ
+ Lookup in the Traffic Router's "Coverage Zone" file will be enabled
+ DEEP_CZ
+ Lookup in the Traffic Router's "Deep Coverage Zone" file will be enabled
+ GEO
+ Use of a geographical location-to-IP mapping database will be enabled
+
+:longitude: An optional field which, if specified, will set the longitude of the new Cache Group\ [1]_
+:name: The desired name of the Cache Group entry
+:parentCachegroup: An optional field which, if specified, should be the integral, unique identifier of Cache Group to use as the new Cache Group's parent
+:secondaryParentCachegroup: An optional field which, if specified, should be the integral, unique identifier of Cache Group to use as the new Cache Group's parent
+:shortName: A more human-friendly abbreviation of the Cache Group's name
+:typeId: The integral, unique identifier of the desired type of the new Cache Group - by default the valid options are: "EDGE_LOC", "MID_LOC" or "ORG_LOC"
+
+ .. note:: Rather than the actual name of the type, be sure to use the "database ID" of the desired type. Typically this will require looking up the types via the API first, as the IDs of even these default types is not deterministic.
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/1.3/cachegroups/8 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 118
+ Content-Type: application/json
+
+ {"latitude": 0.0, "longitude": 0.0, "name": "test", "shortName": "test", "typeId": 23, "localizationMethods": ["GEO"]}
+
+Response Structure
+------------------
+:fallbackToClosest: If ``true``, Traffic Router will direct clients to peers of this Cache Group in the event that it becomes unavailable
+:id: Integral, unique identifier for the Cache Group
+:lastUpdated: The date and time at which this Cache Group was last updated, in an ISO-like format
+:latitude: Latitude of the Cache Group
+:localizationMethods: An array of strings that name the localization methods enabled for this Cache Group. Each of the three available localization methods may be present, with the following meanings:
+
+ CZ
+ Lookup in the Traffic Router's "Coverage Zone" file is enabled
+ DEEP_CZ
+ Lookup in the Traffic Router's "Deep Coverage Zone" file is enabled
+ GEO
+ Use of a geographical location-to-IP mapping database is enabled
+
+:longitude: Longitude of the Cache Group
+:name: The name of the Cache Group
+:parentCachegroupId: Integral, unique identifier of the Cache Group that is this Cache Group's parent
+:parentCachegroupName: The name of the Cache Group that is this Cache Group's parent
+:secondaryParentCachegroupId: Integral, unique identifier of the Cache Group that is this Cache Group's secondary parent
+:secondaryParentCachegroupName: The name of the Cache Group that is this Cache Group's secondary parent
+:shortName: Abbreviation of the Cache Group Name
+:typeId: The integral, unique identifier for the 'Type' of Cache Group
+:typeName: The name of the type of this Cache Group
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: t1W65/2kj25QyHt0Ib0xpBaAR2sXu2kOsRZ49WjKZp/AK5S1YWhX7VNWCuUGiN1VNM4QRNqODC/7ewhYDFUncA==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 19:14:28 GMT
+ Content-Length: 385
+
+ { "alerts": [
+ {
+ "text": "cg was updated.",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "id": 8,
+ "name": "test",
+ "shortName": "test",
+ "latitude": 0,
+ "longitude": 0,
+ "parentCachegroupName": null,
+ "parentCachegroupId": null,
+ "secondaryParentCachegroupName": null,
+ "secondaryParentCachegroupId": null,
+ "fallbackToClosest": null,
+ "localizationMethods": [
+ "GEO"
+ ],
+ "typeName": null,
+ "typeId": 23,
+ "lastUpdated": "2018-11-14 19:14:28+00"
+ }}
+
+.. [1] While these fields are technically optional, note that if they are not specified many things may break. For this reason, Traffic Portal requires them when creating or editing Cache Groups.
+
+``DELETE``
+==========
+Delete Cache Group. Cache Groups which have assigned servers or child Cache Groups cannot be deleted.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: ``undefined``
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +--------------+----------------------------------------------------------------+
+ | Parameter | Description |
+ +==============+================================================================+
+ | ID | The integral, unique identifier of a Cache Group to be deleted |
+ +--------------+----------------------------------------------------------------+
+
+Response Structure
+------------------
+.. code block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: 5jZBgO7h1eNF70J/cmlbi3Hf9KJPx+WLMblH/pSKF3FWb/10GUHIN35ZOB+lN5LZYCkmk3izGbTFkiruG8I41Q==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 20:31:04 GMT
+ Content-Length: 57
+
+ { "alerts": [
+ {
+ "text": "cg was deleted.",
+ "level": "success"
+ }
+ ]}
+
diff --git a/docs/source/api/cachegroups_id_deliveryservices.rst b/docs/source/api/cachegroups_id_deliveryservices.rst
new file mode 100644
index 0000000..845bc9a
--- /dev/null
+++ b/docs/source/api/cachegroups_id_deliveryservices.rst
@@ -0,0 +1,91 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cachegroups-id-deliveryservices:
+
+***************************************
+``cachegroups/{{ID}}/deliveryservices``
+***************************************
+
+``POST``
+========
+Assigns a Cache Group to one or more Delivery Services
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table::Request Path Parameters
+
+ +------+-------------------------------------------------------------------+
+ | Name | Description |
+ +======+===================================================================+
+ | ID | The integral, unique identifier of the Cache Group being assigned |
+ +------+-------------------------------------------------------------------+
+
+:deliveryServices: The integral, unique identifiers of the Delivery Services to which the Cache Group is being assigned
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.3/cachegroups/8/deliveryservices HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 25
+ Content-Type: application/x-www-form-urlencoded
+
+ {"deliveryServices": [2]}
+
+Response Structure
+------------------
+:deliveryServices: An array of *all* Delivery Services to which the Cache Group is assigned (**not** just the one(s) to which it was assigned via the request)
+:id: The Cache Group's ID
+:serverNames: An array of the (short) hostnames of all servers in the Cache Group
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: j/yH0gvJoaGjiLZU/0MA8o5He20O4aJ5wh1eF9ex6F6IBO1liM9Wk9RkWCw7sdiUHoy13/mf7gDntisZwzP7yw==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 19:54:17 GMT
+ Content-Length: 183
+
+ { "alerts": [
+ {
+ "text": "Delivery services successfully assigned to all the servers of cache group 8.",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "id": 8,
+ "serverNames": [
+ "foo"
+ ],
+ "deliveryServices": [
+ 2
+ ]
+ }}
+
diff --git a/docs/source/api/cachegroups_id_parameters.rst b/docs/source/api/cachegroups_id_parameters.rst
new file mode 100644
index 0000000..899f1a9
--- /dev/null
+++ b/docs/source/api/cachegroups_id_parameters.rst
@@ -0,0 +1,77 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cachegroup_id_parameters:
+
+*********************************
+``cachegroups/{{ID}}/parameters``
+*********************************
+Gets all the parameters associated with a Cache Group
+
+.. seealso:: :ref:`param-prof`
+
+``GET``
+=======
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +-----------+--------------------------------------------------+
+ | Parameter | Description |
+ +===========+==================================================+
+ | ID | The integral, unique identifier of a Cache Group |
+ +-----------+--------------------------------------------------+
+
+
+Response Structure
+------------------
+:configFile: Configuration file associated with the parameter
+:id: A numeric, unique identifier for this parameter
+:lastUpdated: The date and time at which this parameter was last updated, in an ISO-like format
+:name: Name of the parameter
+:secure: If ``true``, the parameter value is only visible to "admin"-role users
+:value: Value of the parameter
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 19:56:23 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Wed, 14 Nov 2018 23:56:23 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: DfqPtySzVMpnBYqVt/45sSRG/1pRTlQdIcYuQZ0CQt79QSHLzU5e4TbDqht6ntvNP041LimKsj5RzPlPX1n6tg==
+ Content-Length: 135
+
+ { "response": [
+ {
+ "lastUpdated": "2018-11-14 18:22:43.754786+00",
+ "value": "foobar",
+ "secure": false,
+ "name": "foo",
+ "id": 124,
+ "configFile": "bar"
+ }
+ ]}
diff --git a/docs/source/api/cachegroups_id_queue_updates.rst b/docs/source/api/cachegroups_id_queue_updates.rst
new file mode 100644
index 0000000..ce016ba
--- /dev/null
+++ b/docs/source/api/cachegroups_id_queue_updates.rst
@@ -0,0 +1,90 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cachegroups-id-queue_update:
+
+***********************************
+``cachegroups/{{ID}}/queue_update``
+***********************************
+
+``POST``
+========
+Queue or dequeue updates for all servers assigned to a cache group limited to a specific CDN.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+-------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+=================================================================================================+
+ | ID | The integral, unique identifier for the Cache Group for which updates are being queued/dequeued |
+ +------+-------------------------------------------------------------------------------------------------+
+
+:action: The action to perform; one of "queue" or "dequeue"
+:cdn: The full name of the CDN in need of update queue/dequeue\ [1]_
+:cdnId: The integral, unique identifier for the CDN in need of update queue/dequeue\ [1]_
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.3/cachegroups/8/queue_update HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 42
+ Content-Type: application/json
+
+ {"action": "queue", "cdn": "CDN-in-a-Box"}
+
+.. [1] Either 'cdn' or 'cdnID' *must* be in the request data (but not both).
+
+Response Structure
+------------------
+:action: The action processed, one of "queue" or "dequeue"
+:cachegroupId: The integral, unique identifier of the Cache Group for which updates were queued/dequeued
+:cachegroupName: The name of the Cache Group for which updates were queued/dequeued
+:cdn: The name of the CDN to which the queue/dequeue operation was restricted
+:serverNames: An array of the (short) hostnames of the servers within the Cache Group which are also assigned to the CDN specified in the ``"cdn"`` field
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: UAcP7LrflU1RnfR4UqbQrJczlk5rkrcLOtTXJTFvIUXxK1EklZkHkE4vewjDaVIhJJ6YQg8jmPGQpr+x1RHabw==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 20:19:46 GMT
+ Content-Length: 115
+
+ { "response": {
+ "cachegroupName": "test",
+ "action": "queue",
+ "serverNames": [
+ "foo"
+ ],
+ "cdn": "CDN-in-a-Box",
+ "cachegroupID": 8
+ }}
diff --git a/docs/source/api/cachegroups_id_unassigned_parameters.rst b/docs/source/api/cachegroups_id_unassigned_parameters.rst
new file mode 100644
index 0000000..4534769
--- /dev/null
+++ b/docs/source/api/cachegroups_id_unassigned_parameters.rst
@@ -0,0 +1,87 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cachegroup_id_unassigned_parameters:
+
+********************************************
+``cachegroups/{{id}}/unassigned_parameters``
+********************************************
+Gets all the parameters NOT associated with a specific Cache Group
+
+.. seealso:: :ref:`param-prof`
+
+``GET``
+=======
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------------------+----------+-----------------------+
+ | Name | Required | Description |
+ +==================+==========+=======================+
+ | ``id`` | yes | Cache Group ID |
+ +------------------+----------+-----------------------+
+
+
+Response Structure
+------------------
+:configFile: Configuration file associated with the parameter
+:id: A numeric, unique identifier for this parameter
+:lastUpdated: The Time / Date this entry was last updated
+:name: Name of the parameter
+:secure: Is the parameter value only visible to admin users
+:value: Value of the parameter
+
+.. code-block:: json
+ :caption: Response Example
+
+ { "response": [
+ {
+ "lastUpdated": "2018-10-09 11:14:33.862905+00",
+ "value": "/opt/trafficserver/etc/trafficserver",
+ "secure": false,
+ "name": "location",
+ "id": 6836,
+ "configFile": "hdr_rw_bamtech-nhl-live.config"
+ },
+ {
+ "lastUpdated": "2018-10-09 11:14:33.862905+00",
+ "value": "/opt/trafficserver/etc/trafficserver",
+ "secure": false,
+ "name": "location",
+ "id": 6837,
+ "configFile": "hdr_rw_mid_bamtech-nhl-live.config"
+ },
+ {
+ "lastUpdated": "2018-10-09 11:55:46.014844+00",
+ "value": "/opt/trafficserver/etc/trafficserver",
+ "secure": false,
+ "name": "location",
+ "id": 6842,
+ "configFile": "hdr_rw_bamtech-nhl-live-t.config"
+ },
+ {
+ "lastUpdated": "2018-10-09 11:55:46.014844+00",
+ "value": "/opt/trafficserver/etc/trafficserver",
+ "secure": false,
+ "name": "location",
+ "id": 6843,
+ "configFile": "hdr_rw_mid_bamtech-nhl-live-t.config"
+ }
+ ]}
diff --git a/docs/source/api/cachegroups_parameterID_parameter_available.rst b/docs/source/api/cachegroups_parameterID_parameter_available.rst
new file mode 100644
index 0000000..c0e35bd
--- /dev/null
+++ b/docs/source/api/cachegroups_parameterID_parameter_available.rst
@@ -0,0 +1,61 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cachegroups-parameterID-parameter-available:
+
+****************************************************
+``cachegroups/{{parameter ID}}/parameter/available``
+****************************************************
+.. deprecated:: 1.1
+ Use :ref:`to-api-cachegroupparameters` instead
+
+.. caution:: This endpoint does not appear to work, and thus its use is strongly discouraged!
+
+``GET``
+=======
+Gets a list of Cache Groups which are available to have a specific parameter assigned to them
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------------------+----------+--------------------------------------------------------------+
+ | Name | Required | Description |
+ +==================+==========+==============================================================+
+ | ``parameter ID`` | yes | The integral, unique identifier of the parameter of interest |
+ +------------------+----------+--------------------------------------------------------------+
+
+Response Structure
+------------------
+:id: An integral, unique identifier for the Cache Group
+:name: The name of the Cache Group
+
+.. code-block:: json
+ :caption: Response Example
+
+ { "response": [
+ {
+ "name": "dc-chicago",
+ "id": "21"
+ },
+ {
+ "name": "dc-cmc",
+ "id": "22"
+ }
+ ]}
diff --git a/docs/source/api/cachegroups_trimmed.rst b/docs/source/api/cachegroups_trimmed.rst
new file mode 100644
index 0000000..ae46e30
--- /dev/null
+++ b/docs/source/api/cachegroups_trimmed.rst
@@ -0,0 +1,78 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cachegroups_trimmed:
+
+***********************
+``cachegroups/trimmed``
+***********************
+Extract just the names of all Cache Groups.
+
+``GET``
+=======
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+No parameters available
+
+Response Structure
+------------------
+:name: The name of the Cache Group |
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: OyOKqpB24AMlrENIEoA4la/3rclnuKMayvzskmPNPXrDMQksGt0UjVwORYmMdmIS5dQHuIlglBlksvLtqjziHQ==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 20:23:23 GMT
+ Content-Length: 216
+
+ { "response": [
+ {
+ "name": "TRAFFIC_ANALYTICS"
+ },
+ {
+ "name": "TRAFFIC_OPS"
+ },
+ {
+ "name": "TRAFFIC_OPS_DB"
+ },
+ {
+ "name": "TRAFFIC_PORTAL"
+ },
+ {
+ "name": "TRAFFIC_STATS"
+ },
+ {
+ "name": "CDN_in_a_Box_Mid"
+ },
+ {
+ "name": "CDN_in_a_Box_Edge"
+ },
+ {
+ "name": "test"
+ }
+ ]}
+
diff --git a/docs/source/api/caches_stats.rst b/docs/source/api/caches_stats.rst
new file mode 100644
index 0000000..e9d0185
--- /dev/null
+++ b/docs/source/api/caches_stats.rst
@@ -0,0 +1,80 @@
+..
+..
+.. 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.
+..
+
+
+.. _to-api-caches_stats:
+
+****************
+``caches/stats``
+****************
+An API endpoint that returns cache statistics using the :ref:`tm-api`.
+
+.. seealso:: This gives a set of basic statistics for *all caches* at the current time. For statistics from time ranges and/or aggregated over a specific CDN, use :ref:`to-api-cache_stats`.
+
+``GET``
+=======
+Retrieves cache stats from Traffic Monitor. Also includes rows for aggregates.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+No parameters available.
+
+Response Structure
+------------------
+:cachegroup: The name of the Cache Group to which this cache belongs
+:connections: Current number of TCP connections maintained by the cache
+:healthy: ``true`` if Traffic Monitor has marked the cache as "healthy", ``false`` otherwise
+
+ .. seealso:: :ref:`health-proto`
+
+:hostname: The (short) hostname of the cache
+:ip: The IP address of the cache
+:kbps: Cache upload speed (to clients) in Kilobits per second
+:profile: The name of the profile in use by this cache
+:status: The status of the cache
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 20:25:01 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 15 Nov 2018 00:25:01 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: DqbLgitanS8q81/qKC1i+ImMiEMF+SW4G9rb79FWdeWcgwFjL810tlTRp1nNNfHV+tajgjyK+wMHobqVyaNEfA==
+ Content-Length: 133
+
+ { "response": [
+ {
+ "profile": "ALL",
+ "connections": 0,
+ "ip": null,
+ "status": "ALL",
+ "healthy": true,
+ "kbps": 0,
+ "hostname": "ALL",
+ "cachegroup": "ALL"
+ }
+ ]}
diff --git a/docs/source/api/capabilities.rst b/docs/source/api/capabilities.rst
new file mode 100644
index 0000000..589cdef
--- /dev/null
+++ b/docs/source/api/capabilities.rst
@@ -0,0 +1,132 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-capabilities:
+
+****************
+``capabilities``
+****************
+
+``GET``
+=======
+Get all capabilities.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+No available parameters
+
+Response Structure
+------------------
+:name: Name of the capability
+:description: Describes the APIs covered by the capability.
+:lastUpdated: Date and time of the last update made to this capability, in ISO format
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 20:26:19 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 15 Nov 2018 00:26:19 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: zmjsQO3Y4r1/xCFOHB+E+8+bbgDyVcvoR0d4gKqqsWTFaUnxp2flIzuFqWjXf+wb4Bbd1e2Ojse4nQKnyIFKGw==
+ Transfer-Encoding: chunked
+
+ { "response": [
+ {
+ "name": "cdn-read",
+ "description": "View CDN configuration",
+ "lastUpdated": "2017-04-02 08:22:43"
+ },
+ {
+ "name": "cdn-write",
+ "description": "Create, edit or delete CDN configuration",
+ "lastUpdated": "2017-04-02 08:22:43"
+ }
+ ]}
+
+``POST``
+========
+Create a capability.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+
+Request Structure
+-----------------
+:name: The name of the capability being created
+:description: A description of what the capability allows
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.4/capabilities HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 109
+ Content-Type: application/json
+
+ {
+ "name": "test",
+ "description": "This is only a test. If this were a real capability, it might do something"
+ }
+
+Response Structure
+------------------
+:description: Describes the APIs covered by the capability.
+:name: Name of the capability
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 20:33:00 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 15 Nov 2018 00:33:00 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: HhhQzw3JBLv90lOeeSGj75uknADanz3fUnQt1E266HAKPTFuTjuIJpf8ni9fb9Chv9LN7mt16utcHMbP8MBHZw==
+ Content-Length: 183
+
+ { "alerts": [
+ {
+ "level": "success",
+ "text": "Capability was created."
+ }
+ ],
+ "response": {
+ "name": "test",
+ "description": "This is only a test. If this were a real capability, it might do something"
+ }}
+
diff --git a/docs/source/api/capabilities_name.rst b/docs/source/api/capabilities_name.rst
new file mode 100644
index 0000000..14038cb
--- /dev/null
+++ b/docs/source/api/capabilities_name.rst
@@ -0,0 +1,184 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-capabilities-name:
+
+*************************
+``capabilities/{{name}}``
+*************************
+
+``GET``
+=======
+Get a capability by name.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+----------------------------------------+
+ | Name | Description |
+ +======+========================================+
+ | name | The name of the capability of interest |
+ +------+----------------------------------------+
+
+Response Structure
+------------------
+:description: Describes the APIs covered by the capability
+:lastUpdated: Date and time of the last update made to this capability, in ISO format
+:name: Name of the capability
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 20:37:17 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 15 Nov 2018 00:37:17 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: 0YBTC5TEAOJ6B8gsaKgOD1ni2hnZ8Kh9u2JhcmExoGIPaMEKpp4Omr4FglkOQZuh/IB90eJjBMNMeCEvZCxWRg==
+ Content-Length: 167
+
+ { "response": [
+ {
+ "lastUpdated": "2018-11-14 20:33:00.275376+00",
+ "name": "test",
+ "description": "This is only a test. If this were a real capability, it might do something"
+ }
+ ]}
+
+
+``PUT``
+=======
+Edit a capability.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+-------------------------------------------+
+ | Name | Description |
+ +======+===========================================+
+ | name | The name of the capability to be modified |
+ +------+-------------------------------------------+
+
+:description: Describes the APIs covered by the capability
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/1.4/capabilities/test HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 45
+ Content-Type: application/json
+
+ {"description": "A much shorter description"}
+
+Response Structure
+------------------
+:description: Describes the APIs covered by the capability.
+:lastUpdated: Date and time of the last update made to this capability, in ISO format
+:name: The name of the capability
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 20:40:33 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 15 Nov 2018 00:40:33 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: +5mLZ/CJnDkJMbnFviXtVdjwt4bu7ykiMIs73zsnuKV/k4q/d025b2pjYDQkSgtfWPJ73FcusAuBM9TCVT3KsA==
+ Content-Length: 181
+
+ { "alerts": [
+ {
+ "level": "success",
+ "text": "Capability was updated."
+ }
+ ],
+ "response": {
+ "lastUpdated": "2018-11-14 20:33:00.275376+00",
+ "name": "test",
+ "description": "A much shorter description"
+ }}
+
+
+``DELETE``
+==========
+Delete a capability.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: ``undefined``
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters**
+
+ +-----------------+----------+------------------------------------------------+
+ | Name | Required | Description |
+ +=================+==========+================================================+
+ | ``name`` | yes | Capability name. |
+ +-----------------+----------+------------------------------------------------+
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 20:45:37 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 15 Nov 2018 00:45:37 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: IlAiV4ebwTpMIgeYlR5RuwOhwmHsFs8Ekt7AaEDb3v+lXjvjkqU98xFsfNWvpvPbT/iJnotENhtVq8TVdvoPLg==
+ Content-Length: 61
+
+ { "alerts": [
+ {
+ "level": "success",
+ "text": "Capability deleted."
+ }
+ ]}
+
diff --git a/docs/source/api/cdns.rst b/docs/source/api/cdns.rst
new file mode 100644
index 0000000..357570c
--- /dev/null
+++ b/docs/source/api/cdns.rst
@@ -0,0 +1,136 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns:
+
+********
+``cdns``
+********
+Extract information about all CDNs
+
+``GET``
+=======
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+No parameters available
+
+Response Structure
+------------------
+:dnssecEnabled: ``true`` if DNSSEC is enabled on this CDN, otherwise ``false``
+:domainName: Top Level Domain name within which this CDN operates
+:id: The integral, unique identifier for the CDN
+:lastUpdated: Date and time when the CDN was last modified in ISO format
+:name: The name of the CDN
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: z9P1NkxGebPncUhaChDHtYKYI+XVZfhE6Y84TuwoASZFIMfISELwADLpvpPTN+wwnzBfREksLYn+0313QoBWhA==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 20:46:57 GMT
+ Content-Length: 237
+
+ { "response": [
+ {
+ "dnssecEnabled": false,
+ "domainName": "-",
+ "id": 1,
+ "lastUpdated": "2018-11-14 18:21:06+00",
+ "name": "ALL"
+ },
+ {
+ "dnssecEnabled": false,
+ "domainName": "mycdn.ciab.test",
+ "id": 2,
+ "lastUpdated": "2018-11-14 18:21:14+00",
+ "name": "CDN-in-a-Box"
+ }
+ ]}
+
+
+``POST``
+========
+Allows user to create a CDN
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+:dnssecEnabled: If ``true``, this CDN will use DNSSEC, if ``false`` it will not
+:domainName: The top-level domain (TLD) belonging to the new CDN
+:name: Name of the new CDN
+
+.. code-block:: http
+ :caption: Request Structure
+
+ POST /api/1.4/cdns HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 63
+ Content-Type: application/json
+
+ {"name": "test", "domainName": "quest", "dnssecEnabled": false}
+
+Response Structure
+------------------
+:dnssecEnabled: ``true`` if the CDN uses DNSSEC, ``false`` otherwise
+:domainName: The top-level domain (TLD) assigned to the newly created CDN
+:id: An integral, unique identifier for the newly created CDN
+:name: The newly created CDN's name
+
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: 1rZRlOfQioGRrEb4nCfjGGx7y3Ub2h7BZ4z6NbhcY4acPslKSUNM8QLjWTVwLU4WpkfJNxcoyy8NlKULFrY9Bg==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 20:49:28 GMT
+ Content-Length: 174
+
+ { "alerts": [
+ {
+ "text": "cdn was created.",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "dnssecEnabled": false,
+ "domainName": "quest",
+ "id": 3,
+ "lastUpdated": "2018-11-14 20:49:28+00",
+ "name": "test"
+ }}
diff --git a/docs/source/api/cdns_capacity.rst b/docs/source/api/cdns_capacity.rst
new file mode 100644
index 0000000..953404e
--- /dev/null
+++ b/docs/source/api/cdns_capacity.rst
@@ -0,0 +1,51 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-capacity:
+
+*****************
+``cdns/capacity``
+*****************
+
+``GET``
+=======
+Retrieves the aggregate capacity percentages of all locations (cache groups) for a given CDN.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Object
+
+Request Structure
+-----------------
+No parameters available.
+
+Response Structure
+------------------
+:availablePercent: The percent of available (unused) bandwidth to 64 bits of precision\ [1]_
+:unavailablePercent: The percent of unavailable (used) bandwidth to 64 bits of precision\ [1]_
+:utilizedPercent: The percent of bandwidth currently in use to 64 bits of precision\ [1]_
+:maintenancePercent: The percent of bandwidth being used for administrative or analytical processes internal to the CDN to 64 bits of precision\ [1]_
+
+.. code-block:: json
+ :caption: Response Example
+
+ { "response": {
+ "availablePercent": 89.0939840205533,
+ "unavailablePercent": 0,
+ "utilizedPercent": 10.9060020300395,
+ "maintenancePercent": 0.0000139494071146245
+ }}
+
+.. [1] Following `IEEE 754 <https://ieeexplore.ieee.org/document/4610935>`_
diff --git a/docs/source/api/cdns_cdn_configfiles_ats_filename.rst b/docs/source/api/cdns_cdn_configfiles_ats_filename.rst
new file mode 100644
index 0000000..a8788dd
--- /dev/null
+++ b/docs/source/api/cdns_cdn_configfiles_ats_filename.rst
@@ -0,0 +1,54 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-cdn-configfiles-ats-filename:
+
+*********************************************
+``cdns/{{cdn}}/configfiles/ats/{{filename}}``
+*********************************************
+.. seealso:: The :ref:`to-api-servers-server-configfiles-ats` endpoint
+
+``GET``
+=======
+Gets the configuration file ``filename`` from the CDN ``cdn`` (by either name or ID).
+
+:Auth. Required: Yes
+:Roles Required: "operations"
+:Response Type: **NOT PRESENT** - endpoint returns custom text/plain response (represents the contents of the requested configuration file)
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +-----------+-------------------+----------+----------------------------------------------------------+
+ | Parameter | Type | Required | Description |
+ +===========+===================+==========+==========================================================+
+ | cdn | string or integer | yes | Either the name or integral, unique, identifier of a CDN |
+ +-----------+-------------------+----------+----------------------------------------------------------+
+ | filename | string | yes | The name of a configuration file used by ``cdn`` |
+ +-----------+-------------------+----------+----------------------------------------------------------+
+
+Response Structure
+------------------
+.. note:: If the file identified by ``filename`` does exist, but is not used by the entire CDN, a JSON response will be returned and the ``alerts`` array will contain a ``"level": "error"`` node which identifies the correct scope of the configuration file.
+
+.. code-block:: squid
+ :caption: Response Example
+
+ # DO NOT EDIT - Generated for CDN-in-a-Box by Traffic Ops (https://trafficops.infra.ciab.test:443/) on Thu Oct 25 13:26:31 UTC 2018
+ cond %{REMAP_PSEUDO_HOOK}
+ set-conn-dscp 8 [L]
+
+
diff --git a/docs/source/api/cdns_configs.rst b/docs/source/api/cdns_configs.rst
new file mode 100644
index 0000000..dfe0900
--- /dev/null
+++ b/docs/source/api/cdns_configs.rst
@@ -0,0 +1,44 @@
+..
+..
+.. 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.
+..
+.. _to-api-cdns-config:
+
+****************
+``cdns/configs``
+****************
+.. deprecated:: 1.0
+ Use one of :ref:`to-api-cdns-name-configs-monitoring`, :ref:`to-api-cdns-name-configs-routing`, or :ref:`to-api-servers-server-configfiles-ats` instead.
+
+.. caution:: This endpoint doesn't appear to work as of Traffic Control version 3.0.0 - it is strongly advised that its used be avoided.
+
+``GET``
+=======
+Retrieves CDN configuration information.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+No parameters available.
+
+Response Properties
+-------------------
+:config_file: Presumably the name of some configuration file\ [1]_
+:id: The integral, unique identifier for this CDN
+:name: The CDN's name
+:value: Presumably the content of some configuration file\ [1]_
+
+.. [1] These values are currently missing from this endpoint's output. **DO NOT count on this endpoint to provide this information**.
diff --git a/docs/source/api/cdns_dnsseckeys_refresh.rst b/docs/source/api/cdns_dnsseckeys_refresh.rst
new file mode 100644
index 0000000..63687d9
--- /dev/null
+++ b/docs/source/api/cdns_dnsseckeys_refresh.rst
@@ -0,0 +1,55 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-dnsseckeys-refresh:
+
+***************************
+``cdns/dnsseckeys/refresh``
+***************************
+
+``GET``
+=======
+Refresh the DNSSEC keys for all CDNs. This call initiates a background process to refresh outdated keys, and immediately returns a response that the process has started.
+
+:Auth. Required: Yes
+:Roles Required: "admin"
+:Response Type: Object (string)
+
+Request Structure
+-----------------
+No parameters available
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 21:37:30 GMT
+ X-Server-Name: traffic_ops_golang/
+ Set-Cookie: mojolicious=...; expires=Thu, 15 Nov 2018 01:37:30 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: Uwl+924m6Ye3NraFP+RBpldkhcNTTDyXHZbzRaYV95p9tP56Z61gckeKSr1oQIkNXjXcCsDN5Dmum7Zk1AR6Hw==
+ Content-Length: 69
+
+ {
+ "response": "Checking DNSSEC keys for refresh in the background"
+ }
diff --git a/docs/source/api/cdns_domains.rst b/docs/source/api/cdns_domains.rst
new file mode 100644
index 0000000..ec56610
--- /dev/null
+++ b/docs/source/api/cdns_domains.rst
@@ -0,0 +1,53 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-domains:
+
+****************
+``cdns/domains``
+****************
+
+``GET``
+=======
+Gets a list of domains and their related Traffic Router profiles for all CDNs.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+No parameters available.
+
+Response Structure
+------------------
+:domainName: The top-level domain (TLD) assigned to this CDN
+:parameterId: The integral, unique identifier for the parameter that sets this TLD on the Traffic Router
+:profileDescription: A short, human-readable description of the Traffic Router's profile
+:profileId: The integral, unique identifier for the profile assigned to the Traffic Router responsible for serving ``domainName``
+:profileName: The name of the profile assigned to the Traffic Router responsible for serving ``domainName``
+
+.. code-block:: json
+ :caption: Response Example
+
+ { "response": [
+ {
+ "profileId": 12,
+ "parameterId": -1,
+ "profileName": "CCR_CIAB",
+ "profileDescription": "Traffic Router for CDN-In-A-Box",
+ "domainName": "mycdn.ciab.test"
+ }
+ ]}
diff --git a/docs/source/api/cdns_health.rst b/docs/source/api/cdns_health.rst
new file mode 100644
index 0000000..fe14e9f
--- /dev/null
+++ b/docs/source/api/cdns_health.rst
@@ -0,0 +1,59 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-health:
+
+***************
+``cdns/health``
+***************
+Extract health information from all Cache Groups across all CDNs
+
+.. seealso:: :ref:`health-proto`
+
+``GET``
+=======
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Object
+
+Request Structure
+-----------------
+No parameters available
+
+Response Structure
+------------------
+:cachegroups: An array of objects describing the health of each Cache Group
+
+ :name: The name of the Cache Group
+ :offline: The number of OFFLINE caches in the Cache Group
+ :online: The number of ONLINE caches in the Cache Group
+
+:totalOffline: Total number of OFFLINE caches across all Cache Groups which are assigned to any CDN
+:totalOnline: Total number of ONLINE caches across all Cache Groups which are assigned to any CDN
+
+.. code-block:: json
+ :caption: Response Example
+
+ { "response": {
+ "totalOffline": 0,
+ "totalOnline": 1,
+ "cachegroups": [
+ {
+ "offline": 0,
+ "name": "CDN_in_a_Box_Edge",
+ "online": 1
+ }
+ ]
+ }}
diff --git a/docs/source/api/cdns_id.rst b/docs/source/api/cdns_id.rst
new file mode 100644
index 0000000..a3bed21
--- /dev/null
+++ b/docs/source/api/cdns_id.rst
@@ -0,0 +1,187 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-id:
+
+***************
+``cdns/{{ID}}``
+***************
+
+``GET``
+=======
+Extract information about a specific CDN.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+----------------------------------------------------+
+ | Name | Description |
+ +======+====================================================+
+ | ID | Integral, unique identifier for the CDN to inspect |
+ +------+----------------------------------------------------+
+
+Response Structure
+------------------
+:dnssecEnabled: ``true`` if DNSSEC is enabled on this CDN, otherwise ``false``
+:domainName: Top Level Domain name within which this CDN operates
+:id: The integral, unique identifier for the CDN
+:lastUpdated: Date and time when the CDN was last modified in ISO format
+:name: The name of the CDN
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: bTz86xdnGfbKhxnneb4geXohaw3lhG+h5wc21/ncHFATwp1h80h+txxySCIVfa0hgBrJHEdpGZQsH5w5IknsrQ==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 20:59:34 GMT
+ Content-Length: 137
+
+ { "response": [
+ {
+ "dnssecEnabled": false,
+ "domainName": "mycdn.ciab.test",
+ "id": 2,
+ "lastUpdated": "2018-11-14 18:21:14+00",
+ "name": "CDN-in-a-Box"
+ }
+ ]}
+
+
+``PUT``
+=======
+Allows a user to edit a specific CDN
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+---------------------------------------------------+
+ | Name | Description |
+ +======+===================================================+
+ | ID | Integral, unique identifier for the CDN to update |
+ +------+---------------------------------------------------+
+
+:dnssecEnabled: If ``true``, this CDN will use DNSSEC, if ``false`` it will not
+:domainName: The top-level domain (TLD) belonging to the CDN
+:name: Name of the new CDN
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/1.4/cdns/3 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 63
+ Content-Type: application/json
+
+ {"name": "quest", "domainName": "test", "dnssecEnabled": false}
+
+Response Structure
+------------------
+:dnssecEnabled: ``true`` if the CDN uses DNSSEC, ``false`` otherwise
+:domainName: The top-level domain (TLD) assigned to the newly created CDN
+:id: An integral, unique identifier for the newly created CDN
+:name: The newly created CDN's name
+
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: sI1hzBwG+/VAzoFY20kqGFA2RgrUOThtMeeJqk0ZxH3TRxTWuA8BetACct/XICC3n7hPDLlRVpwckEyBdyJkXg==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 20:54:33 GMT
+ Content-Length: 174
+
+ { "alerts": [
+ {
+ "text": "cdn was updated.",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "dnssecEnabled": false,
+ "domainName": "test",
+ "id": 4,
+ "lastUpdated": "2018-11-14 20:54:33+00",
+ "name": "quest"
+ }}
+
+``DELETE``
+==========
+Allows a user to delete a specific CDN
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: ``undefined``
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+------------------------------------------------------+
+ | Name | Description |
+ +======+======================================================+
+ | ID | The integral, unique identifier of the CDN to delete |
+ +------+------------------------------------------------------+
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: Zy4cJN6BEct4ltFLN4e296mM8XnzOs0EQ3/jp4TA3L+g8qtkI0WrL+ThcFq4xbJPU+KHVDSi+b0JBav3xsYPqQ==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 20:51:23 GMT
+ Content-Length: 58
+
+ { "alerts": [
+ {
+ "text": "cdn was deleted.",
+ "level": "success"
+ }
+ ]}
+
diff --git a/docs/source/api/cdns_id_queue_update.rst b/docs/source/api/cdns_id_queue_update.rst
new file mode 100644
index 0000000..ea1ff58
--- /dev/null
+++ b/docs/source/api/cdns_id_queue_update.rst
@@ -0,0 +1,78 @@
+..
+..
+.. 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.
+..
+
+.. _to-cdns-id-queue_update:
+
+****************************
+``cdns/{{ID}}/queue_update``
+****************************
+
+``POST``
+========
+Queue or dequeue updates for all servers assigned to a specific CDN.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+---------------------------------------------------------------------------+
+ | Name | Description |
+ +======+===========================================================================+
+ | ID | The integral, unique identifier for the CDN on which to (de)queue updates |
+ +------+---------------------------------------------------------------------------+
+
+:action: One of "queue" or "dequeue" as appropriate
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.4/cdns/2/queue_update HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 19
+ Content-Type: application/json
+
+ {"action": "queue"}
+
+Response Structure
+------------------
+:action: The action processed, either ``"queue"`` or ``"dequeue"``
+:cdnId: The integral, unique identifier for the CDN on which updates were (de)queued
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: rBpFfrrP+9IFkwsRloEM+v+I8MuBZDXqFu+WUTGtRGypnAn2gHooPoNQRyVvJGjyIQrLXLvqjEtve+lH2Tj4uw==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 21:02:07 GMT
+ Content-Length: 41
+
+ { "response": {
+ "action": "queue",
+ "cdnId": 2
+ }}
diff --git a/docs/source/api/cdns_id_snapshot.rst b/docs/source/api/cdns_id_snapshot.rst
new file mode 100644
index 0000000..fa140a9
--- /dev/null
+++ b/docs/source/api/cdns_id_snapshot.rst
@@ -0,0 +1,66 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-id-snapshot:
+
+************************
+``cdns/{{ID}}/snapshot``
+************************
+.. deprecated:: 1.1
+ Use :ref:`to-api-snapshot-name` instead.
+
+``PUT``
+=======
+Performs a CDN snapshot. Effectively, this propagates the new *configuration* of the CDN to its *operating state*, which replaces the output of the :ref:`to-api-cdns-name-snapshot` endpoint with the output of the :ref:`to-api-cdns-name-snapshot-new` endpoint.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: ``undefined``
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+--------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+================================================================================+
+ | ID | The integral, unique identifier of the CDN for which a snapshot shall be taken |
+ +------+--------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/1.4/cdns/2/snapshot HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: z4PhNX7vuL3xVChQ1m2AB9Yg5AULVxXcg/SpIdNs6c5H0NE8XYXysP+DGNKHfuwvY7kxvUdBeoGlODJ6+SfaPg==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 12 Dec 2018 22:04:46 GMT
+ Content-Length: 0
+ Content-Type: text/plain; charset=utf-8
diff --git a/docs/source/api/cdns_metric_types_metric_start_date_start_end_date_end.rst b/docs/source/api/cdns_metric_types_metric_start_date_start_end_date_end.rst
new file mode 100644
index 0000000..c616c9e
--- /dev/null
+++ b/docs/source/api/cdns_metric_types_metric_start_date_start_end_date_end.rst
@@ -0,0 +1,94 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-metric_types-metric-start_date-start-end_date-end:
+
+**********************************************************************
+``cdns/metric_types/{{metric}}/start_date/{{start}}/end_date/{{end}}``
+**********************************************************************
+
+.. caution:: This API endpoint *does* **not** *work*. It isn't implemented in Traffic Ops, and is not expected to be added at any point in the near future. See `GitHub issue #2309 <https://github.com/apache/trafficcontrol/issues/2309>`_ for more information.
+
+.. deprecated:: 1.2
+ Use Traffic Stats or :ref:`to-api-cache_stats` instead
+
+``GET``
+=======
+Retrieves edge metrics of one or all Cache Groups.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +-----------------+----------+---------------------------+
+ | Name | Required | Description |
+ +=================+==========+===========================+
+ | ``metric_type`` | yes | ooff, origin_tps |
+ +-----------------+----------+---------------------------+
+ | ``start`` | yes | UNIX time, yesterday, now |
+ +-----------------+----------+---------------------------+
+ | ``end`` | yes | UNIX time, yesterday, now |
+ +-----------------+----------+---------------------------+
+
+Response Structure
+------------------
+:stats: object
+
+ :count: string
+ :98thPercentile: string
+ :min: string
+ :max: string
+ :5thPercentile: string
+ :95thPercentile: string
+ :mean: string
+ :sum: string
+
+:data: array
+
+ :time: int
+ :value: number
+
+:label: string
+
+.. code-block:: json
+ :caption: Response Example
+
+ { "response": [ {
+ "stats": {
+ "count": 1,
+ "98thPercentile": 1668.03,
+ "min": 1668.03,
+ "max": 1668.03,
+ "5thPercentile": 1668.03,
+ "95thPercentile": 1668.03,
+ "mean": 1668.03,
+ "sum": 1668.03
+ },
+ "data": [
+ [
+ 1425135900000,
+ 1668.03
+ ],
+ [
+ 1425136200000,
+ null
+ ]
+ ],
+ "label": "Origin TPS"
+ }]}
diff --git a/docs/source/api/cdns_name_configs_monitoring.rst b/docs/source/api/cdns_name_configs_monitoring.rst
new file mode 100644
index 0000000..ff50cf6
--- /dev/null
+++ b/docs/source/api/cdns_name_configs_monitoring.rst
@@ -0,0 +1,228 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-name-configs-monitoring:
+
+************************************
+``cdns/{{name}}/configs/monitoring``
+************************************
+
+.. seealso:: :ref:`health-proto`
+
+``GET``
+=======
+Retrieves information concerning the monitoring configuration for a specific CDN.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+------------------------------------------------------------------------+
+ | Name | Description |
+ +======+========================================================================+
+ | name | The name of the CDN for which monitoring configuration will be fetched |
+ +------+------------------------------------------------------------------------+
+
+Response Structure
+------------------
+:cacheGroups: An array of objects representing each of the Cache Groups being monitored within this CDN
+
+ :coordinates: An object representing the physical location of this Cache Group
+
+ :latitude: The geographic latitude of this Cache Group
+ :longitude: The geographic longitude of this Cache Group
+
+ :name: The name of this Cache Group
+
+:config: A collection of parameters used to configure the monitoring behaviour of Traffic Monitor
+
+ :hack.ttl: Unknown
+ :health.event-count: The total number of health events to store
+ :health.polling.interval: An interval in milliseconds on which to poll for health statistics
+ :health.threadPool: The number of threads to be used for health polling
+ :health.timepad: A 'padding time' to add to requests to spread them out for Traffic Control systems that use a large number of Traffic Monitors
+ :tm.crConfig.polling.url: The URL from which a CRConfig can be obtained
+ :tm.dataServer.polling.url: The URL from which a list of data servers can be obtained
+ :tm.healthParams.polling.url: The URL from which a list of health-polling parameters can be obtained
+ :tm.polling.interval: The interval at which to poll for configuration updates
+
+:deliveryServices: An array of objects representing each Delivery Service provided by this CDN
+
+ :status: The Delivery Service's status
+ :totalKbpsThreshold: A threshold rate of data transfer this Delivery Service is configured to handle, in Kilobits per second
+ :totalTpsThreshold: A threshold amount of transactions per second that this Delivery Service is configured to handle
+ :xmlId: An integral, unique identifier for this Deliver Service (named "xmlId" for legacy reasons)
+
+:profiles: An array of the profiles in use by the cache servers and Delivery Services belonging to this CDN
+
+ :name: The profile's name
+ :parameters: An array of the parameters in this profile that relate to monitoring configuration. This can be ``null`` if the servers using this profile cannot be monitored (e.g. Traffic Routers)
+
+ :health.connection.timeout: A timeout value, in milliseconds, to wait before giving up on a health check request
+ :health.polling.url: A URL to request for polling health. Substitutions can be made in a shell-like syntax using the properties of an object from the ``"trafficServers"`` array
+ :health.threshold.availableBandwidthInKbps: The total amount of bandwidth that servers using this profile are allowed, in Kilobits per second. This is a string and using comparison operators to specify ranges, e.g. ">10" means "more than 10 kbps"
+ :health.threshold.loadavg: The UNIX loadavg at which the server should be marked "unhealthy" - see ``man uptime``
+ :health.threshold.queryTime: The highest allowed length of time for completing health queries (after connection has been established) in milliseconds
+ :history.count: The number of past events to store; once this number is reached, the oldest event will be forgotten before a new one can be added
+
+ :type: The type of the profile
+
+:trafficMonitors: An array of objects representing each Traffic Monitor that monitors this CDN (this is used by Traffic Monitor's "peer polling" function)
+
+ :fqdn: AN FQDN that resolves to the IP (and/or IPv6) address of the server running this Traffic Monitor instance
+ :hostname: The hostname of the server running this Traffic Monitor instance
+ :ip6: The IPv6 address of this Traffic Monitor - when applicable
+ :ip: The IP address of this Traffic Monitor
+ :port: The port on which this Traffic Monitor listens for incoming connections
+ :profile: The name of the profile assigned to this Traffic Monitor
+ :status: The status of the server running this Traffic Monitor instance
+
+:trafficServers: An array of objects that represent the caches being monitored within this CDN
+
+ :cacheGroup: The Cache Group to which this cache belongs
+ :fqdn: A Fully Qualified Domain Name (FQDN) that resolves to the cache server's IP (or IPv6) address
+ :hashId: The short name for the cache server - named "hashId" for legacy reasons
+ :hostName: The (short) hostname of the cache server
+ :interfacename: The name of the network interface device being used by the cache's HTTP proxy
+ :ip6: The cache's IPv6 address - when applicable
+ :ip: The cache's IP address
+ :port: The port on which the cache listens for incoming connections
+ :profile: The name of the profile assigned to this cache
+ :status: The status of the Cache
+ :type: The type of the cache - should be either ``EDGE`` or ``MID``
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: uLR+tRoqR8SYO38j3DV9wQ+IkJ7Kf+MCoFkcWZtsgbpLJ+0S6f+IiI8laNVeDgrM/P23MAQ6BSepm+EJRl1AXQ==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 21:09:31 GMT
+ Transfer-Encoding: chunked
+
+ { "response": {
+ "trafficServers": [
+ {
+ "profile": "ATS_EDGE_TIER_CACHE",
+ "status": "REPORTED",
+ "ip": "172.16.239.100",
+ "ip6": "fc01:9400:1000:8::100",
+ "port": 80,
+ "cachegroup": "CDN_in_a_Box_Edge",
+ "hostname": "edge",
+ "fqdn": "edge.infra.ciab.test",
+ "interfacename": "eth0",
+ "type": "EDGE",
+ "hashid": "edge"
+ },
+ {
+ "profile": "ATS_MID_TIER_CACHE",
+ "status": "REPORTED",
+ "ip": "172.16.239.120",
+ "ip6": "fc01:9400:1000:8::120",
+ "port": 80,
+ "cachegroup": "CDN_in_a_Box_Mid",
+ "hostname": "mid",
+ "fqdn": "mid.infra.ciab.test",
+ "interfacename": "eth0",
+ "type": "MID",
+ "hashid": "mid"
+ }
+ ],
+ "trafficMonitors": [
+ {
+ "profile": "RASCAL-Traffic_Monitor",
+ "status": "ONLINE",
+ "ip": "172.16.239.40",
+ "ip6": "fc01:9400:1000:8::40",
+ "port": 80,
+ "cachegroup": "CDN_in_a_Box_Edge",
+ "hostname": "trafficmonitor",
+ "fqdn": "trafficmonitor.infra.ciab.test"
+ }
+ ],
+ "cacheGroups": [
+ {
+ "name": "CDN_in_a_Box_Mid",
+ "coordinates": {
+ "latitude": 38.897663,
+ "longitude": -77.036574
+ }
+ },
+ {
+ "name": "CDN_in_a_Box_Edge",
+ "coordinates": {
+ "latitude": 38.897663,
+ "longitude": -77.036574
+ }
+ }
+ ],
+ "profiles": [
+ {
+ "name": "CCR_CIAB",
+ "type": "CCR",
+ "parameters": null
+ },
+ {
+ "name": "ATS_EDGE_TIER_CACHE",
+ "type": "EDGE",
+ "parameters": {
+ "health.connection.timeout": 2000,
+ "health.polling.url": "http://${hostname}/_astats?application=&inf.name=${interface_name}",
+ "health.threshold.availableBandwidthInKbps": ">1750000",
+ "health.threshold.loadavg": "25.0",
+ "health.threshold.queryTime": 1000,
+ "history.count": 30
+ }
+ },
+ {
+ "name": "ATS_MID_TIER_CACHE",
+ "type": "MID",
+ "parameters": {
+ "health.connection.timeout": 2000,
+ "health.polling.url": "http://${hostname}/_astats?application=&inf.name=${interface_name}",
+ "health.threshold.availableBandwidthInKbps": ">1750000",
+ "health.threshold.loadavg": "25.0",
+ "health.threshold.queryTime": 1000,
+ "history.count": 30
+ }
+ }
+ ],
+ "deliveryServices": [],
+ "config": {
+ "hack.ttl": 30,
+ "health.event-count": 200,
+ "health.polling.interval": 6000,
+ "health.threadPool": 4,
+ "health.timepad": 0,
+ "heartbeat.polling.interval": 3000,
+ "location": "/opt/traffic_monitor/conf",
+ "peers.polling.interval": 3000,
+ "tm.crConfig.polling.url": "https://${tmHostname}/CRConfig-Snapshots/${cdnName}/CRConfig.xml",
+ "tm.dataServer.polling.url": "https://${tmHostname}/dataserver/orderby/id",
+ "tm.healthParams.polling.url": "https://${tmHostname}/health/${cdnName}",
+ "tm.polling.interval": 2000
+ }
+ }}
diff --git a/docs/source/api/cdns_name_configs_routing.rst b/docs/source/api/cdns_name_configs_routing.rst
new file mode 100644
index 0000000..d1bca9b
--- /dev/null
+++ b/docs/source/api/cdns_name_configs_routing.rst
@@ -0,0 +1,161 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-name-configs-routing:
+
+*********************************
+``cdns/{{name}}/configs/routing``
+*********************************
+.. caution:: This API route is currently broken, see `GitHub issue #2941 <https://github.com/apache/trafficcontrol/issues/2941>`_ for more information.
+
+``GET``
+=======
+Retrieves CDN routing information.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type:
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +----------+----------+-------------------------------------+
+ | Name | Required | Description |
+ +==========+==========+=====================================+
+ | ``name`` | yes | The name of the CDN to be inspected |
+ +----------+----------+-------------------------------------+
+
+Response Structure
+------------------
+:cacheGroups: A collection of cache groups.
+
+ :coordinates: object
+
+ :latitude: number
+ :longitude: number
+
+ :name: string
+
+:config: object
+
+ :coveragezone.polling.url: string
+ :domain_name: string
+ :geolocation.polling.interval: integer
+ :geolocation.polling.url: string
+ :geolocation6.polling.interval: integer
+ :geolocation6.polling.url: string
+ :tcoveragezone.polling.interval: integer
+ :tld.soa.admin: string
+ :tld.soa.expire: integer
+ :tld.soa.minimum: integer
+ :tld.soa.refresh: integer
+ :tld.soa.retry: integer
+ :tld.ttls.A: integer
+ :tld.ttls.AAAA: integer
+ :tld.ttls.NS: integer
+ :tld.ttls.SOA: integer
+
+:deliveryServices: An array of delivery services.
+
+ :coverageZoneOnly: boolean
+ :bypassDestination: object
+
+ :maxDnsIpsForLocation: integer
+ :ttl: integer
+ :type: string
+
+ :geoEnabled: string
+ :matchSets: array
+
+ :protocol: string
+ :matchList: array
+
+ :matchType: string
+ :regex: string
+
+ :missCoordinates: object
+
+ :latitude: number
+ :longitude: number
+
+ :soa: object
+
+ :admin: string
+ :expire: integer
+ :minimum: integer
+ :refresh: integer
+ :retry: integer
+
+ :ttl: integer
+ :ttls: object
+
+ :A: integer
+ :AAAA: integer
+ :NS: integer
+ :SOA: integer
+
+ :xmlId: string
+
+:stats: object
+
+ :cdnName: string
+ :date: integer
+ :trafficOpsHost: string
+ :trafficOpsPath: string
+ :trafficOpsUser: string
+ :trafficOpsVersion: string
+
+:trafficMonitors: An array of Traffic Monitors
+
+ :fqdn: string
+ :hostName: string
+ :ip6: string
+ :ip: string
+ :location: string
+ :port: integer
+ :profile: string
+ :status: string
+
+:trafficRouters: object
+
+ :apiPort: integer
+ :fqdn: string
+ :hostName: string
+ :ip6: string
+ :ip: string
+ :location: string
+ :port: integer
+ :profile: integer
+ :status: string
+
+:trafficServers: An array of Traffic Servers.
+
+ :cacheGroup: string
+ :deliveryServices: array
+
+ :xmlId: string
+ :remaps: array
+ :hostName: string
+
+ :fqdn: string
+ :hashId: string
+ :interfaceName: string
+ :ip: string
+ :ip6: string
+ :port: integer
+ :profile: string
+ :status: string
+ :type: string
diff --git a/docs/source/api/cdns_name_dnsseckeys_ksk_generate.rst b/docs/source/api/cdns_name_dnsseckeys_ksk_generate.rst
new file mode 100644
index 0000000..62eaf9e
--- /dev/null
+++ b/docs/source/api/cdns_name_dnsseckeys_ksk_generate.rst
@@ -0,0 +1,57 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-name-dnsseckeys-ksk-generate:
+
+*****************************************
+``cdns/{{name}}/dnsseckeys/ksk/generate``
+*****************************************
+
+.. versionadded:: 1.4
+
+``POST``
+========
+Generates a new Key-Signing Key (KSK) for a specific CDN.
+
+:Auth. Required: Yes
+:Roles Required: "admin"
+:Response Type: Object (string)
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+----------+---------------------------------------------------------+
+ | Name | Required | Description |
+ +======+==========+=========================================================+
+ | name | yes | The name of the CDN for which the KSK will be generated |
+ +------+----------+---------------------------------------------------------+
+
+.. table:: Request Data Parameters
+
+ +--------------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Type | Description |
+ +====================+==========+=========+========================================================================================================================================================+
+ | ``expirationDays`` | yes | integer | The number of days until the newly generated KSK expires |
+ +--------------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | ``effectiveDate`` | no | string | The time at which the newly generated KSK becomes effective, in `RFC3339 <https://tools.ietf.org/html/rfc3339>`_ format - defaults to the current time |
+ +--------------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+Response Structure
+------------------
+.. code-block:: json
+ :caption: Response Example
+
+ { "response": "Successfully generated ksk dnssec keys for my-cdn-name" }
diff --git a/docs/source/api/cdns_name_federations.rst b/docs/source/api/cdns_name_federations.rst
new file mode 100644
index 0000000..beb63fa
--- /dev/null
+++ b/docs/source/api/cdns_name_federations.rst
@@ -0,0 +1,174 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-name-federations:
+
+*****************************
+``cdns/{{name}}/federations``
+*****************************
+
+``GET``
+=======
+Retrieves a list of federations in use by a specific CDN.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+----------------------------------------------------------+
+ | Name | Description |
+ +======+==========================================================+
+ | name | The name of the CDN for which federations will be listed |
+ +------+----------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.4/cdns/CDN-in-a-Box/federations HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.62.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:cname: The Canonical Name (CNAME) used by the federation
+:deliveryService: An object with keys that provide identifying information for the Delivery Service using this federation
+
+ :id: The integral, unique identifier for the Delivery Service
+ :xmlId: The Delivery Service's uniquely identifying 'xml_id'
+
+:description: An optionally-present field containing a description of the field
+
+ .. note:: This key will only be present if the description was provided when the federation was created. Refer to the ``POST`` method of this endpoint to see how federations can be created.
+
+:lastUpdated: The date and time at which this federation was last modified, in ISO format
+:ttl: Time to Live (TTL) for the ``cname``, in hours
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ content-type: application/json
+ set-cookie: mojolicious=...; Path=/; HttpOnly
+ whole-content-sha512: SJA7G+7G5KcOfCtnE3Dq5DCobWtGRUKSppiDkfLZoG5+paq4E1aZGqUb6vGVsd+TpPg75MLlhyqfdfCHnhLX/g==
+ x-server-name: traffic_ops_golang/
+ content-length: 170
+ date: Wed, 05 Dec 2018 00:35:40 GMT
+
+ { "response": [
+ {
+ "id": 1,
+ "cname": "test.quest.",
+ "ttl": 48,
+ "description": "A test federation",
+ "lastUpdated": "2018-12-05 00:05:16+00",
+ "deliveryService": {
+ "id": 1,
+ "xmlId": "demo1"
+ }
+ }
+ ]}
+
+``POST``
+========
+Creates a new federation.
+
+:Auth. Required: Yes
+:Roles Required: "admin"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+----------------------------------------------------------------+
+ | Name | Description |
+ +======+================================================================+
+ | name | The name of the CDN for which a new federation will be created |
+ +------+----------------------------------------------------------------+
+
+:cname: The Canonical Name (CNAME) used by the federation
+
+ .. note:: The CNAME must end with a "``.``"
+
+:description: An optional description of the federation
+:ttl: Time to Live (TTL) for the name record used for ``cname``
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.4/cdns/CDN-in-a-Box/federations HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.62.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 72
+ Content-Type: application/json
+
+ {
+ "cname": "test.quest.",
+ "ttl": 48,
+ "description": "A test federation"
+ }
+
+
+Response Structure
+------------------
+:cname: The Canonical Name (CNAME) used by the federation
+:description: An optionally-present field containing a description of the field
+
+ .. note:: This key will only be present if the description was provided when the federation was created
+
+:lastUpdated: The date and time at which this federation was last modified, in ISO format
+:ttl: Time to Live (TTL) for the ``cname``, in hours
+
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ content-type: application/json
+ set-cookie: mojolicious=...; Path=/; HttpOnly
+ whole-content-sha512: rRsWAIhXzVlj8Hy+8aFjp4Jo1QGTK49m0N1AP5QDyyAZ1TfNIdgtcgiuehu7FiN1IPWRFiv6D9CygFYKGcVDOw==
+ x-server-name: traffic_ops_golang/
+ content-length: 192
+ date: Wed, 05 Dec 2018 00:05:16 GMT
+
+ { "alerts": [
+ {
+ "text": "cdnfederation was created.",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "id": 1,
+ "cname": "test.quest.",
+ "ttl": 48,
+ "description": "A test federation",
+ "lastUpdated": "2018-12-05 00:05:16+00"
+ }}
diff --git a/docs/source/api/cdns_name_federations_id.rst b/docs/source/api/cdns_name_federations_id.rst
new file mode 100644
index 0000000..fa4f183
--- /dev/null
+++ b/docs/source/api/cdns_name_federations_id.rst
@@ -0,0 +1,232 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-name-federations-id:
+
+************************************
+``cdns/{{name}}/federations/{{ID}}``
+************************************
+
+``GET``
+=======
+Retrieves a specific federation used within a specific CDN.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+-------------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+=====================================================================================+
+ | name | The name of the CDN for which the federation identified by ``ID`` will be inspected |
+ +------+-------------------------------------------------------------------------------------+
+ | ID | An integral, unique identifier for the federation to be inspected |
+ +------+-------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.4/cdns/CDN-in-a-Box/federations/1 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.62.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:cname: The Canonical Name (CNAME) used by the federation
+:deliveryService: An object with keys that provide identifying information for the Delivery Service using this federation
+
+ :id: The integral, unique identifer for the Delivery Service
+ :xmlId: The Delivery Service's uniquely identifying 'xml_id'
+
+:description: An optionally-present field containing a description of the field
+
+ .. note:: This key will only be present if the description was provided when the federation was created. Refer to the ``POST`` method of the :ref:`to-api-cdns-name-federations` endpoint to see how federations can be created.
+
+:lastUpdated: The date and time at which this federation was last modified, in ISO format
+:ttl: Time to Live (TTL) for the ``cname``, in hours
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ content-type: application/json
+ set-cookie: mojolicious=...; Path=/; HttpOnly
+ whole-content-sha512: SJA7G+7G5KcOfCtnE3Dq5DCobWtGRUKSppiDkfLZoG5+paq4E1aZGqUb6vGVsd+TpPg75MLlhyqfdfCHnhLX/g==
+ x-server-name: traffic_ops_golang/
+ content-length: 170
+ date: Wed, 05 Dec 2018 00:36:57 GMT
+
+ { "response": [
+ {
+ "id": 1,
+ "cname": "test.quest.",
+ "ttl": 48,
+ "description": "A test federation",
+ "lastUpdated": "2018-12-05 00:05:16+00",
+ "deliveryService": {
+ "id": 1,
+ "xmlId": "demo1"
+ }
+ }
+ ]}
+
+
+``PUT``
+=======
+Updates a federation.
+
+:Auth. Required: Yes
+:Roles Required: "admin"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+-------------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+=====================================================================================+
+ | name | The name of the CDN for which the federation identified by ``ID`` will be inspected |
+ +------+-------------------------------------------------------------------------------------+
+ | ID | An integral, unique identifier for the federation to be inspected |
+ +------+-------------------------------------------------------------------------------------+
+
+:cname: The Canonical Name (CNAME) used by the federation
+
+ .. note:: The CNAME must end with a "``.``"
+
+:description: An optional description of the federation
+:ttl: Time to Live (TTL) for the name record used for ``cname``
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/1.4/cdns/CDN-in-a-Box/federations/1 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.62.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 33
+ Content-Type: application/json
+
+ {
+ "cname": "foo.bar.",
+ "ttl": 48
+ }
+
+
+Response Structure
+------------------
+:cname: The Canonical Name (CNAME) used by the federation
+:description: An optionally-present field containing a description of the field
+
+ .. note:: This key will only be present if the description was provided when the federation was created
+
+:lastUpdated: The date and time at which this federation was last modified, in ISO format
+:ttl: Time to Live (TTL) for the ``cname``, in hours
+
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ content-type: application/json
+ set-cookie: mojolicious=...; Path=/; HttpOnly
+ whole-content-sha512: qcjfQ+gDjNxYQ1aq+dlddgrkFWnkFYxsFF+SHDqqH0uVHBVksmU0aTFgltozek/u6wbrGoR1LFf9Fr1C1SbigA==
+ x-server-name: traffic_ops_golang/
+ content-length: 174
+ date: Wed, 05 Dec 2018 01:03:40 GMT
+
+ { "alerts": [
+ {
+ "text": "cdnfederation was updated.",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "id": 1,
+ "cname": "foo.bar.",
+ "ttl": 48,
+ "description": null,
+ "lastUpdated": "2018-12-05 01:03:40+00"
+ }}
+
+
+``DELETE``
+==========
+Deletes a specific federation.
+
+:Auth. Required: Yes
+:Roles Required: "admin"
+:Response Type: ``undefined``
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+-------------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+=====================================================================================+
+ | name | The name of the CDN for which the federation identified by ``ID`` will be inspected |
+ +------+-------------------------------------------------------------------------------------+
+ | ID | An integral, unique identifier for the federation to be inspected |
+ +------+-------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ DELETE /api/1.4/cdns/CDN-in-a-Box/federations/1 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.62.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ content-type: application/json
+ set-cookie: mojolicious=...; Path=/; HttpOnly
+ whole-content-sha512: Cnkfj6dmzTD3if9oiDq33tqf7CnAflKK/SPgqJyfu6HUfOjLJOgKIZvkcs2wWY6EjLVdw5qsatsd4FPoCyjvcw==
+ x-server-name: traffic_ops_golang/
+ content-length: 68
+ date: Wed, 05 Dec 2018 01:17:24 GMT
+
+ { "alerts": [
+ {
+ "text": "cdnfederation was deleted.",
+ "level": "success"
+ }
+ ]}
diff --git a/docs/source/api/cdns_name_health.rst b/docs/source/api/cdns_name_health.rst
new file mode 100644
index 0000000..7f2da1e
--- /dev/null
+++ b/docs/source/api/cdns_name_health.rst
@@ -0,0 +1,78 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-name-health:
+
+************************
+``cdns/{{name}}/health``
+************************
+
+``GET``
+=======
+Retrieves the health of all Cache Groups for a given CDN.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+-------------------------------------------------------+
+ | Name | Description |
+ +======+=======================================================+
+ | name | The name of the CDN for which health will be reported |
+ +------+-------------------------------------------------------+
+
+Response Structure
+------------------
+:cachegroups: An array of objects describing the health of each Cache Group
+
+ :name: The name of the Cache Group
+ :offline: The number of OFFLINE caches in the Cache Group
+ :online: The number of ONLINE caches in the Cache Group
+
+:totalOffline: Total number of OFFLINE caches across all Cache Groups which are assigned to the CDN defined by the ``name`` request path parameter
+:totalOnline: Total number of ONLINE caches across all Cache Groups which are assigned to the CDN defined by the ``name`` request path parameter
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 21:14:05 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 15 Nov 2018 01:14:05 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: KpXViXeAgch58ueQqdyU8NuINBw1EUedE6Rv2ewcLUajJp6kowdbVynpwW7XiSvAyHdtClIOuT3OkhIimghzSA==
+ Content-Length: 115
+
+ { "response": {
+ "totalOffline": 0,
+ "totalOnline": 1,
+ "cachegroups": [
+ {
+ "offline": 0,
+ "name": "CDN_in_a_Box_Edge",
+ "online": 1
+ }
+ ]
+ }}
diff --git a/docs/source/api/cdns_name_name.rst b/docs/source/api/cdns_name_name.rst
new file mode 100644
index 0000000..cde7b61
--- /dev/null
+++ b/docs/source/api/cdns_name_name.rst
@@ -0,0 +1,114 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-name-name:
+
+**********************
+``cdns/name/{{name}}``
+**********************
+
+``GET``
+=======
+Extract information about a CDN, identified by name.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+---------------------------------------------+
+ | Name | Description |
+ +======+=============================================+
+ | name | The name of the CDN to be inspected |
+ +------+---------------------------------------------+
+
+Response Structure
+------------------
+:dnssecEnabled: ``true`` if DNSSEC is enabled on this CDN, otherwise ``false``
+:domainName: Top Level Domain name within which this CDN operates
+:id: The integral, unique identifier for the CDN
+:lastUpdated: Date and time when the CDN was last modified in ISO format
+:name: The name of the CDN
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: bTz86xdnGfbKhxnneb4geXohaw3lhG+h5wc21/ncHFATwp1h80h+txxySCIVfa0hgBrJHEdpGZQsH5w5IknsrQ==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 21:22:16 GMT
+ Content-Length: 137
+
+ { "response": [
+ {
+ "dnssecEnabled": false,
+ "domainName": "mycdn.ciab.test",
+ "id": 2,
+ "lastUpdated": "2018-11-14 18:21:14+00",
+ "name": "CDN-in-a-Box"
+ }
+ ]}
+
+``DELETE``
+==========
+Allows a user to delete a CDN by name
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: ``undefined``
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+---------------------------------------------+
+ | Name | Description |
+ +======+=============================================+
+ | name | The name of the CDN to be deleted |
+ +------+---------------------------------------------+
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: Zy4cJN6BEct4ltFLN4e296mM8XnzOs0EQ3/jp4TA3L+g8qtkI0WrL+ThcFq4xbJPU+KHVDSi+b0JBav3xsYPqQ==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 20:59:22 GMT
+ Content-Length: 58
+
+ { "alerts": [
+ {
+ "text": "cdn was deleted.",
+ "level": "success"
+ }
+ ]}
+
diff --git a/docs/source/api/cdns_name_name_dnsseckeys.rst b/docs/source/api/cdns_name_name_dnsseckeys.rst
new file mode 100644
index 0000000..2f050fe
--- /dev/null
+++ b/docs/source/api/cdns_name_name_dnsseckeys.rst
@@ -0,0 +1,116 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-name-name-dnsseckeys:
+
+*********************************
+``cdns/name/{{name}}/dnsseckeys``
+*********************************
+
+``GET``
+=======
+Gets a list of DNSSEC keys for CDN and all associated Delivery Services. Before returning response to user, this will make sure DNSSEC keys for all delivery services exist and are not expired. If they don't exist or are expired, they will be (re-)generated.
+
+:Auth. Required: Yes
+:Roles Required: "admin"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+----------------------------------------------------+
+ | Name | Description |
+ +======+====================================================+
+ | name | The name of the CDN for which keys will be fetched |
+ +------+----------------------------------------------------+
+
+Response Structure
+------------------
+:name: The name of the CDN or Delivery Service to which the enclosed keys belong
+
+ :zsk: The short-term Zone-Signing Key (ZSK)
+
+ :expirationDate: A Unix epoch timestamp (in seconds) representing the date and time whereupon the key will expire
+ :inceptionDate: A Unix epoch timestamp (in seconds) representing the date and time when the key was created
+ :name: The name of the domain for which this key will be used
+ :private: Encoded private key
+ :public: Encoded public key
+ :ttl: The time for which the key should be trusted by the client
+
+ :ksk: The long-term Key-Signing Key (KSK)
+
+ :dsRecord: An optionally present object containing information about the algorithm used to generate the key
+
+ :algorithm: The name of the algorithm used to generate the key
+ :digest: A hash of the DNSKEY record
+ :digestType: The type of hash algorithm used to create the value of ``digest``
+
+ :expirationDate: A Unix epoch timestamp (in seconds) representing the date and time whereupon the key will expire
+ :inceptionDate: A Unix epoch timestamp (in seconds) representing the date and time when the key was created
+ :name: The name of the domain for which this key will be used
+ :private: Encoded private key
+ :public: Encoded public key
+ :ttl: The time for which the key should be trusted by the client
+
+.. versionchanged:: 1.2
+ Added the ``dsRecord`` field to KSK entries
+
+.. code-block:: json
+ :caption: Response Example
+
+ { "response": {
+ "cdn1": {
+ "zsk": {
+ "ttl": "60",
+ "inceptionDate": "1426196750",
+ "private": "zsk private key",
+ "public": "zsk public key",
+ "expirationDate": "1428788750",
+ "name": "foo.kabletown.com."
+ },
+ "ksk": {
+ "name": "foo.kabletown.com.",
+ "expirationDate": "1457732750",
+ "public": "ksk public key",
+ "private": "ksk private key",
+ "inceptionDate": "1426196750",
+ "ttl": "60",
+ "dsRecord": {
+ "algorithm": "5",
+ "digestType": "2",
+ "digest": "abc123def456"
+ }
+ }
+ },
+ "ds-01": {
+ "zsk": {
+ "ttl": "60",
+ "inceptionDate": "1426196750",
+ "private": "zsk private key",
+ "public": "zsk public key",
+ "expirationDate": "1428788750",
+ "name": "ds-01.foo.kabletown.com."
+ },
+ "ksk": {
+ "name": "ds-01.foo.kabletown.com.",
+ "expirationDate": "1457732750",
+ "public": "ksk public key",
+ "private": "ksk private key",
+ "inceptionDate": "1426196750"
+ }
+ }
+ }}
+
diff --git a/docs/source/api/cdns_name_name_dnsseckeys_delete.rst b/docs/source/api/cdns_name_name_dnsseckeys_delete.rst
new file mode 100644
index 0000000..5693839
--- /dev/null
+++ b/docs/source/api/cdns_name_name_dnsseckeys_delete.rst
@@ -0,0 +1,48 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-name-name-dnsseckeys-delete:
+
+****************************************
+``cdns/name/{{name}}/dnsseckeys/delete``
+****************************************
+
+``GET``
+=======
+Delete DNSSEC keys for a CDN and all associated Delivery Services.
+
+:Auth. Required: Yes
+:Roles Required: "admin"
+:Response Type: Object (string)
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+-----------------------------------------------------------+
+ | Name | Description |
+ +======+===========================================================+
+ | name | The name of the CDN for which DNSSEC keys will be deleted |
+ +------+-----------------------------------------------------------+
+
+Response Structure
+------------------
+.. code-block:: json
+ :caption: Response Example
+
+ {
+ "response": "Successfully deleted dnssec keys for test"
+ }
+
diff --git a/docs/source/api/cdns_name_name_sslkeys.rst b/docs/source/api/cdns_name_name_sslkeys.rst
new file mode 100644
index 0000000..7ffaf56
--- /dev/null
+++ b/docs/source/api/cdns_name_name_sslkeys.rst
@@ -0,0 +1,67 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-name-name-sslkeys:
+
+******************************
+``cdns/name/{{name}}/sslkeys``
+******************************
+
+``GET``
+=======
+Returns SSL certificates for all Delivery Services that are a part of the CDN.
+
+:Auth. Required: Yes
+:Roles Required: "admin"
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+----------------------------------------------------+
+ | Name | Description |
+ +======+====================================================+
+ | name | The name of the CDN for which keys will be fetched |
+ +------+----------------------------------------------------+
+
+Response Structure
+------------------
+:certificate: An object representing The SSL keys used for the Delivery Service identified by ``deliveryservice``
+
+ :key: Base 64-encoded private key for SSL certificate
+ :crt: Base 64-encoded SSL certificate
+
+:deliveryservice: The ``xml_id`` of the Delivery Service using the SSL key within ``certificate``
+
+.. code-block:: json
+ :caption: Response Example
+
+ { "response": [
+ {
+ "deliveryservice": "ds1",
+ "certificate": {
+ "crt": "base64encodedcrt1",
+ "key": "base64encodedkey1"
+ }
+ },
+ {
+ "deliveryservice": "ds2",
+ "certificate": {
+ "crt": "base64encodedcrt2",
+ "key": "base64encodedkey2"
+ }
+ }
+ ]}
diff --git a/docs/source/api/cdns_name_snapshot.rst b/docs/source/api/cdns_name_snapshot.rst
new file mode 100644
index 0000000..91d976c
--- /dev/null
+++ b/docs/source/api/cdns_name_snapshot.rst
@@ -0,0 +1,540 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-snapshot-name:
+
+**************************
+``cdns/{{name}}/snapshot``
+**************************
+.. caution:: This page is a stub! Much of it may be missing or just downright wrong - it needs a lot of love from people with the domain knowledge required to update it.
+
+``GET``
+=======
+Retrieves the *current* snapshot for a CDN, which represents the current *operating state* of the CDN, **not** the current *configuration* of the CDN. The contents of this snapshot are currently used by Traffic Monitor and Traffic Router.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+------------------------------------------------------------+
+ | Name | Description |
+ +======+============================================================+
+ | name | The name of the CDN for which a snapshot shall be returned |
+ +------+------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.4/cdns/CDN-in-a-Box/snapshot HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:config: An object containing basic configurations on the actual CDN object
+
+ :api.cache-control.max-age: A string containing an integer which specifies the value of ``max-age`` in the ``Cache-Control`` header of some HTTP responses, likely the Traffic Router API responses
+
+ .. deprecated:: 1.1
+ This field still exists for legacy compatibility reasons, but has no known use at the time of this writing
+
+ :certificates.polling.interval: A string containing an integer which specifies the interval, in seconds, on which other Traffic Control components should check for updated SSL certificates
+ :consistent.dns.routing: A string containing a boolean which indicates whether DNS routing will use a consistent hashing method or "round-robin"
+
+ "false"
+ The "round-robin" method will be used to define DNS routing
+ "true"
+ A consistent hashing method will be used to define DNS routing
+
+ :coveragezone.polling.interval: A string containing an integer which specifies the interval, in seconds, on which Traffic Routers should check for a new Coverage Zone file
+ :coveragezone.polling.url: The URL where a Coverage Zone file may be requested by Traffic Routers
+ :dnssec.dynamic.response.expiration: A string containing a number and unit suffix that specifies the length of time for which dynamic responses to DNSSEC lookup queries should remain valid
+ :dnssec.enabled: A string that tells whether or not the CDN uses DNSSEC; one of:
+
+ "false"
+ DNSSEC is not used within this CDN
+ "true"
+ DNSSEC is used within this CDN
+
+ :domain_name: The Top-Level Domain Name (TLD) served by the CDN
+ :edge.dns.limit: This field is of unknown use, and may be remnants of a legacy system
+ :edge.dns.routing: This field is of unknown use, and may be remnants of a legacy system
+ :edge.http.limit: This field is of unknown use, and may be remnants of a legacy system
+ :edge.http.routing: This field is of unknown use, and may be remnants of a legacy system
+ :federationmapping.polling.interval: A string containing an integer which specifies the interval, in seconds, on which other Traffic Control components should check for new federation mappings
+ :federationmapping.polling.url: The URL where Traffic Control components can request federation mappings
+ :geolocation.polling.interval: A string containing an integer which specifies the interval, in seconds, on which other Traffic Control components should check for new IP-to-geographic-location mapping databases
+ :geolocation.polling.url: The URL where Traffic Control components can request IP-to-geographic-location mapping database files
+ :keystore.maintenance.interval: A string containing an integer which specifies the interval, in seconds, on which Traffic Routers should refresh their zone caches
+ :neustar.polling.interval: A string containing an integer which specifies the interval, in seconds, on which other Traffic Control components should check for new "Neustar" databases
+ :neustar.polling.url: The URL where Traffic Control components can request "Neustar" databases
+ :soa: An object defining the Start of Authority (SOA) for the CDN's TLD (defined in ``domain_name``)
+
+ :admin: The name of the administrator for this zone - i.e. the RNAME
+
+ .. note:: This rarely represents a proper email address, unfortunately.
+
+ :expire: A string containing an integer that sets the number of seconds after which secondary name servers should stop answering requests for this zone if the master does not respond
+ :minimum: A string containing an integer that sets the Time To Live (TTL) - in seconds - of the record for the purpose of negative caching
+ :refresh: A string containing an integer that sets the number of seconds after which secondary name servers should query the master for the SOA record, to detect zone changes
+ :retry: A string containing an integer that sets the number of seconds after which secondary name servers should retry to request the serial number from the master if the master does not respond
+
+ .. note:: `RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ dictates that this should always be less than ``refresh``.
+
+ .. seealso:: `The Wikipedia page on Start of Authority records <https://en.wikipedia.org/wiki/SOA_record>`_.
+
+ :steeringmapping.polling.interval: A string containing an integer which specifies the interval, in seconds, on which Traffic Control components should check for new steering mappings
+ :ttls: An object that contains keys which are types of DNS records that have values which are strings containing integers that specify the time for which a response to the specific type of record request should remain valid
+ :zonemanager.cache.maintenance.interval: A configuration option for the ZoneManager Java class of Traffic Router
+ :zonemanager.threadpool.scale: A configuration option for the ZoneManager Java class of Traffic Router
+
+:contentRouters: An object containing keys which are the (short) hostnames of the Traffic Routers that serve requests for Delivery Services in this CDN
+
+ :api.port: A string containing the port number on which the :ref:`tr-api` is served by this Traffic Router
+ :fqdn: This Traffic Router's Fully Qualified Domain Name (FQDN)
+ :httpsPort: The port number on which this Traffic Router listens for incoming HTTPS requests
+ :ip: This Traffic Router's IPv4 address
+ :ip6: This Traffic Router's IPv6 address
+ :location: The name of the Cache Group to which this Traffic Router belongs
+ :port: The port number on which this Traffic Router listens for incoming HTTP requests
+ :profile: The name of the profile used by this Traffic Router
+ :status: The health status of this Traffic Router
+
+ .. seealso:: :ref:`health-proto`
+
+:contentServers: An object containing keys which are the (short) hostnames of the Edge-Tier cache servers in the CDN; the values corresponding to those keys are routing information for said servers
+
+ :cacheGroup: The name of the Cache Group to which the server belongs
+ :deliveryServices: An object containing keys which are the names of Delivery Services to which this cache server is assigned; the values corresponding to those keys are arrays of FQDNs that resolve to this cache server
+
+ .. note:: Only Edge-tier cache servers can be assigned to a Delivery SErvice, and therefore this field will only be present when ``type`` is ``"EDGE"``.
+
+ :fqdn: The server's Fully Qualified Domain Name (FQDN)
+ :hashCount: The number of servers to be placed into a single "hash ring" in Traffic Router
+ :hashId: A unique string to be used as the key for hashing servers - as of version 3.0.0 of Traffic Control, this is always the same as the server's (short) hostname and only still exists for legacy compatibility reasons
+ :httpsPort: The port on which the cache server listens for incoming HTTPS requests
+ :interfaceName: The name of the main network interface device used by this cache server
+ :ip6: The server's IPv6 address
+ :ip: The server's IPv4 address
+ :locationId: This field is exactly the same as ``cacheGroup`` and only exists for legacy compatibility reasons
+ :port: The port on which this cache server listens for incoming HTTP requests
+ :profile: The name of the profile used by the cache server
+ :routingDisabled: An integer representing the boolean concept of whether or not Traffic Routers should route client traffic this cache server; one of:
+
+ 0
+ Do not route traffic to this server
+ 1
+ Route traffic to this server normally
+
+ :status: This cache server's status
+
+ .. seealso:: :ref:`health-proto`
+
+ :type: The type of this cache server; one of:
+
+ EDGE
+ This is an Edge-tier cache server
+ MID
+ This is a Mid-tier cache server
+
+:deliveryServices: An object containing keys which are the 'xml_id's of all of the Delivery Services within the CDN
+
+ :anonymousBlockingEnabled: A string containing a boolean that tells whether or not Anonymized IP Addresses are blocked by this Delivery Service; one of:
+
+ "true"
+ Anonymized IP addresses are blocked by this Delivery Service
+ "false"
+ Anonymized IP addresses are not blocked by this Delivery Service
+
+ .. seealso:: :ref:`anonymous_blocking-qht`
+
+ :coverageZoneOnly: A string containing a boolean that tells whether or not this Delivery Service routes traffic based only on its Coverage Zone file
+ :deepCachingType: A string that tells when Deep Caching is used by this Delivery Service; one of:
+
+ "ALWAYS"
+ Deep Caching is always used by this Delivery Service
+ "NEVER"
+ Deep Caching is never used by this Delivery Service
+
+ :dispersion: An object describing the "dispersion" - or number of caches within a single Cache Group across which the same content is spread - within the Delivery Service
+
+ :limit: The maximum number of caches in which the response to a single request URL will be stored
+
+ .. note:: If this is greater than the number of caches in the Cache Group chosen to service the request, then content will be spread across all of them. That is, it causes no problems.
+
+ :shuffled: A string containing a boolean that tells whether the caches chosen for content dispersion are chosen randomly or based on a consistent hash of the request URL; one of:
+
+ "false"
+ Caches will be chosen consistently
+ "true"
+ Caches will be chosen at random
+
+ :domains: An array of domains served by this Delivery Service
+ :geolocationProvider: The name of a provider for IP-to-geographic-location mapping services - currently the only valid value is ``"maxmindGeolocationService"``
+ :ip6RoutingEnabled: A string containing a boolean that tells whether IPv6 traffic can be routed on this Delivery Service; one of:
+
+ "false"
+ IPv6 traffic will not be routed by this Delivery Service
+ "true"
+ IPv6 traffic will be routed by this Delivery Service
+
+ :matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this Delivery Service
+
+ :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped)
+ :setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs
+ :type: The type of match performed using ``pattern`` to determine whether or not to use this Delivery Service
+
+ HOST_REGEXP
+ Use the Delivery Service if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [1]_
+ HEADER_REGEXP
+ Use the Delivery Service if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [1]_
+ PATH_REGEXP
+ Use the Delivery Service if ``pattern`` matches the request path of this Delivery Service's URL
+ STEERING_REGEXP
+ Use the Delivery Service if ``pattern`` matches the ``xml_id`` of one of this Delivery Service's "Steering" target Delivery Services
+
+ :missLocation: An object representing the default geographic coordinates to use for a client when lookup of their IP has failed in both the Coverage Zone file(s) and the IP-to-geographic-location database
+
+ :lat: Geographic latitude
+ :long: Geographic longitude
+
+ :protocol: An object that describes how the Delivery Service ought to handle HTTP requests both with and without TLS encryption
+
+ :acceptHttps: A string containing a boolean that tells whether HTTPS requests should be normally serviced by this Delivery Service; one of:
+
+ "false"
+ Refuse to service HTTPS requests
+ "true"
+ Service HTTPS requests normally
+
+ :redirectToHttps: A string containing a boolean that tells whether HTTP requests ought to be re-directed to use HTTPS; one of:
+
+ "false"
+ Do not redirect unencrypted traffic; service it normally
+ "true"
+ Respond to HTTP requests with instructions to use HTTPS instead
+
+ :regionalGeoBlocking: A string containing a boolean that tells whether Regional Geographic Blocking is enabled on this Delivery Service; one of:
+
+ "false"
+ Regional Geographic Blocking is not used by this Delivery Service
+ "true"
+ Regional Geographic Blocking is used by this Delivery Service
+
+ .. seealso:: :ref:`regionalgeo-qht`
+
+ :routingName: The highest-level part of the FQDNs serviced by this Delivery Service
+ :soa: An object defining the Start of Authority (SOA) record for the Delivery Service's TLDs (defined in ``domains``)
+
+ :admin: The name of the administrator for this zone - i.e. the RNAME
+
+ .. note:: This rarely represents a proper email address, unfortunately.
+
+ :expire: A string containing an integer that sets the number of seconds after which secondary name servers should stop answering requests for this zone if the master does not respond
+ :minimum: A string containing an integer that sets the Time To Live (TTL) - in seconds - of the record for the purpose of negative caching
+ :refresh: A string containing an integer that sets the number of seconds after which secondary name servers should query the master for the SOA record, to detect zone changes
+ :retry: A string containing an integer that sets the number of seconds after which secondary name servers should retry to request the serial number from the master if the master does not respond
+
+ .. note:: `RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ dictates that this should always be less than ``refresh``.
+
+ .. seealso:: `The Wikipedia page on Start of Authority records <https://en.wikipedia.org/wiki/SOA_record>`_.
+
+ :sslEnabled: A string containing a boolean that tells whether this Delivery Service uses SSL; one of:
+
+ "false"
+ SSL is not used by this Delivery Service
+ "true"
+ SSL is used by this Delivery Service
+
+ :ttls: An object that contains keys which are types of DNS records that have values which are strings containing integers that specify the time for which a response to the specific type of record request should remain valid
+
+ .. note:: This overrides ``config.ttls``.
+
+:edgeLocations: An object containing keys which are the names of Edge-Tier Cache Groups within the CDN
+
+ :backupLocations: An object that describes fallbacks for when this Cache Group is unavailable
+
+ :fallbackToClosest: A string containing a boolean which tells whether requests should fall back on the closest available Cache Group when this Cache Group is not available; one of:
+
+ "false"
+ Do not fall back on the closest available Cache Group
+ "true"
+ Fall back on the closest available Cache Group
+
+ :list: If any fallback Cache Groups have been configured for this Cache Group, this key will appear and will be an array of the names of all of those fallback Cache Groups, in the prescribed order
+
+ :latitude: The geographic latitude of this Cache Group
+ :localizationMethods: An array of short names for localization methods available for this Cache Group
+ :longitude: The geographic longitude of this Cache Group
+
+:monitors: An object containing keys which are the (short) hostnames of Traffic Monitors within this CDN
+
+ :fqdn: The FQDN of this Traffic Monitor
+ :httpsPort: The port number on which this Traffic Monitor listens for incoming HTTPS requests
+ :ip6: This Traffic Monitor's IPv6 address
+ :ip: This Traffic Monitor's IPv4 address
+ :location: The name of the Cache Group to which this Traffic Monitor belongs
+ :port: The port number on which this Traffic Monitor listens for incoming HTTP requests
+ :profile: The name of the profile used by this Traffic Monitor
+
+ .. note:: For legacy reasons, this must always start with "RASCAL-".
+
+ :status: The health status of this Traffic Monitor
+
+ .. seealso:: :ref:`health-proto`
+
+:stats: An object containing metadata information regarding the CDN
+
+ :CDN_name: The name of this CDN
+ :date: The UNIX epoch timestamp date in the Traffic Ops server's own timezone
+ :tm_host: The FQDN of the Traffic Ops server
+ :tm_path: A path relative to the root of the Traffic Ops server where a request may be replaced to have this snapshot overwritten by the current *configured state* of the CDN
+
+ .. deprecated:: 1.1
+ This field is still present for legacy compatibility reasons, but its contents should be ignored. Instead, make a ``PUT`` request to :ref:`to-api-snapshot-name`.
+
+ :tm_user: The username of the currently logged-in user
+ :tm_version: The full version number of the Traffic Ops server, including release number, git commit hash, and supported Enterprise Linux version
+
+:trafficRouterLocations: An object containing keys which are the names of Cache Groups within the CDN which contain Traffic Routers
+
+ :backupLocations: An object that describes fallbacks for when this Cache Group is unavailable
+
+ :fallbackToClosest: A string containing a boolean which tells whether requests should fall back on the closest available Cache Group when this Cache Group is not available; one of:
+
+ "false"
+ Do not fall back on the closest available Cache Group
+ "true"
+ Fall back on the closest available Cache Group
+
+ :latitude: The geographic latitude of this Cache Group
+ :localizationMethods: An array of short names for localization methods available for this Cache Group
+ :longitude: The geographic longitude of this Cache Group
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: 220bc4XXwaj+s7ODd3QAF5leGj06lnApiN5E8H/B2RgxSphnQIfnwy6WWbBDjonWXPV1IWDCjBMO+rR+lAabMg==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 12 Dec 2018 17:36:25 GMT
+ Transfer-Encoding: chunked
+
+ { "response": {
+ "config": {
+ "api.cache-control.max-age": "10",
+ "certificates.polling.interval": "300000",
+ "consistent.dns.routing": "true",
+ "coveragezone.polling.interval": "3600000",
+ "coveragezone.polling.url": "https://trafficops.infra.ciab.test:443/coverage-zone.json",
+ "dnssec.dynamic.response.expiration": "300s",
+ "dnssec.enabled": "false",
+ "domain_name": "mycdn.ciab.test",
+ "edge.dns.limit": "6",
+ "edge.dns.routing": "true",
+ "edge.http.limit": "6",
+ "edge.http.routing": "true",
+ "federationmapping.polling.interval": "60000",
+ "federationmapping.polling.url": "https://${toHostname}/internal/api/1.3/federations.json",
+ "geolocation.polling.interval": "86400000",
+ "geolocation.polling.url": "https://trafficops.infra.ciab.test:443/GeoLite2-City.mmdb.gz",
+ "keystore.maintenance.interval": "300",
+ "neustar.polling.interval": "86400000",
+ "neustar.polling.url": "https://trafficops.infra.ciab.test:443/neustar.tar.gz",
+ "soa": {
+ "admin": "twelve_monkeys",
+ "expire": "604800",
+ "minimum": "30",
+ "refresh": "28800",
+ "retry": "7200"
+ },
+ "steeringmapping.polling.interval": "60000",
+ "ttls": {
+ "A": "3600",
+ "AAAA": "3600",
+ "DNSKEY": "30",
+ "DS": "30",
+ "NS": "3600",
+ "SOA": "86400"
+ },
+ "zonemanager.cache.maintenance.interval": "300",
+ "zonemanager.threadpool.scale": "0.50"
+ },
+ "contentServers": {
+ "edge": {
+ "cacheGroup": "CDN_in_a_Box_Edge",
+ "fqdn": "edge.infra.ciab.test",
+ "hashCount": 999,
+ "hashId": "edge",
+ "httpsPort": 443,
+ "interfaceName": "eth0",
+ "ip": "172.16.239.100",
+ "ip6": "fc01:9400:1000:8::100",
+ "locationId": "CDN_in_a_Box_Edge",
+ "port": 80,
+ "profile": "ATS_EDGE_TIER_CACHE",
+ "status": "REPORTED",
+ "type": "EDGE",
+ "deliveryServices": {
+ "demo1": [
+ "edge.demo1.mycdn.ciab.test"
+ ]
+ },
+ "routingDisabled": 0
+ },
+ "mid": {
+ "cacheGroup": "CDN_in_a_Box_Mid",
+ "fqdn": "mid.infra.ciab.test",
+ "hashCount": 999,
+ "hashId": "mid",
+ "httpsPort": 443,
+ "interfaceName": "eth0",
+ "ip": "172.16.239.120",
+ "ip6": "fc01:9400:1000:8::120",
+ "locationId": "CDN_in_a_Box_Mid",
+ "port": 80,
+ "profile": "ATS_MID_TIER_CACHE",
+ "status": "REPORTED",
+ "type": "MID",
+ "routingDisabled": 0
+ }
+ },
+ "contentRouters": {
+ "trafficrouter": {
+ "api.port": "3333",
+ "fqdn": "trafficrouter.infra.ciab.test",
+ "httpsPort": 443,
+ "ip": "172.16.239.60",
+ "ip6": "fc01:9400:1000:8::60",
+ "location": "CDN_in_a_Box_Edge",
+ "port": 80,
+ "profile": "CCR_CIAB",
+ "status": "ONLINE"
+ }
+ },
+ "deliveryServices": {
+ "demo1": {
+ "anonymousBlockingEnabled": "false",
+ "coverageZoneOnly": "false",
+ "dispersion": {
+ "limit": 1,
+ "shuffled": "true"
+ },
+ "domains": [
+ "demo1.mycdn.ciab.test"
+ ],
+ "geolocationProvider": "maxmindGeolocationService",
+ "matchsets": [
+ {
+ "protocol": "HTTP",
+ "matchlist": [
+ {
+ "regex": ".*\\.demo1\\..*",
+ "match-type": "HOST"
+ }
+ ]
+ }
+ ],
+ "missLocation": {
+ "lat": 42,
+ "long": -88
+ },
+ "protocol": {
+ "acceptHttps": "false",
+ "redirectToHttps": "false"
+ },
+ "regionalGeoBlocking": "false",
+ "soa": {
+ "admin": "traffic_ops",
+ "expire": "604800",
+ "minimum": "30",
+ "refresh": "28800",
+ "retry": "7200"
+ },
+ "sslEnabled": "false",
+ "ttls": {
+ "A": "",
+ "AAAA": "",
+ "NS": "3600",
+ "SOA": "86400"
+ },
+ "ip6RoutingEnabled": "true",
+ "routingName": "video",
+ "deepCachingType": "NEVER"
+ }
+ },
+ "edgeLocations": {
+ "CDN_in_a_Box_Edge": {
+ "latitude": 38.897663,
+ "longitude": -77.036574,
+ "backupLocations": {
+ "fallbackToClosest": "true"
+ },
+ "localizationMethods": [
+ "GEO",
+ "CZ",
+ "DEEP_CZ"
+ ]
+ }
+ },
+ "trafficRouterLocations": {
+ "CDN_in_a_Box_Edge": {
+ "latitude": 38.897663,
+ "longitude": -77.036574,
+ "backupLocations": {
+ "fallbackToClosest": "false"
+ },
+ "localizationMethods": [
+ "GEO",
+ "CZ",
+ "DEEP_CZ"
+ ]
+ }
+ },
+ "monitors": {
+ "trafficmonitor": {
+ "fqdn": "trafficmonitor.infra.ciab.test",
+ "httpsPort": 443,
+ "ip": "172.16.239.40",
+ "ip6": "fc01:9400:1000:8::40",
+ "location": "CDN_in_a_Box_Edge",
+ "port": 80,
+ "profile": "RASCAL-Traffic_Monitor",
+ "status": "ONLINE"
+ }
+ },
+ "stats": {
+ "CDN_name": "CDN-in-a-Box",
+ "date": 1544635937,
+ "tm_host": "trafficops.infra.ciab.test",
+ "tm_path": "/tools/write_crconfig/CDN-in-a-Box",
+ "tm_user": "admin",
+ "tm_version": "traffic_ops-3.0.0-9813.8ad7bd8e.el7"
+ }
+ }}
+
+.. [1] These only apply to HTTP-routed Delivery Services
diff --git a/docs/source/api/cdns_name_snapshot_new.rst b/docs/source/api/cdns_name_snapshot_new.rst
new file mode 100644
index 0000000..b2238b8
--- /dev/null
+++ b/docs/source/api/cdns_name_snapshot_new.rst
@@ -0,0 +1,543 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-name-snapshot-new:
+
+******************************
+``cdns/{{name}}/snapshot/new``
+******************************
+
+``GET``
+=======
+Retrieves the *pending* snapshot for a CDN, which represents the current *configuration* of the CDN, **not** the current *operating state* of the CDN. The contents of this snapshot are currently used by Traffic Monitor and Traffic Router.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+------------------------------------------------------------+
+ | Name | Description |
+ +======+============================================================+
+ | name | The name of the CDN for which a snapshot shall be returned |
+ +------+------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.4/cdns/CDN-in-a-Box/snapshot/new HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:config: An object containing basic configurations on the actual CDN object
+
+ :api.cache-control.max-age: A string containing an integer which specifies the value of ``max-age`` in the ``Cache-Control`` header of some HTTP responses, likely the Traffic Router API responses
+
+ .. deprecated:: 1.1
+ This field still exists for legacy compatibility reasons, but has no known use at the time of this writing
+
+ :certificates.polling.interval: A string containing an integer which specifies the interval, in seconds, on which other Traffic Control components should check for updated SSL certificates
+ :consistent.dns.routing: A string containing a boolean which indicates whether DNS routing will use a consistent hashing method or "round-robin"
+
+ "false"
+ The "round-robin" method will be used to define DNS routing
+ "true"
+ A consistent hashing method will be used to define DNS routing
+
+ :coveragezone.polling.interval: A string containing an integer which specifies the interval, in seconds, on which Traffic Routers should check for a new Coverage Zone file
+ :coveragezone.polling.url: The URL where a Coverage Zone file may be requested by Traffic Routers
+ :dnssec.dynamic.response.expiration: A string containing a number and unit suffix that specifies the length of time for which dynamic responses to DNSSEC lookup queries should remain valid
+ :dnssec.enabled: A string that tells whether or not the CDN uses DNSSEC; one of:
+
+ "false"
+ DNSSEC is not used within this CDN
+ "true"
+ DNSSEC is used within this CDN
+
+ :domain_name: The Top-Level Domain Name (TLD) served by the CDN
+ :edge.dns.limit: This field is of unknown use, and may be remnants of a legacy system
+ :edge.dns.routing: This field is of unknown use, and may be remnants of a legacy system
+ :edge.http.limit: This field is of unknown use, and may be remnants of a legacy system
+ :edge.http.routing: This field is of unknown use, and may be remnants of a legacy system
+ :federationmapping.polling.interval: A string containing an integer which specifies the interval, in seconds, on which other Traffic Control components should check for new federation mappings
+ :federationmapping.polling.url: The URL where Traffic Control components can request federation mappings
+ :geolocation.polling.interval: A string containing an integer which specifies the interval, in seconds, on which other Traffic Control components should check for new IP-to-geographic-location mapping databases
+ :geolocation.polling.url: The URL where Traffic Control components can request IP-to-geographic-location mapping database files
+ :keystore.maintenance.interval: A string containing an integer which specifies the interval, in seconds, on which Traffic Routers should refresh their zone caches
+ :neustar.polling.interval: A string containing an integer which specifies the interval, in seconds, on which other Traffic Control components should check for new "Neustar" databases
+ :neustar.polling.url: The URL where Traffic Control components can request "Neustar" databases
+ :soa: An object defining the Start of Authority (SOA) for the CDN's TLD (defined in ``domain_name``)
+
+ :admin: The name of the administrator for this zone - i.e. the RNAME
+
+ .. note:: This rarely represents a proper email address, unfortunately.
+
+ :expire: A string containing an integer that sets the number of seconds after which secondary name servers should stop answering requests for this zone if the master does not respond
+ :minimum: A string containing an integer that sets the Time To Live (TTL) - in seconds - of the record for the purpose of negative caching
+ :refresh: A string containing an integer that sets the number of seconds after which secondary name servers should query the master for the SOA record, to detect zone changes
+ :retry: A string containing an integer that sets the number of seconds after which secondary name servers should retry to request the serial number from the master if the master does not respond
+
+ .. note:: `RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ dictates that this should always be less than ``refresh``.
+
+ .. seealso:: `The Wikipedia page on Start of Authority records <https://en.wikipedia.org/wiki/SOA_record>`_.
+
+ :steeringmapping.polling.interval: A string containing an integer which specifies the interval, in seconds, on which Traffic Control components should check for new steering mappings
+ :ttls: An object that contains keys which are types of DNS records that have values which are strings containing integers that specify the time for which a response to the specific type of record request should remain valid
+ :zonemanager.cache.maintenance.interval: A configuration option for the ZoneManager Java class of Traffic Router
+ :zonemanager.threadpool.scale: A configuration option for the ZoneManager Java class of Traffic Router
+
+:contentRouters: An object containing keys which are the (short) hostnames of the Traffic Routers that serve requests for Delivery Services in this CDN
+
+ :api.port: A string containing the port number on which the :ref:`tr-api` is served by this Traffic Router
+ :fqdn: This Traffic Router's Fully Qualified Domain Name (FQDN)
+ :httpsPort: The port number on which this Traffic Router listens for incoming HTTPS requests
+ :ip: This Traffic Router's IPv4 address
+ :ip6: This Traffic Router's IPv6 address
+ :location: The name of the Cache Group to which this Traffic Router belongs
+ :port: The port number on which this Traffic Router listens for incoming HTTP requests
+ :profile: The name of the profile used by this Traffic Router
+ :status: The health status of this Traffic Router
+
+ .. seealso:: :ref:`health-proto`
+
+:contentServers: An object containing keys which are the (short) hostnames of the Edge-Tier cache servers in the CDN; the values corresponding to those keys are routing information for said servers
+
+ :cacheGroup: The name of the Cache Group to which the server belongs
+ :deliveryServices: An object containing keys which are the names of Delivery Services to which this cache server is assigned; the values corresponding to those keys are arrays of FQDNs that resolve to this cache server
+
+ .. note:: Only Edge-tier cache servers can be assigned to a Delivery SErvice, and therefore this field will only be present when ``type`` is ``"EDGE"``.
+
+ :fqdn: The server's Fully Qualified Domain Name (FQDN)
+ :hashCount: The number of servers to be placed into a single "hash ring" in Traffic Router
+ :hashId: A unique string to be used as the key for hashing servers - as of version 3.0.0 of Traffic Control, this is always the same as the server's (short) hostname and only still exists for legacy compatibility reasons
+ :httpsPort: The port on which the cache server listens for incoming HTTPS requests
+ :interfaceName: The name of the main network interface device used by this cache server
+ :ip6: The server's IPv6 address
+ :ip: The server's IPv4 address
+ :locationId: This field is exactly the same as ``cacheGroup`` and only exists for legacy compatibility reasons
+ :port: The port on which this cache server listens for incoming HTTP requests
+ :profile: The name of the profile used by the cache server
+ :routingDisabled: An integer representing the boolean concept of whether or not Traffic Routers should route client traffic this cache server; one of:
+
+ 0
+ Do not route traffic to this server
+ 1
+ Route traffic to this server normally
+
+ :status: This cache server's status
+
+ .. seealso:: :ref:`health-proto`
+
+ :type: The type of this cache server; one of:
+
+ EDGE
+ This is an Edge-tier cache server
+ MID
+ This is a Mid-tier cache server
+
+:deliveryServices: An object containing keys which are the 'xml_id's of all of the Delivery Services within the CDN
+
+ :anonymousBlockingEnabled: A string containing a boolean that tells whether or not Anonymized IP Addresses are blocked by this Delivery Service; one of:
+
+ "true"
+ Anonymized IP addresses are blocked by this Delivery Service
+ "false"
+ Anonymized IP addresses are not blocked by this Delivery Service
+
+ .. seealso:: :ref:`anonymous_blocking-qht`
+
+ :coverageZoneOnly: A string containing a boolean that tells whether or not this Delivery Service routes traffic based only on its Coverage Zone file
+ :deepCachingType: A string that tells when Deep Caching is used by this Delivery Service; one of:
+
+ "ALWAYS"
+ Deep Caching is always used by this Delivery Service
+ "NEVER"
+ Deep Caching is never used by this Delivery Service
+
+ :dispersion: An object describing the "dispersion" - or number of caches within a single Cache Group across which the same content is spread - within the Delivery Service
+
+ :limit: The maximum number of caches in which the response to a single request URL will be stored
+
+ .. note:: If this is greater than the number of caches in the Cache Group chosen to service the request, then content will be spread across all of them. That is, it causes no problems.
+
+ :shuffled: A string containing a boolean that tells whether the caches chosen for content dispersion are chosen randomly or based on a consistent hash of the request URL; one of:
+
+ "false"
+ Caches will be chosen consistently
+ "true"
+ Caches will be chosen at random
+
+ :domains: An array of domains served by this Delivery Service
+ :geolocationProvider: The name of a provider for IP-to-geographic-location mapping services - currently the only valid value is ``"maxmindGeolocationService"``
+ :ip6RoutingEnabled: A string containing a boolean that tells whether IPv6 traffic can be routed on this Delivery Service; one of:
+
+ "false"
+ IPv6 traffic will not be routed by this Delivery Service
+ "true"
+ IPv6 traffic will be routed by this Delivery Service
+
+ :matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this Delivery Service
+
+ :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped)
+ :setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs
+ :type: The type of match performed using ``pattern`` to determine whether or not to use this Delivery Service
+
+ HOST_REGEXP
+ Use the Delivery Service if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [1]_
+ HEADER_REGEXP
+ Use the Delivery Service if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [1]_
+ PATH_REGEXP
+ Use the Delivery Service if ``pattern`` matches the request path of this Delivery Service's URL
+ STEERING_REGEXP
+ Use the Delivery Service if ``pattern`` matches the ``xml_id`` of one of this Delivery Service's "Steering" target Delivery Services
+
+ :missLocation: An object representing the default geographic coordinates to use for a client when lookup of their IP has failed in both the Coverage Zone file(s) and the IP-to-geographic-location database
+
+ :lat: Geographic latitude
+ :long: Geographic longitude
+
+ :protocol: An object that describes how the Delivery Service ought to handle HTTP requests both with and without TLS encryption
+
+ :acceptHttps: A string containing a boolean that tells whether HTTPS requests should be normally serviced by this Delivery Service; one of:
+
+ "false"
+ Refuse to service HTTPS requests
+ "true"
+ Service HTTPS requests normally
+
+ :redirectToHttps: A string containing a boolean that tells whether HTTP requests ought to be re-directed to use HTTPS; one of:
+
+ "false"
+ Do not redirect unencrypted traffic; service it normally
+ "true"
+ Respond to HTTP requests with instructions to use HTTPS instead
+
+ :regionalGeoBlocking: A string containing a boolean that tells whether Regional Geographic Blocking is enabled on this Delivery Service; one of:
+
+ "false"
+ Regional Geographic Blocking is not used by this Delivery Service
+ "true"
+ Regional Geographic Blocking is used by this Delivery Service
+
+ .. seealso:: :ref:`regionalgeo-qht`
+
+ :routingName: The highest-level part of the FQDNs serviced by this Delivery Service
+ :soa: An object defining the Start of Authority (SOA) record for the Delivery Service's TLDs (defined in ``domains``)
+
+ :admin: The name of the administrator for this zone - i.e. the RNAME
+
+ .. note:: This rarely represents a proper email address, unfortunately.
+
+ :expire: A string containing an integer that sets the number of seconds after which secondary name servers should stop answering requests for this zone if the master does not respond
+ :minimum: A string containing an integer that sets the Time To Live (TTL) - in seconds - of the record for the purpose of negative caching
+ :refresh: A string containing an integer that sets the number of seconds after which secondary name servers should query the master for the SOA record, to detect zone changes
+ :retry: A string containing an integer that sets the number of seconds after which secondary name servers should retry to request the serial number from the master if the master does not respond
+
+ .. note:: `RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ dictates that this should always be less than ``refresh``.
+
+ .. seealso:: `The Wikipedia page on Start of Authority records <https://en.wikipedia.org/wiki/SOA_record>`_.
+
+ :sslEnabled: A string containing a boolean that tells whether this Delivery Service uses SSL; one of:
+
+ "false"
+ SSL is not used by this Delivery Service
+ "true"
+ SSL is used by this Delivery Service
+
+ :ttls: An object that contains keys which are types of DNS records that have values which are strings containing integers that specify the time for which a response to the specific type of record request should remain valid
+
+ .. note:: This overrides ``config.ttls``.
+
+:edgeLocations: An object containing keys which are the names of Edge-Tier Cache Groups within the CDN
+
+ :backupLocations: An object that describes fallbacks for when this Cache Group is unavailable
+
+ :fallbackToClosest: A string containing a boolean which tells whether requests should fall back on the closest available Cache Group when this Cache Group is not available; one of:
+
+ "false"
+ Do not fall back on the closest available Cache Group
+ "true"
+ Fall back on the closest available Cache Group
+
+ :list: If any fallback Cache Groups have been configured for this Cache Group, this key will appear and will be an array of the names of all of those fallback Cache Groups, in the prescribed order
+
+ :latitude: The geographic latitude of this Cache Group
+ :localizationMethods: An array of short names for localization methods available for this Cache Group
+ :longitude: The geographic longitude of this Cache Group
+
+:monitors: An object containing keys which are the (short) hostnames of Traffic Monitors within this CDN
+
+ :fqdn: The FQDN of this Traffic Monitor
+ :httpsPort: The port number on which this Traffic Monitor listens for incoming HTTPS requests
+ :ip6: This Traffic Monitor's IPv6 address
+ :ip: This Traffic Monitor's IPv4 address
+ :location: The name of the Cache Group to which this Traffic Monitor belongs
+ :port: The port number on which this Traffic Monitor listens for incoming HTTP requests
+ :profile: The name of the profile used by this Traffic Monitor
+
+ .. note:: For legacy reasons, this must always start with "RASCAL-".
+
+ :status: The health status of this Traffic Monitor
+
+ .. seealso:: :ref:`health-proto`
+
+:stats: An object containing metadata information regarding the CDN
+
+ :CDN_name: The name of this CDN
+ :date: The UNIX epoch timestamp date in the Traffic Ops server's own timezone
+ :tm_host: The FQDN of the Traffic Ops server
+ :tm_path: A path relative to the root of the Traffic Ops server where a request may be replaced to have this snapshot overwritten by the current *configured state* of the CDN
+
+ .. deprecated:: 1.1
+ This field is still present for legacy compatibility reasons, but its contents should be ignored. Instead, make a ``PUT`` request to :ref:`to-api-snapshot-name`.
+
+ :tm_user: The username of the currently logged-in user
+ :tm_version: The full version number of the Traffic Ops server, including release number, git commit hash, and supported Enterprise Linux version
+
+:trafficRouterLocations: An object containing keys which are the names of Cache Groups within the CDN which contain Traffic Routers
+
+ :backupLocations: An object that describes fallbacks for when this Cache Group is unavailable
+
+ :fallbackToClosest: A string containing a boolean which tells whether requests should fall back on the closest available Cache Group when this Cache Group is not available; one of:
+
+ "false"
+ Do not fall back on the closest available Cache Group
+ "true"
+ Fall back on the closest available Cache Group
+
+ :latitude: The geographic latitude of this Cache Group
+ :localizationMethods: An array of short names for localization methods available for this Cache Group
+ :longitude: The geographic longitude of this Cache Group
+
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: MWzgAYngmU1IEIxRa0C6VfY+MMuu7T9OCiIj1Aul58pA7J7DiS6r8wjVRVVW8W2Eu2V9BC7OEacR1fQyuIsRWg==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 12 Dec 2018 21:41:48 GMT
+ Transfer-Encoding: chunked
+
+ { "response": {
+ "config": {
+ "api.cache-control.max-age": "10",
+ "certificates.polling.interval": "300000",
+ "consistent.dns.routing": "true",
+ "coveragezone.polling.interval": "3600000",
+ "coveragezone.polling.url": "https://trafficops.infra.ciab.test:443/coverage-zone.json",
+ "dnssec.dynamic.response.expiration": "300s",
+ "dnssec.enabled": "false",
+ "domain_name": "mycdn.ciab.test",
+ "edge.dns.limit": "6",
+ "edge.dns.routing": "true",
+ "edge.http.limit": "6",
+ "edge.http.routing": "true",
+ "federationmapping.polling.interval": "60000",
+ "federationmapping.polling.url": "https://${toHostname}/internal/api/1.3/federations.json",
+ "geolocation.polling.interval": "86400000",
+ "geolocation.polling.url": "https://trafficops.infra.ciab.test:443/GeoLite2-City.mmdb.gz",
+ "keystore.maintenance.interval": "300",
+ "neustar.polling.interval": "86400000",
+ "neustar.polling.url": "https://trafficops.infra.ciab.test:443/neustar.tar.gz",
+ "soa": {
+ "admin": "twelve_monkeys",
+ "expire": "604800",
+ "minimum": "30",
+ "refresh": "28800",
+ "retry": "7200"
+ },
+ "steeringmapping.polling.interval": "60000",
+ "ttls": {
+ "A": "3600",
+ "AAAA": "3600",
+ "DNSKEY": "30",
+ "DS": "30",
+ "NS": "3600",
+ "SOA": "86400"
+ },
+ "zonemanager.cache.maintenance.interval": "300",
+ "zonemanager.threadpool.scale": "0.50"
+ },
+ "contentServers": {
+ "edge": {
+ "cacheGroup": "CDN_in_a_Box_Edge",
+ "fqdn": "edge.infra.ciab.test",
+ "hashCount": 999,
+ "hashId": "edge",
+ "httpsPort": 443,
+ "interfaceName": "eth0",
+ "ip": "172.16.239.100",
+ "ip6": "fc01:9400:1000:8::100",
+ "locationId": "CDN_in_a_Box_Edge",
+ "port": 80,
+ "profile": "ATS_EDGE_TIER_CACHE",
+ "status": "REPORTED",
+ "type": "EDGE",
+ "deliveryServices": {
+ "demo1": [
+ "edge.demo1.mycdn.ciab.test"
+ ]
+ },
+ "routingDisabled": 0
+ },
+ "mid": {
+ "cacheGroup": "CDN_in_a_Box_Mid",
+ "fqdn": "mid.infra.ciab.test",
+ "hashCount": 999,
+ "hashId": "mid",
+ "httpsPort": 443,
+ "interfaceName": "eth0",
+ "ip": "172.16.239.120",
+ "ip6": "fc01:9400:1000:8::120",
+ "locationId": "CDN_in_a_Box_Mid",
+ "port": 80,
+ "profile": "ATS_MID_TIER_CACHE",
+ "status": "REPORTED",
+ "type": "MID",
+ "routingDisabled": 0
+ }
+ },
+ "contentRouters": {
+ "trafficrouter": {
+ "api.port": "3333",
+ "fqdn": "trafficrouter.infra.ciab.test",
+ "httpsPort": 443,
+ "ip": "172.16.239.60",
+ "ip6": "fc01:9400:1000:8::60",
+ "location": "CDN_in_a_Box_Edge",
+ "port": 80,
+ "profile": "CCR_CIAB",
+ "status": "ONLINE"
+ }
+ },
+ "deliveryServices": {
+ "demo1": {
+ "anonymousBlockingEnabled": "false",
+ "coverageZoneOnly": "false",
+ "dispersion": {
+ "limit": 1,
+ "shuffled": "true"
+ },
+ "domains": [
+ "demo1.mycdn.ciab.test"
+ ],
+ "geolocationProvider": "maxmindGeolocationService",
+ "matchsets": [
+ {
+ "protocol": "HTTP",
+ "matchlist": [
+ {
+ "regex": ".*\\.demo1\\..*",
+ "match-type": "HOST"
+ }
+ ]
+ }
+ ],
+ "missLocation": {
+ "lat": 42,
+ "long": -88
+ },
+ "protocol": {
+ "acceptHttps": "false",
+ "redirectToHttps": "false"
+ },
+ "regionalGeoBlocking": "false",
+ "soa": {
+ "admin": "traffic_ops",
+ "expire": "604800",
+ "minimum": "30",
+ "refresh": "28800",
+ "retry": "7200"
+ },
+ "sslEnabled": "false",
+ "ttls": {
+ "A": "",
+ "AAAA": "",
+ "NS": "3600",
+ "SOA": "86400"
+ },
+ "ip6RoutingEnabled": "true",
+ "routingName": "video",
+ "deepCachingType": "NEVER"
+ }
+ },
+ "edgeLocations": {
+ "CDN_in_a_Box_Edge": {
+ "latitude": 38.897663,
+ "longitude": -77.036574,
+ "backupLocations": {
+ "fallbackToClosest": "true",
+ "list": [
+ "test"
+ ]
+ },
+ "localizationMethods": [
+ "GEO",
+ "CZ",
+ "DEEP_CZ"
+ ]
+ }
+ },
+ "trafficRouterLocations": {
+ "CDN_in_a_Box_Edge": {
+ "latitude": 38.897663,
+ "longitude": -77.036574,
+ "backupLocations": {
+ "fallbackToClosest": "false"
+ },
+ "localizationMethods": [
+ "GEO",
+ "CZ",
+ "DEEP_CZ"
+ ]
+ }
+ },
+ "monitors": {
+ "trafficmonitor": {
+ "fqdn": "trafficmonitor.infra.ciab.test",
+ "httpsPort": 443,
+ "ip": "172.16.239.40",
+ "ip6": "fc01:9400:1000:8::40",
+ "location": "CDN_in_a_Box_Edge",
+ "port": 80,
+ "profile": "RASCAL-Traffic_Monitor",
+ "status": "ONLINE"
+ }
+ },
+ "stats": {
+ "CDN_name": "CDN-in-a-Box",
+ "date": 1544650908,
+ "tm_host": "ipcdn-cache-51.cdnlab.comcast.net:6443",
+ "tm_path": "/tools/write_crconfig/CDN-in-a-Box",
+ "tm_user": "admin",
+ "tm_version": "traffic_ops-3.0.0-9813.8ad7bd8e.el7"
+ }
+ }}
+
+.. [1] These only apply to HTTP-routed Delivery Services
diff --git a/docs/source/api/cdns_routing.rst b/docs/source/api/cdns_routing.rst
new file mode 100644
index 0000000..e354855
--- /dev/null
+++ b/docs/source/api/cdns_routing.rst
@@ -0,0 +1,71 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-routing:
+
+****************
+``cdns/routing``
+****************
+
+``GET``
+=======
+Retrieves the aggregate routing percentages of Cache Groups assigned to any CDN.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Object
+
+Request Structure
+-----------------
+No parameters available
+
+Response Structure
+------------------
+:cz: Used Coverage Zone geographic IP mapping
+:dsr: Overflow traffic sent to secondary CDN
+:err: Error localizing client IP
+:geo: Used 3rd party geographic IP mapping
+:miss: No location available for client IP
+:staticRoute: Used pre-configured DNS entries
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 21:29:32 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 15 Nov 2018 01:29:32 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: 7LjytwKyRzSKM4cRIol4OMIJxApFpTWJaSK73rbtUIQdASZjI64XxLVzZP0OGRU7XeJ22YKUyQ30qbKHDRv7FQ==
+ Content-Length: 130
+
+ { "response": {
+ "staticRoute": 0,
+ "geo": 20.6251834458468,
+ "err": 0,
+ "fed": 0.287643087760493,
+ "cz": 79.0607572644555,
+ "regionalAlternate": 0,
+ "dsr": 0,
+ "miss": 0.0264162019371881,
+ "regionalDenied": 0
+ }}
+
diff --git a/docs/source/api/cdns_usage_overview.rst b/docs/source/api/cdns_usage_overview.rst
new file mode 100644
index 0000000..475b7d8
--- /dev/null
+++ b/docs/source/api/cdns_usage_overview.rst
@@ -0,0 +1,55 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-cdns-usage-overview:
+
+***********************
+``cdns/usage/overview``
+***********************
+
+.. versionadded:: 1.2
+
+``GET``
+=======
+Retrieves the high-level CDN usage metrics from Traffic Stats
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Object
+
+Request Structure
+-----------------
+No parameters available.
+
+Response Structure
+------------------
+:currentGbps: The current throughput of all CDNs, in Gigabits per second
+:maxGbps: The all-time maximum throughput of all CDNs, in Gigabits per second
+:source: The name of the service providing the statistics. This will almost always be "TrafficStats"
+:tps: The number of transactions being performed per second
+:version: The version of the service providing the statistics (named in ``"source"``)
+
+.. warning:: The ``"tps"`` field is currently broken, and will return ``0`` every time. See `GitHub issue #1020 <https://github.com/apache/trafficcontrol/issues/1020>`_ for more information.
+
+.. code-block:: json
+ :caption: Response Example
+
+ { "response": {
+ "currentGbps": 975.920621333333,
+ "source": "TrafficStats",
+ "tps": 0,
+ "version": "1.2",
+ "maxGbps": 12085
+ }}
diff --git a/docs/source/api/coordinates.rst b/docs/source/api/coordinates.rst
new file mode 100644
index 0000000..c96bd8e
--- /dev/null
+++ b/docs/source/api/coordinates.rst
@@ -0,0 +1,295 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-coordinates:
+
+***************
+``coordinates``
+***************
+.. versionadded:: 1.3
+
+``GET``
+=======
+Gets a list of all coordinates in the Traffic Ops database
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +------+----------+---------------------------------------------------------------------+
+ | Name | Required | Description |
+ +======+==========+=====================================================================+
+ | id | no | Return only coordinates that have this integral, unique identifier |
+ +------+----------+---------------------------------------------------------------------+
+ | name | no | Return only coordinates with this name |
+ +------+----------+---------------------------------------------------------------------+
+
+Response Structure
+------------------
+:id: Integral, unique, identifier for this coordinate pair
+:lastUpdated: The time and date at which this entry was last updated, in a ``ctime``-like format
+:latitude: Latitude of the coordinate
+:longitude: Longitude of the coordinate
+:name: The name of the coordinate - typically this just reflects the name of the Cache Group for which the coordinate was created
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: Y2vxC3hpxIg6aRNBBT7i2hbAViIJp+dJoqHIzu3acFM+vGay/I5E+eZYOC9RY8hcJPrKNXysZOD8DOb9KsFgaw==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 21:32:28 GMT
+ Content-Length: 942
+
+ { "response": [
+ {
+ "id": 1,
+ "name": "from_cachegroup_TRAFFIC_ANALYTICS",
+ "latitude": 38.897663,
+ "longitude": -77.036574,
+ "lastUpdated": "2018-10-24 16:07:04+00"
+ },
+ {
+ "id": 2,
+ "name": "from_cachegroup_TRAFFIC_OPS",
+ "latitude": 38.897663,
+ "longitude": -77.036574,
+ "lastUpdated": "2018-10-24 16:07:04+00"
+ },
+ {
+ "id": 3,
+ "name": "from_cachegroup_TRAFFIC_OPS_DB",
+ "latitude": 38.897663,
+ "longitude": -77.036574,
+ "lastUpdated": "2018-10-24 16:07:04+00"
+ },
+ {
+ "id": 4,
+ "name": "from_cachegroup_TRAFFIC_PORTAL",
+ "latitude": 38.897663,
+ "longitude": -77.036574,
+ "lastUpdated": "2018-10-24 16:07:04+00"
+ },
+ {
+ "id": 5,
+ "name": "from_cachegroup_TRAFFIC_STATS",
+ "latitude": 38.897663,
+ "longitude": -77.036574,
+ "lastUpdated": "2018-10-24 16:07:04+00"
+ },
+ {
+ "id": 6,
+ "name": "from_cachegroup_CDN_in_a_Box_Mid",
+ "latitude": 38.897663,
+ "longitude": -77.036574,
+ "lastUpdated": "2018-10-24 16:07:04+00"
+ },
+ {
+ "id": 7,
+ "name": "from_cachegroup_CDN_in_a_Box_Edge",
+ "latitude": 38.897663,
+ "longitude": -77.036574,
+ "lastUpdated": "2018-10-24 16:07:05+00"
+ }
+ ]}
+
+``POST``
+========
+Creates a new coordinate pair
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+:name: The name of the new coordinate
+:latitude: The desired latitude of the new coordinate (must be on the interval [-180, 180])
+:longitude: The desired longitude of the new coordinate (must be on the interval [-90, 90])
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.4/coordinates HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 47
+ Content-Type: application/json
+
+ {"name": "test", "latitude": 0, "longitude": 0}
+
+Response Structure
+------------------
+:id: Integral, unique, identifier for the newly created coordinate pair
+:lastUpdated: The time and date at which this entry was last updated, in a ``ctime``-like format
+:latitude: Latitude of the newly created coordinate
+:longitude: Longitude of the newly created coordinate
+:name: The name of the coordinate
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: 7pWdeZyIIXE1P7o/JVon+5eSCbDw+FGamAzdXzWHXJ8IhF+Vh+/tWFCkzHYw3rP2kBVwZu+gqLffjQpBCMjt7A==
+ X-Server-Name: traffic_ops_golang/
+ Date: Thu, 15 Nov 2018 17:48:55 GMT
+ Content-Length: 165
+
+ { "alerts": [
+ {
+ "text": "coordinate was created.",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "id": 9,
+ "name": "test",
+ "latitude": 0,
+ "longitude": 0,
+ "lastUpdated": "2018-11-15 17:48:55+00"
+ }}
+
+
+``PUT``
+=======
+Updates a coordinate
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +------+----------+------------------------------------------------------------+
+ | Name | Required | Description |
+ +======+==========+============================================================+
+ | id | yes | The integral, unique identifier of the coordinate to edit |
+ +------+----------+------------------------------------------------------------+
+
+:name: The name of the new coordinate
+:latitude: The desired new latitude of the coordinate (must be on the interval [-180, 180])
+:longitude: The desired new longitude of the coordinate (must be on the interval [-90, 90])
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/1.4/coordinates?id=9 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 48
+ Content-Type: application/json
+
+ {"name": "quest", "latitude": 0, "longitude": 0}
+
+Response Structure
+------------------
+:id: Integral, unique, identifier for the coordinate pair
+:lastUpdated: The time and date at which this entry was last updated, in a ``ctime``-like format
+:latitude: Latitude of the coordinate
+:longitude: Longitude of the coordinate
+:name: The name of the coordinate
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: zd03Uvbnv8EbSZZ75Xp5tnnYStZsZTdyPxXnoqK4QZ5WhELLPL8iHlRfOaiLTbrUWUeJ8ue2HRz6aBS/iXCCGA==
+ X-Server-Name: traffic_ops_golang/
+ Date: Thu, 15 Nov 2018 17:54:30 GMT
+ Content-Length: 166
+
+ { "alerts": [
+ {
+ "text": "coordinate was updated.",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "id": 9,
+ "name": "quest",
+ "latitude": 0,
+ "longitude": 0,
+ "lastUpdated": "2018-11-15 17:54:30+00"
+ }}
+
+``DELETE``
+==========
+Deletes a coordinate
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: ``undefined``
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +------+----------+-------------------------------------------------------------+
+ | Name | Required | Description |
+ +======+==========+=============================================================+
+ | id | yes | The integral, unique identifier of the coordinate to delete |
+ +------+----------+-------------------------------------------------------------+
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: 82x/Wdckqgk4LN5LIlZfBJ26xkDrUVUGDjs5QFa/Lzap7dU3OZkjv8XW41xeFYj8PDmxHIpb7hiVObvLaxnEDA==
+ X-Server-Name: traffic_ops_golang/
+ Date: Thu, 15 Nov 2018 17:57:42 GMT
+ Content-Length: 65
+
+ { "alerts": [
+ {
+ "text": "coordinate was deleted.",
+ "level": "success"
+ }
+ ]}
diff --git a/docs/source/api/deliveryservice_server_dsid_serverid.rst b/docs/source/api/deliveryservice_server_dsid_serverid.rst
new file mode 100644
index 0000000..f8b60eb
--- /dev/null
+++ b/docs/source/api/deliveryservice_server_dsid_serverid.rst
@@ -0,0 +1,68 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-deliveryservice_server-dsid-serverid:
+
+************************************************
+``deliveryservice_server/{{DSID}}/{{serverID}}``
+************************************************
+
+``DELETE``
+==========
+Removes a cache server from a Delivery Service.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"\ [1]_
+:Response Type: ``undefined``
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +----------+----------+-------------------------------------------------------+
+ | Name | Required | Description |
+ +==========+==========+=======================================================+
+ | dsId | yes | An integral, unique identifier for a Delivery Service |
+ +----------+----------+-------------------------------------------------------+
+ | serverID | yes | An integral, unique identifier for a server |
+ +----------+----------+-------------------------------------------------------+
+
+.. note:: The server identified by ``serverID`` must be a cache server, or the assignment will fail.
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: rGD2sOMHYF0sga1zuTytyLHCUkkc3ZwQRKvZ/HuPzObOP4WztKTOVXB4uhs3iJqBg9zRB2TucMxONHN+3/yShQ==
+ X-Server-Name: traffic_ops_golang/
+ Date: Thu, 01 Nov 2018 14:24:34 GMT
+ Content-Length: 80
+
+ { "alerts": [
+ {
+ "text": "Server unlinked from delivery service.",
+ "level": "success"
+ }
+ ]}
+
+.. [1] Users with the "admin" or "operations" roles will be able to delete *any* Delivery Service, whereas other users will only be able to delete Delivery Services that their tenant has permissions to delete.
diff --git a/docs/source/api/deliveryservice_stats.rst b/docs/source/api/deliveryservice_stats.rst
new file mode 100644
index 0000000..8e9f655
--- /dev/null
+++ b/docs/source/api/deliveryservice_stats.rst
@@ -0,0 +1,176 @@
+..
+..
+.. 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.
+..
+
+
+.. _to-api-deliveryservice_stats:
+
+*************************
+``deliveryservice_stats``
+*************************
+.. caution:: This page is a stub! Much of it may be missing or just downright wrong - it needs a lot of love from people with the domain knowledge required to update it.
+
+.. versionadded:: 1.2
+
+.. warning:: This endpoint does **NOT** respect tenancy permissions!
+
+``GET``
+=======
+Retrieves time-aggregated statistics on a specific Delivery Service.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +----------------------+----------+--------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +======================+==========+====================================================================================================================+
+ | deliveryServiceName | yes | The name of the Delivery Service for which statistics will be aggregated |
+ +----------------------+----------+--------------------------------------------------------------------------------------------------------------------+
+ | metricType | yes | The metric type being reported - one of: |
+ | | | |
+ | | | kbps |
+ | | | The total traffic rate in kilobytes per second served by the Delivery Service |
+ | | | out_bytes |
+ | | | The total number of bytes sent out to clients through the Delivery Service |
+ | | | status_4xx |
+ | | | The amount of requests that were serviced with 400-499 HTTP status codes |
+ | | | status_5xx |
+ | | | The amount of requests that were serviced with 500-599 HTTP status codes |
+ | | | tps_total |
+ | | | The total traffic rate in transactions per second served by the Delivery Service |
+ | | | tps_2xx |
+ | | | The total traffic rate in transactions per second serviced with 200-299 HTTP status codes |
+ | | | tps_3xx |
+ | | | The total traffic rate in transactions per second serviced with 300-399 HTTP status codes |
+ | | | tps_4xx |
+ | | | The total traffic rate in transactions per second serviced with 400-499 HTTP status codes |
+ | | | tps_5xx |
+ | | | The total traffic rate in transactions per second serviced with 500-599 HTTP status codes |
+ | | | |
+ +----------------------+----------+--------------------------------------------------------------------------------------------------------------------+
+ | startDate | yes | The date and time from which statistics shall be aggregated in ISO8601 format, e.g. ``2018-08-11T12:30:00-07:00`` |
+ +----------------------+----------+--------------------------------------------------------------------------------------------------------------------+
+ | endDate | yes | The date and time until which statistics shall be aggregated in ISO8601 format, e.g. ``2018-08-12T12:30:00-07:00`` |
+ +----------------------+----------+--------------------------------------------------------------------------------------------------------------------+
+
+Response Structure
+------------------
+.. table:: Response Keys
+
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ | Parameter | Type | Description |
+ +============================+===============+=========================================================================================+
+ |``source`` | string | The source of the data |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``summary`` | hash | Summary data |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>totalBytes`` | float | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>count`` | int | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>min`` | float | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>max`` | float | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>fifthPercentile`` | float | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>ninetyEighthPercentile`` | float | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>ninetyFifthPercentile`` | float | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>average`` | float | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>totalTransactions`` | int | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``series`` | hash | Series data |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>count`` | int | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>columns`` | array | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>name`` | string | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>values`` | array | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>>time`` | string | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+ |``>>value`` | float | |
+ +----------------------------+---------------+-----------------------------------------------------------------------------------------+
+
+.. code-block:: json
+ :caption: Response Example
+
+ { "response": {
+ "source": "TrafficStats",
+ "summary": {
+ "average": 1081172.785,
+ "count": 28,
+ "fifthPercentile": 888827.26,
+ "max": 1326680.31,
+ "min": 888827.26,
+ "ninetyEighthPercentile": 1324785.47,
+ "ninetyFifthPercentile": 1324785.47,
+ "totalBytes": 37841047.475,
+ "totalTransactions": 1020202030101
+ },
+ "series": {
+ "columns": [
+ "time",
+ ""
+ ],
+ "count": 60,
+ "name": "kbps",
+ "tags": {
+ "cachegroup": "total"
+ },
+ "values": [
+ [
+ "2015-08-11T11:36:00Z",
+ 888827.26
+ ],
+ [
+ "2015-08-11T11:37:00Z",
+ 980336.563333333
+ ],
+ [
+ "2015-08-11T11:38:00Z",
+ 952111.975
+ ],
+ [
+ "2015-08-11T11:39:00Z",
+ null
+ ],
+ [
+ "2015-08-11T11:43:00Z",
+ null
+ ],
+ [
+ "2015-08-11T11:44:00Z",
+ 934682.943333333
+ ],
+ [
+ "2015-08-11T11:45:00Z",
+ 1251121.28
+ ],
+ [
+ "2015-08-11T11:46:00Z",
+ 1111012.99
+ ]
+ ]
+ }}}
diff --git a/docs/source/api/deliveryservice_user.rst b/docs/source/api/deliveryservice_user.rst
new file mode 100644
index 0000000..bfa908a
--- /dev/null
+++ b/docs/source/api/deliveryservice_user.rst
@@ -0,0 +1,83 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-deliveryservice_user:
+
+************************
+``deliveryservice_user``
+************************
+
+``POST``
+========
+Assigns one or more Delivery Services to a user.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+:userId: An integral, unique identifier for the user to whom the Delivery Service(s) identified in ``deliveryServices`` will be assigned
+:deliveryServices: An array of integral, unique identifiers for the Delivery Service(s) being assigned to the user identified by ``userId``
+:replace: An optional field which, when present and ``true`` will replace existing user/ds assignments? (true|false)
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.4/deliveryservice_user HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 38
+ Content-Type: application/json
+
+ {"userId": 5, "deliveryServices": [1]}
+
+Response Structure
+------------------
+:userId: The integral, unique identifier of the user to whom the Delivery Service(s) identified in ``deliveryServices`` are assigned
+:deliveryServices: An array of integral, unique identifiers of Delivery Services assigned to the user identified by ``userId``
+:replace: If ``true``, any and all existing, conflicting Delivery Service assignments were overwritten by this assignment operation
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 21:37:30 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 15 Nov 2018 01:37:30 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: Uwl+924m6Ye3NraFP+RBpldkhcNTTDyXHZbzRaYV95p9tP56Z61gckeKSr1oQIkNXjXcCsDN5Dmum7Zk1AR6Hw==
+ Content-Length: 127
+
+ { "alerts": [
+ {
+ "level": "success",
+ "text": "Delivery service assignments complete."
+ }
+ ],
+ "response": {
+ "userId": 5,
+ "deliveryServices": [
+ 1
+ ]
+ }}
diff --git a/docs/source/api/deliveryservice_user_dsid_userid.rst b/docs/source/api/deliveryservice_user_dsid_userid.rst
new file mode 100644
index 0000000..0fbec63
--- /dev/null
+++ b/docs/source/api/deliveryservice_user_dsid_userid.rst
@@ -0,0 +1,66 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-deliveryservice_user-dsid-userid:
+
+********************************************
+``deliveryservice_user/{{dsID}}/{{userID}}``
+********************************************
+
+``DELETE``
+==========
+Removes a Delivery Service from a user.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: ``undefined``
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +--------+---------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +========+=================================================================================================================================+
+ | dsId | An integral, unique identifier for the Delivery Service which should no longer be assigned to the user identified by ``userID`` |
+ +--------+---------------------------------------------------------------------------------------------------------------------------------+
+ | userId | An integral, unique identifier for the user to whom the Delivery Service identified by ``dsID`` should no longer be assigned |
+ +--------+---------------------------------------------------------------------------------------------------------------------------------+
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Wed, 14 Nov 2018 21:40:06 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 15 Nov 2018 01:40:06 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: /eNE3LhFABGukcczjxJOYiwmfVTUUKII9RRuZi14AbF65BLhHdXZ5lAVEi4Hc65+ojNaijBgI9jTmgO4XCcP/A==
+ Content-Length: 100
+
+ { "alerts": [
+ {
+ "level": "success",
+ "text": "User [ test ] unlinked from deliveryservice [ 1 | demo1 ]."
+ }
+ ]}
diff --git a/docs/source/api/deliveryservices.rst b/docs/source/api/deliveryservices.rst
new file mode 100644
index 0000000..e1bb0f9
--- /dev/null
+++ b/docs/source/api/deliveryservices.rst
@@ -0,0 +1,685 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-deliveryservices:
+
+********************
+``deliveryservices``
+********************
+
+``GET``
+=======
+Retrieves all Delivery Services
+
+:Auth. Required: Yes
+:Roles Required: None\ [1]_
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +=============+==========+============================================================================================================================+
+ | cdn | no | Show only the Delivery Services belonging to the CDN identified by this integral, unique identifier |
+ +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+ | id | no | Show only the Delivery Service that has this integral, unique identifier |
+ +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+ | logsEnabled | no | If true, return only Delivery Services with logging enabled, otherwise return only Delivery Services with logging disabled |
+ +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+ | profile | no | Return only Delivery Services using the profile identified by this integral, unique identifier |
+ +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+ | tenant | no | Show only the Delivery Services belonging to the tenant identified by this integral, unique identifier |
+ +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+ | type | no | Return only Delivery Services of the Delivery Service type identified by this integral, unique identifier |
+ +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+
+Response Structure
+------------------
+:active: ``true`` if the Delivery Service is active, ``false`` otherwise
+:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the Delivery Service, ``false`` otherwise
+:cacheurl: A setting for a deprecated feature of now-unsupported Trafficserver versions
+:ccrDnsTtl: The Time To Live (TTL) of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
+:cdnId: The integral, unique identifier of the CDN to which the Delivery Service belongs
+:cdnName: Name of the CDN to which the Delivery Service belongs
+:checkPath: The path portion of the URL to check connections to this Delivery Service's origin server
+:displayName: The display name of the Delivery Service
+:dnsBypassCname: Domain name to overflow requests for HTTP Delivery Services - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
+:dnsBypassIp: The IPv4 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
+:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
+:dnsBypassTtl: The time for which a DNS bypass of this Delivery Service shall remain active\ [4]_
+:dscp: The Differentiated Services Code Point (DSCP) with which to mark traffic as it leaves the CDN and reaches clients
+:edgeHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
+:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the Delivery Service (see ``man tc-fc_codel`` for more information) - Linux only
+:geoLimit: The setting that determines how content is geographically limited - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ None - no limitations
+ 1
+ Only route when the client's IP is found in the Coverage Zone File (CZF)
+ 2
+ Only route when the client's IP is found in the CZF, or when the client can be determined to be from the United States of America
+
+ .. warning:: This does not prevent access to content or make content secure; it merely prevents routing to the content through Traffic Router
+
+:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this Delivery Service
+:geoLimitRedirectUrl: A URL to which clients blocked by :ref:`Regional Geographic Blocking <regionalgeo-qht>` or the ``geoLimit`` settings will be re-directed
+:geoProvider: An integer that represents the provider of a database for mapping IPs to geographic locations; currently only the following values are supported:
+
+ 0
+ The "Maxmind" GeoIP2 database (default)
+ 1
+ Neustar
+
+:globalMaxMbps: The maximum global bandwidth allowed on this Delivery Service. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS Delivery Services and to ``httpBypassFqdn`` for HTTP Delivery Services
+:globalMaxTps: The maximum global transactions per second allowed on this Delivery Service. When this is exceeded traffic will be sent to the ``dnsBypassIp`` (and/or ``dnsBypassIp6``) for DNS Delivery Services and to the httpBypassFqdn for HTTP Delivery Services
+:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
+:id: An integral, unique identifier for this Delivery Service
+:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
+:initialDispersion: The number of caches between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1\ [2]_
+:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection\ [2]_
+:lastUpdated: The date and time at which this Delivery Service was last updated, in a ``ctime``-like format
+:logsEnabled: If ``true``, logging is enabled for this Delivery Service, otherwise it is disabled
+:longDesc: A description of the Delivery Service
+:longDesc1: A field used when more detailed information that that provided by ``longDesc`` is desired
+:longDesc2: A field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
+:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this Delivery Service
+
+ :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped)
+ :setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs
+ :type: The type of match performed using ``pattern`` to determine whether or not to use this Delivery Service
+
+ HOST_REGEXP
+ Use the Delivery Service if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [2]_
+ HEADER_REGEXP
+ Use the Delivery Service if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [2]_
+ PATH_REGEXP
+ Use the Delivery Service if ``pattern`` matches the request path of this Delivery Service's URL
+ STEERING_REGEXP
+ Use the Delivery Service if ``pattern`` matches the ``xml_id`` of one of this Delivery Service's "Steering" target Delivery Services
+
+:maxDnsAnswers: The maximum number of IPs to put in responses to A/AAAA DNS record requests (0 means all available)\ [4]_
+:midHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
+:missLat: The latitude to use when the client cannot be found in the CZF or a geographic IP lookup
+:missLong: The longitude to use when the client cannot be found in the CZF or a geographic IP lookup
+:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this Delivery Service, ``false`` otherwise\ [3]_
+:orgServerFqdn: The URL of the Delivery Service's origin server for use in retrieving content from the origin server
+
+ .. note:: Despite the field name, this must truly be a full URL - including the protocol (e.g. ``http://`` or ``https://``) - **NOT** merely the server's Fully Qualified Domain Name (FQDN)
+
+:originShield: An "origin shield" is a forward proxy that sits between Mid-tier caches and the origin and performs further caching beyond what's offered by a standard CDN. This field is a string of FQDNs to use as origin shields, delimited by ``|``
+:profileDescription: The description of the Traffic Router Profile with which this Delivery Service is associated
+:profileId: The integral, unique identifier for the Traffic Router profile with which this Delivery Service is associated
+:profileName: The name of the Traffic Router Profile with which this Delivery Service is associated
+:protocol: The protocol which clients will use to communicate with Edge-tier cache servers\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ HTTP
+ 1
+ HTTPS
+ 2
+ Both HTTP and HTTPS
+
+:qstringIgnore: Tells caches whether or not to consider URLs with different query parameter strings to be distinct - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ URLs with different query parameter strings will be considered distinct for caching purposes, and query strings will be passed upstream to the origin
+ 1
+ URLs with different query parameter strings will be considered identical for caching purposes, and query strings will be passed upstream to the origin
+ 2
+ Query strings are stripped out by Edge-tier caches, and thus are neither taken into consideration for caching purposes, nor passed upstream in requests to the origin
+
+:rangeRequestHandling: Tells caches how to handle range requests\ [7]_ - this is an integer on the interval [0,2] where the values have these meanings:
+
+ 0
+ Range requests will not be cached, but range requests that request ranges of content already cached will be served from the cache
+ 1
+ Use the `background_fetch plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/background_fetch.en.html>`_ to service the range request while caching the whole object
+ 2
+ Use the `experimental cache_range_requests plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/cache_range_requests>`_ to treat unique ranges as unique objects
+
+:regexRemap: A regular expression remap rule to apply to this Delivery Service at the Edge tier
+
+ .. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
+
+:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this Delivery Service, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
+:remapText: Additional, raw text to add to the remap line for caches
+
+ .. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
+
+:signed: ``true`` if token-based authentication is enabled for this Delivery Service, ``false`` otherwise
+:signingAlgorithm: Type of URL signing method to sign the URLs, basically comes down to one of two plugins or ``null``:
+
+ ``null``
+ Token-based authentication is not enabled for this Delivery Service
+ url_sig:
+ URL Signing token-based authentication is enabled for this Delivery Service
+ uri_signing
+ URI Signing token-based authentication is enabled for this Delivery Service
+
+ .. seealso:: `The Apache Trafficserver documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/url_sig.en.html>`_ and `the draft RFC for uri_signing <https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16>`_ - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, **NOT** the latest
+
+:sslKeyVersion: This integer indicates the generation of keys in use by the Delivery Service - if any - and is incremented by the Traffic Portal client whenever new keys are generated
+
+ .. warning:: This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!
+
+:tenantId: The integral, unique identifier of the tenant who owns this Delivery Service
+:trRequestHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router access logs for requests - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
+:trResponseHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router responses - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
+:type: The name of the routing type of this Delivery Service e.g. "HTTP"
+:typeId: The integral, unique identifier of the routing type of this Delivery Service
+:xmlId: A unique string that describes this Delivery Service - exists for legacy reasons
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: mCLMjvACRKHNGP/OSx4javkOtxxzyiDdQzsV78IamUhVmvyKyKaCeOKRmpsG69w+nhh3OkPZ6e9MMeJpcJSKcA==
+ X-Server-Name: traffic_ops_golang/
+ Date: Thu, 15 Nov 2018 19:04:29 GMT
+ Transfer-Encoding: chunked
+
+ { "response": [
+ {
+ "active": true,
+ "anonymousBlockingEnabled": false,
+ "cacheurl": null,
+ "ccrDnsTtl": null,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "checkPath": null,
+ "displayName": "Demo 1",
+ "dnsBypassCname": null,
+ "dnsBypassIp": null,
+ "dnsBypassIp6": null,
+ "dnsBypassTtl": null,
+ "dscp": 0,
+ "edgeHeaderRewrite": null,
+ "geoLimit": 0,
+ "geoLimitCountries": null,
+ "geoLimitRedirectURL": null,
+ "geoProvider": 0,
+ "globalMaxMbps": null,
+ "globalMaxTps": null,
+ "httpBypassFqdn": null,
+ "id": 1,
+ "infoUrl": null,
+ "initialDispersion": 1,
+ "ipv6RoutingEnabled": true,
+ "lastUpdated": "2018-11-14 18:21:17+00",
+ "logsEnabled": true,
+ "longDesc": "Apachecon North America 2018",
+ "longDesc1": null,
+ "longDesc2": null,
+ "matchList": [
+ {
+ "type": "HOST_REGEXP",
+ "setNumber": 0,
+ "pattern": ".*\\.demo1\\..*"
+ }
+ ],
+ "maxDnsAnswers": null,
+ "midHeaderRewrite": null,
+ "missLat": 42,
+ "missLong": -88,
+ "multiSiteOrigin": false,
+ "originShield": null,
+ "orgServerFqdn": "http://origin.infra.ciab.test",
+ "profileDescription": null,
+ "profileId": null,
+ "profileName": null,
+ "protocol": 0,
+ "qstringIgnore": 0,
+ "rangeRequestHandling": 0,
+ "regexRemap": null,
+ "regionalGeoBlocking": false,
+ "remapText": null,
+ "routingName": "video",
+ "signed": false,
+ "sslKeyVersion": null,
+ "tenantId": 1,
+ "type": "HTTP",
+ "typeId": 1,
+ "xmlId": "demo1",
+ "exampleURLs": [
+ "http://video.demo1.mycdn.ciab.test"
+ ],
+ "deepCachingType": "NEVER",
+ "signingAlgorithm": null,
+ "tenant": "root"
+ }]}
+
+.. [1] Users with the roles "admin" and/or "operations" will be able to see *all* Delivery Services, whereas any other user will only see the Delivery Services their Tenant is allowed to see.
+.. [2] This only applies to HTTP-routed Delivery Services
+.. [3] See :ref:`multi-site-origin`
+.. [4] This only applies to DNS-routed Delivery Services
+
+``POST``
+========
+Allows users to create Delivery Service.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Array
+
+Request Structure
+-----------------
+:active: If ``true``, the Delivery Service will immediately become active and serves traffic
+:anonymousBlockingEnabled: An optional field which, if defined and ``true`` will cause :ref:`Anonymous Blocking <anonymous_blocking-qht>` to be used with the new Delivery Service
+:cacheurl: An optional setting for a deprecated feature of now-unsupported Trafficserver versions (read: "Don't use this")
+:ccrDnsTtl: The Time To Live (TTL) in seconds of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
+:cdnId: The integral, unique identifier for the CDN to which this Delivery Service shall be assigned
+:checkPath: The path portion of the URL which will be used to check connections to this Delivery Service's origin server
+:deepCachingType: A string describing when to do Deep Caching for this Delivery Service:
+
+ NEVER
+ Deep Caching will never be used by this Delivery Service (default)
+ ALWAYS
+ Deep Caching will always be used by this Delivery Service
+
+:displayName: The human-friendly name for this Delivery Service
+:dnsBypassCname: Domain name to overflow requests for HTTP Delivery Services - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
+:dnsBypassIp: The IPv4 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
+:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
+:dnsBypassTtl: The time for which a DNS bypass of this Delivery Service shall remain active
+:dscp: The Differentiated Services Code Point (DSCP) with which to mark downstream (EDGE -> customer) traffic. This should be zero in most cases
+:edgeHeaderRewrite: An optional string which, if present, defines rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
+:fqPacingRate: An optional integer which, if present, sets the Fair-Queuing Pacing Rate in bytes per second set on the all TCP connection sockets in the Delivery Service (see ``man tc-fc_codel`` for more information) - Linux only, defaults to 0 meaning "disabled"
+:geoLimit: The setting that determines how content is geographically limited - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ None - no limitations
+ 1
+ Only route when the client's IP is found in the Coverage Zone File (CZF)
+ 2
+ Only route when the client's IP is found in the CZF, or when the client can be determined to be from the United States of America
+
+ .. warning:: This does not prevent access to content or make content secure; it merely prevents routing to the content through Traffic Router
+
+:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this Delivery Service\ [5]_
+:geoLimitRedirectUrl: A URL to which clients blocked by :ref:`Regional Geographic Blocking <regionalgeo-qht>` or the ``geoLimit`` settings will be re-directed\ [5]_
+:geoProvider: An integer that represents the provider of a database for mapping IPs to geographic locations; currently only the following values are supported:
+
+ 0
+ The "Maxmind" GeoIP2 database (default)
+ 1
+ Neustar
+
+:globalMaxMbps: An optional integer that will set the maximum global bandwidth allowed on this Delivery Service. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS Delivery Services and to ``httpBypassFqdn`` for HTTP Delivery Services
+:globalMaxTps: An optional integer that will set the maximum global transactions per second allowed on this Delivery Service. When this is exceeded traffic will be sent to the ``dnsBpassIp`` (and/or ``dnsBypassIp6``)for DNS Delivery Services and to the ``httpBypassFqdn`` for HTTP Delivery Services
+:httpBypassFqdn: An optional Fully Qualified Domain Name (FQDN) to use for bypass on an HTTP Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [2]_
+:infoUrl: An optional string which, if present, is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
+:initialDispersion: The number of caches between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1\ [2]_\ [6]_
+:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection - optional for ANY_MAP Delivery Services
+:logsEnabled: If ``true``, logging is enabled for this Delivery Service, otherwise it is disabled
+:longDesc: An optional description of the Delivery Service
+:longDesc1: An optional field used when more detailed information that that provided by ``longDesc`` is desired
+:longDesc2: An optional field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
+:maxDnsAnswers: An optional field which, when present, specifies the maximum number of IPs to put in responses to A/AAAA DNS record requests - defaults to 0, meaning "no limit"\ [4]_
+:midHeaderRewrite: An optional string containing rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
+:missLat: The latitude to use when the client cannot be found in the CZF or a geographic IP lookup\ [7]_
+:missLong: The longitude to use when the client cannot be found in the CZF or a geographic IP lookup\ [7]_
+:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this Delivery Service, ``false`` otherwise\ [3]_\ [7]_
+:orgServerFqdn: The URL of the Delivery Service's origin server for use in retrieving content from the origin server\ [7]_
+
+ .. note:: Despite the field name, this must truly be a full URL - including the protocol (e.g. ``http://`` or ``https://``) - **NOT** merely the server's Fully Qualified Domain Name (FQDN)
+
+:originShield: An "origin shield" is a forward proxy that sits between Mid-tier caches and the origin and performs further caching beyond what's offered by a standard CDN. This optional field is a string of FQDNs to use as origin shields, delimited by ``|``
+:profileId: An optional, integral, unique identifier for the Traffic Router profile with which this Delivery Service shall be associated
+:protocol: The protocol which clients will use to communicate with Edge-tier cache servers - this is an (optional for ANY_MAP Delivery Services) integer on the interval [0,2] where the values have these meanings:
+
+ 0
+ HTTP
+ 1
+ HTTPS
+ 2
+ Both HTTP and HTTPS
+
+:qstringIgnore: Tells caches whether or not to consider URLs with different query parameter strings to be distinct\ [7]_ - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ URLs with different query parameter strings will be considered distinct for caching purposes, and query strings will be passed upstream to the origin
+ 1
+ URLs with different query parameter strings will be considered identical for caching purposes, and query strings will be passed upstream to the origin
+ 2
+ Query strings are stripped out by Edge-tier caches, and thus are neither taken into consideration for caching purposes, nor passed upstream in requests to the origin
+
+:rangeRequestHandling: Tells caches how to handle range requests\ [7]_ - this is an integer on the interval [0,2] where the values have these meanings:
+
+ 0
+ Range requests will not be cached, but range requests that request ranges of content already cached will be served from the cache
+ 1
+ Use the `background_fetch plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/background_fetch.en.html>`_ to service the range request while caching the whole object
+ 2
+ Use the `experimental cache_range_requests plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/cache_range_requests>`_ to treat unique ranges as unique objects
+
+:regexRemap: An optional, regular expression remap rule to apply to this Delivery Service at the Edge tier
+
+ .. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
+
+:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this Delivery Service, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
+:remapText: Optional, raw text to add to the remap line for caches
+
+ .. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
+
+:routingName: The routing name of this Delivery Service, used as the top-level part of the FQDN used by clients to request content from the Delivery Service e.g. ``routingName.xml_id.CDNName.com``
+:signed: An optional field which should be ``true`` if token-based authentication will be enabled for this Delivery Service, ``false`` (default) otherwise
+:signingAlgorithm: Type of URL signing method to sign the URLs, basically comes down to one of two plugins or ``null``:
+
+ ``null``
+ Token-based authentication is not enabled for this Delivery Service
+ url_sig:
+ URL Signing token-based authentication is enabled for this Delivery Service
+ uri_signing
+ URI Signing token-based authentication is enabled for this Delivery Service
+
+ .. seealso:: `The Apache Trafficserver documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/url_sig.en.html>`_ and `the draft RFC for uri_signing <https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16>`_ - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, **NOT** the latest
+
+:sslKeyVersion: This optional integer indicates the generation of keys to be used by the Delivery Service - if any - and is incremented by the Traffic Portal client whenever new keys are generated
+
+ .. warning:: This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!
+
+:tenantId: An optional, integral, unique identifier of the tenant who will own this Delivery Service
+:trRequestHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router access logs for requests - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
+:trResponseHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router responses - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
+:typeId: The integral, unique identifier for the routing type of this Delivery Service
+:xmlId: A unique string that describes this Delivery Service - exists for legacy reasons
+
+ .. note:: This should almost never be different from the Delivery Service's ``displayName``
+
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.4/deliveryservices HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 761
+ Content-Type: application/json
+
+ {
+ "active": false,
+ "anonymousBlockingEnabled": false,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "deepCachingType": "NEVER",
+ "displayName": "test",
+ "exampleURLs": [
+ "http://test.test.mycdn.ciab.test"
+ ],
+ "dscp": 0,
+ "geoLimit": 0,
+ "geoProvider": 0,
+ "initialDispersion": 1,
+ "ipv6RoutingEnabled": false,
+ "lastUpdated": "2018-11-14 18:21:17+00",
+ "logsEnabled": true,
+ "longDesc": "A Delivery Service created expressly for API documentation examples",
+ "missLat": -1,
+ "missLong": -1,
+ "multiSiteOrigin": false,
+ "orgServerFqdn": "http://origin.infra.ciab.test",
+ "protocol": 0,
+ "qstringIgnore": 0,
+ "rangeRequestHandling": 0,
+ "regionalGeoBlocking": false,
+ "routingName": "test",
+ "signed": false,
+ "tenant": "root",
+ "tenantId": 1,
+ "typeId": 1,
+ "xmlId": "test"
+ }
+
+.. [5] These fields must be defined if and only if ``geoLimit`` is non-zero
+.. [6] These fields are required for HTTP-routed Delivery Services, and optional for all others
+.. [7] These fields are required for HTTP-routed and DNS-routed Delivery Services, but are optional for (and in fact may have no effect on) STEERING and ANY_MAP Delivery Services
+
+Response Structure
+------------------
+:active: ``true`` if the Delivery Service is active, ``false`` otherwise
+:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the Delivery Service, ``false`` otherwise
+:cacheurl: A setting for a deprecated feature of now-unsupported Trafficserver versions
+:ccrDnsTtl: The Time To Live (TTL) of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
+:cdnId: The integral, unique identifier of the CDN to which the Delivery Service belongs
+:cdnName: Name of the CDN to which the Delivery Service belongs
+:checkPath: The path portion of the URL to check connections to this Delivery Service's origin server
+:displayName: The display name of the Delivery Service
+:dnsBypassCname: Domain name to overflow requests for HTTP Delivery Services - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
+:dnsBypassIp: The IPv4 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
+:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
+:dnsBypassTtl: The time for which a DNS bypass of this Delivery Service shall remain active\ [4]_
+:dscp: The Differentiated Services Code Point (DSCP) with which to mark traffic as it leaves the CDN and reaches clients
+:edgeHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
+:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the Delivery Service (see ``man tc-fc_codel`` for more information) - Linux only
+:geoLimit: The setting that determines how content is geographically limited - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ None - no limitations
+ 1
+ Only route when the client's IP is found in the Coverage Zone File (CZF)
+ 2
+ Only route when the client's IP is found in the CZF, or when the client can be determined to be from the United States of America
+
+ .. warning:: This does not prevent access to content or make content secure; it merely prevents routing to the content through Traffic Router
+
+:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this Delivery Service
+:geoLimitRedirectUrl: A URL to which clients blocked by :ref:`Regional Geographic Blocking <regionalgeo-qht>` or the ``geoLimit`` settings will be re-directed
+:geoProvider: An integer that represents the provider of a database for mapping IPs to geographic locations; currently only the following values are supported:
+
+ 0
+ The "Maxmind" GeoIP2 database (default)
+ 1
+ Neustar
+
+:globalMaxMbps: The maximum global bandwidth allowed on this Delivery Service. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS Delivery Services and to ``httpBypassFqdn`` for HTTP Delivery Services
+:globalMaxTps: The maximum global transactions per second allowed on this Delivery Service. When this is exceeded traffic will be sent to the ``dnsBypassIp`` (and/or ``dnsBypassIp6``) for DNS Delivery Services and to the httpBypassFqdn for HTTP Delivery Services
+:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
+:id: An integral, unique identifier for this Delivery Service
+:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
+:initialDispersion: The number of caches between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1\ [2]_
+:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection\ [2]_
+:lastUpdated: The date and time at which this Delivery Service was last updated, in a ``ctime``-like format
+:logsEnabled: If ``true``, logging is enabled for this Delivery Service, otherwise it is disabled
+:longDesc: A description of the Delivery Service
+:longDesc1: A field used when more detailed information that that provided by ``longDesc`` is desired
+:longDesc2: A field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
+:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this Delivery Service
+
+ :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped)
+ :setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs
+ :type: The type of match performed using ``pattern`` to determine whether or not to use this Delivery Service
+
+ HOST_REGEXP
+ Use the Delivery Service if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [2]_
+ HEADER_REGEXP
+ Use the Delivery Service if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [2]_
+ PATH_REGEXP
+ Use the Delivery Service if ``pattern`` matches the request path of this Delivery Service's URL
+ STEERING_REGEXP
+ Use the Delivery Service if ``pattern`` matches the ``xml_id`` of one of this Delivery Service's "Steering" target Delivery Services
+
+:maxDnsAnswers: The maximum number of IPs to put in responses to A/AAAA DNS record requests (0 means all available)\ [4]_
+:midHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
+:missLat: The latitude to use when the client cannot be found in the CZF or a geographic IP lookup
+:missLong: The longitude to use when the client cannot be found in the CZF or a geographic IP lookup
+:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this Delivery Service, ``false`` otherwise\ [3]_
+:orgServerFqdn: The URL of the Delivery Service's origin server for use in retrieving content from the origin server
+
+ .. note:: Despite the field name, this must truly be a full URL - including the protocol (e.g. ``http://`` or ``https://``) - **NOT** merely the server's Fully Qualified Domain Name (FQDN)
+
+:originShield: An "origin shield" is a forward proxy that sits between Mid-tier caches and the origin and performs further caching beyond what's offered by a standard CDN. This field is a string of FQDNs to use as origin shields, delimited by ``|``
+:profileDescription: The description of the Traffic Router Profile with which this Delivery Service is associated
+:profileId: The integral, unique identifier for the Traffic Router profile with which this Delivery Service is associated
+:profileName: The name of the Traffic Router Profile with which this Delivery Service is associated
+:protocol: The protocol which clients will use to communicate with Edge-tier cache servers\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ HTTP
+ 1
+ HTTPS
+ 2
+ Both HTTP and HTTPS
+
+:qstringIgnore: Tells caches whether or not to consider URLs with different query parameter strings to be distinct - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ URLs with different query parameter strings will be considered distinct for caching purposes, and query strings will be passed upstream to the origin
+ 1
+ URLs with different query parameter strings will be considered identical for caching purposes, and query strings will be passed upstream to the origin
+ 2
+ Query strings are stripped out by Edge-tier caches, and thus are neither taken into consideration for caching purposes, nor passed upstream in requests to the origin
+
+:rangeRequestHandling: Tells caches how to handle range requests\ [7]_ - this is an integer on the interval [0,2] where the values have these meanings:
+
+ 0
+ Range requests will not be cached, but range requests that request ranges of content already cached will be served from the cache
+ 1
+ Use the `background_fetch plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/background_fetch.en.html>`_ to service the range request while caching the whole object
+ 2
+ Use the `experimental cache_range_requests plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/cache_range_requests>`_ to treat unique ranges as unique objects
+
+:regexRemap: A regular expression remap rule to apply to this Delivery Service at the Edge tier
+
+ .. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
+
+:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this Delivery Service, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
+:remapText: Additional, raw text to add to the remap line for caches
+
+ .. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
+
+:signed: ``true`` if token-based authentication is enabled for this Delivery Service, ``false`` otherwise
+:signingAlgorithm: Type of URL signing method to sign the URLs, basically comes down to one of two plugins or ``null``:
+
+ ``null``
+ Token-based authentication is not enabled for this Delivery Service
+ url_sig:
+ URL Signing token-based authentication is enabled for this Delivery Service
+ uri_signing
+ URI Signing token-based authentication is enabled for this Delivery Service
+
+ .. seealso:: `The Apache Trafficserver documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/url_sig.en.html>`_ and `the draft RFC for uri_signing <https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16>`_ - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, **NOT** the latest
+
+:sslKeyVersion: This integer indicates the generation of keys in use by the Delivery Service - if any - and is incremented by the Traffic Portal client whenever new keys are generated
+
+ .. warning:: This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!
+
+:tenantId: The integral, unique identifier of the tenant who owns this Delivery Service
+:trRequestHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router access logs for requests - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
+:trResponseHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router responses - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
+:type: The name of the routing type of this Delivery Service e.g. "HTTP"
+:typeId: The integral, unique identifier of the routing type of this Delivery Service
+:xmlId: A unique string that describes this Delivery Service - exists for legacy reasons
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: SVveQ5hGwfPv8N5APUskwLOzwrTUVA+z8wuFLsSLCr1/vVnFJJ0VQOGMUctg1NbqhAuQ795MJmuuAaAwR8dSOQ==
+ X-Server-Name: traffic_ops_golang/
+ Date: Mon, 19 Nov 2018 19:45:49 GMT
+ Content-Length: 1404
+
+ { "alerts": [
+ {
+ "text": "Deliveryservice creation was successful.",
+ "level": "success"
+ }
+ ],
+ "response": [
+ {
+ "active": false,
+ "anonymousBlockingEnabled": false,
+ "cacheurl": null,
+ "ccrDnsTtl": null,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "checkPath": null,
+ "displayName": "test",
+ "dnsBypassCname": null,
+ "dnsBypassIp": null,
+ "dnsBypassIp6": null,
+ "dnsBypassTtl": null,
+ "dscp": 0,
+ "edgeHeaderRewrite": null,
+ "geoLimit": 0,
+ "geoLimitCountries": null,
+ "geoLimitRedirectURL": null,
+ "geoProvider": 0,
+ "globalMaxMbps": null,
+ "globalMaxTps": null,
+ "httpBypassFqdn": null,
+ "id": 2,
+ "infoUrl": null,
+ "initialDispersion": 1,
+ "ipv6RoutingEnabled": false,
+ "lastUpdated": "2018-11-19 19:45:49+00",
+ "logsEnabled": true,
+ "longDesc": "A Delivery Service created expressly for API documentation examples",
+ "longDesc1": null,
+ "longDesc2": null,
+ "matchList": [
+ {
+ "type": "HOST_REGEXP",
+ "setNumber": 0,
+ "pattern": ".*\\.test\\..*"
+ }
+ ],
+ "maxDnsAnswers": null,
+ "midHeaderRewrite": null,
+ "missLat": -1,
+ "missLong": -1,
+ "multiSiteOrigin": false,
+ "originShield": null,
+ "orgServerFqdn": "http://origin.infra.ciab.test",
+ "profileDescription": null,
+ "profileId": null,
+ "profileName": null,
+ "protocol": 0,
+ "qstringIgnore": 0,
+ "rangeRequestHandling": 0,
+ "regexRemap": null,
+ "regionalGeoBlocking": false,
+ "remapText": null,
+ "routingName": "test",
+ "signed": false,
+ "sslKeyVersion": null,
+ "tenantId": 1,
+ "type": "HTTP",
+ "typeId": 1,
+ "xmlId": "test",
+ "exampleURLs": [
+ "http://test.test.mycdn.ciab.test"
+ ],
+ "deepCachingType": "NEVER",
+ "signingAlgorithm": null,
+ "tenant": "root"
+ }
+ ]}
diff --git a/docs/source/api/deliveryservices_dnsseckeys_generate.rst b/docs/source/api/deliveryservices_dnsseckeys_generate.rst
new file mode 100644
index 0000000..797cf3e
--- /dev/null
+++ b/docs/source/api/deliveryservices_dnsseckeys_generate.rst
@@ -0,0 +1,50 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-deliveryservices-dnsseckeys-generate:
+
+****************************************
+``deliveryservices/dnsseckeys/generate``
+****************************************
+
+``POST``
+========
+Generates Zone-Signing Key (ZSK) and Key-Signing Key (KSK) keypairs for a CDN and all associated Delivery Services.
+
+:Auth. Required: Yes
+:Roles Required: "admin"
+:Response Type: Object (string)
+
+Request Structure
+-----------------
+:key: Name of the CDN
+:name: Domain name used by the CDN
+:ttl: Time for which the keypairs shall remain valid
+:kskExpirationDays: Expiration (in days) for the KSKs
+:zskExpirationDays: Expiration (in days) for the ZSKs
+:effectiveDate: UNIX epoch start date for the signing keys
+
+.. versionchanged:: 1.2
+ Added required 'effectiveDate' field to request
+
+Response Structure
+------------------
+.. code-block:: json
+ :caption: Response Example
+
+ {
+ "response": "Successfully created dnssec keys for cdn1"
+ }
+
diff --git a/docs/source/api/deliveryservices_hostname_name_sslkeys.rst b/docs/source/api/deliveryservices_hostname_name_sslkeys.rst
new file mode 100644
index 0000000..4c48b88
--- /dev/null
+++ b/docs/source/api/deliveryservices_hostname_name_sslkeys.rst
@@ -0,0 +1,89 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-deliveryservices-hostname-name-sslkeys:
+
+**********************************************
+``deliveryservices/hostname/{{name}}/sslkeys``
+**********************************************
+
+``GET``
+=======
+:Auth. Required: Yes
+:Roles Required: "admin"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+----------------------------------------------+
+ | Name | Description |
+ +======+==============================================+
+ | name | The hostname of the desired Delivery Service |
+ +------+----------------------------------------------+
+
+.. table:: Request Query Parameters
+
+ +---------+----------+---------------------------------------------------------+
+ | Name | Required | Description |
+ +=========+==========+=========================================================+
+ | version | no | The version number of SSL keys which shall be retrieved |
+ +---------+----------+---------------------------------------------------------+
+
+Response Structure
+------------------
+:businessUnit: An optional field which, if present, contains the business unit entered by the user when generating the SSL certificate\ [1]_
+:certificate: An object containing the actual generated key, certificate, and signature of the SSL keys
+
+ :crt: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) certificate for the Delivery Service identified by ``deliveryservice``
+ :csr: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) csr file for the Delivery Service identified by ``deliveryservice``
+ :key: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) private key for the Delivery Service identified by ``deliveryservice``
+
+ .. caution:: There's almost certainly no good reason to request the private key! Even when "base 64-encoded" do not let **ANYONE** see this who would be unable to request it themselves!
+
+:cdn: The CDN of the Delivery Service for which the certs were generated
+:city: An optional field which, if present, contains the city entered by the user when generating the SSL certificate\ [1]_
+:country: An optional field which, if present, contains the country entered by the user when generating the SSL certificate\ [1]_
+:deliveryservice: The 'xml_id' of the Delivery Service for which the certificate was generated
+:hostname: The hostname generated by Traffic Ops that is used as the common name when generating the certificate - this will be a Fully Qualified Domain Name (FQDN) for DNS Delivery Services and a wildcard URL for HTTP Delivery Services
+:organization: An optional field which, if present, contains the organization entered by the user when generating certificate\ [1]_
+:state: An optional field which, if present, contains the state entered by the user when generating certificate\ [1]_
+:version: The version of the certificate record in Riak
+
+.. code- block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ { "response": {
+ "certificate": {
+ "crt": "crt",
+ "key": "key",
+ "csr": "csr"
+ },
+ "deliveryservice": "my-ds",
+ "cdn": "qa",
+ "businessUnit": "CDN_Eng",
+ "city": "Denver",
+ "organization": "KableTown",
+ "hostname": "foober.com",
+ "country": "US",
+ "state": "Colorado",
+ "version": "1"
+ }}
+
+.. [1] These optional fields will be present in the response if and only if they were specified during key generation; they are optional during key generation and thus cannot be guaranteed to exist or not exist.
diff --git a/docs/source/api/deliveryservices_id.rst b/docs/source/api/deliveryservices_id.rst
new file mode 100644
index 0000000..c7635e4
--- /dev/null
+++ b/docs/source/api/deliveryservices_id.rst
@@ -0,0 +1,556 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-deliveryservices-id:
+
+***************************
+``deliveryservices/{{ID}}``
+***************************
+.. deprecated:: 1.1
+ Use the ``id`` query parameter of :ref:`to-api-deliveryservices` instead
+
+``GET``
+=======
+Retrieves a specific Delivery Service
+
+:Auth. Required: Yes
+:Roles Required: None\ [1]_
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +=============+==========+============================================================================================================================+
+ | cdn | no | Show only the Delivery Services belonging to the CDN identified by this integral, unique identifier |
+ +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+ | logsEnabled | no | If true, return only Delivery Services with logging enabled, otherwise return only Delivery Services with logging disabled |
+ +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+ | profile | no | Return only Delivery Services using the profile identified by this integral, unique identifier |
+ +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+ | tenant | no | Show only the Delivery Services belonging to the tenant identified by this integral, unique identifier |
+ +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+ | type | no | Return only Delivery Services of the Delivery Service type identified by this integral, unique identifier |
+ +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+
+.. table:: Request Path Parameters
+
+ +------+----------------------------------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+============================================================================================================================+
+ | ID | The integral, unique identifier of the Delivery Service to be retrieved |
+ +------+----------------------------------------------------------------------------------------------------------------------------+
+
+
+Response Structure
+------------------
+.. versionchanged:: 1.3
+ Removed ``fqPacingRate`` field, added fields: ``deepCachingType``, ``signingAlgorithm``, and ``tenant``.
+
+:active: ``true`` if the Delivery Service is active, ``false`` otherwise
+:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the Delivery Service, ``false`` otherwise
+:cacheurl: A setting for a deprecated feature of now-unsupported Trafficserver versions
+:ccrDnsTtl: The Time To Live (TTL) of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
+:cdnId: The integral, unique identifier of the CDN to which the Delivery Service belongs
+:cdnName: Name of the CDN to which the Delivery Service belongs
+:checkPath: The path portion of the URL to check connections to this Delivery Service's origin server
+:deepCachingType: A string that describes when "Deep Caching" will be used by this Delivery Service - one of:
+
+ ALWAYS
+ "Deep Caching" will always be used with this Delivery Service
+ NEVER
+ "Deep Caching" will never be used with this Delivery Service
+
+ .. versionadded:: 1.3
+
+:displayName: The display name of the Delivery Service
+:dnsBypassCname: Domain name to overflow requests for HTTP Delivery Services - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
+:dnsBypassIp: The IPv4 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
+:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
+:dnsBypassTtl: The time for which a DNS bypass of this Delivery Service shall remain active
+:dscp: The Differentiated Services Code Point (DSCP) with which to mark traffic as it leaves the CDN and reaches clients
+:edgeHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
+:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the Delivery Service (see ``man tc-fc_codel`` for more information) - Linux only
+
+ .. deprecated:: 1.3
+ This field is only present/available in API versions 1.2 and lower - it has been removed in API version 1.3
+
+:geoLimit: The setting that determines how content is geographically limited - this is an integer on the interval [0-2] where the values have these meanings:
+:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this Delivery Service
+:geoLimitRedirectUrl: A URL to which clients blocked by :ref:`Regional Geographic Blocking <regionalgeo-qht>` or the ``geoLimit`` settings will be re-directed
+
+ 0
+ None - no limitations
+ 1
+ Only route when the client's IP is found in the Coverage Zone File (CZF)
+ 2
+ Only route when the client's IP is found in the CZF, or when the client can be determined to be from the United States of America
+
+ .. warning:: This does not prevent access to content or make content secure; it merely prevents routing to the content through Traffic Router
+
+:geoProvider: An integer that represents the provider of a database for mapping IPs to geographic locations; currently only ``0`` - which represents MaxMind - is supported
+:globalMaxMbps: The maximum global bandwidth allowed on this Delivery Service. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS Delivery Services and to ``httpBypassFqdn`` for HTTP Delivery Services
+:globalMaxTps: The maximum global transactions per second allowed on this Delivery Service. When this is exceeded traffic will be sent to the dnsByPassIp* for DNS Delivery Services and to the httpBypassFqdn for HTTP Delivery Services
+:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
+:id: An integral, unique identifier for this Delivery Service
+:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
+:initialDispersion: The number of caches between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1
+:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection\ [2]_
+:lastUpdated: The date and time at which this Delivery Service was last updated, in a ``ctime``-like format
+:logsEnabled: If ``true``, logging is enabled for this Delivery Service, otherwise it is disabled
+:longDesc: A description of the Delivery Service
+:longDesc1: A field used when more detailed information that that provided by ``longDesc`` is desired
+:longDesc2: A field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
+:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this Delivery Service
+
+ :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped)
+ :setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs
+ :type: The type of match performed using ``pattern`` to determine whether or not to use this Delivery Service
+
+ HOST_REGEXP
+ Use the Delivery Service if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [2]_
+ HEADER_REGEXP
+ Use the Delivery Service if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [2]_
+ PATH_REGEXP
+ Use the Delivery Service if ``pattern`` matches the request path of this Delivery Service's URL
+ STEERING_REGEXP
+ Use the Delivery Service if ``pattern`` matches the ``xml_id`` of one of this Delivery Service's "Steering" target Delivery Services
+
+:maxDnsAnswers: The maximum number of IPs to put in a A/AAAA response for a DNS Delivery Service (0 means all available)
+:midHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
+:missLat: The latitude to use when the client cannot be found in the CZF or a geographic IP lookup
+:missLong: The longitude to use when the client cannot be found in the CZF or a geographic IP lookup
+:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this Delivery Service, ``false`` otherwise\ [3]_
+:originShield: An "origin shield" is a forward proxy that sits between Mid-tier caches and the origin and performs further caching beyond what's offered by a standard CDN. This field is a string of FQDNs to use as origin shields, delimited by ``|``
+:orgServerFqdn: The origin server's Fully Qualified Domain Name (FQDN) - including the protocol (e.g. http:// or https://) - for use in retrieving content from the origin server
+:profileDescription: The description of the Traffic Router Profile with which this Delivery Service is associated
+:profileId: The integral, unique identifier for the Traffic Router profile with which this Delivery Service is associated
+:profileName: The name of the Traffic Router Profile with which this Delivery Service is associated
+:protocol: The protocol which clients will use to communicate with Edge-tier cache servers\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ HTTP
+ 1
+ HTTPS
+ 2
+ Both HTTP and HTTPS
+
+:qstringIgnore: Tells caches whether or not to consider URLs with different query parameter strings to be distinct - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ URLs with different query parameter strings will be considered distinct for caching purposes, and query strings will be passed upstream to the origin
+ 1
+ URLs with different query parameter strings will be considered identical for caching purposes, and query strings will be passed upstream to the origin
+ 2
+ Query strings are stripped out by Edge-tier caches, and thus are neither taken into consideration for caching purposes, nor passed upstream in requests to the origin
+
+:rangeRequestHandling: Tells caches how to handle range requests\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ Range requests will not be cached, but range requests that request ranges of content already cached will be served from the cache
+ 1
+ Use the `background_fetch plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/background_fetch.en.html>`_ to service the range request while caching the whole object
+ 2
+ Use the `experimental cache_range_requests plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/cache_range_requests>`_ to treat unique ranges as unique objects
+
+:regexRemap: A regular expression remap rule to apply to this Delivery Service at the Edge tier
+
+ .. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
+
+:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this Delivery Service, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
+:remapText: Additional, raw text to add to the remap line for caches
+
+ .. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
+
+:signed: ``true`` if token-based authentication is enabled for this Delivery Service, ``false`` otherwise
+:signingAlgorithm: Type of URL signing method to sign the URLs, basically comes down to one of two plugins or ``null``:
+
+ ``null``
+ Token-based authentication is not enabled for this Delivery Service
+ url_sig:
+ URL Signing token-based authentication is enabled for this Delivery Service
+ uri_signing
+ URI Signing token-based authentication is enabled for this Delivery Service
+
+ .. seealso:: `The Apache Trafficserver documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/url_sig.en.html>`_ and `the draft RFC for uri_signing <https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16>`_ - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, NOT the latest.
+
+ .. versionadded:: 1.3
+
+:sslKeyVersion: This integer indicates the generation of keys in use by the Delivery Service - if any - and is incremented by the Traffic Portal client whenever new keys are generated
+
+ .. warning:: This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!
+
+:tenant: The name of the tenant who owns this Delivery Service
+
+ .. versionadded:: 1.3
+
+:tenantId: The integral, unique identifier of the tenant who owns this Delivery Service
+:trRequestHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router access logs for requests - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
+:trResponseHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router responses - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
+:type: The name of the routing type of this Delivery Service e.g. "HTTP"
+:typeId: The integral, unique identifier of the routing type of this Delivery Service
+:xmlId: A unique string that describes this Delivery Service - exists for legacy reasons
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: Mw4ZsiNKfnxZvN+LsfAzxIZjgGTzcBLcZK24mMdhN1XMRBtwEj9VI3ExNvWKv3dp0f3HRRCUTx6C+ST8bRL9jA==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 14 Nov 2018 21:43:36 GMT
+ Content-Length: 1290
+
+ { "response": [
+ {
+ "active": true,
+ "anonymousBlockingEnabled": false,
+ "cacheurl": null,
+ "ccrDnsTtl": null,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "checkPath": null,
+ "displayName": "Demo 1",
+ "dnsBypassCname": null,
+ "dnsBypassIp": null,
+ "dnsBypassIp6": null,
+ "dnsBypassTtl": null,
+ "dscp": 0,
+ "edgeHeaderRewrite": null,
+ "geoLimit": 0,
+ "geoLimitCountries": null,
+ "geoLimitRedirectURL": null,
+ "geoProvider": 0,
+ "globalMaxMbps": null,
+ "globalMaxTps": null,
+ "httpBypassFqdn": null,
+ "id": 1,
+ "infoUrl": null,
+ "initialDispersion": 1,
+ "ipv6RoutingEnabled": true,
+ "lastUpdated": "2018-11-14 18:21:17+00",
+ "logsEnabled": true,
+ "longDesc": "Apachecon North America 2018",
+ "longDesc1": null,
+ "longDesc2": null,
+ "matchList": [
+ {
+ "type": "HOST_REGEXP",
+ "setNumber": 0,
+ "pattern": ".*\\.demo1\\..*"
+ }
+ ],
+ "maxDnsAnswers": null,
+ "midHeaderRewrite": null,
+ "missLat": 42,
+ "missLong": -88,
+ "multiSiteOrigin": false,
+ "originShield": null,
+ "orgServerFqdn": "http://origin.infra.ciab.test",
+ "profileDescription": null,
+ "profileId": null,
+ "profileName": null,
+ "protocol": 0,
+ "qstringIgnore": 0,
+ "rangeRequestHandling": 0,
+ "regexRemap": null,
+ "regionalGeoBlocking": false,
+ "remapText": null,
+ "routingName": "video",
+ "signed": false,
+ "sslKeyVersion": null,
+ "tenantId": 1,
+ "type": "HTTP",
+ "typeId": 1,
+ "xmlId": "demo1",
+ "exampleURLs": [
+ "http://video.demo1.mycdn.ciab.test"
+ ],
+ "deepCachingType": "NEVER",
+ "signingAlgorithm": null,
+ "tenant": "root"
+ }
+ ]}
+
+
+.. [1] Users with the roles "admin" and/or "operation" will be able to see *all* Delivery Services, whereas any other user will only see the Delivery Services their Tenant is allowed to see.
+.. [2] This only applies to HTTP Delivery Services
+.. [3] See :ref:`multi-site-origin`
+.. [4] This only applies to DNS-routed Delivery Services
+
+``PUT``
+=======
+Allows users to edit an existing Delivery Service.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"\ [10]_
+:Response Type: **NOT PRESENT** - Despite returning a ``200 OK`` response (rather than e.g. a ``204 NO CONTENT`` response), this endpoint does **not** return a representation of the modified resource in its payload, and instead returns nothing - not even a success message.
+
+Request Structure
+-----------------
+:active: If ``true``, the Delivery Service will immediately become active and serves traffic
+:anonymousBlockingEnabled: An optional field which, if defined and ``true`` will cause :ref:`Anonymous Blocking <anonymous_blocking-qht>` to be used with the new Delivery Service
+:cacheurl: An optional setting for a deprecated feature of now-unsupported Trafficserver versions (read: "Don't use this")
+:ccrDnsTtl: The Time To Live (TTL) in seconds of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
+:cdnId: The integral, unique identifier for the CDN to which this Delivery Service shall be assigned
+:checkPath: The path portion of the URL which will be used to check connections to this Delivery Service's origin server
+:deepCachingType: A string describing when to do Deep Caching for this Delivery Service:
+
+ NEVER
+ Deep Caching will never be used by this Delivery Service (default)
+ ALWAYS
+ Deep Caching will always be used by this Delivery Service
+
+:displayName: The human-friendly name for this Delivery Service
+:dnsBypassCname: Domain name to overflow requests for HTTP Delivery Services - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
+:dnsBypassIp: The IPv4 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
+:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
+:dnsBypassTtl: The time for which a DNS bypass of this Delivery Service shall remain active
+:dscp: The Differentiated Services Code Point (DSCP) with which to mark downstream (EDGE -> customer) traffic. This should be zero in most cases
+:edgeHeaderRewrite: An optional string which, if present, defines rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
+:fqPacingRate: An optional integer which, if present, sets the Fair-Queuing Pacing Rate in bytes per second set on the all TCP connection sockets in the Delivery Service (see ``man tc-fc_codel`` for more information) - Linux only, defaults to 0 meaning "disabled"
+:geoLimit: The setting that determines how content is geographically limited - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ None - no limitations
+ 1
+ Only route when the client's IP is found in the Coverage Zone File (CZF)
+ 2
+ Only route when the client's IP is found in the CZF, or when the client can be determined to be from the United States of America
+
+ .. warning:: This does not prevent access to content or make content secure; it merely prevents routing to the content through Traffic Router
+
+:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this Delivery Service\ [5]_
+:geoLimitRedirectUrl: A URL to which clients blocked by :ref:`Regional Geographic Blocking <regionalgeo-qht>` or the ``geoLimit`` settings will be re-directed\ [5]_
+:geoProvider: An integer that represents the provider of a database for mapping IPs to geographic locations; currently only the following values are supported:
+
+ 0
+ The "Maxmind" GeoIP2 database (default)
+ 1
+ Neustar
+
+:globalMaxMbps: An optional integer that will set the maximum global bandwidth allowed on this Delivery Service. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS Delivery Services and to ``httpBypassFqdn`` for HTTP Delivery Services
+:globalMaxTps: An optional integer that will set the maximum global transactions per second allowed on this Delivery Service. When this is exceeded traffic will be sent to the ``dnsBpassIp`` (and/or ``dnsBypassIp6``)for DNS Delivery Services and to the ``httpBypassFqdn`` for HTTP Delivery Services
+:httpBypassFqdn: An optional Fully Qualified Domain Name (FQDN) to use for bypass on an HTTP Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [2]_
+:infoUrl: An optional string which, if present, is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
+:initialDispersion: The number of caches between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1\ [2]_\ [6]_
+:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection - optional for ANY_MAP Delivery Services
+:logsEnabled: If ``true``, logging is enabled for this Delivery Service, otherwise it is disabled
+:longDesc: An optional description of the Delivery Service
+:longDesc1: An optional field used when more detailed information that that provided by ``longDesc`` is desired
+:longDesc2: An optional field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
+:maxDnsAnswers: An optional field which, when present, specifies the maximum number of IPs to put in responses to A/AAAA DNS record requests - defaults to 0, meaning "no limit"\ [4]_
+:midHeaderRewrite: An optional string containing rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
+:missLat: The latitude to use when the client cannot be found in the CZF or a geographic IP lookup\ [7]_
+:missLong: The longitude to use when the client cannot be found in the CZF or a geographic IP lookup\ [7]_
+:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this Delivery Service, ``false`` otherwise\ [3]_\ [7]_
+:orgServerFqdn: The URL of the Delivery Service's origin server for use in retrieving content from the origin server\ [7]_
+
+ .. note:: Despite the field name, this must truly be a full URL - including the protocol (e.g. ``http://`` or ``https://``) - **NOT** merely the server's Fully Qualified Domain Name (FQDN)
+
+:originShield: An "origin shield" is a forward proxy that sits between Mid-tier caches and the origin and performs further caching beyond what's offered by a standard CDN. This optional field is a string of FQDNs to use as origin shields, delimited by ``|``
+:profileId: An optional, integral, unique identifier for the Traffic Router profile with which this Delivery Service shall be associated
+:protocol: The protocol which clients will use to communicate with Edge-tier cache servers - this is an (optional for ANY_MAP Delivery Services) integer on the interval [0,2] where the values have these meanings:
+
+ 0
+ HTTP
+ 1
+ HTTPS
+ 2
+ Both HTTP and HTTPS
+
+:qstringIgnore: Tells caches whether or not to consider URLs with different query parameter strings to be distinct\ [7]_ - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ URLs with different query parameter strings will be considered distinct for caching purposes, and query strings will be passed upstream to the origin
+ 1
+ URLs with different query parameter strings will be considered identical for caching purposes, and query strings will be passed upstream to the origin
+ 2
+ Query strings are stripped out by Edge-tier caches, and thus are neither taken into consideration for caching purposes, nor passed upstream in requests to the origin
+
+:rangeRequestHandling: Tells caches how to handle range requests\ [7]_ - this is an integer on the interval [0,2] where the values have these meanings:
+
+ 0
+ Range requests will not be cached, but range requests that request ranges of content already cached will be served from the cache
+ 1
+ Use the `background_fetch plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/background_fetch.en.html>`_ to service the range request while caching the whole object
+ 2
+ Use the `experimental cache_range_requests plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/cache_range_requests>`_ to treat unique ranges as unique objects
+
+:regexRemap: An optional, regular expression remap rule to apply to this Delivery Service at the Edge tier
+
+ .. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
+
+:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this Delivery Service, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
+:remapText: Optional, raw text to add to the remap line for caches
+
+ .. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
+
+:routingName: The routing name of this Delivery Service, used as the top-level part of the FQDN used by clients to request content from the Delivery Service e.g. ``routingName.xml_id.CDNName.com``
+:signed: An optional field which should be ``true`` if token-based authentication\ [8]_ will be enabled for this Delivery Service, ``false`` (default) otherwise
+:signingAlgorithm: Type of URL signing method to sign the URLs\ [8]_, basically comes down to one of two plugins or ``null``:
+
+ ``null``
+ Token-based authentication is not enabled for this Delivery Service
+ url_sig:
+ URL Signing token-based authentication is enabled for this Delivery Service
+ uri_signing
+ URI Signing token-based authentication is enabled for this Delivery Service
+
+ .. seealso:: `The Apache Trafficserver documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/url_sig.en.html>`_ and `the draft RFC for uri_signing <https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16>`_ - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, **NOT** the latest
+
+:sslKeyVersion: This optional integer indicates the generation of keys to be used by the Delivery Service - if any - and is incremented by the Traffic Portal client whenever new keys are generated
+
+ .. warning:: This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!
+
+:tenantId: An optional, integral, unique identifier of the tenant who will own this Delivery Service
+:trRequestHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router access logs for requests - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
+:trResponseHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router responses - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
+:typeId: The integral, unique identifier for the routing type of this Delivery Service
+:xmlId: A unique string that describes this Delivery Service - exists for legacy reasons
+
+ .. note:: While this field **must** be present, it is **not** allowed to change; this must be the same as the ``xml_id`` the Delivery Service already has. This should almost never be different from the Delivery Service's ``displayName``.
+
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/1.4/deliveryservices/1 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 761
+ Content-Type: application/json
+
+ {
+ "active": true,
+ "anonymousBlockingEnabled": false,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "deepCachingType": "NEVER",
+ "displayName": "demo",
+ "exampleURLs": [
+ "http://video.demo.mycdn.ciab.test"
+ ],
+ "dscp": 0,
+ "geoLimit": 0,
+ "geoProvider": 0,
+ "initialDispersion": 1,
+ "ipv6RoutingEnabled": false,
+ "lastUpdated": "2018-11-14 18:21:17+00",
+ "logsEnabled": true,
+ "longDesc": "A Delivery Service created expressly for API documentation examples",
+ "missLat": -1,
+ "missLong": -1,
+ "multiSiteOrigin": false,
+ "orgServerFqdn": "http://origin.infra.ciab.test",
+ "protocol": 0,
+ "qstringIgnore": 0,
+ "rangeRequestHandling": 0,
+ "regionalGeoBlocking": false,
+ "routingName": "video",
+ "signed": false,
+ "tenant": "root",
+ "tenantId": 1,
+ "typeId": 1,
+ "xmlId": "demo1"
+ }
+
+.. [5] These fields must be defined if and only if ``geoLimit`` is non-zero
+.. [6] These fields are required for HTTP-routed Delivery Services, and optional for all others
+.. [7] These fields are required for HTTP-routed and DNS-routed Delivery Services, but are optional for (and in fact may have no effect on) STEERING and ANY_MAP Delivery Services
+.. [8] See "token-based-auth" TODO --- wat for more information
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: z4PhNX7vuL3xVChQ1m2AB9Yg5AULVxXcg/SpIdNs6c5H0NE8XYXysP+DGNKHfuwvY7kxvUdBeoGlODJ6+SfaPg==
+ X-Server-Name: traffic_ops_golang/
+ Date: Tue, 20 Nov 2018 14:12:25 GMT
+ Content-Length: 0
+ Content-Type: text/plain; charset=utf-8
+
+
+.. [10] Users with the roles "admin" and/or "operation" will be able to edit *all* Delivery Services, whereas any other user will only be able to edit the Delivery Services their Tenant is allowed to edit.
+
+``DELETE``
+==========
+Deletes the target Delivery Service
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"\ [11]_
+:Response Type: ``undefined``
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+----------------------------------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+============================================================================================================================+
+ | ID | The integral, unique identifier of the Delivery Service to be retrieved |
+ +------+----------------------------------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ DELETE /api/1.4/deliveryservices/2 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: w9NlQpJJEl56r6iYq/fk8o5WfAXeUS5XR9yDHvKUgPO8lYEo8YyftaSF0MPFseeOk60dk6kQo+MLYTDIAhhRxw==
+ X-Server-Name: traffic_ops_golang/
+ Date: Tue, 20 Nov 2018 14:56:37 GMT
+ Content-Length: 57
+
+ { "alerts": [
+ {
+ "text": "ds was deleted.",
+ "level": "success"
+ }
+ ]}
+
+.. [11] Users with the roles "admin" and/or "operation" will be able to delete *all* Delivery Services, whereas any other user will only be able to delete the Delivery Services their Tenant is allowed to delete.
diff --git a/docs/source/api/deliveryservices_id_capacity.rst b/docs/source/api/deliveryservices_id_capacity.rst
new file mode 100644
index 0000000..741e1db
--- /dev/null
+++ b/docs/source/api/deliveryservices_id_capacity.rst
@@ -0,0 +1,73 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-deliveryservices-id-capacity:
+
+************************************
+``deliveryservices/{{ID}}/capacity``
+************************************
+
+.. seealso:: :ref:`health-proto`
+
+``GET``
+=======
+Retrieves the usage percentages of a servers associated with a Delivery Service
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"\ [1]_
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+----------------------------------------------------------------------+
+ | Name | Description |
+ +======+======================================================================+
+ | ID | The integral, unique identifier for the Delivery Service of interest |
+ +------+----------------------------------------------------------------------+
+
+Response Structure
+------------------
+:availablePercent: The percent of servers assigned to this Delivery Service that is available - the allowed traffic level in terms of data per time period for all cache servers that remains unused
+:unavailablePercent: The percent of servers assigned to this Delivery Service that is unavailable - the allowed traffic level in terms of data per time period for all cache servers that can't be used because the servers are deemed unhealthy
+:utilizedPercent: The percent of servers assigned to this Delivery Service that is currently in use - the allowed traffic level in terms of data per time period that is currently devoted to servicing requests
+:maintenancePercent: The percent of servers assigned to this Delivery Service that is unavailable due to server maintenance - the allowed traffic level in terms of data per time period that is unavailable because servers have intentionally been marked offline by administrators
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Thu, 15 Nov 2018 14:41:27 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 15 Nov 2018 18:41:27 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: ++dFR9V1c60CHGNwMjX6JSFEjHreXcL4QnhTO3hiv04ByY379aLpL4OrOzX2bPgJgpR94+f6jZ0+iDIyTMwtFQ==
+ Content-Length: 134
+
+ { "response": {
+ "availablePercent": 99.9993696969697,
+ "unavailablePercent": 0,
+ "utilizedPercent": 0.00063030303030303,
+ "maintenancePercent": 0
+ }}
+
+.. [1] Users with the roles "admin" and/or "operations" will be able to see details for *all* Delivery Services, whereas any other user will only see details for the Delivery Services their Tenant is allowed to see.
diff --git a/docs/source/api/deliveryservices_id_health.rst b/docs/source/api/deliveryservices_id_health.rst
new file mode 100644
index 0000000..0007f07
--- /dev/null
+++ b/docs/source/api/deliveryservices_id_health.rst
@@ -0,0 +1,83 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-deliveryservices-id-health:
+
+**********************************
+``deliveryservices/{{ID}}/health``
+**********************************
+
+.. seealso:: :ref:`health-proto`
+
+``GET``
+=======
+Retrieves the health of all Cache Groups assigned to a particular Delivery Service
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"\ [1]_
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+--------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+==================================================================================================+
+ | ID | The integral, unique identifier of the Delivery service for which Cache Groups will be displayed |
+ +------+--------------------------------------------------------------------------------------------------+
+
+
+Response Structure
+------------------
+:cachegroups: An array of objects that represent the health of each Cache Group assigned to this Delivery Service
+
+ :name: The name of the Cache Group represented by this object
+ :offline: The number of offline cache servers within this Cache Group
+ :online: The number of online cache servers within this Cache Group
+
+:totalOffline: Total number of offline cache servers assigned to this Delivery Service
+:totalOnline: Total number of online cache servers assigned to this Delivery Service
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Thu, 15 Nov 2018 14:43:43 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Thu, 15 Nov 2018 18:43:43 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: KpXViXeAgch58ueQqdyU8NuINBw1EUedE6Rv2ewcLUajJp6kowdbVynpwW7XiSvAyHdtClIOuT3OkhIimghzSA==
+ Content-Length: 115
+
+ { "response": {
+ "totalOffline": 0,
+ "totalOnline": 1,
+ "cachegroups": [
+ {
+ "offline": 0,
+ "name": "CDN_in_a_Box_Edge",
+ "online": 1
+ }
+ ]
+ }}
+
+.. [1] Users with the roles "admin" and/or "operations" will be able to the see Cache Groups associated with *any* Delivery Services, whereas any other user will only be able to see the Cache Groups associated with Delivery Services their Tenant is allowed to see.
diff --git a/docs/source/api/deliveryservices_id_regexes.rst b/docs/source/api/deliveryservices_id_regexes.rst
new file mode 100644
index 0000000..80dad49
--- /dev/null
+++ b/docs/source/api/deliveryservices_id_regexes.rst
@@ -0,0 +1,164 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-deliveryservices-id-regexes:
+
+***********************************
+``deliveryservices/{{ID}}/regexes``
+***********************************
+
+``GET``
+=======
+Retrieves routing regular expressions for a specific Delivery Service.
+
+:Auth. Required: Yes
+:Roles Required: None\ [1]_
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+-------------------------------------------------------------------------+
+ | Name | Description |
+ +======+=========================================================================+
+ | ID | The integral, unique identifier of the Delivery Service being inspected |
+ +------+-------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.4/deliveryservices/1/regexes HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:id: The integral, unique identifier of this regular expression
+:pattern: The actual regular expression - ``\``\ s are escaped
+:setNumber: The order in which the regular expression is evaluated against requests
+:type: The integral, unique identifier of the type of this regular expression
+:typeName: The type of regular expression - determines that against which it will be evaluated
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: fW9Fde4WRpp2ShRAC41P9s/PhU71LI/SEzHgYjGqfzhk45wq0kpaWy76JvPfLpowY8eDTp8Y8TL5rNGEc+bM+A==
+ X-Server-Name: traffic_ops_golang/
+ Date: Tue, 27 Nov 2018 20:56:43 GMT
+ Content-Length: 100
+
+ { "response": [
+ {
+ "id": 1,
+ "type": 31,
+ "typeName": "HOST_REGEXP",
+ "setNumber": 0,
+ "pattern": ".*\\.demo1\\..*"
+ }
+ ]}
+
+.. [1] If tenancy is used, then users (regardless of role) will only be able to see the routing regular expressions used by Delivery Services their tenant has permissions to see.
+
+``POST``
+========
+Creates a routing regular expression for a Delivery Service.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"\ [2]_
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+-------------------------------------------------------------------------+
+ | Name | Description |
+ +======+=========================================================================+
+ | ID | The integral, unique identifier of the Delivery Service being inspected |
+ +------+-------------------------------------------------------------------------+
+
+:pattern: The actual regular expression
+
+ .. warning:: Be sure that ``\``\ s are escaped, or the expression may not work as intended!
+
+:setNumber: The order in which this regular expression should be checked
+:type: The integral, unique identifier of a routing regular expression type
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/1.4/deliveryservices/1/regexes HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 55
+ Content-Type: application/json
+
+ {
+ "pattern": ".*\\.foo-bar\\..*",
+ "type": 31,
+ "setNumber": 1
+ }
+
+Response Structure
+------------------
+:id: The integral, unique identifier of this regular expression
+:pattern: The actual regular expression - ``\``\ s are escaped
+:setNumber: The order in which the regular expression is evaluated against requests
+:type: The integral, unique identifier of the type of this regular expression
+:typeName: The type of regular expression - determines that against which it will be evaluated
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: kS5dRzAhFKE7vfzHK7XVIwpMOjztksk9MU+qtj5YU/1oxVHmqNbJ12FeOOIJsZJCXbYlnBS04sCI95Sz5wed1Q==
+ X-Server-Name: traffic_ops_golang/
+ Date: Wed, 28 Nov 2018 17:00:42 GMT
+ Content-Length: 188
+
+ { "alerts": [
+ {
+ "text": "Delivery service regex creation was successful.",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "id": 2,
+ "type": 31,
+ "typeName": "HOST_REGEXP",
+ "setNumber": 1,
+ "pattern": ".*\\.foo-bar\\..*"
+ }}
+
+
+.. [2] If tenancy is used, then users (regardless of role) will only be able to edit the routing regular expressions used by Delivery Services their tenant has permissions to edit. Assuming tenancy is satisfied, a routing regular expression can only be created by a user with the "admin" or "operations" role.
diff --git a/docs/source/api/deliveryservices_id_regexes_rid.rst b/docs/source/api/deliveryservices_id_regexes_rid.rst
new file mode 100644
index 0000000..3e5f1c9
--- /dev/null
+++ b/docs/source/api/deliveryservices_id_regexes_rid.rst
@@ -0,0 +1,224 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-deliveryservices-id-regexes-rid:
+
+*******************************************
+``deliveryservices/{{ID}}/regexes/{{rID}}``
+*******************************************
+
+``GET``
+=======
+Retrieves a specific routing regular expression for a specific Delivery Service.
+
+:Auth. Required: Yes
+:Roles Required: None\ [1]_
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+-----------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+===================================================================================+
+ | ID | The integral, unique identifier of the Delivery Service being inspected |
+ +------+-----------------------------------------------------------------------------------+
+ | rID | The integral, unique identifier of the routing regular expression being inspected |
+ +------+-----------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.4/deliveryservices/1/regexes/1 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:id: The integral, unique identifier of this regular expression
+:pattern: The actual regular expression - ``\``\ s are escaped
+:setNumber: The order in which the regular expression is evaluated against requests
+:type: The integral, unique identifier of the type of this regular expression
+:typeName: The type of regular expression - determines that against which it will be evaluated
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: fW9Fde4WRpp2ShRAC41P9s/PhU71LI/SEzHgYjGqfzhk45wq0kpaWy76JvPfLpowY8eDTp8Y8TL5rNGEc+bM+A==
+ X-Server-Name: traffic_ops_golang/
+ Date: Tue, 27 Nov 2018 21:08:34 GMT
+ Content-Length: 100
+
+ { "response": [
+ {
+ "id": 1,
+ "type": 31,
+ "typeName": "HOST_REGEXP",
+ "setNumber": 0,
+ "pattern": ".*\\.demo1\\..*"
+ }
+ ]}
+
+.. [1] If tenancy is used, then users (regardless of role) will only be able to see the routing regular expressions used by Delivery Services their tenant has permissions to see.
+
+
+``PUT``
+=======
+Updates a routing regular expression.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"\ [2]_
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+-----------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+===================================================================================+
+ | ID | The integral, unique identifier of the Delivery Service being inspected |
+ +------+-----------------------------------------------------------------------------------+
+ | rID | The integral, unique identifier of the routing regular expression being inspected |
+ +------+-----------------------------------------------------------------------------------+
+
+:pattern: The actual regular expression
+
+ .. warning:: Be sure that ``\``\ s are escaped, or the expression may not work as intended!
+
+:setNumber: The order in which this regular expression should be checked
+:type: The integral, unique identifier of a routing regular expression type
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/1.4/deliveryservices/1/regexes/2 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 55
+ Content-Type: application/json
+
+ {
+ "pattern": ".*\\.foo-bar\\..*",
+ "type": 33,
+ "setNumber": 1
+ }
+
+Response Structure
+------------------
+:id: The integral, unique identifier of this regular expression
+:pattern: The actual regular expression - ``\``\ s are escaped
+:setNumber: The order in which the regular expression is evaluated against requests
+:type: The integral, unique identifier of the type of this regular expression
+:typeName: The type of regular expression - determines that against which it will be evaluated
+
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: kS5dRzAhFKE7vfzHK7XVIwpMOjztksk9MU+qtj5YU/1oxVHmqNbJ12FeOOIJsZJCXbYlnBS04sCI95Sz5wed1Q==
+ X-Server-Name: traffic_ops_golang/
+ Date: Thu, 29 Nov 2018 17:54:58 GMT
+ Content-Length: 188
+
+ { "alerts": [
+ {
+ "text": "Delivery service regex creation was successful.",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "id": 2,
+ "type": 33,
+ "typeName": "PATH_REGEXP",
+ "setNumber": 1,
+ "pattern": ".*\\.foo-bar\\..*"
+ }}
+
+
+.. [2] If tenancy is used, then users (regardless of role) will only be able to edit the routing regular expressions used by Delivery Services their tenant has permissions to edit. Assuming tenancy is satisfied, a routing regular expression can only be edited by a user with the "admin" or "operations" role.
+
+``DELETE``
+==========
+Deletes a routing regular expression.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"\ [3]_
+:Response Type: ``undefined``
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+-----------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+===================================================================================+
+ | ID | The integral, unique identifier of the Delivery Service being inspected |
+ +------+-----------------------------------------------------------------------------------+
+ | rID | The integral, unique identifier of the routing regular expression being inspected |
+ +------+-----------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ DELETE /api/1.4/deliveryservices/1/regexes/2 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+.. code-block:: http
+ :caption: Response Example
+
+ 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: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: 8oEa78x7f/o39LIS98W6G+UqE6cX/Iw4v3mMHvbAs1iWHALuDYRz3VOtA6jzfGQKpB04Om8qaVG+zWRrBVoCmQ==
+ X-Server-Name: traffic_ops_golang/
+ Date: Thu, 29 Nov 2018 18:44:00 GMT
+ Content-Length: 76
+
+ { "alerts": [
+ {
+ "text": "deliveryservice_regex was deleted.",
+ "level": "success"
+ }
+ ]}
+
+.. [3] If tenancy is used, then users (regardless of role) will only be able to delete the routing regular expressions used by Delivery Services their tenant has permissions to delete. Assuming tenancy is satisfied, a routing regular expression can only be deleted by a user with the "admin" or "operations" role.
diff --git a/docs/source/api/deliveryservices_id_routing.rst b/docs/source/api/deliveryservices_id_routing.rst
new file mode 100644
index 0000000..8b01929
--- /dev/null
+++ b/docs/source/api/deliveryservices_id_routing.rst
@@ -0,0 +1,91 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-deliveryservices-id-routing:
+
+***********************************
+``deliveryservices/{{ID}}/routing``
+***********************************
+
+``GET``
+=======
+Retrieves routing method statistics for a particular Delivery Service
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"\ [1]_
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+----------------------------------------------------------------------+
+ | Name | Description |
+ +======+======================================================================+
+ | ID | The integral, unique identifier for the Delivery Service of interest |
+ +------+----------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.4/deliveryservices/1/routing HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:cz: The percent of requests to the Traffic Router for this Delivery Service that were satisfied by a coverage zone file (CZF)
+:dsr: The percent of requests to the Traffic Router for this Delivery Service that were satisfied by sending the client to an overflow Delivery Service
+:err: The percent of requests to the Traffic Router for this Delivery Service that resulted in an error
+:fed: The percent of requests to the Traffic Router for this Delivery Service that were satisfied by sending the client to a federated CDN
+:geo: The percent of requests to the Traffic Router for this Delivery Service that were satisfied using 3rd party geographic IP mapping
+:miss: The percent of requests to the Traffic Router for this Delivery Service that could not be satisfied
+:regionalAlternate: The percent of requests to the Traffic Router for this Delivery Service that were satisfied by sending the client to the alternate, Regional Geo-blocking URL
+:regionalDenied: The percent of Traffic Router requests for this Delivery Service that were denied due to geographic location policy
+:staticRoute: The percent of requests to the Traffic Router for this Delivery Service that were satisfied with pre-configured DNS entries
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Fri, 30 Nov 2018 15:08:07 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Fri, 30 Nov 2018 19:08:07 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: UgPziRC/5u4+CfkZ9xm0EkEzjjJVu6cwBrFd/n3xH/ZmlkaXkQaa1y4+B7DyE46vxFLYE0ODOcQchyn7JkoQOg==
+ Content-Length: 132
+
+ { "response": {
+ "staticRoute": 0,
+ "geo": 100,
+ "err": 0,
+ "fed": 0,
+ "cz": 0,
+ "dsr": 0,
+ "regionalAlternate": 0,
+ "deepCz": 0,
+ "regionalDenied": 0,
+ "miss": 0
+ }}
+
+.. [1] Users with the roles "admin" and/or "operations" will be able to see details for *all* Delivery Services, whereas any other user will only see details for the Delivery Services their Tenant is allowed to see.
diff --git a/docs/source/api/deliveryservices_id_safe.rst b/docs/source/api/deliveryservices_id_safe.rst
new file mode 100644
index 0000000..675e700
--- /dev/null
+++ b/docs/source/api/deliveryservices_id_safe.rst
@@ -0,0 +1,317 @@
+..
+..
+.. 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.
+..
+
+.. _to-api-deliveryservices-id-safe:
+
+********************************
+``deliveryservices/{{ID}}/safe``
+********************************
+
+``PUT``
+=======
+Allows a user to edit metadata fields of a Delivery Service.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"\ [1]_
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+------------------------------------------------------------------------+
+ | Name | Description |
+ +======+========================================================================+
+ | ID | The integral, unique identifier of the Delivery Service being modified |
+ +------+------------------------------------------------------------------------+
+
+:displayName: The human-friendly name for this Delivery Service
+:infoUrl: A string which is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
+:longDesc: A description of the Delivery Service
+:longDesc1: A field used when more detailed information that that provided by ``longDesc`` is desired
+:longDesc2: A field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
+
+.. note:: All of these fields are optional; this ``PUT`` behaves more like a ``PATCH``
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/1.4/deliveryservices/1/safe HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 165
+ Content-Type: application/x-www-form-urlencoded
+
+ {
+ "displayName": "demo",
+ "infoUrl": "www.info.com",
+ "longDesc": "A Delivery Service created for the CDN-in-a-Box project",
+ "longDesc1": null,
+ "longDesc2": null
+ }
+
+
+Response Structure
+------------------
+.. versionchanged:: 1.3
+ Removed ``fqPacingRate`` field, added fields: ``deepCachingType``, ``signingAlgorithm``, and ``tenant``.
+
+:active: ``true`` if the Delivery Service is active, ``false`` otherwise
+:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the Delivery Service, ``false`` otherwise
+:cacheurl: A setting for a deprecated feature of now-unsupported Trafficserver versions
+:ccrDnsTtl: The Time To Live (TTL) of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
+:cdnId: The integral, unique identifier of the CDN to which the Delivery Service belongs
+:cdnName: Name of the CDN to which the Delivery Service belongs
+:checkPath: The path portion of the URL to check connections to this Delivery Service's origin server
+:deepCachingType: A string that describes when "Deep Caching" will be used by this Delivery Service - one of:
+
+ ALWAYS
+ "Deep Caching" will always be used with this Delivery Service
+ NEVER
+ "Deep Caching" will never be used with this Delivery Service
+
+ .. versionadded:: 1.3
+
+:displayName: The display name of the Delivery Service
+:dnsBypassCname: Domain name to overflow requests for HTTP Delivery Services - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
+:dnsBypassIp: The IPv4 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
+:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
+:dnsBypassTtl: The time for which a DNS bypass of this Delivery Service shall remain active\ [4]_
+:dscp: The Differentiated Services Code Point (DSCP) with which to mark traffic as it leaves the CDN and reaches clients
+:edgeHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
+:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the Delivery Service (see ``man tc-fc_codel`` for more information) - Linux only
+
+ .. deprecated:: 1.3
+ This field is only present/available in API versions 1.2 and lower - it has been removed in API version 1.3
+
+:geoLimit: The setting that determines how content is geographically limited - this is an integer on the interval [0-2] where the values have these meanings:
+:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this Delivery Service
+:geoLimitRedirectUrl: A URL to which clients blocked by :ref:`Regional Geographic Blocking <regionalgeo-qht>` or the ``geoLimit`` settings will be re-directed
+
+ 0
+ None - no limitations
+ 1
+ Only route when the client's IP is found in the Coverage Zone File (CZF)
+ 2
+ Only route when the client's IP is found in the CZF, or when the client can be determined to be from the United States of America
+
+ .. warning:: This does not prevent access to content or make content secure; it merely prevents routing to the content through Traffic Router
+
+:geoProvider: An integer that represents the provider of a database for mapping IPs to geographic locations; currently only ``0`` - which represents MaxMind - is supported
+:globalMaxMbps: The maximum global bandwidth allowed on this Delivery Service. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS Delivery Services and to ``httpBypassFqdn`` for HTTP Delivery Services
+:globalMaxTps: The maximum global transactions per second allowed on this Delivery Service. When this is exceeded traffic will be sent to the dnsByPassIp* for DNS Delivery Services and to the httpBypassFqdn for HTTP Delivery Services
+:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
+:id: An integral, unique identifier for this Delivery Service
+:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
+:initialDispersion: The number of caches between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1
+:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection\ [2]_
+:lastUpdated: The date and time at which this Delivery Service was last updated, in a ``ctime``-like format
+:logsEnabled: If ``true``, logging is enabled for this Delivery Service, otherwise it is disabled
+:longDesc: A description of the Delivery Service
+:longDesc1: A field used when more detailed information that that provided by ``longDesc`` is desired
+:longDesc2: A field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
+:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this Delivery Service
+
+ :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped)
+ :setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs
+ :type: The type of match performed using ``pattern`` to determine whether or not to use this Delivery Service
+
+ HOST_REGEXP
+ Use the Delivery Service if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [2]_
+ HEADER_REGEXP
+ Use the Delivery Service if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [2]_
+ PATH_REGEXP
+ Use the Delivery Service if ``pattern`` matches the request path of this Delivery Service's URL
+ STEERING_REGEXP
+ Use the Delivery Service if ``pattern`` matches the ``xml_id`` of one of this Delivery Service's "Steering" target Delivery Services
+
+:maxDnsAnswers: The maximum number of IPs to put in a A/AAAA response for a DNS Delivery Service (0 means all available)\ [4]_
+:midHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
+:missLat: The latitude to use when the client cannot be found in the CZF or a geographic IP lookup
+:missLong: The longitude to use when the client cannot be found in the CZF or a geographic IP lookup
+:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this Delivery Service, ``false`` otherwise\ [3]_
+:originShield: An "origin shield" is a forward proxy that sits between Mid-tier caches and the origin and performs further caching beyond what's offered by a standard CDN. This field is a string of FQDNs to use as origin shields, delimited by ``|``
+:orgServerFqdn: The origin server's Fully Qualified Domain Name (FQDN) - including the protocol (e.g. http:// or https://) - for use in retrieving content from the origin server
+:profileDescription: The description of the Traffic Router Profile with which this Delivery Service is associated
+:profileId: The integral, unique identifier for the Traffic Router profile with which this Delivery Service is associated
+:profileName: The name of the Traffic Router Profile with which this Delivery Service is associated
+:protocol: The protocol which clients will use to communicate with Edge-tier cache servers\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ HTTP
+ 1
+ HTTPS
+ 2
+ Both HTTP and HTTPS
+
+:qstringIgnore: Tells caches whether or not to consider URLs with different query parameter strings to be distinct - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ URLs with different query parameter strings will be considered distinct for caching purposes, and query strings will be passed upstream to the origin
+ 1
+ URLs with different query parameter strings will be considered identical for caching purposes, and query strings will be passed upstream to the origin
+ 2
+ Query strings are stripped out by Edge-tier caches, and thus are neither taken into consideration for caching purposes, nor passed upstream in requests to the origin
+
+:rangeRequestHandling: Tells caches how to handle range requests\ [5]_ - this is an integer on the interval [0-2] where the values have these meanings:
+
+ 0
+ Range requests will not be cached, but range requests that request ranges of content already cached will be served from the cache
+ 1
+ Use the `background_fetch plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/background_fetch.en.html>`_ to service the range request while caching the whole object
+ 2
+ Use the `experimental cache_range_requests plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/cache_range_requests>`_ to treat unique ranges as unique objects
+
+:regexRemap: A regular expression remap rule to apply to this Delivery Service at the Edge tier
+
+ .. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
+
+:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this Delivery Service, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
+:remapText: Additional, raw text to add to the remap line for caches
+
+ .. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
+
+:signed: ``true`` if token-based authentication is enabled for this Delivery Service, ``false`` otherwise
+:signingAlgorithm: Type of URL signing method to sign the URLs, basically comes down to one of two plugins or ``null``:
+
+ ``null``
+ Token-based authentication is not enabled for this Delivery Service
+ url_sig:
+ URL Signing token-based authentication is enabled for this Delivery Service
+ uri_signing
+ URI Signing token-based authentication is enabled for this Delivery Service
+
+ .. seealso:: `The Apache Trafficserver documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/url_sig.en.html>`_ and `the draft RFC for uri_signing <https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16>`_ - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, NOT the latest.
+
+ .. versionadded:: 1.3
+
+:sslKeyVersion: This integer indicates the generation of keys in use by the Delivery Service - if any - and is incremented by the Traffic Portal client whenever new keys are generated
+
+ .. warning:: This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!
+
+:tenant: The name of the tenant who owns this Delivery Service
+
+ .. versionadded:: 1.3
+
+:tenantId: The integral, unique identifier of the tenant who owns this Delivery Service
+:trRequestHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router access logs for requests - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
+:trResponseHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router responses - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
+:type: The name of the routing type of this Delivery Service e.g. "HTTP"
+:typeId: The integral, unique identifier of the routing type of this Delivery Service
+:xmlId: A unique string that describes this Delivery Service - exists for legacy reasons
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ 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: application/json
+ Date: Mon, 19 Nov 2018 19:29:40 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Mon, 19 Nov 2018 23:29:40 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: wSCPoNQbFTN0FonjXYH13jwTvOwo0ltSD0ACRQ4d/eaWIfzNyAFAD/RapflUP2PIqttb6NlnHkZve0j6ETJ+gw==
+ Content-Length: 1439
+
+ { "alerts": [
+ {
+ "level": "success",
+ "text": "Deliveryservice safe update was successful."
+ }
+ ],
+ "response": [
+ {
+ "profileId": null,
+ "protocol": 0,
+ "deepCachingType": "NEVER",
+ "regionalGeoBlocking": 0,
+ "routingName": "video",
+ "orgServerFqdn": "http://origin.infra.ciab.test",
+ "cdnId": 2,
+ "geoProvider": 0,
+ "longDesc2": null,
+ "globalMaxMbps": null,
+ "dnsBypassIp6": null,
+ "geoLimit": 0,
+ "maxDnsAnswers": null,
+ "id": 1,
+ "sslKeyVersion": null,
+ "midHeaderRewrite": null,
+ "geoLimitRedirectURL": null,
+ "active": 1,
+ "logsEnabled": 1,
+ "initialDispersion": 1,
+ "regexRemap": null,
+ "geoLimitCountries": null,
+ "missLat": 42,
+ "anonymousBlockingEnabled": 0,
+ "longDesc": "A Delivery Service created for the CDN-in-a-Box project",
+ "matchList": [
+ {
+ "pattern": ".*\\.demo1\\..*",
+ "setNumber": 0,
+ "type": "HOST_REGEXP"
+ }
+ ],
+ "rangeRequestHandling": 0,
+ "profileName": null,
+ "dnsBypassCname": null,
+ "globalMaxTps": null,
+ "type": "HTTP",
+ "httpBypassFqdn": null,
+ "infoUrl": "www.info.com",
+ "signingAlgorithm": null,
+ "missLong": -88,
+ "trRequestHeaders": null,
+ "trResponseHeaders": null,
+ "exampleURLs": [
... 40555 lines suppressed ...