diff --git a/docs/source/admin/traffic_portal/usingtrafficportal.rst b/docs/source/admin/traffic_portal/usingtrafficportal.rst index e805f3e860..661d6ae853 100644 --- a/docs/source/admin/traffic_portal/usingtrafficportal.rst +++ b/docs/source/admin/traffic_portal/usingtrafficportal.rst @@ -178,7 +178,7 @@ A table showing the results of the periodic :ref:`to-check-ext` that are run. Th :Profile: :ref:`profile-name` of the :term:`Profile` applied to the Edge-tier or Mid-tier :term:`cache server`, or the special name "ALL" indicating that this row is a group of all :term:`cache servers` within a single :term:`Cache Group` :Host: 'ALL' for entries grouped by :term:`Cache Group`, or the hostname of a particular :term:`cache server` -:Cache Group: Name of the :term:`Cache Group` to which this server belongs, or the name of the :term:`Cache Group` that is grouped for entries grouped by :term:`Cache Group`, or the special name "ALL" indicating that this row is an aggregate across all :term:`Cache Groups` +:Cache Group: :ref:`Name of the Cache Group ` to which this server belongs, or the name of the :term:`Cache Group` that is grouped for entries grouped by :term:`Cache Group`, or the special name "ALL" indicating that this row is an aggregate across all :term:`Cache Groups` :Healthy: True/False as determined by Traffic Monitor .. seealso:: :ref:`health-proto` @@ -362,7 +362,7 @@ A configurable table of all servers (of all kinds) across all :term:`Delivery Se Use the `Select Columns` menu to select the server columns to view and search. Columns can also be rearranged using drag-and-drop. Available server columns include: -:Cache Group: [Visible by default] The name of the :term:`Cache Group` to which this server belongs +:Cache Group: [Visible by default] The :ref:`Name of the Cache Group ` to which this server belongs :CDN: [Visible by default] The name of the CDN to which the server belongs :Domain: [Visible by default] The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)` :Host: [Visible by default] The (short) hostname of the server @@ -437,7 +437,7 @@ A table of all :term:`origins`. These are automatically created for the :term:`o .. note:: If this field appears blank in the table, it means that a default was chosen for the :term:`origin` based on its Protocol - ``80`` for "http", ``443`` for "https". :Coordinate: The name of the geographic coordinate pair that defines the physical location of this :term:`origin server`. :term:`Origins` created for :term:`Delivery Services` automatically will **not** have associated Coordinates. This can be rectified on the details pages for said :term:`origins` -:Cachegroup: The name of the :term:`Cache Group` to which this :term:`origin` belongs, if any. +:Cachegroup: The :ref:`Name of the Cache Group ` to which this :term:`origin` belongs, if any. :Profile: The :ref:`profile-name` of a :term:`Profile` used by this :term:`origin`. :term:`Origin` management includes the ability to (where applicable): @@ -537,11 +537,11 @@ Cache Groups ------------ This page is a table of :term:`Cache Groups`, each entry of which has the following fields: -:Name: The full name of this :term:`Cache Group` -:Short Name: A shorter, more human-friendly name for this :term:`Cache Group` -:Type: The :term:`Type` of this :term:`Cache Group` -:Latitude: A geographic latitude assigned to this :term:`Cache Group` -:Longitude: A geographic longitude assigned to this :term:`Cache Group` +:Name: The full :ref:`Name of this Cache Group ` +:Short Name: This :ref:`Cache Group's Short Name ` +:Type: This :ref:`Cache Group's Type ` +:Latitude: This :ref:`Cache Group's Latitude ` +:Longitude: This :ref:`Cache Group's Longitude ` :term:`Cache Group` management includes the ability to (where applicable): diff --git a/docs/source/api/asns.rst b/docs/source/api/asns.rst index b3ee261b9c..fe17514439 100644 --- a/docs/source/api/asns.rst +++ b/docs/source/api/asns.rst @@ -19,15 +19,19 @@ ******** ``asns`` ******** -.. seealso:: `The Autonomous System Wikipedia page ` for an explanation of what an ASN actually is. +.. seealso:: `The Autonomous System Wikipedia page `_ for an explanation of what an :abbr:`ASN (Autonomous System Number)` actually is. ``GET`` ======= -List all Autonomous System Numbers (ASNs). +List all :abbr:`ASNs (Autonomous System Numbers)`. + :Auth. Required: Yes :Roles Required: None :Response Type: Array + .. versionchanged:: 1.2 + Previously was an object with only one key ("asns") that contained the response array. This has been flattened so that the response is the actual array. + Request Structure ----------------- .. table:: Request Query Parameters @@ -35,8 +39,8 @@ Request Structure +------------+----------+-----------------------------------------------------------------------------------------------------+ | Parameter | Required | Description | +============+==========+=====================================================================================================+ - | cachegroup | no | An integral, unique identifier for a :term:`Cache Group` - only ANSs for this :term:`Cache Group` | - | | | will be returned. | + | cachegroup | no | The :ref:`cache-group-id` of a :term:`Cache Group` - only :abbr:`ASNs (Autonomous System Numbers)` | + | | | for this :term:`Cache Group` will be returned. | +------------+----------+-----------------------------------------------------------------------------------------------------+ | orderby | no | Choose the ordering of the results - must be the name of one of the fields of the objects in the | | | | ``response`` array | @@ -53,16 +57,23 @@ Request Structure | | | effect. ``limit`` must be defined to make use of ``page``. | +------------+----------+-----------------------------------------------------------------------------------------------------+ +.. code-block:: http + :caption: Request Example + + GET /api/1.4/asns HTTP/1.1 + User-Agent: python-requests/2.22.0 + Accept-Encoding: gzip, deflate + Accept: */* + Connection: keep-alive + Cookie: mojolicious=... + 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 +:asn: An :abbr:`ASN (Autonomous System Number)` as specified by IANA for identifying a service provider +:cachegroup: A string that is the :ref:`cache-group-name` of the :term:`Cache Group` that is associated with this :abbr:`ASN (Autonomous System Number)` +:cachegroupId: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` that is associated with this :abbr:`ASN (Autonomous System Number)` +:id: An integral, unique identifier for this association between an :abbr:`ASN (Autonomous System Number)` and a :term:`Cache Group` +:lastUpdated: The time and date this server entry was last updated in an ISO-like format .. code-block:: http :caption: Response Example @@ -72,12 +83,13 @@ Response Structure 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-Encoding: gzip Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 2zeWYI/dGyCzi0ZUWXuuycLFPyL9M5nDJchC7nJMQPW3cwXTaTwf0qI3mP3G1ArZlJTk/ju6/jbUVCNcVIXX1Q== + Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 02 Dec 2019 22:51:14 GMT; Max-Age=3600; HttpOnly + Whole-Content-Sha512: F2NmDbTpXqrIQDX7IBKH9+1drtTL4XedSfJv6klMgLEZwbLCkddIXuSLpmgVCID6kTVqy3fTKjZS3U+HJ3YUEQ== X-Server-Name: traffic_ops_golang/ - Date: Thu, 01 Nov 2018 18:56:38 GMT - Content-Length: 129 + Date: Mon, 02 Dec 2019 21:51:14 GMT + Content-Length: 128 { "response": [ { @@ -85,14 +97,15 @@ Response Structure "cachegroup": "TRAFFIC_ANALYTICS", "cachegroupId": 1, "id": 1, - "lastUpdated": "2018-11-01 18:55:39+00" + "lastUpdated": "2019-12-02 21:49:08+00" } ]} + ``POST`` ======== -Creates a new Autonomous System Number (ASN). +Creates a new :abbr:`ASN (Autonomous System Number)`. :Auth. Required: Yes :Roles Required: "admin" or "operations" @@ -100,32 +113,34 @@ Creates a new Autonomous System Number (ASN). 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 +:asn: The value of the new :abbr:`ASN (Autonomous System Number)` +:cachegroup: An optional field which, if present, is a string that specifies the :ref:`cache-group-name` of a :term:`Cache Group` to which this :abbr:`ASN (Autonomous System Number)` 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. + .. 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 :term:`Cache Group` to which the :abbr:`ASN (Autonomous System Number)` was assigned. Any subsequent requests will reveal that, in fact, the :term:`Cache Group` is set entirely by the ``cachegroupId`` field, and so the actual :ref:`cache-group-name` may differ from what was in the request. + +:cachegroupId: An integer that is the :ref:`cache-group-id` of a :term:`Cache Group` to which this :abbr:`ASN (Autonomous System Number)` will be assigned .. 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 + POST /api/1.4/asns HTTP/1.1 + User-Agent: python-requests/2.22.0 + Accept-Encoding: gzip, deflate Accept: */* + Connection: keep-alive Cookie: mojolicious=... - Content-Length: 60 - Content-Type: application/x-www-form-urlencoded + Content-Length: 29 {"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 +:asn: An :abbr:`ASN (Autonomous System Number)` as specified by IANA for identifying a service provider +:cachegroup: A string that is the :ref:`cache-group-name` of the :term:`Cache Group` that is associated with this :abbr:`ASN (Autonomous System Number)` +:cachegroupId: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` that is associated with this :abbr:`ASN (Autonomous System Number)` +:id: An integral, unique identifier for this association between an :abbr:`ASN (Autonomous System Number)` and a :term:`Cache Group` +:lastUpdated: The time and date this server entry was last updated in an ISO-like format .. code-block:: http :caption: Response Example @@ -135,12 +150,13 @@ Response Structure 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-Encoding: gzip Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: DnM8HexH7LFkVNH8UYFe6uBQ445Ic8lRLDlOSDIuo4gjokMafxh5Ebr+CsSixNt//OxP0hoWZ+DKymSC5Hdi9Q== + Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 02 Dec 2019 22:49:08 GMT; Max-Age=3600; HttpOnly + Whole-Content-Sha512: mx8b2GTYojz4QtMxXCMoQyZogCB504vs0yv6WGly4dwM81W3XiejWNuUwchRBYYi8QHaWsMZ3DaiGGfQi/8Giw== X-Server-Name: traffic_ops_golang/ - Date: Thu, 01 Nov 2018 18:57:08 GMT - Content-Length: 175 + Date: Mon, 02 Dec 2019 21:49:08 GMT + Content-Length: 150 { "alerts": [ { @@ -150,8 +166,9 @@ Response Structure ], "response": { "asn": 1, - "cachegroup": "TRAFFIC_ANALYTICS", + "cachegroup": null, "cachegroupId": 1, - "id": 2, - "lastUpdated": "2018-11-01 18:57:08+00" + "id": 1, + "lastUpdated": "2019-12-02 21:49:08+00" }} + diff --git a/docs/source/api/asns_id.rst b/docs/source/api/asns_id.rst index b01b90d661..f775e9d5df 100644 --- a/docs/source/api/asns_id.rst +++ b/docs/source/api/asns_id.rst @@ -19,11 +19,12 @@ *************** ``asns/{{id}}`` *************** -.. seealso:: `The Autonomous System Wikipedia page ` for an explanation of what an ASN actually is. +.. seealso:: `The Autonomous System Wikipedia page `_ for an explanation of what an :abbr:`ASN (Autonomous System Number)` actually is. ``GET`` ======= -Deal with a specific Autonomous System Number (ASN). +Retrieve information about a specific :abbr:`ASN (Autonomous System Number)`-to-:term:`Cache Group` association. + :Auth. Required: Yes :Roles Required: None :Response Type: Array @@ -32,19 +33,29 @@ Request Structure ----------------- .. table:: Request Path Parameters - +-------------------+----------+----------------------------------------------------+ - | Name | Required | Description | - +===================+==========+====================================================+ - | id | yes | The integral, unique identifier of the desired ASN | - +-------------------+----------+----------------------------------------------------+ + +------+----------+--------------------------------------------------------------------------------------------------------------------------+ + | Name | Required | Description | + +======+==========+==========================================================================================================================+ + | id | yes | The integral, unique identifier of the desired :abbr:`ASN (Autonomous System Number)`-to-:term:`Cache Group` association | + +------+----------+--------------------------------------------------------------------------------------------------------------------------+ + +.. code-block:: http + :caption: Request Structure + + GET /api/1.1/asns/1 HTTP/1.1 + User-Agent: python-requests/2.22.0 + Accept-Encoding: gzip, deflate + Accept: */* + Connection: keep-alive + Cookie: mojolicious=... 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 +:asn: An :abbr:`ASN (Autonomous System Number)` as specified by IANA for identifying a service provider +:cachegroup: A string that is the :ref:`cache-group-name` of the :term:`Cache Group` that is associated with this :abbr:`ASN (Autonomous System Number)` +:cachegroupId: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` that is associated with this :abbr:`ASN (Autonomous System Number)` +:id: An integral, unique identifier for this association between an :abbr:`ASN (Autonomous System Number)` and a :term:`Cache Group` +:lastUpdated: The time and date this server entry was last updated in an ISO-like format .. code-block:: http :caption: Response Example @@ -54,26 +65,27 @@ Response Structure 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-Encoding: gzip Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: oeifOX6ImU1KVyCmyswh4uddhbNPZqxliMuNw+lNea1q/SJOYKXpaKnYqVjRm9QqJ7gH3vqeBxCftMLtb3sAWg== + Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 02 Dec 2019 22:53:17 GMT; Max-Age=3600; HttpOnly + Whole-Content-Sha512: F2NmDbTpXqrIQDX7IBKH9+1drtTL4XedSfJv6klMgLEZwbLCkddIXuSLpmgVCID6kTVqy3fTKjZS3U+HJ3YUEQ== X-Server-Name: traffic_ops_golang/ - Date: Wed, 07 Nov 2018 18:44:31 GMT - Content-Length: 120 + Date: Mon, 02 Dec 2019 21:53:17 GMT + Content-Length: 128 { "response": [ { - "lastUpdated": "2012-09-17 21:41:22", - "id": "28", - "asn": "7016", - "cachegroup": "us-pa-pittsburgh", - "cachegroupId": "13" + "asn": 1, + "cachegroup": "TRAFFIC_ANALYTICS", + "cachegroupId": 1, + "id": 1, + "lastUpdated": "2019-12-02 21:49:08+00" } ]} ``PUT`` ======= -Allows user to edit an existing Autonomous System Number (ASN). +Allows user to edit an existing :abbr:`ASN (Autonomous System Number)`-to-:term:`Cache Group` association. :Auth. Required: Yes :Roles Required: "admin" or "operations" @@ -81,24 +93,27 @@ Allows user to edit an existing Autonomous System Number (ASN). 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 +:asn: The new :abbr:`ASN (Autonomous System Number)` which will be associated with the identified :term:`Cache Group` - must not conflict with existing associations +:cachegroup: An optional field which, if present, is a string that specifies the :ref:`cache-group-name` of a :term:`Cache Group` to which this :abbr:`ASN (Autonomous System Number)` 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 :term:`Cache Group` to which the :abbr:`ASN (Autonomous System Number)` was assigned. Any subsequent requests will reveal that, in fact, the :term:`Cache Group` is set entirely by the ``cachegroupId`` field, and so the actual :ref:`cache-group-name` may differ from what was in the request. + +:cachegroupId: An integer that is the :ref:`cache-group-id` of a :term:`Cache Group` to which this :abbr:`ASN (Autonomous System Number)` will be assigned - must not conflict with existing associations -.. 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 | - +-------------------+----------+----------------------------------------------------+ + +------+----------+--------------------------------------------------------------------------------------------------------------------------+ + | Name | Required | Description | + +======+==========+==========================================================================================================================+ + | id | yes | The integral, unique identifier of the desired :abbr:`ASN (Autonomous System Number)`-to-:term:`Cache Group` association | + +------+----------+--------------------------------------------------------------------------------------------------------------------------+ + .. code-block:: http :caption: Request Example - PUT /api/1.1/asns/1 HTTP/1.1 + PUT /api/1.4/asns/1 HTTP/1.1 Host: trafficops.infra.ciab.test User-Agent: curl/7.47.0 Accept: */* @@ -110,11 +125,11 @@ Request Structure 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 +:asn: An :abbr:`ASN (Autonomous System Number)` as specified by IANA for identifying a service provider +:cachegroup: A string that is the :ref:`cache-group-name` of the :term:`Cache Group` that is associated with this :abbr:`ASN (Autonomous System Number)` +:cachegroupId: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` that is associated with this :abbr:`ASN (Autonomous System Number)` +:id: An integral, unique identifier for this association between an :abbr:`ASN (Autonomous System Number)` and a :term:`Cache Group` +:lastUpdated: The time and date this server entry was last updated in an ISO-like format .. code-block:: http :caption: Response Example @@ -147,7 +162,7 @@ Response Structure ``DELETE`` ========== -Deletes an Autonomous System Number (ASN). +Deletes an association between an :abbr:`ASN (Autonomous System Number)` and a :term:`Cache Group`. :Auth. Required: Yes :Roles Required: "admin" or "operations" @@ -157,11 +172,22 @@ Request Structure ----------------- .. table:: Request Path Parameters - +------+----------+----------------------------------------------------+ - | Name | Required | Description | - +======+==========+====================================================+ - | id | yes | The integral, unique identifier of the desired ASN | - +------+----------+----------------------------------------------------+ + +------+----------+--------------------------------------------------------------------------------------------------------------------------+ + | Name | Required | Description | + +======+==========+==========================================================================================================================+ + | id | yes | The integral, unique identifier of the desired :abbr:`ASN (Autonomous System Number)`-to-:term:`Cache Group` association | + +------+----------+--------------------------------------------------------------------------------------------------------------------------+ + +.. code-block:: http + :caption: Request Example + + DELETE /api/1.4/asns/1 HTTP/1.1 + User-Agent: python-requests/2.22.0 + Accept-Encoding: gzip, deflate + Accept: */* + Connection: keep-alive + Cookie: mojolicious=... + Content-Length: 0 Response Structure ------------------ @@ -173,12 +199,13 @@ Response Structure 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-Encoding: gzip Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly + Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 02 Dec 2019 23:06:24 GMT; Max-Age=3600; HttpOnly Whole-Content-Sha512: 6t3WA+DOcfPJB5UnvDpzEVx5ySfmJgEV9wgkO71U5k32L1VXpxcaTdDVLNGgDDl9sdNftmYnKXf5jpfWUuFYJQ== X-Server-Name: traffic_ops_golang/ - Date: Wed, 07 Nov 2018 19:14:08 GMT - Content-Length: 58 + Date: Mon, 02 Dec 2019 22:06:24 GMT + Content-Length: 81 { "alerts": [ { diff --git a/docs/source/api/cachegroup_fallbacks.rst b/docs/source/api/cachegroup_fallbacks.rst index d189624ac0..2b404c9abb 100644 --- a/docs/source/api/cachegroup_fallbacks.rst +++ b/docs/source/api/cachegroup_fallbacks.rst @@ -19,13 +19,13 @@ ``cachegroup_fallbacks`` ************************ -.. deprecated:: ATCv4.0 +.. deprecated:: 1.4 - The :ref:`to-api-cachegroups` and :ref:`to-api-cachegroups-id` endpoints now contain a list of "fallbacks" in the output, and support it in input, and so this endpoint is redundant. + The :ref:`to-api-cachegroups` and :ref:`to-api-cachegroups-id` endpoints now contain a list of :ref:`cache-group-fallbacks` in the output, and support it in input, and so this endpoint is redundant. ``GET`` ======= -Retrieve fallback-related configurations for a :term:`Cache Group`. +Retrieve the :ref:`cache-group-fallbacks` of a :term:`Cache Group`. :Auth. Required: Yes :Roles Required: None @@ -38,27 +38,28 @@ Request Structure +--------------+----------+-----------------------------------------------------------------------------------------------------------+ | Name | Required | Description | +==============+==========+===========================================================================================================+ - | cacheGroupId |yes\ [1]_ | The integral, unique identifier of a :term:`Cache Group` whose fallback configurations shall be retrieved | + | cacheGroupId | yes | The :ref:`cache-group-id` of a :term:`Cache Group` whose :ref:`cache-group-fallbacks` shall be retrieved | +--------------+----------+-----------------------------------------------------------------------------------------------------------+ - | fallbackId |yes\ [1]_ | The integral, unique identifier of a fallback :term:`Cache Group` | + | fallbackId | no | The integral, unique identifier of a single :ref:`"fallback" ` :term:`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 + GET /api/1.4/cachegroup_fallbacks?cacheGroupId=7 HTTP/1.1 + User-Agent: python-requests/2.22.0 + Accept-Encoding: gzip, deflate Accept: */* + Connection: keep-alive Cookie: mojolicious=... Response Structure ------------------ -:cacheGroupId: The integral, unique identifier of the :term:`Cache Group` described by this entry -:cacheGroupName: The name of the :term:`Cache Group` described by this entry -:fallbackId: The integral, unique identifier of the :term:`Cache Group` on which the :term:`Cache Group` described by this entry will fall back -:fallbackName: The name of the :term:`Cache Group` on which the :term:`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 :term:`Cache Group` described by this entry +:cacheGroupId: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` described by this entry +:cacheGroupName: The :ref:`cache-group-name` of the :term:`Cache Group` described by this entry as a string +:fallbackId: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` on which the :term:`Cache Group` described by this entry will "fall back" +:fallbackName: The :ref:`cache-group-name` of the :term:`Cache Group` on which the :term:`Cache Group` described by this entry will "fall back" as a string +:fallbackOrder: The place in the list of :ref:`cache-group-fallbacks` of the :term:`Cache Group` identified by ``cacheGroupId`` and ``cacheGroupName`` where the :term:`Cache Group` identified by ``fallbackId`` and ``fallbackName`` starting from index 1. .. code-block:: http :caption: Response Example @@ -69,30 +70,35 @@ Response Structure 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-Encoding: gzip + Content-Length: 189 Content-Type: application/json - Date: Wed, 14 Nov 2018 15:40:34 GMT + Date: Mon, 02 Dec 2019 22:26:27 GMT Server: Mojolicious (Perl) - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly + Set-Cookie: mojolicious=...; expires=Tue, 03 Dec 2019 02:26:27 GMT; path=/; HttpOnly Vary: Accept-Encoding - Whole-Content-Sha512: 9kauJ9tA4Ca5ElMHZk0fIJpQr+Wcx6NHiqWrnZJvyupRIOBQiUec3UW/fI9HdtE98xkrthz1daXKmdUkDhon8Q== - Content-Length: 125 + Whole-Content-Sha512: zSAeB8nxonyinsg1/at/l0/9FRRPw7N27DpkcZxRIwEzDOEY5XVfYcCHHFg1d/Q2JWtWZ9iRhs8mK5rLbKkccw== - { "response": [ + { "alerts": [ { - "cacheGroupId": 11, - "fallbackOrder": 1, - "fallbackName": "CDN_in_a_Box_Edge", - "fallbackId": 7, - "cacheGroupName": "test" + "level": "warning", + "text": "This endpoint is deprecated, please use 'GET /cachegroups' instead" + } + ], + "response": [ + { + "cacheGroupId": 7, + "fallbackOrder": 2, + "fallbackName": "test", + "fallbackId": 8, + "cacheGroupName": "CDN_in_a_Box_Edge" } ]} -.. [1] At least one of these must be provided, not necessarily both (though both is perfectly valid). - ``POST`` ======== -Creates fallback configuration for a :term:`Cache Group`. +Creates :ref:`"fallback" ` configuration for a :term:`Cache Group`. :Auth. Required: Yes :Roles Required: "admin" or "operations" @@ -100,33 +106,32 @@ Creates fallback configuration for a :term:`Cache Group`. Request Structure ----------------- -The request payload for this endpoint **must** be an array, even if only one fallback relationship is being created. +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 :term:`Cache Group` to which to assign a fallback -:fallbackId: Integral, unique identifier of a :term:`Cache Group` on which the :term:`Cache Group` identified by ``cacheGroupId`` will fall back -:fallbackOrder: The order of this fallback for the :term:`Cache Group` identified by ``cacheGroupId`` +:cacheGroupId: An integer that is the :ref:`cache-group-id` of a :term:`Cache Group` to which to assign a :ref:`fallback ` +:fallbackId: An integer that is the :ref:`cache-group-id` of a :term:`Cache Group` on which the :term:`Cache Group` identified by ``cacheGroupId`` will "fall back" +:fallbackOrder: The place in the list of :ref:`cache-group-fallbacks` of the :term:`Cache Group` identified by ``cacheGroupId`` and ``cacheGroupName`` where the :term:`Cache Group` identified by ``fallbackId`` and ``fallbackName`` starting from index 1. .. 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 + POST /api/1.4/cachegroup_fallbacks HTTP/1.1 + User-Agent: python-requests/2.22.0 + Accept-Encoding: gzip, deflate Accept: */* + Connection: keep-alive Cookie: mojolicious=... - Content-Length: 59 - Content-Type: application/x-www-form-urlencoded + Content-Length: 57 - [{"cacheGroupId": 11, "fallbackId": 7, "fallbackOrder": 1}] + [{"cacheGroupId": 7, "fallbackId": 8, "fallbackOrder": 2}] Response Structure ------------------ -:cacheGroupId: The integral, unique identifier of the :term:`Cache Group` to which this fallback was assigned -:cacheGroupName: The name of the :term:`Cache Group` to which this fallback was assigned -:fallbackId: The integral, unique identifier of the :term:`Cache Group` on which this entries :term:`Cache Group` will fall back -:fallbackName: The name of the :term:`Cache Group` on which this entries :term:`Cache Group` will fall back -:fallbackOrder: The order of the fallback described by "fallbackId" and "fallbackName" in the list of fallbacks for the :term:`Cache Group` described by this entry - +:cacheGroupId: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` described by this entry +:cacheGroupName: The :ref:`cache-group-name` of the :term:`Cache Group` described by this entry as a string +:fallbackId: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` on which the :term:`Cache Group` described by this entry will "fall back" +:fallbackName: The :ref:`cache-group-name` of the :term:`Cache Group` on which the :term:`Cache Group` described by this entry will "fall back" as a string +:fallbackOrder: The place in the list of :ref:`cache-group-fallbacks` of the :term:`Cache Group` identified by ``cacheGroupId`` and ``cacheGroupName`` where the :term:`Cache Group` identified by ``fallbackId`` and ``fallbackName`` starting from index 1. .. code-block:: http :caption: Response Example @@ -137,34 +142,30 @@ Response Structure 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-Encoding: gzip + Content-Length: 174 Content-Type: application/json - Date: Thu, 08 Nov 2018 14:59:46 GMT + Date: Mon, 02 Dec 2019 22:23:22 GMT Server: Mojolicious (Perl) - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly + Set-Cookie: mojolicious=...; expires=Tue, 03 Dec 2019 02:23:22 GMT; path=/; HttpOnly Vary: Accept-Encoding - Whole-Content-Sha512: 0twD50R5e7V2DtVrALQxzr2DmeHPPu8rTY8aGU4dFkx4XnOzjeRK5z+SYCrZEZ9Mh8QnWha3yZ2PtlxVTZt1YA== - Content-Length: 225 + Whole-Content-Sha512: S8CMeR3P22itBNYOQaIjiQPMDoq2AzGt0/oBYpMPm1b8/iKeZfGSS4zyt4WYbVJrgrzFZYGUhBEJe6uimQYdCQ== { "alerts": [ { "level": "success", - "text": "Backup configuration CREATE for cache group 11 successful." - } - ], - "response": [ + "text": "Backup configuration CREATE for cache group 7 successful." + }, { - "cacheGroupId": 11, - "fallbackName": "CDN_in_a_Box_Edge", - "fallbackOrder": 1, - "fallbackId": 7, - "cacheGroupName": "test" + "level": "warning", + "text": "This endpoint is deprecated, please use 'POST /cachegroups with a non-empty 'fallbacks' array' instead" } ]} ``PUT`` ======= -Updates an existing fallback configuration for one or more :term:`Cache Groups`. +Updates an existing :ref:`fallback ` configuration for one or more :term:`Cache Groups`. :Auth. Required: Yes :Roles Required: "admin" or "operations" @@ -173,32 +174,31 @@ Updates an existing fallback configuration for one or more :term:`Cache Groups`. 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 :term:`Cache Group` to which to assign a fallback -:fallbackId: Integral, unique identifier of a :term:`Cache Group` on which the :term:`Cache Group` identified by ``cacheGroupId`` will fall back -:fallbackOrder: The order of this fallback for the :term:`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 +:cacheGroupId: An integer that is the :ref:`cache-group-id` of a :term:`Cache Group` to which to assign a :ref:`fallback ` +:fallbackId: An integer that is the :ref:`cache-group-id` of a :term:`Cache Group` on which the :term:`Cache Group` identified by ``cacheGroupId`` will "fall back" +:fallbackOrder: The place in the list of :ref:`cache-group-fallbacks` of the :term:`Cache Group` identified by ``cacheGroupId`` and ``cacheGroupName`` where the :term:`Cache Group` identified by ``fallbackId`` and ``fallbackName`` starting from index 1. .. 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 + PUT /api/1.4/cachegroup_fallbacks HTTP/1.1 + User-Agent: python-requests/2.22.0 + Accept-Encoding: gzip, deflate Accept: */* + Connection: keep-alive Cookie: mojolicious=... - Content-Length: 59 - Content-Type: application/x-www-form-urlencoded + Content-Length: 58 - [{"cacheGroupId": 11, "fallbackId": 7, "fallbackOrder": 2}] + [{"cacheGroupId": 7, "fallbackId": 8, "fallbackOrder": 2}] Response Structure ------------------ -:cacheGroupId: The integral, unique identifier of the :term:`Cache Group` to which this fallback was assigned -:cacheGroupName: The name of the :term:`Cache Group` to which this fallback was assigned -:fallbackId: The integral, unique identifier of the :term:`Cache Group` on which this entries :term:`Cache Group` will fall back -:fallbackName: The name of the :term:`Cache Group` on which this entries :term:`Cache Group` will fall back -:fallbackOrder: The order of the fallback described by "fallbackId" and "fallbackName" in the list of fallbacks for the :term:`Cache Group` described by this entry +:cacheGroupId: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` described by this entry +:cacheGroupName: The :ref:`cache-group-name` of the :term:`Cache Group` described by this entry as a string +:fallbackId: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` on which the :term:`Cache Group` described by this entry will "fall back" +:fallbackName: The :ref:`cache-group-name` of the :term:`Cache Group` on which the :term:`Cache Group` described by this entry will "fall back" as a string +:fallbackOrder: The place in the list of :ref:`cache-group-fallbacks` of the :term:`Cache Group` identified by ``cacheGroupId`` and ``cacheGroupName`` where the :term:`Cache Group` identified by ``fallbackId`` and ``fallbackName`` starting from index 1. .. code-block:: http :caption: Response Example @@ -209,59 +209,65 @@ Response Structure 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-Encoding: gzip + Content-Length: 237 Content-Type: application/json - Date: Thu, 08 Nov 2018 15:07:06 GMT + Date: Mon, 02 Dec 2019 22:28:55 GMT Server: Mojolicious (Perl) - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly + Set-Cookie: mojolicious=...; expires=Tue, 03 Dec 2019 02:28:55 GMT; path=/; HttpOnly Vary: Accept-Encoding - Whole-Content-Sha512: 7QQpwDEmSpSPn6E3FAjxNw3E7xKP3TOBdnvZiBHQwOLmOH6Eiaq58f3eMPYAuK4qMSAKBj9Y2R//Fpa59YCMRw== - Content-Length: 225 + Whole-Content-Sha512: /rGLP3gbnqFUjDhC/4mSYr2a2HoVsGTukxHX8CbURnwDS5LV7U6gwvlOcgtMfEUyX1FEa4+1Xa94tiL/dRFj6w== { "alerts": [ { "level": "success", - "text": "Backup configuration UPDATE for cache group 11 successful." + "text": "Backup configuration UPDATE for cache group 7 successful." + }, + { + "level": "warning", + "text": "This endpoint is deprecated, please use 'PUT /cachegroups' instead" } ], "response": [ { - "cacheGroupId": 11, - "fallbackName": "CDN_in_a_Box_Edge", + "cacheGroupId": 7, "fallbackOrder": 2, - "fallbackId": 7, - "cacheGroupName": "test" + "fallbackName": "test", + "fallbackId": 8, + "cacheGroupName": "CDN_in_a_Box_Edge" } ]} ``DELETE`` ========== -Delete fallback list assigned to a :term:`Cache Group` +Remove one or more :ref:`cache-group-fallbacks` from one or more :term:`Cache Groups`. :Auth. Required: Yes :Roles Required: "admin" or "operations" -:Response Type: Object (string) +:Response Type: ``undefined`` Request Structure ----------------- .. table:: Request Query Parameters - +--------------+----------+-----------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +==============+==========+===========================================================================================================+ - | cacheGroupId |yes\ [2]_ | The integral, unique identifier of a :term:`Cache Group` whose fallback configurations shall be retrieved | - +--------------+----------+-----------------------------------------------------------------------------------------------------------+ - | fallbackId |yes\ [2]_ | The integral, unique identifier of a fallback :term:`Cache Group` | - +--------------+----------+-----------------------------------------------------------------------------------------------------------+ + +--------------+----------+--------------------------------------------------------------------------------------------------------------+ + | Name | Required | Description | + +==============+==========+==============================================================================================================+ + | cacheGroupId |yes\ [2]_ | The :ref:`cache-group-id` of a :term:`Cache Group` from which :ref:`cache-group-fallbacks` are being removed | + +--------------+----------+--------------------------------------------------------------------------------------------------------------+ + | fallbackId |yes\ [2]_ | The :ref:`cache-group-id` of a :ref:`"fallback" ` :term:`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 + DELETE /api/1.4/cachegroup_fallbacks?fallbackId=8 HTTP/1.1 + User-Agent: python-requests/2.22.0 + Accept-Encoding: gzip, deflate Accept: */* + Connection: keep-alive Cookie: mojolicious=... - + Content-Length: 0 Response Structure ------------------ @@ -274,17 +280,24 @@ Response Structure 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-Encoding: gzip + Content-Length: 186 Content-Type: application/json - Date: Thu, 08 Nov 2018 15:48:56 GMT + Date: Mon, 02 Dec 2019 22:30:58 GMT Server: Mojolicious (Perl) - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly + Set-Cookie: mojolicious=...; expires=Tue, 03 Dec 2019 02:30:58 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" - } + Whole-Content-Sha512: iag1k8Ym4K6nrpahJwzyA45m2RO6159gSRg4ozUvg69/TKrTLyggMeAIVdzbwn8+ayOFq01lTK1Ho9jQFJ5j2w== + { "alerts": [ + { + "level": "success", + "text": "Cachegroup 8 DELETED from all the configured fallback lists" + }, + { + "level": "warning", + "text": "This endpoint is deprecated, please use 'PUT /cachegroups with an empty 'fallbacks' array' instead" + } + ]} .. [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 :term:`Cache Group` identified by that integral, unique identifier, and using only "fallbackId" will remove the :term:`Cache Group` identified by *that* integral, unique identifier from all other :term:`Cache Groups`' fallback lists. diff --git a/docs/source/api/cachegroup_parameterID_parameter.rst b/docs/source/api/cachegroup_parameterID_parameter.rst index 4db7783f13..4abd13be3e 100644 --- a/docs/source/api/cachegroup_parameterID_parameter.rst +++ b/docs/source/api/cachegroup_parameterID_parameter.rst @@ -18,10 +18,7 @@ ***************************************** ``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! +.. danger:: This endpoint does not appear to work, and thus its use is strongly discouraged! ``GET`` ======= @@ -35,22 +32,47 @@ Request Structure ----------------- .. table:: Request Path Parameters - +------------------+----------+------------------------------------------------+ - | Name | Required | Description | - +==================+==========+================================================+ - | parameter_ID | yes | An integral, unique identifier for a parameter | - +------------------+----------+------------------------------------------------+ + +--------------+----------+-----------------------+ + | Name | Required | Description | + +==============+==========+=======================+ + | parameter_ID | yes | A :ref:`parameter-id` | + +--------------+----------+-----------------------+ + +.. code-block:: http + :caption: Request Example + + GET /api/1.4/cachegroup/1/parameter HTTP/1.1 + User-Agent: python-requests/2.22.0 + Accept-Encoding: gzip, deflate + Accept: */* + Connection: keep-alive + Cookie: mojolicious=... Response Structure ------------------ :cachegroups: An array of all :term:`Cache Groups` with an associated :term:`Parameter` identifiable by the ``parameter_id`` request path parameter - :id: The integral, unique identifier of the :term:`Cache Group` - :name: The human-readable name of the :term:`Cache Group` + :id: An integer that is the :term:`Cache Group`'s :ref:`cache-group-id` + :name: A string that is the :ref:`cache-group-name` of the :term:`Cache Group` -.. code-block:: json +.. 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-Encoding: gzip + Content-Length: 161 + Content-Type: application/json + Date: Tue, 03 Dec 2019 15:15:26 GMT + Server: Mojolicious (Perl) + Set-Cookie: mojolicious=...; expires=Tue, 03 Dec 2019 19:15:26 GMT; path=/; HttpOnly + Vary: Accept-Encoding + Whole-Content-Sha512: H03AKuJ2IjG3wb6SEplNtIjm8ka3JJdRxc2HyOkNzjHdsh8p7UcJ1teYvYUf8yMNDt8HHBaKzIDoHODLwhktjA== + { "response": { "cachegroups": [ { diff --git a/docs/source/api/cachegroupparameters.rst b/docs/source/api/cachegroupparameters.rst index 45270038f6..06f9a7808d 100644 --- a/docs/source/api/cachegroupparameters.rst +++ b/docs/source/api/cachegroupparameters.rst @@ -21,7 +21,7 @@ ``GET`` ======= -Extract information about :term:`Parameters` associated with :term:`Cache Groups` +Extract information about the :ref:`cache-group-parameters` associated with :term:`Cache Groups`. :Auth. Required: Yes :Roles Required: None @@ -33,11 +33,11 @@ No available parameters Response Structure ------------------ -:cachegroupParameters: An array of identifying information for :term:`Parameters` assigned to :term:`Cache Group` :term:`Profiles` +:cachegroupParameters: An array of identifying information for the :ref:`cache-group-parameters` of :term:`Cache Groups` - :parameter: The :term:`Parameter`'s :ref:`parameter-id` + :cachegroup: A string containing the :ref:`cache-group-name` of the :term:`Cache Group` :last_updated: Date and time of last modification in an ISO-like format - :cachegroup: Name of the :term:`Cache Group` + :parameter: An integer that is the :term:`Parameter`'s :ref:`parameter-id` .. code-block:: http :caption: Response Example @@ -78,8 +78,8 @@ 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 :term:`Cache Group` to which a :term:`Parameter` is being assigned -:parameterId: Integral, unique identifier for the :term:`Parameter` being assigned +:cacheGroupId: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` to which a :term:`Parameter` is being assigned +:parameterId: An integer that is the :ref:`parameter-id` of the :term:`Parameter` being assigned .. code-block:: http :caption: Request Example @@ -99,9 +99,9 @@ The request data can take the form of either a single object or an array of one Response Structure ------------------ -:parameter: Integral, unique identifier of the :term:`Parameter` +:cachegroup: A string containing the :ref:`cache-group-name` of the :term:`Cache Group` :last_updated: Date and time of last modification in an ISO-like format -:cachegroup: Name of the :term:`Cache Group` +:parameter: An integer that is the :term:`Parameter`'s :ref:`parameter-id` .. code-block:: http :caption: Response Example diff --git a/docs/source/api/cachegroupparameters_id_parameterID.rst b/docs/source/api/cachegroupparameters_id_parameterID.rst index 4aa3c91063..a6731b233b 100644 --- a/docs/source/api/cachegroupparameters_id_parameterID.rst +++ b/docs/source/api/cachegroupparameters_id_parameterID.rst @@ -31,13 +31,13 @@ Request Structure ----------------- .. table:: Request Path Parameters - +-------------+---------------------------------------------------------------------------------------------------------+ - | Name | Description | - +=============+=========================================================================================================+ - | ID | Unique identifier for the :term:`Cache Group` which will have the :term:`Parameter` association deleted | - +-------------+---------------------------------------------------------------------------------------------------------+ - | parameterID | Unique identifier for the :term:`Parameter` which will be removed from a :term:`Cache Group` | - +-------------+---------------------------------------------------------------------------------------------------------+ + +-------------+----------------------------------------------------------------------------------------------------------------+ + | Name | Description | + +=============+================================================================================================================+ + | ID | The :ref:`cache-group-id` of the :term:`Cache Group` which will have the :term:`Parameter` association deleted | + +-------------+----------------------------------------------------------------------------------------------------------------+ + | parameterID | The :ref:`parameter-id` of the :term:`Parameter` which will be removed from a :term:`Cache Group` | + +-------------+----------------------------------------------------------------------------------------------------------------+ .. code-block:: http :caption: Request Example diff --git a/docs/source/api/cachegroups.rst b/docs/source/api/cachegroups.rst index afb4465cb9..397a752fae 100644 --- a/docs/source/api/cachegroups.rst +++ b/docs/source/api/cachegroups.rst @@ -31,24 +31,23 @@ Request Structure ----------------- .. table:: Request Query Parameters - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+===============================================================================================================+ - | type | no | Return only :term:`Cache Groups` that are of the :term:`type` identified by this integral, unique identifier | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | orderby | no | Choose the ordering of the results - must be the name of one of the fields of the objects in the ``response`` | - | | | array | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | sortOrder | no | Changes the order of sorting. Either ascending (default or "asc") or descending ("desc") | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | limit | no | Choose the maximum number of results to return | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | offset | no | The number of results to skip before beginning to return results. Must use in conjunction with limit | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | page | no | Return the n\ :sup:`th` page of results, where "n" is the value of this parameter, pages are ``limit`` long | - | | | and the first page is 1. If ``offset`` was defined, this query parameter has no effect. ``limit`` must be | - | | | defined to make use of ``page``. | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ + +-----------+----------+--------------------------------------------------------------------------------------------------------------------------+ + | Name | Required | Description | + +===========+==========+==========================================================================================================================+ + | type | no | Return only :term:`Cache Groups` that are of the :ref:`cache-group-type` identified by this integral, unique identifier | + +-----------+----------+--------------------------------------------------------------------------------------------------------------------------+ + | orderby | no | Choose the ordering of the results - must be the name of one of the fields of the objects in the ``response`` array | + +-----------+----------+--------------------------------------------------------------------------------------------------------------------------+ + | sortOrder | no | Changes the order of sorting. Either ascending (default or "asc") or descending ("desc") | + +-----------+----------+--------------------------------------------------------------------------------------------------------------------------+ + | limit | no | Choose the maximum number of results to return | + +-----------+----------+--------------------------------------------------------------------------------------------------------------------------+ + | offset | no | The number of results to skip before beginning to return results. Must use in conjunction with limit | + +-----------+----------+--------------------------------------------------------------------------------------------------------------------------+ + | page | no | Return the n\ :sup:`th` page of results, where "n" is the value of this parameter, pages are ``limit`` long and the | + | | | first page is 1. If ``offset`` was defined, this query parameter has no effect. ``limit`` must be defined to make use of | + | | | ``page``. | + +-----------+----------+--------------------------------------------------------------------------------------------------------------------------+ .. code-block:: http :caption: Request Example @@ -62,25 +61,31 @@ Request Structure Response Structure ------------------ -:fallbacks: An array of :term:`Cache Group` names that are registered as "fallbacks" for use when this :term:`Cache Group` is unavailable.\ [#fallbacks]_ +:fallbacks: An array of strings that are :ref:`Cache Group names ` that are registered as :ref:`cache-group-fallbacks` for this :term:`Cache Group`\ [#fallbacks]_ .. versionadded:: ATCv4.0 - This field was added to all versions of this endpoint with Apache Traffic Control version 4.0 - -:fallbackToClosest: If ``true``, Traffic Router will direct clients to peers of this :term:`Cache Group` in the event that it becomes unavailable.\ [#fallbacks]_ -:id: A numeric, unique identifier for the :term:`Cache Group` -:lastUpdated: The time and date at which this entry was last updated in ISO format -:latitude: Latitude for the :term:`Cache Group` -:longitude: Longitude for the :term:`Cache Group` -:name: The name of the :term:`Cache Group` entry -:parentCachegroupId: ID of this :term:`Cache Group`'s parent :term:`Cache Group` (if any) -:parentCachegroupName: Name of this :term:`Cache Group`'s parent :term:`Cache Group` (if any) -:secondaryParentCachegroupId: ID of this :term:`Cache Group`'s secondary parent :term:`Cache Group` (if any) -:secondaryParentCachegroupName: Name of this :term:`Cache Group`'s secondary parent :term:`Cache Group` (if any) -:shortName: Abbreviation of the :term:`Cache Group` name -:typeId: Unique identifier for the ':term:`Type`' of :term:`Cache Group` entry -:typeName: The name of the :term:`type` of :term:`Cache Group` entry + This field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0 + +:fallbackToClosest: A boolean value that defines the :ref:`cache-group-fallback-to-closest` behavior of this :term:`Cache Group`\ [#fallbacks]_ +:id: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` +:lastUpdated: The time and date at which this entry was last updated in an ISO-like format +:latitude: A floating-point :ref:`cache-group-latitude` for the :term:`Cache Group` +:localizationMethods: An array of :ref:`cache-group-localization-methods` as strings + + .. versionadded:: ATCv4.0 + + This field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0 + +:longitude: A floating-point :ref:`cache-group-longitude` for the :term:`Cache Group` +:name: A string containing the :ref:`cache-group-name` of the :term:`Cache Group` +:parentCachegroupId: An integer that is the :ref:`cache-group-id` of this :term:`Cache Group`'s :ref:`cache-group-parent` - or ``null`` if it doesn't have a :ref:`cache-group-parent` +:parentCachegroupName: A string containing the :ref:`cache-group-name` of this :term:`Cache Group`'s :ref:`cache-group-parent` - or ``null`` if it doesn't have a :ref:`cache-group-parent` +:secondaryParentCachegroupId: An integer that is the :ref:`cache-group-id` of this :term:`Cache Group`'s :ref:`cache-group-secondary-parent` - or ``null`` if it doesn't have a :ref:`cache-group-secondary-parent` +:secondaryParentCachegroupName: A string containing the :ref:`cache-group-name` of this :term:`Cache Group`'s :ref:`cache-group-secondary-parent` :term:`Cache Group` - or ``null`` if it doesn't have a :ref:`cache-group-secondary-parent` +:shortName: A string containing the :ref:`cache-group-short-name` of the :term:`Cache Group` +:typeId: An integral, unique identifier for the ':term:`Type`' of the :term:`Cache Group` +:typeName: A string that names the :ref:`cache-group-type` of this :term:`Cache Group` .. note:: The default value of ``fallbackToClosest`` is 'true', and if it is 'null' Traffic Control components will still interpret it as 'true'. @@ -130,34 +135,33 @@ Creates a :term:`Cache Group` Request Structure ----------------- -:fallbacks: An optional field which, when present, should contain an array of names of other :term:`Cache Groups` on which the Traffic Router will fall back in the event that this :term:`Cache Group` fails/becomes unavailable\ [#fallbacks]_ +:fallbacks: An optional field which, when present, should contain an array of strings that are the :ref:`Names ` of other :term:`Cache Groups` which will be the :ref:`cache-group-fallbacks`\ [#fallbacks]_ .. versionadded:: ATCv4.0 Support for this field was added to all versions of this endpoint with Apache Traffic Control version 4.0 -:fallbackToClosest: If ``true``, the Traffic Router will fall back on the 'closest' :term:`Cache Group` to this one, when this one fails\ [#fallbacks]_ +:fallbackToClosest: A boolean that sets the :ref:`cache-group-fallback-to-closest` behavior of the :term:`Cache Group`\ [#fallbacks]_ + + .. note:: The default value of ``fallbackToClosest`` is ``true``, and if it is ``null`` Traffic Control components will still interpret it as though it were ``true``. - .. 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, should be a floating-point number that will define the :ref:`cache-group-latitude` for the :term:`Cache Group`\ [#optional]_ +:localizationMethods: Array of :ref:`cache-group-localization-methods` (as strings) -:latitude: An optional field which, if present, will define the latitude for the :term:`Cache Group` to ISO-standard double specification\ [#optional]_ -:longitude: An optional field which, if present, will define the longitude for the :term:`Cache Group` to ISO-standard double specification\ [#optional]_ -:localizationMethods: Array of enabled localization methods (as strings) -:fallbacks: Array of fallback server hostnames. -:name: The name of the :term:`Cache Group` -:parentCachegroupId: An optional field which, if present, should be an integral, unique identifier for this :term:`Cache Group`'s primary parent + .. versionadded:: ATCv4.0 + + Support for this field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0. + + .. tip:: This field has no defined meaning if the :ref:`cache-group-type` identified by ``typeId`` is not "EDGE_LOC". + +:longitude: An optional field which, if present, should be a floating-point number that will define the :ref:`cache-group-longitude` for the :term:`Cache Group`\ [#optional]_ +:name: The :ref:`cache-group-name` of the :term:`Cache Group` +:parentCachegroupId: An optional field which, if present, should be an integer that is the :ref:`cache-group-id` of a :ref:`cache-group-parent` for this :term:`Cache Group`. :secondaryParentCachegroupId: An optional field which, if present, should be an integral, unique identifier for this :term:`Cache Group`'s secondary parent :shortName: An abbreviation of the ``name`` -:typeId: An integral, unique identifier for the :term:`type` of :term:`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) +:typeId: An integral, unique identifier for the :ref:`Cache Group's Type ` - .. note:: The actual, integral, unique identifiers for these types must first be obtained, generally via :ref:`to-api-types`. + .. note:: The actual, integral, unique identifiers for these :term:`Types` must first be obtained, generally via :ref:`to-api-types`. .. code-block:: http :caption: Request Example @@ -168,44 +172,49 @@ Request Structure Accept: */* Cookie: mojolicious=... Content-Length: 252 - Content-Type: application/x-www-form-urlencoded + Content-Type: application/json { - "fallbackToClosest": false, - "latitude": 0, - "longitude": 0, - "localizationMethods": [], - "fallbacks": [], "name": "test", - "parentCachegroupId": 7, "shortName": "test", - "typeId": 23 + "latitude": 0, + "longitude": 0, + "fallbackToClosest": true, + "localizationMethods": [ + "DEEP_CZ", + "CZ", + "GEO" + ], + "typeId": 23, } Response Structure ------------------ -:fallbacks: An array of :term:`Cache Group` names that are registered as "fallbacks" for use when this :term:`Cache Group` is unavailable\ [#fallbacks]_ +:fallbacks: An array of strings that are :ref:`Cache Group names ` that are registered as :ref:`cache-group-fallbacks` for this :term:`Cache Group`\ [#fallbacks]_ .. versionadded:: ATCv4.0 - This field was added to all versions of this endpoint with Apache Traffic Control version 4.0 - -:fallbackToClosest: If ``true``, Traffic Router will direct clients to peers of this :term:`Cache Group` in the event that it becomes unavailable\ [#fallbacks]_ -:id: A numeric, unique identifier for the :term:`Cache Group` -:lastUpdated: The time and date at which this entry was last updated in ISO format -:latitude: Latitude for the :term:`Cache Group` -:longitude: Longitude for the :term:`Cache Group` -:localizationMethods: Array of enabled localization methods (as strings) -:fallbacks: Array of fallback server hostnames -:name: The name of the :term:`Cache Group` entry -:parentCachegroupId: ID of this :term:`Cache Group`'s parent :term:`Cache Group` (if any) -:parentCachegroupName: Name of this :term:`Cache Group`'s parent :term:`Cache Group` (if any) -:secondaryParentCachegroupId: ID of this :term:`Cache Group`'s secondary parent :term:`Cache Group` (if any) -:secondaryParentCachegroupName: Name of this :term:`Cache Group`'s secondary parent :term:`Cache Group` (if any) -:shortName: Abbreviation of the :term:`Cache Group` name -:typeId: Unique identifier for the ':term:`Type`' of :term:`Cache Group` entry -:typeName: The name of the :term:`type` of :term:`Cache Group` entry + This field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0 +:fallbackToClosest: A boolean value that defines the :ref:`cache-group-fallback-to-closest` behavior of this :term:`Cache Group`\ [#fallbacks]_ +:id: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` +:lastUpdated: The time and date at which this entry was last updated in an ISO-like format +:latitude: A floating-point :ref:`cache-group-latitude` for the :term:`Cache Group` +:localizationMethods: An array of :ref:`cache-group-localization-methods` as strings + + .. versionadded:: ATCv4.0 + + This field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0 + +:longitude: A floating-point :ref:`cache-group-longitude` for the :term:`Cache Group` +:name: A string containing the :ref:`cache-group-name` of the :term:`Cache Group` +:parentCachegroupId: An integer that is the :ref:`cache-group-id` of this :term:`Cache Group`'s :ref:`cache-group-parent` - or ``null`` if it doesn't have a :ref:`cache-group-parent` +:parentCachegroupName: A string containing the :ref:`cache-group-name` of this :term:`Cache Group`'s :ref:`cache-group-parent` - or ``null`` if it doesn't have a :ref:`cache-group-parent` +:secondaryParentCachegroupId: An integer that is the :ref:`cache-group-id` of this :term:`Cache Group`'s :ref:`cache-group-secondary-parent` - or ``null`` if it doesn't have a :ref:`cache-group-secondary-parent` +:secondaryParentCachegroupName: A string containing the :ref:`cache-group-name` of this :term:`Cache Group`'s :ref:`cache-group-secondary-parent` :term:`Cache Group` - or ``null`` if it doesn't have a :ref:`cache-group-secondary-parent` +:shortName: A string containing the :ref:`cache-group-short-name` of the :term:`Cache Group` +:typeId: An integral, unique identifier for the ':term:`Type`' of the :term:`Cache Group` +:typeName: A string that names the :ref:`cache-group-type` of this :term:`Cache Group` .. code-block:: http :caption: Response Example @@ -229,26 +238,26 @@ Response Structure } ], "response": { - "id": 10, + "id": 8, "name": "test", "shortName": "test", "latitude": 0, "longitude": 0, - "parentCachegroupName": "CDN_in_a_Box_Mid", - "parentCachegroupId": 7, + "parentCachegroupName": null, + "parentCachegroupId": null, "secondaryParentCachegroupName": null, "secondaryParentCachegroupId": null, - "fallbackToClosest": false, - "localizationMethods": [], - "fallbacks": [], + "fallbackToClosest": true, + "localizationMethods": [ + "DEEP_CZ", + "CZ", + "GEO" + ], "typeName": "EDGE_LOC", "typeId": 23, - "lastUpdated": "2018-11-07 22:11:50+00" + "lastUpdated": "2019-12-02 22:21:08+00", + "fallbacks": [] }} .. [#fallbacks] Traffic Router will first check for a ``fallbacks`` array and, when that is empty/unset/all the :term:`Cache Groups` in it are also unavailable, will subsequently check for ``fallbackToClosest``. If that is ``true``, then it falls back to the geographically closest :term:`Cache Group` capable of serving the same content or, when it is ``false``/no such :term:`Cache Group` exists/said :term:`Cache Group` is also unavailable, will respond to clients with a failure response indicating the problem. .. [#optional] 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 :term:`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 index e25b65beb5..bdf2d7e4cf 100644 --- a/docs/source/api/cachegroups_id.rst +++ b/docs/source/api/cachegroups_id.rst @@ -49,42 +49,39 @@ Request Structure .. table:: Request Path Parameters - +--------------+---------------------------------------------------------------+ - | Parameter | Description | - +==============+===============================================================+ - | ID | The integral, unique identifier of a :term:`Cache Group` | - +--------------+---------------------------------------------------------------+ + +--------------+----------------------------------------------------+ + | Parameter | Description | + +==============+====================================================+ + | ID | The :ref:`cache-group-id` of a :term:`Cache Group` | + +--------------+----------------------------------------------------+ Response Structure ------------------ -:fallbacks: An array of :term:`Cache Group` names that are registered as "fallbacks" for use when this :term:`Cache Group` is unavailable\ [#fallbacks]_ +:fallbacks: An array of strings that are :ref:`Cache Group names ` that are registered as :ref:`cache-group-fallbacks` for this :term:`Cache Group`\ [#fallbacks]_ .. versionadded:: ATCv4.0 - This field was added to all versions of this endpoint with Apache Traffic Control version 4.0 - -:fallbackToClosest: If ``true``, Traffic Router will direct clients to peers of this :term:`Cache Group` in the event that it becomes unavailable\ [#fallbacks]_ -:id: Integral, unique identifier for the :term:`Cache Group` -:lastUpdated: The date and time at which this :term:`Cache Group` was last updated, in an ISO-like format -:latitude: Latitude of the :term:`Cache Group` -:localizationMethods: An array of strings that name the localization methods enabled for this :term:`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 :term:`Cache Group` -:name: The name of the :term:`Cache Group` -:parentCachegroupId: Integral, unique identifier of the :term:`Cache Group` that is this :term:`Cache Group`'s parent -:parentCachegroupName: The name of the :term:`Cache Group` that is this :term:`Cache Group`'s parent -:secondaryParentCachegroupId: Integral, unique identifier of the :term:`Cache Group` that is this :term:`Cache Group`'s secondary parent -:secondaryParentCachegroupName: The name of the :term:`Cache Group` that is this :term:`Cache Group`'s secondary parent -:shortName: Abbreviation of the :term:`Cache Group` Name -:typeId: The integral, unique identifier for the :term:`Type` of :term:`Cache Group` -:typeName: The name of the :term:`type` of this :term:`Cache Group` + This field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0 + +:fallbackToClosest: A boolean value that defines the :ref:`cache-group-fallback-to-closest` behavior of this :term:`Cache Group`\ [#fallbacks]_ +:id: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` +:lastUpdated: The time and date at which this entry was last updated in an ISO-like format +:latitude: A floating-point :ref:`cache-group-latitude` for the :term:`Cache Group` +:localizationMethods: An array of :ref:`cache-group-localization-methods` as strings + + .. versionadded:: ATCv4.0 + + This field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0 + +:longitude: A floating-point :ref:`cache-group-longitude` for the :term:`Cache Group` +:name: A string containing the :ref:`cache-group-name` of the :term:`Cache Group` +:parentCachegroupId: An integer that is the :ref:`cache-group-id` of this :term:`Cache Group`'s :ref:`cache-group-parent` - or ``null`` if it doesn't have a :ref:`cache-group-parent` +:parentCachegroupName: A string containing the :ref:`cache-group-name` of this :term:`Cache Group`'s :ref:`cache-group-parent` - or ``null`` if it doesn't have a :ref:`cache-group-parent` +:secondaryParentCachegroupId: An integer that is the :ref:`cache-group-id` of this :term:`Cache Group`'s :ref:`cache-group-secondary-parent` - or ``null`` if it doesn't have a :ref:`cache-group-secondary-parent` +:secondaryParentCachegroupName: A string containing the :ref:`cache-group-name` of this :term:`Cache Group`'s :ref:`cache-group-secondary-parent` :term:`Cache Group` - or ``null`` if it doesn't have a :ref:`cache-group-secondary-parent` +:shortName: A string containing the :ref:`cache-group-short-name` of the :term:`Cache Group` +:typeId: An integral, unique identifier for the ':term:`Type`' of the :term:`Cache Group` +:typeName: A string that names the :ref:`cache-group-type` of this :term:`Cache Group` .. note:: The default value of ``fallbackToClosest`` is 'true', and if it is 'null' Traffic Control components will still interpret it as 'true'. @@ -139,40 +136,39 @@ Request Structure ----------------- .. table:: Request Path Parameters - +--------------+---------------------------------------------------------------+ - | Parameter | Description | - +==============+===============================================================+ - | ID | The integral, unique identifier of a :term:`Cache Group` | - +--------------+---------------------------------------------------------------+ + +-----------+----------------------------------------------------+ + | Parameter | Description | + +===========+====================================================+ + | ID | The :ref:`cache-group-id` of a :term:`Cache Group` | + +-----------+----------------------------------------------------+ -:fallbacks: An optional field which, when present, should contain an array of names of other :term:`Cache Groups` on which the Traffic Router will fall back in the event that this :term:`Cache Group` fails/becomes unavailable\ [#fallbacks]_ +:fallbacks: An optional field which, when present, should contain an array of strings that are the :ref:`Names ` of other :term:`Cache Groups` which will be the :ref:`cache-group-fallbacks`\ [#fallbacks]_ .. versionadded:: ATCv4.0 - Support for this field was added to all versions of this endpoint with Apache Traffic Control version 4.0 + Support for this field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0. + +:fallbackToClosest: A boolean that sets the :ref:`cache-group-fallback-to-closest` behavior of the :term:`Cache Group`\ [#fallbacks]_ -:fallbackToClosest: An optional field which, if present and ``true``, will cause Traffic Router to direct clients to peers of this :term:`Cache Group` in the event that it becomes unavailable\ [#fallbacks]_ + .. note:: The default value of ``fallbackToClosest`` is ``true``, and if it is ``null`` Traffic Control components will still interpret it as though it were ``true``. - .. 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 present, should be a floating-point number that will define the :ref:`cache-group-latitude` for the :term:`Cache Group`\ [#optional]_ +:localizationMethods: Array of :ref:`cache-group-localization-methods` (as strings) -:latitude: An optional field which, if specified, will set the latitude of the new :term:`Cache Group`\ [#optional]_ -:localizationMethods: An optional array of strings that name the localization methods enabled for this :term:`Cache Group`. Each of the three available localization methods may be present, with the following meanings: + .. versionadded:: ATCv4.0 - 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 + Support for this field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0. -:longitude: An optional field which, if specified, will set the longitude of the new :term:`Cache Group`\ [#optional]_ -:name: The desired name of the :term:`Cache Group` entry -:parentCachegroup: An optional field which, if specified, should be the integral, unique identifier of :term:`Cache Group` to use as the new :term:`Cache Group`'s parent -:secondaryParentCachegroup: An optional field which, if specified, should be the integral, unique identifier of :term:`Cache Group` to use as the new :term:`Cache Group`'s parent -:shortName: A more human-friendly abbreviation of the :term:`Cache Group`'s name -:typeId: The integral, unique identifier of the desired :term:`type` of the new :term:`Cache Group` - by default the valid options are: "EDGE_LOC", "MID_LOC" or "ORG_LOC" + .. tip:: This field has no defined meaning if the :ref:`cache-group-type` identified by ``typeId`` is not "EDGE_LOC". - .. note:: Rather than the actual name of the :term:`type`, be sure to use the "database ID" of the desired :term:`type`. Typically this will require looking up the types via the API first, as the IDs of even these default types is not deterministic. +:longitude: An optional field which, if present, should be a floating-point number that will define the :ref:`cache-group-longitude` for the :term:`Cache Group`\ [#optional]_ +:name: The :ref:`cache-group-name` of the :term:`Cache Group` +:parentCachegroupId: An optional field which, if present, should be an integer that is the :ref:`cache-group-id` of a :ref:`cache-group-parent` for this :term:`Cache Group`. +:secondaryParentCachegroupId: An optional field which, if present, should be an integral, unique identifier for this :term:`Cache Group`'s secondary parent +:shortName: An abbreviation of the ``name`` +:typeId: An integral, unique identifier for the :ref:`Cache Group's Type ` + + .. note:: The actual, integral, unique identifiers for these :term:`Types` must first be obtained, generally via :ref:`to-api-types`. .. code-block:: http :caption: Request Example @@ -198,34 +194,31 @@ Request Structure Response Structure ------------------ -:fallbacks: An array of :term:`Cache Group` names that are registered as "fallbacks" for use when this :term:`Cache Group` is unavailable\ [#fallbacks]_ +:fallbacks: An array of strings that are :ref:`Cache Group names ` that are registered as :ref:`cache-group-fallbacks` for this :term:`Cache Group`\ [#fallbacks]_ + + .. versionadded:: ATCv4.0 + + This field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0 + +:fallbackToClosest: A boolean value that defines the :ref:`cache-group-fallback-to-closest` behavior of this :term:`Cache Group`\ [#fallbacks]_ +:id: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` +:lastUpdated: The time and date at which this entry was last updated in an ISO-like format +:latitude: A floating-point :ref:`cache-group-latitude` for the :term:`Cache Group` +:localizationMethods: An array of :ref:`cache-group-localization-methods` as strings .. versionadded:: ATCv4.0 - This field was added to all versions of this endpoint with Apache Traffic Control version 4.0 - -:fallbackToClosest: If ``true``, Traffic Router will direct clients to peers of this :term:`Cache Group` in the event that it becomes unavailable\ [#fallbacks]_ -:id: Integral, unique identifier for the :term:`Cache Group` -:lastUpdated: The date and time at which this :term:`Cache Group` was last updated, in an ISO-like format -:latitude: Latitude of the :term:`Cache Group` -:localizationMethods: An array of strings that name the localization methods enabled for this :term:`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 :term:`Cache Group` -:name: The name of the :term:`Cache Group` -:parentCachegroupId: Integral, unique identifier of the :term:`Cache Group` that is this :term:`Cache Group`'s parent -:parentCachegroupName: The name of the :term:`Cache Group` that is this :term:`Cache Group`'s parent -:secondaryParentCachegroupId: Integral, unique identifier of the :term:`Cache Group` that is this :term:`Cache Group`'s secondary parent -:secondaryParentCachegroupName: The name of the :term:`Cache Group` that is this :term:`Cache Group`'s secondary parent -:shortName: Abbreviation of the :term:`Cache Group` Name -:typeId: The integral, unique identifier for the :term:`Type` of :term:`Cache Group` -:typeName: The name of the :term:`Type` of this :term:`Cache Group` + This field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0 + +:longitude: A floating-point :ref:`cache-group-longitude` for the :term:`Cache Group` +:name: A string containing the :ref:`cache-group-name` of the :term:`Cache Group` +:parentCachegroupId: An integer that is the :ref:`cache-group-id` of this :term:`Cache Group`'s :ref:`cache-group-parent` - or ``null`` if it doesn't have a :ref:`cache-group-parent` +:parentCachegroupName: A string containing the :ref:`cache-group-name` of this :term:`Cache Group`'s :ref:`cache-group-parent` - or ``null`` if it doesn't have a :ref:`cache-group-parent` +:secondaryParentCachegroupId: An integer that is the :ref:`cache-group-id` of this :term:`Cache Group`'s :ref:`cache-group-secondary-parent` - or ``null`` if it doesn't have a :ref:`cache-group-secondary-parent` +:secondaryParentCachegroupName: A string containing the :ref:`cache-group-name` of this :term:`Cache Group`'s :ref:`cache-group-secondary-parent` :term:`Cache Group` - or ``null`` if it doesn't have a :ref:`cache-group-secondary-parent` +:shortName: A string containing the :ref:`cache-group-short-name` of the :term:`Cache Group` +:typeId: An integral, unique identifier for the ':term:`Type`' of the :term:`Cache Group` +:typeName: A string that names the :ref:`cache-group-type` of this :term:`Cache Group` .. code-block:: http :caption: Response Example @@ -271,7 +264,7 @@ Response Structure ``DELETE`` ========== -Delete :term:`Cache Group`. :term:`Cache Groups` which have assigned servers or child :term:`Cache Groups` cannot be deleted. +Delete a :term:`Cache Group`. A :term:`Cache Group` which has assigned servers or is the :ref:`cache-group-parent` of one or more other :term:`Cache Groups` cannot be deleted. :Auth. Required: Yes :Roles Required: "admin" or "operations" @@ -281,11 +274,11 @@ Request Structure ----------------- .. table:: Request Path Parameters - +--------------+------------------------------------------------------------------------+ - | Parameter | Description | - +==============+========================================================================+ - | ID | The integral, unique identifier of a :term:`Cache Group` to be deleted | - +--------------+------------------------------------------------------------------------+ + +-----------+------------------------------------------------------------------+ + | Parameter | Description | + +===========+==================================================================+ + | ID | The :ref:`cache-group-id` of a :term:`Cache Group` to be deleted | + +-----------+------------------------------------------------------------------+ .. code-block:: http :caption: Request Example diff --git a/docs/source/api/cachegroups_id_deliveryservices.rst b/docs/source/api/cachegroups_id_deliveryservices.rst index bc5210c57a..77434980ff 100644 --- a/docs/source/api/cachegroups_id_deliveryservices.rst +++ b/docs/source/api/cachegroups_id_deliveryservices.rst @@ -21,7 +21,9 @@ ``POST`` ======== -Assigns a :term:`Cache Group` to one or more :term:`Delivery Services` +Assigns all of the "assignable" servers within a :term:`Cache Group` to one or more :term:`Delivery Services`. + +.. note:: "Assignable" here means all of the :ref:`Cache Group's servers ` that have a :term:`Type` that matches one of the glob patterns ``EDGE*`` or ``ORG*``. If even one server of any :term:`Type` exists within the :term:`Cache Group` that is not assigned to the same CDN as the :term:`Delivery Service` to which an attempt is being made to assign them, the request will fail. :Auth. Required: Yes :Roles Required: "admin" or "operations" @@ -31,13 +33,13 @@ Request Structure ----------------- .. table::Request Path Parameters - +------+---------------------------------------------------------------------------+ - | Name | Description | - +======+===========================================================================+ - | ID | The integral, unique identifier of the :term:`Cache Group` being assigned | - +------+---------------------------------------------------------------------------+ + +------+-----------------------------------------------------------------------------------+ + | Name | Description | + +======+===================================================================================+ + | ID | The :ref:`cache-group-id` of the :term:`Cache Group` from which to assign servers | + +------+-----------------------------------------------------------------------------------+ -:deliveryServices: The integral, unique identifiers of the :term:`Delivery Services` to which the :term:`Cache Group` is being assigned +:deliveryServices: The integral, unique identifiers of the :term:`Delivery Services` to which the :ref:`Cache Group's servers ` are being assigned .. code-block:: http :caption: Request Example @@ -48,15 +50,15 @@ Request Structure Accept: */* Cookie: mojolicious=... Content-Length: 25 - Content-Type: application/x-www-form-urlencoded + Content-Type: application/json {"deliveryServices": [2]} Response Structure ------------------ -:deliveryServices: An array of *all* :term:`Delivery Services` to which the :term:`Cache Group` is assigned (**not** just the one(s) to which it was assigned via the request) -:id: The :term:`Cache Group`\ 's ID -:serverNames: An array of the (short) hostnames of all servers in the :term:`Cache Group` +:deliveryServices: An array of integral, unique identifiers for :term:`Delivery Services` to which the :ref:`Cache Group's servers ` have been assigned +:id: An integer that is the :ref:`Cache Group's ID ` +:serverNames: An array of the (short) hostnames of all of the :term:`Cache Group`'s "assignable" :ref:`cache-group-servers` .. code-block:: http :caption: Response Example diff --git a/docs/source/api/cachegroups_id_parameters.rst b/docs/source/api/cachegroups_id_parameters.rst index 7ed7f0fa95..5b0789ab56 100644 --- a/docs/source/api/cachegroups_id_parameters.rst +++ b/docs/source/api/cachegroups_id_parameters.rst @@ -18,10 +18,11 @@ ********************************* ``cachegroups/{{ID}}/parameters`` ********************************* -Gets all the :term:`Parameters` associated with a :term:`Cache Group` ``GET`` ======= +Gets all of a :ref:`Cache Group's parameters `. + :Auth. Required: Yes :Roles Required: None :Response Type: Array @@ -33,7 +34,7 @@ Request Structure +-------------+----------+---------------------------------------------------------------------------------------------------------------+ | Name | Required | Description | +=============+==========+===============================================================================================================+ - | parameterId | no | Show only the :term:`Parameter` with the given ID | + | parameterId | no | Show only the :term:`Parameter` with the given :ref:`parameter-id` | +-------------+----------+---------------------------------------------------------------------------------------------------------------+ | orderby | no | Choose the ordering of the results - must be the name of one of the fields of the objects in the ``response`` | | | | array | @@ -54,7 +55,7 @@ Request Structure +-----------+----------------------------------------------------------+ | Parameter | Description | +===========+==========================================================+ - | ID | The integral, unique identifier of a :term:`Cache Group` | + | ID | The :ref:`cache-group-id` of a :term:`Cache Group` | +-----------+----------------------------------------------------------+ diff --git a/docs/source/api/cachegroups_id_queue_update.rst b/docs/source/api/cachegroups_id_queue_update.rst index 148e597454..5ff8640628 100644 --- a/docs/source/api/cachegroups_id_queue_update.rst +++ b/docs/source/api/cachegroups_id_queue_update.rst @@ -21,7 +21,7 @@ ``POST`` ======== -:term:`Queue` or "dequeue" updates for all servers assigned to a :term:`Cache Group` limited to a specific CDN. +:term:`Queue` or "dequeue" updates for all of a :ref:`Cache Group's servers `, limited to a specific CDN. :Auth. Required: Yes :Roles Required: "admin" or "operations" @@ -31,11 +31,11 @@ Request Structure ----------------- .. table:: Request Path Parameters - +------+---------------------------------------------------------------------------------------------------------+ - | Name | Description | - +======+=========================================================================================================+ - | ID | The integral, unique identifier for the :term:`Cache Group` for which updates are being queued/dequeued | - +------+---------------------------------------------------------------------------------------------------------+ + +------+------------------------------------------------------------------------------------------------------------+ + | Name | Description | + +======+============================================================================================================+ + | ID | The :ref:`cache-group-id` of the :term:`Cache Group` for which updates are being :term:`Queue`\ d/dequeued | + +------+------------------------------------------------------------------------------------------------------------+ :action: The action to perform; one of "queue" or "dequeue" :cdn: The full name of the CDN in need of :term:`Queue Updates`, or a "dequeue" thereof\ [#required]_ @@ -58,10 +58,10 @@ Request Structure Response Structure ------------------ :action: The action processed, one of "queue" or "dequeue" -:cachegroupId: The integral, unique identifier of the :term:`Cache Group` for which :term:`Queue Updates` was performed or cleared +:cachegroupId: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` for which :term:`Queue Updates` was performed or cleared :cachegroupName: The name of the :term:`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 :term:`Cache Group` which are also assigned to the CDN specified in the ``"cdn"`` field +:serverNames: An array of the (short) hostnames of the :ref:`Cache Group's servers ` which are also assigned to the CDN specified in the ``"cdn"`` field .. code-block:: http :caption: Response Example diff --git a/docs/source/api/cachegroups_id_unassigned_parameters.rst b/docs/source/api/cachegroups_id_unassigned_parameters.rst index d00410ae2f..60efa732f7 100644 --- a/docs/source/api/cachegroups_id_unassigned_parameters.rst +++ b/docs/source/api/cachegroups_id_unassigned_parameters.rst @@ -21,7 +21,7 @@ ``GET`` ======= -Gets all the :term:`Parameters` *not* associated with a specific :term:`Cache Group` +Gets all the :term:`Parameters` that are *not* a specific :ref:`Cache Group's parameters `. :Auth. Required: Yes :Roles Required: None @@ -52,11 +52,11 @@ Request Structure .. table:: Request Path Parameters - +------------------+----------+---------------------------------------------------------+ - | Name | Required | Description | - +==================+==========+=========================================================+ - | ``id`` | yes | An integral, unique identifier of a :term:`Cache Group` | - +------------------+----------+---------------------------------------------------------+ + +--------+----------+----------------------------------------------------+ + | Name | Required | Description | + +========+==========+====================================================+ + | ``id`` | yes | The :ref:`cache-group-id` of a :term:`Cache Group` | + +--------+----------+----------------------------------------------------+ Response Structure diff --git a/docs/source/api/cachegroups_parameterID_parameter_available.rst b/docs/source/api/cachegroups_parameterID_parameter_available.rst index f2646131c7..404a980e9e 100644 --- a/docs/source/api/cachegroups_parameterID_parameter_available.rst +++ b/docs/source/api/cachegroups_parameterID_parameter_available.rst @@ -18,14 +18,11 @@ **************************************************** ``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! +.. danger:: This endpoint does not appear to work, and thus its use is strongly discouraged! ``GET`` ======= -Gets a list of :term:`Cache Groups` which are available to have a specific :term:`Parameter` assigned to them +Gets a list of :term:`Cache Groups` which are available to have a specific :term:`Parameter` assigned to them. :Auth. Required: Yes :Roles Required: None @@ -36,15 +33,15 @@ Request Structure .. table:: Request Path Parameters +------------------+----------+--------------------------------------------------------------+ - | Name | Required | Description | + | Name | Required | Description | +==================+==========+==============================================================+ | ``parameter ID`` | yes | The :ref:`parameter-id` of the :term:`Parameter` of interest | +------------------+----------+--------------------------------------------------------------+ Response Structure ------------------ -:id: An integral, unique identifier for the :term:`Cache Group` -:name: The name of the :term:`Cache Group` +:id: An integer that is the :ref:`Cache Group's ID ` +:name: A string that is the :ref:`Cache Group's name ` .. code-block:: json :caption: Response Example diff --git a/docs/source/api/cachegroups_trimmed.rst b/docs/source/api/cachegroups_trimmed.rst index 4041187673..e0a87efd2a 100644 --- a/docs/source/api/cachegroups_trimmed.rst +++ b/docs/source/api/cachegroups_trimmed.rst @@ -18,7 +18,7 @@ *********************** ``cachegroups/trimmed`` *********************** -Extract just the names of all :term:`Cache Groups`. +Extract just the :ref:`Names ` of all :term:`Cache Groups`. ``GET`` ======= @@ -32,7 +32,7 @@ No parameters available Response Structure ------------------ -:name: The name of the :term:`Cache Group` | +:name: A string that is a :ref:`Cache Group's Name ` .. code-block:: http :caption: Response Example diff --git a/docs/source/api/caches_stats.rst b/docs/source/api/caches_stats.rst index d87ab23842..ef0430fe7f 100644 --- a/docs/source/api/caches_stats.rst +++ b/docs/source/api/caches_stats.rst @@ -21,7 +21,7 @@ **************** 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`. +.. seealso:: This gives a set of basic statistics for *all* :term:`cache servers` at the current time. For statistics from time ranges and/or aggregated over a specific CDN, use :ref:`to-api-cache_stats`. ``GET`` ======= @@ -37,17 +37,17 @@ No parameters available. Response Structure ------------------ -:cachegroup: The name of the :term:`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 +:cachegroup: A string that is the :ref:`cache-group-name` of the :term:`Cache Group` to which this :term:`cache server` belongs +:connections: Current number of TCP connections maintained by the :term:`cache server` +:healthy: ``true`` if Traffic Monitor has marked the :term:`cache server` 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 +:hostname: The (short) hostname of the :term:`cache server` +:ip: The IP address of the :term:`cache server` +:kbps: The :term:`cache server`'s upload speed (to clients) in Kilobits per second :profile: The :ref:`profile-name` of the :term:`Profile` in use by this :term:`cache server` -:status: The status of the cache +:status: The status of the :term:`cache server` .. code-block:: http :caption: Response Example diff --git a/docs/source/api/cdns_configs.rst b/docs/source/api/cdns_configs.rst index dfe090087c..066732658e 100644 --- a/docs/source/api/cdns_configs.rst +++ b/docs/source/api/cdns_configs.rst @@ -17,10 +17,8 @@ **************** ``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. +.. danger:: This endpoint does not appear to work, and thus its use is strongly discouraged! ``GET`` ======= diff --git a/docs/source/api/cdns_id_snapshot.rst b/docs/source/api/cdns_id_snapshot.rst index ef46b9e75c..880bbcaed4 100644 --- a/docs/source/api/cdns_id_snapshot.rst +++ b/docs/source/api/cdns_id_snapshot.rst @@ -18,8 +18,6 @@ ************************ ``cdns/{{ID}}/snapshot`` ************************ -.. deprecated:: 1.1 - Use :ref:`to-api-snapshot-name` instead. ``PUT`` ======= 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 index c616c9eb27..bcd963f0d2 100644 --- 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 @@ -19,14 +19,12 @@ ``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 `_ for more information. +.. danger:: 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 :issue:`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. +Retrieves :term:`Edge-tier` metrics of one or all :term:`Cache Groups`. :Auth. Required: Yes :Roles Required: None diff --git a/docs/source/api/cdns_name_configs_monitoring.rst b/docs/source/api/cdns_name_configs_monitoring.rst index eb60a238be..c1a92b79bb 100644 --- a/docs/source/api/cdns_name_configs_monitoring.rst +++ b/docs/source/api/cdns_name_configs_monitoring.rst @@ -41,14 +41,14 @@ Request Structure Response Structure ------------------ -:cacheGroups: An array of objects representing each of the Cache Groups being monitored within this CDN +:cacheGroups: An array of objects representing each of the :term:`Cache Groups` being monitored within this CDN - :coordinates: An object representing the physical location of this Cache Group + :coordinates: An object representing the geographic location of this :term:`Cache Group` - :latitude: The geographic latitude of this Cache Group - :longitude: The geographic longitude of this Cache Group + :latitude: This :ref:`Cache Group's latitude ` as a floating-point number + :longitude: This :ref:`Cache Group's longitude ` as a floating-point number - :name: The name of this Cache Group + :name: A string that is this :ref:`Cache Group's name ` :config: A collection of parameters used to configure the monitoring behaviour of Traffic Monitor @@ -67,45 +67,48 @@ Response Structure :status: The :term:`Delivery Service`'s status :totalKbpsThreshold: A threshold rate of data transfer this :term:`Delivery Service` is configured to handle, in Kilobits per second :totalTpsThreshold: A threshold amount of transactions per second that this :term:`Delivery Service` is configured to handle - :xmlId: An integral, unique identifier for this Deliver Service (named "xmlId" for legacy reasons) + :xmlId: A string that is the :ref:`Delivery Service's XMLID ` :profiles: An array of the :term:`Profiles` in use by the :term:`cache servers` and :term:`Delivery Services` belonging to this CDN - :name: The :term:`Profile`'s :ref:`profile-name` + :name: A string that is the :ref:`Profile's Name ` :parameters: An array of the :term:`Parameters` in this :term:`Profile` that relate to monitoring configuration. This can be ``null`` if the servers using this :term:`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 + :health.threshold.loadavg: The UNIX loadavg at which the server should be marked "unhealthy" - :type: The :ref:`profile-type` of the :term:`Profile` + .. seealso:: :manpage:`uptime(1)` + + :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: A string that names the :ref:`Profile's Type ` :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 + :fqdn: An :abbr:`FQDN (Fully Qualified Domain Name)` that resolves to the IPv4 (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 + :ip: The IPv4 address of this Traffic Monitor :port: The port on which this Traffic Monitor listens for incoming connections - :profile: The :ref:`profile-name` of the :term:`Profile` assigned to this Traffic Monitor + :profile: A string that is the :ref:`profile-name` of the :term:`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 :term:`cache servers` 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 :term:`cache server`'s IP (or IPv6) address - :hashId: The short name for the :term:`cache server` - named "hashId" for legacy reasons + :cacheGroup: The :term:`Cache Group` to which this :term:`cache server` belongs + :fqdn: An :abbr:`FQDN (Fully Qualified Domain Name)` that resolves to the :term:`cache server`'s IPv4 (or IPv6) address + :hashId: The (short) hostname for the :term:`cache server` - named "hashId" for legacy reasons :hostName: The (short) hostname of the :term:`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 :ref:`profile-name` of the :term:`Profile` assigned to this :term:`cache server` - :status: The status of the Cache - :type: The type of the cache - should be either ``EDGE`` or ``MID`` + :interfacename: The name of the network interface device being used by the :term:`cache server`'s HTTP proxy + :ip6: The :term:`cache server`'s IPv6 address - when applicable + :ip: The :term:`cache server`'s IPv4 address + :port: The port on which the :term:`cache server` listens for incoming connections + :profile: A string that is the :ref:`profile-name` of the :term:`Profile` assigned to this :term:`cache server` + :status: The status of the :term:`cache server` + :type: A string that names the :term:`Type` of the :term:`cache server` - should (ideally) be either ``EDGE`` or ``MID`` .. code-block:: http :caption: Response Example diff --git a/docs/source/api/cdns_name_configs_routing.rst b/docs/source/api/cdns_name_configs_routing.rst index d1bca9b79a..28d967f1a1 100644 --- a/docs/source/api/cdns_name_configs_routing.rst +++ b/docs/source/api/cdns_name_configs_routing.rst @@ -18,7 +18,7 @@ ********************************* ``cdns/{{name}}/configs/routing`` ********************************* -.. caution:: This API route is currently broken, see `GitHub issue #2941 `_ for more information. +.. caution:: This API route is currently broken, see :issue:`2941` for more information. ``GET`` ======= @@ -40,9 +40,9 @@ Request Structure Response Structure ------------------ -:cacheGroups: A collection of cache groups. +:cacheGroups: A collection of objects that represent :term:`Cache Groups`. - :coordinates: object + :coordinates: An object that represents the geographic location of the :term:`Cache Group` :latitude: number :longitude: number diff --git a/docs/source/api/cdns_name_dnsseckeys_ksk_generate.rst b/docs/source/api/cdns_name_dnsseckeys_ksk_generate.rst index 62eaf9ea7a..ce7013acc0 100644 --- a/docs/source/api/cdns_name_dnsseckeys_ksk_generate.rst +++ b/docs/source/api/cdns_name_dnsseckeys_ksk_generate.rst @@ -23,7 +23,7 @@ ``POST`` ======== -Generates a new Key-Signing Key (KSK) for a specific CDN. +Generates a new :abbr:`KSK (Key-Signing Key)` for a specific CDN. :Auth. Required: Yes :Roles Required: "admin" @@ -33,21 +33,14 @@ 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 `_ format - defaults to the current time | - +--------------------+----------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ + +------+----------+-----------------------------------------------------------------------------------+ + | Name | Required | Description | + +======+==========+===================================================================================+ + | name | yes | The name of the CDN for which the :abbr:`KSK (Key-Signing Key)` will be generated | + +------+----------+-----------------------------------------------------------------------------------+ + +:expirationDays: The integral number of days until the newly generated :abbr:`KSK (Key-Signing Key)` expires +:effectiveDate: An optional string containing the date and time at which the newly generated :abbr:`KSK (Key-Signing Key)` becomes effective, in :RFC:`3339` format. Defaults to the current time if not specified Response Structure ------------------ diff --git a/docs/source/api/cdns_name_health.rst b/docs/source/api/cdns_name_health.rst index b1da707acb..48fbd22f72 100644 --- a/docs/source/api/cdns_name_health.rst +++ b/docs/source/api/cdns_name_health.rst @@ -37,16 +37,26 @@ Request Structure | name | The name of the CDN for which health will be reported | +------+-------------------------------------------------------+ +.. code-block:: http + :caption: Request Example + + GET /api/1.4/cdns/CDN-in-a-Box/health HTTP/1.1 + User-Agent: python-requests/2.22.0 + Accept-Encoding: gzip, deflate + Accept: */* + Connection: keep-alive + Cookie: mojolicious=... + Response Structure ------------------ :cachegroups: An array of objects describing the health of each :term:`Cache Group` - :name: The name of the :term:`Cache Group` - :offline: The number of OFFLINE caches in the :term:`Cache Group` - :online: The number of ONLINE caches in the :term:`Cache Group` + :name: A string that is the :ref:`Cache Group's Name ` + :offline: The number of OFFLINE :term:`cache servers` in the :term:`Cache Group` + :online: The number of ONLINE :term:`cache servers` in the :term:`Cache Group` -:totalOffline: Total number of OFFLINE caches across all :term:`Cache Groups` which are assigned to the CDN defined by the ``name`` request path parameter -:totalOnline: Total number of ONLINE caches across all :term:`Cache Groups` which are assigned to the CDN defined by the ``name`` request path parameter +:totalOffline: Total number of OFFLINE :term:`cache servers` across all :term:`Cache Groups` which are assigned to the CDN defined by the ``name`` request path parameter +:totalOnline: Total number of ONLINE :term:`cache servers` across all :term:`Cache Groups` which are assigned to the CDN defined by the ``name`` request path parameter .. code-block:: http :caption: Response Example @@ -57,13 +67,14 @@ Response Structure 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-Encoding: gzip + Content-Length: 108 Content-Type: application/json - Date: Wed, 14 Nov 2018 21:14:05 GMT + Date: Tue, 03 Dec 2019 21:33:59 GMT Server: Mojolicious (Perl) - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly + Set-Cookie: mojolicious=...; expires=Wed, 04 Dec 2019 01:33:59 GMT; path=/; HttpOnly Vary: Accept-Encoding Whole-Content-Sha512: KpXViXeAgch58ueQqdyU8NuINBw1EUedE6Rv2ewcLUajJp6kowdbVynpwW7XiSvAyHdtClIOuT3OkhIimghzSA== - Content-Length: 115 { "response": { "totalOffline": 0, diff --git a/docs/source/api/cdns_name_name_dnsseckeys.rst b/docs/source/api/cdns_name_name_dnsseckeys.rst index 26dccd56c0..e87af7860a 100644 --- a/docs/source/api/cdns_name_name_dnsseckeys.rst +++ b/docs/source/api/cdns_name_name_dnsseckeys.rst @@ -21,7 +21,7 @@ ``GET`` ======= -Gets a list of DNSSEC keys for CDN and all associated :term:`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. +Gets a list of DNSSEC keys for CDN and all associated :term:`Delivery Services`. Before returning response to user, this will make sure DNSSEC keys for all :term:`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" @@ -41,7 +41,7 @@ Response Structure ------------------ :name: The name of the CDN or :term:`Delivery Service` to which the enclosed keys belong - :zsk: The short-term Zone-Signing Key (ZSK) + :zsk: The short-term :abbr:`ZSK (Zone-Signing Key)` :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 @@ -50,10 +50,12 @@ Response Structure :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) + :ksk: The long-term :abbr:`KSK (Key-Signing Key)` :dsRecord: An optionally present object containing information about the algorithm used to generate the key + .. versionadded:: 1.2 + :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`` @@ -65,9 +67,6 @@ Response Structure :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 diff --git a/docs/source/api/cdns_name_name_sslkeys.rst b/docs/source/api/cdns_name_name_sslkeys.rst index b4ec4118a4..15125970c3 100644 --- a/docs/source/api/cdns_name_name_sslkeys.rst +++ b/docs/source/api/cdns_name_name_sslkeys.rst @@ -44,7 +44,7 @@ Response Structure :key: Base 64-encoded private key for SSL certificate :crt: Base 64-encoded SSL certificate -:deliveryservice: The ``xml_id`` of the :term:`Delivery Service` using the SSL key within ``certificate`` +:deliveryservice: A string that is the :ref:`ds-xmlid` of the :term:`Delivery Service` using the SSL key within ``certificate`` .. code-block:: json :caption: Response Example diff --git a/docs/source/api/cdns_name_snapshot.rst b/docs/source/api/cdns_name_snapshot.rst index 311af26b24..7281f0fcb1 100644 --- a/docs/source/api/cdns_name_snapshot.rst +++ b/docs/source/api/cdns_name_snapshot.rst @@ -51,11 +51,7 @@ 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 - + :api.cache-control.max-age: A string containing an integer which specifies the value of ``max-age`` in the :mailheader:`Cache-Control` header of some HTTP responses, likely the :ref:`tr-api` responses :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" @@ -65,7 +61,7 @@ Response Structure 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 + :coveragezone.polling.url: The URL where a :term:`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.dynamic.concurrencylevel: An integer that defines the size of the concurrency level (threads) of the Guava cache used by ZoneManager to store zone material :dnssec.dynamic.initialcapacity: An integer that defines the initial size of the Guava cache, default is 10000. Too low of a value can lead to expensive resizing @@ -77,7 +73,7 @@ Response Structure "true" DNSSEC is used within this CDN - :domain_name: The Top-Level Domain Name (TLD) served by the CDN + :domain_name: A string that is the :abbr:`TLD (Top-Level Domain)` served by the CDN :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 @@ -85,15 +81,15 @@ Response Structure :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``) + :soa: An object defining the :abbr:`SOA (Start of Authority)` for the CDN's :abbr:`TLD (Top-Level Domain)` (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 + :minimum: A string containing an integer that sets the :abbr:`TTL (Time To Live)` - 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 :abbr:`SOA (Start of Authority)` 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` dictates that this should always be less than ``refresh``. @@ -108,26 +104,26 @@ Response Structure :contentRouters: An object containing keys which are the (short) hostnames of the Traffic Routers that serve requests for :term:`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 via HTTP - :secure.api.port: A string containing the port number on which the :ref:`tr-api` is served by this Traffic Router via HTTPS (optional) - :fqdn: This Traffic Router's Fully Qualified Domain Name (FQDN) + :secure.api.port: An optionally present string containing the port number on which the :ref:`tr-api` is served by this Traffic Router via HTTPS + :fqdn: This Traffic Router's :abbr:`FQDN (Fully Qualified Domain Name)` :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 + :location: A string which is the :ref:`cache-group-name` of the :term:`Cache Group` to which this Traffic Router belongs :port: The port number on which this Traffic Router listens for incoming HTTP requests :profile: The :ref:`profile-name` of the :term:`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 :term:`cache servers` in the CDN; the values corresponding to those keys are routing information for said servers +:contentServers: An object containing keys which are the (short) hostnames of the :term:`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 :term:`Delivery Services` to which this :term:`cache server` is assigned; the values corresponding to those keys are arrays of FQDNs that resolve to this :term:`cache server` + :cacheGroup: A string that is the :ref:`cache-group-name` of the :term:`Cache Group` to which the server belongs + :deliveryServices: An object containing keys which are the names of :term:`Delivery Services` to which this :term:`cache server` is assigned; the values corresponding to those keys are arrays of :abbr:`FQDNs (Fully Qualified Domain Names)` that resolve to this :term:`cache server` - .. note:: Only Edge-tier :term:`cache servers` can be assigned to a Delivery SErvice, and therefore this field will only be present when ``type`` is ``"EDGE"``. + .. note:: Only :term:`Edge-tier cache servers` can be assigned to a :term:`Delivery Service`, and therefore this field will only be present when ``type`` is ``"EDGE"``. - :fqdn: The server's Fully Qualified Domain Name (FQDN) + :fqdn: The server's :abbr:`FQDN (Fully Qualified Domain Name)` :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 :term:`cache server` listens for incoming HTTPS requests @@ -137,7 +133,7 @@ Response Structure :locationId: This field is exactly the same as ``cacheGroup`` and only exists for legacy compatibility reasons :port: The port on which this :term:`cache server` listens for incoming HTTP requests :profile: The :ref:`profile-name` of the :term:`Profile` used by the :term:`cache server` - :routingDisabled: An integer representing the boolean concept of whether or not Traffic Routers should route client traffic this :term:`cache server`; one of: + :routingDisabled: An integer representing the boolean concept of whether or not Traffic Routers should route client traffic to this :term:`cache server`; one of: 0 Do not route traffic to this server @@ -148,16 +144,16 @@ Response Structure .. seealso:: :ref:`health-proto` - :type: The type of this :term:`cache server`; one of: + :type: The :term:`Type` of this :term:`cache server`; which ought to be one of (but in practice need not be in certain special circumstances): EDGE - This is an Edge-tier :term:`cache server` + This is an :term:`Edge-tier cache server` MID - This is a Mid-tier :term:`cache server` + This is a :term:`Mid-tier cache server` -:deliveryServices: An object containing keys which are the 'xml_id's of all of the :term:`Delivery Services` within the CDN +:deliveryServices: An object containing keys which are the :ref:`xml_ids ` of all of the :term:`Delivery Services` within the CDN - :anonymousBlockingEnabled: A string containing a boolean that tells whether or not Anonymized IP Addresses are blocked by this :term:`Delivery Service`; one of: + :anonymousBlockingEnabled: A string containing a boolean that tells whether or not :ref:`ds-anonymous-blocking` is set on this :term:`Delivery Service`; one of: "true" Anonymized IP addresses are blocked by this :term:`Delivery Service` @@ -169,37 +165,34 @@ Response Structure :consistentHashQueryParameters: A set of query parameters that Traffic Router should consider when determining a consistent hash for a given client request. .. versionadded:: ATCv4 - This endpoint does not, in general, obey the same versioning rules as all others. So this will appear in all API versions, but *only* if the Traffic Ops server is on version 4+ + This field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0. :consistentHashRegex: An optional regular expression that will ensure clients are consistently routed to a :term:`cache server` based on matches to it. .. versionadded:: ATCv4 - This endpoint does not, in general, obey the same versioning rules as all others. So this will appear in all API versions, but *only* if the Traffic Ops server is on version 4+ + This field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0. - :coverageZoneOnly: A string containing a boolean that tells whether or not this :term:`Delivery Service` routes traffic based only on its Coverage Zone file - :deepCachingType: A string that tells when Deep Caching is used by this :term:`Delivery Service`; one of: + :coverageZoneOnly: A string containing a boolean that tells whether or not this :term:`Delivery Service` routes traffic based only on its :term:`Coverage Zone File` - "ALWAYS" - Deep Caching is always used by this :term:`Delivery Service` - "NEVER" - Deep Caching is never used by this :term:`Delivery Service` + .. seealso:: :ref:`ds-geo-limit` - :dispersion: An object describing the "dispersion" - or number of caches within a single Cache Group across which the same content is spread - within the :term:`Delivery Service` + :deepCachingType: A string that defines the :ref:`ds-deep-caching` setting of this :term:`Delivery Service` + :dispersion: An object describing the "dispersion" - or number of :term:`cache servers` within a single :term:`Cache Group` across which the same content is spread - within the :term:`Delivery Service` - :limit: The maximum number of caches in which the response to a single request URL will be stored + :limit: The maximum number of :term:`cache servers` 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. + .. note:: If this is greater than the number of :term:`cache servers` in the :term:`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: + :shuffled: A string containing a boolean that tells whether the :term:`cache servers` 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 + :term:`Cache servers` will be chosen consistently "true" - Caches will be chosen at random + :term:`Cache servers` will be chosen at random :domains: An array of domains served by this :term:`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 :term:`Delivery Service`; one of: + :ip6RoutingEnabled: A string containing a boolean that defines the :ref:`ds-ipv6-routing` setting for this :term:`Delivery Service`; one of: "false" IPv6 traffic will not be routed by this :term:`Delivery Service` @@ -210,21 +203,21 @@ Response Structure :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 :term:`Delivery Service` + :type: The name of the :term:`Type` of match performed using ``pattern`` to determine whether or not to use this :term:`Delivery Service` HOST_REGEXP - Use the :term:`Delivery Service` if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request, or the name requested for resolution in a DNS request + Use the :term:`Delivery Service` if ``pattern`` matches the :mailheader:`Host` HTTP header of an HTTP request, or the name requested for resolution in a DNS request HEADER_REGEXP Use the :term:`Delivery Service` if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [#httpOnly]_ PATH_REGEXP Use the :term:`Delivery Service` if ``pattern`` matches the request path of this :term:`Delivery Service`'s URL\ [#httpOnly]_ STEERING_REGEXP - Use the :term:`Delivery Service` if ``pattern`` matches the ``xml_id`` of one of this :term:`Delivery Service`'s "Steering" target :term:`Delivery Services` + Use the :term:`Delivery Service` if ``pattern`` matches the :ref:`ds-xmlid` of one of this :term:`Delivery Service`'s "Steering" target :term:`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 + :missLocation: An object representing the default geographic coordinates to use for a client when lookup of their IP has failed in both the :term:`Coverage Zone File` (and/or possibly the :term:`Deep Coverage Zone File`) and the IP-to-geographic-location database - :lat: Geographic latitude - :long: Geographic longitude + :lat: Geographic latitude as a floating point number + :long: Geographic longitude as a floating point number :protocol: An object that describes how the :term:`Delivery Service` ought to handle HTTP requests both with and without TLS encryption @@ -242,7 +235,9 @@ Response Structure "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 :term:`Delivery Service`; one of: + .. seealso:: :ref:`ds-protocol` + + :regionalGeoBlocking: A string containing a boolean that defines the :ref:`ds-regionalgeo` setting of this :term:`Delivery Service`; one of: "false" Regional Geographic Blocking is not used by this :term:`Delivery Service` @@ -251,16 +246,16 @@ Response Structure .. seealso:: :ref:`regionalgeo-qht` - :routingName: The highest-level part of the FQDNs serviced by this :term:`Delivery Service` - :soa: An object defining the Start of Authority (SOA) record for the :term:`Delivery Service`'s TLDs (defined in ``domains``) + :routingName: A string that is this :ref:`Delivery Service's Routing Name ` + :soa: An object defining the :abbr:`SOA (Start of Authority)` record for the :term:`Delivery Service`'s :abbr:`TLDs (Top-Level Domains)` (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 + :minimum: A string containing an integer that sets the :abbr:`TTL (Time To Live)` - 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 :abbr:`SOA (Start of Authority)` 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` dictates that this should always be less than ``refresh``. @@ -274,36 +269,38 @@ Response Structure "true" SSL is used by this :term:`Delivery Service` + .. seealso:: :ref:`ds-protocol` + :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 +:edgeLocations: An object containing keys which are the names of Edge-Tier :term:`Cache Groups` within the CDN - :backupLocations: An object that describes fallbacks for when this Cache Group is unavailable + :backupLocations: An object that describes this :ref:`Cache Group's Fallbacks ` - :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: + :fallbackToClosest: A string containing a boolean which defines the :ref:`cache-group-fallback-to-closest` behavior of this :term:`Cache Group`; one of: "false" - Do not fall back on the closest available Cache Group + Do not fall back on the closest available :term:`Cache Group` "true" - Fall back on the closest available Cache Group + Fall back on the closest available :term:`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 + :list: If this :term:`Cache Group` has any :ref:`cache-group-fallbacks`, this key will appear and will be an array of those :ref:`Cache Groups' Names ` - :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 + :latitude: A floating point number that defines this :ref:`Cache Group's Latitude ` + :localizationMethods: An array of strings that represents this :ref:`Cache Group's Localization Methods ` + :longitude: A floating point number that defines this :ref:`Cache Group's Longitude ` :monitors: An object containing keys which are the (short) hostnames of Traffic Monitors within this CDN - :fqdn: The FQDN of this Traffic Monitor + :fqdn: The :abbr:`FQDN (Fully Qualified Domain Name)` 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 :term:`Cache Group` to which this Traffic Monitor belongs + :location: A string which is the :ref:`cache-group-name` of the :term:`Cache Group` to which this Traffic Monitor belongs :port: The port number on which this Traffic Monitor listens for incoming HTTP requests - :profile: The :ref:`profile-name` of the :term:`Profile` used by this Traffic Monitor + :profile: A string which is the :ref:`profile-name` of the :term:`Profile` used by this Traffic Monitor .. note:: For legacy reasons, this must always start with "RASCAL-". @@ -313,31 +310,27 @@ Response Structure :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 :term:`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`. - + :CDN_name: The name of this CDN + :date: The UNIX epoch timestamp date in the Traffic Ops server's own timezone + :tm_host: The :abbr:`FQDN (Fully Qualified Domain Name)` 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 :term:`Snapshot` overwritten by the current *configured state* of the CDN :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 +:trafficRouterLocations: An object containing keys which are the :ref:`names of Cache Groups ` within the CDN which contain Traffic Routers - :backupLocations: An object that describes fallbacks for when this Cache Group is unavailable + :backupLocations: An object that describes this :ref:`Cache Group's Fallbacks ` - :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: + :fallbackToClosest: A string containing a boolean which defines this :ref:`Cache Group's Fallback to Closest ` setting; one of: "false" - Do not fall back on the closest available Cache Group + Do not fall back on the closest available :term:`Cache Group` "true" - Fall back on the closest available Cache Group + Fall back on the closest available :term:`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 + :latitude: A floating point number that defines this :ref:`Cache Group's Latitude ` + :localizationMethods: An array of strings that represents this :ref:`Cache Group's Localization Methods ` + :longitude: A floating point number that defines this :ref:`Cache Group's Longitude ` .. code-block:: http :caption: Response Example diff --git a/docs/source/api/cdns_name_snapshot_new.rst b/docs/source/api/cdns_name_snapshot_new.rst index 1bd572d75a..25ee2ae58c 100644 --- a/docs/source/api/cdns_name_snapshot_new.rst +++ b/docs/source/api/cdns_name_snapshot_new.rst @@ -50,11 +50,7 @@ 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 - + :api.cache-control.max-age: A string containing an integer which specifies the value of ``max-age`` in the :mailheader:`Cache-Control` header of some HTTP responses, likely the :ref:`tr-api` responses :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" @@ -64,7 +60,7 @@ Response Structure 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 + :coveragezone.polling.url: The URL where a :term:`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.dynamic.concurrencylevel: An integer that defines the size of the concurrency level (threads) of the Guava cache used by ZoneManager to store zone material :dnssec.dynamic.initialcapacity: An integer that defines the initial size of the Guava cache, default is 10000. Too low of a value can lead to expensive resizing @@ -76,7 +72,7 @@ Response Structure "true" DNSSEC is used within this CDN - :domain_name: The Top-Level Domain Name (TLD) served by the CDN + :domain_name: A string that is the :abbr:`TLD (Top-Level Domain)` served by the CDN :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 @@ -84,15 +80,15 @@ Response Structure :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``) + :soa: An object defining the :abbr:`SOA (Start of Authority)` for the CDN's :abbr:`TLD (Top-Level Domain)` (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 + :minimum: A string containing an integer that sets the :abbr:`TTL (Time To Live)` - 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 :abbr:`SOA (Start of Authority)` 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` dictates that this should always be less than ``refresh``. @@ -107,12 +103,12 @@ Response Structure :contentRouters: An object containing keys which are the (short) hostnames of the Traffic Routers that serve requests for :term:`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 via HTTP - :secure.api.port: A string containing the port number on which the :ref:`tr-api` is served by this Traffic Router via HTTPS (optional) - :fqdn: This Traffic Router's Fully Qualified Domain Name (FQDN) + :secure.api.port: An optionally present string containing the port number on which the :ref:`tr-api` is served by this Traffic Router via HTTPS + :fqdn: This Traffic Router's :abbr:`FQDN (Fully Qualified Domain Name)` :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 :term:`Cache Group` to which this Traffic Router belongs + :location: A string which is the :ref:`cache-group-name` of the :term:`Cache Group` to which this Traffic Router belongs :port: The port number on which this Traffic Router listens for incoming HTTP requests :profile: The :ref:`profile-name` of the :term:`Profile` used by this Traffic Router :status: The health status of this Traffic Router @@ -121,12 +117,12 @@ Response Structure :contentServers: An object containing keys which are the (short) hostnames of the :term:`Edge-Tier cache servers` in the CDN; the values corresponding to those keys are routing information for said servers - :cacheGroup: The name of the :term:`Cache Group` to which the server belongs - :deliveryServices: An object containing keys which are the names of :term:`Delivery Services` to which this :term:`cache server` is assigned; the values corresponding to those keys are arrays of FQDNs that resolve to this :term:`cache server` + :cacheGroup: A string that is the :ref:`cache-group-name` of the :term:`Cache Group` to which the server belongs + :deliveryServices: An object containing keys which are the names of :term:`Delivery Services` to which this :term:`cache server` is assigned; the values corresponding to those keys are arrays of :abbr:`FQDNs (Fully Qualified Domain Names)` that resolve to this :term:`cache server` - .. note:: Only Edge-tier :term:`cache servers` can be assigned to a Delivery SErvice, and therefore this field will only be present when ``type`` is ``"EDGE"``. + .. note:: Only :term:`Edge-tier cache servers` can be assigned to a :term:`Delivery Service`, and therefore this field will only be present when ``type`` is ``"EDGE"``. - :fqdn: The server's Fully Qualified Domain Name (FQDN) + :fqdn: The server's :abbr:`FQDN (Fully Qualified Domain Name)` :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 :term:`cache server` listens for incoming HTTPS requests @@ -136,7 +132,7 @@ Response Structure :locationId: This field is exactly the same as ``cacheGroup`` and only exists for legacy compatibility reasons :port: The port on which this :term:`cache server` listens for incoming HTTP requests :profile: The :ref:`profile-name` of the :term:`Profile` used by the :term:`cache server` - :routingDisabled: An integer representing the boolean concept of whether or not Traffic Routers should route client traffic this :term:`cache server`; one of: + :routingDisabled: An integer representing the boolean concept of whether or not Traffic Routers should route client traffic to this :term:`cache server`; one of: 0 Do not route traffic to this server @@ -147,16 +143,16 @@ Response Structure .. seealso:: :ref:`health-proto` - :type: The type of this :term:`cache server`; one of: + :type: The :term:`Type` of this :term:`cache server`; which ought to be one of (but in practice need not be in certain special circumstances): EDGE - This is an Edge-tier :term:`cache server` + This is an :term:`Edge-tier cache server` MID - This is a Mid-tier :term:`cache server` + This is a :term:`Mid-tier cache server` -:deliveryServices: An object containing keys which are the 'xml_id's of all of the :term:`Delivery Services` within the CDN +:deliveryServices: An object containing keys which are the :ref:`xml_ids ` of all of the :term:`Delivery Services` within the CDN - :anonymousBlockingEnabled: A string containing a boolean that tells whether or not Anonymized IP Addresses are blocked by this :term:`Delivery Service`; one of: + :anonymousBlockingEnabled: A string containing a boolean that tells whether or not :ref:`ds-anonymous-blocking` is set on this :term:`Delivery Service`; one of: "true" Anonymized IP addresses are blocked by this :term:`Delivery Service` @@ -168,37 +164,34 @@ Response Structure :consistentHashQueryParameters: A set of query parameters that Traffic Router should consider when determining a consistent hash for a given client request. .. versionadded:: ATCv4 - This endpoint does not, in general, obey the same versioning rules as all others. So this will appear in all API versions, but *only* if the Traffic Ops server is on version 4+ + This field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0. :consistentHashRegex: An optional regular expression that will ensure clients are consistently routed to a :term:`cache server` based on matches to it. .. versionadded:: ATCv4 - This endpoint does not, in general, obey the same versioning rules as all others. So this will appear in all API versions, but *only* if the Traffic Ops server is on version 4+ + This field was added to all versions of this endpoint with :abbr:`ATC (Apache Traffic Control)` version 4.0. - :coverageZoneOnly: A string containing a boolean that tells whether or not this :term:`Delivery Service` routes traffic based only on its Coverage Zone file - :deepCachingType: A string that tells when Deep Caching is used by this :term:`Delivery Service`; one of: + :coverageZoneOnly: A string containing a boolean that tells whether or not this :term:`Delivery Service` routes traffic based only on its :term:`Coverage Zone File` - "ALWAYS" - Deep Caching is always used by this :term:`Delivery Service` - "NEVER" - Deep Caching is never used by this :term:`Delivery Service` + .. seealso:: :ref:`ds-geo-limit` - :dispersion: An object describing the "dispersion" - or number of caches within a single Cache Group across which the same content is spread - within the :term:`Delivery Service` + :deepCachingType: A string that defines the :ref:`ds-deep-caching` setting of this :term:`Delivery Service` + :dispersion: An object describing the "dispersion" - or number of :term:`cache servers` within a single :term:`Cache Group` across which the same content is spread - within the :term:`Delivery Service` - :limit: The maximum number of caches in which the response to a single request URL will be stored + :limit: The maximum number of :term:`cache servers` 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. + .. note:: If this is greater than the number of :term:`cache servers` in the :term:`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: + :shuffled: A string containing a boolean that tells whether the :term:`cache servers` 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 + :term:`Cache servers` will be chosen consistently "true" - Caches will be chosen at random + :term:`Cache servers` will be chosen at random :domains: An array of domains served by this :term:`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 :term:`Delivery Service`; one of: + :ip6RoutingEnabled: A string containing a boolean that defines the :ref:`ds-ipv6-routing` setting for this :term:`Delivery Service`; one of: "false" IPv6 traffic will not be routed by this :term:`Delivery Service` @@ -209,21 +202,21 @@ Response Structure :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 :term:`Delivery Service` + :type: The name of the :term:`Type` of match performed using ``pattern`` to determine whether or not to use this :term:`Delivery Service` HOST_REGEXP - Use the :term:`Delivery Service` if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request, or the name requested for resolution in a DNS request + Use the :term:`Delivery Service` if ``pattern`` matches the :mailheader:`Host` HTTP header of an HTTP request, or the name requested for resolution in a DNS request HEADER_REGEXP Use the :term:`Delivery Service` if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [#httpOnly]_ PATH_REGEXP Use the :term:`Delivery Service` if ``pattern`` matches the request path of this :term:`Delivery Service`'s URL\ [#httpOnly]_ STEERING_REGEXP - Use the :term:`Delivery Service` if ``pattern`` matches the ``xml_id`` of one of this :term:`Delivery Service`'s "Steering" target :term:`Delivery Services` + Use the :term:`Delivery Service` if ``pattern`` matches the :ref:`ds-xmlid` of one of this :term:`Delivery Service`'s "Steering" target :term:`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 + :missLocation: An object representing the default geographic coordinates to use for a client when lookup of their IP has failed in both the :term:`Coverage Zone File` (and/or possibly the :term:`Deep Coverage Zone File`) and the IP-to-geographic-location database - :lat: Geographic latitude - :long: Geographic longitude + :lat: Geographic latitude as a floating point number + :long: Geographic longitude as a floating point number :protocol: An object that describes how the :term:`Delivery Service` ought to handle HTTP requests both with and without TLS encryption @@ -241,7 +234,9 @@ Response Structure "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 :term:`Delivery Service`; one of: + .. seealso:: :ref:`ds-protocol` + + :regionalGeoBlocking: A string containing a boolean that defines the :ref:`ds-regionalgeo` setting of this :term:`Delivery Service`; one of: "false" Regional Geographic Blocking is not used by this :term:`Delivery Service` @@ -250,16 +245,16 @@ Response Structure .. seealso:: :ref:`regionalgeo-qht` - :routingName: The highest-level part of the FQDNs serviced by this :term:`Delivery Service` - :soa: An object defining the Start of Authority (SOA) record for the :term:`Delivery Service`'s TLDs (defined in ``domains``) + :routingName: A string that is this :ref:`Delivery Service's Routing Name ` + :soa: An object defining the :abbr:`SOA (Start of Authority)` record for the :term:`Delivery Service`'s :abbr:`TLDs (Top-Level Domains)` (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 + :minimum: A string containing an integer that sets the :abbr:`TTL (Time To Live)` - 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 :abbr:`SOA (Start of Authority)` 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` dictates that this should always be less than ``refresh``. @@ -273,67 +268,68 @@ Response Structure "true" SSL is used by this :term:`Delivery Service` + .. seealso:: :ref:`ds-protocol` + :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 +:edgeLocations: An object containing keys which are the names of Edge-Tier :term:`Cache Groups` within the CDN - :backupLocations: An object that describes fallbacks for when this Cache Group is unavailable + :backupLocations: An object that describes this :ref:`Cache Group's Fallbacks ` - :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: + :fallbackToClosest: A string containing a boolean which defines the :ref:`cache-group-fallback-to-closest` behavior of this :term:`Cache Group`; one of: "false" - Do not fall back on the closest available Cache Group + Do not fall back on the closest available :term:`Cache Group` "true" - Fall back on the closest available Cache Group + Fall back on the closest available :term:`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 + :list: If this :term:`Cache Group` has any :ref:`cache-group-fallbacks`, this key will appear and will be an array of those :ref:`Cache Groups' Names ` - :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 + :latitude: A floating point number that defines this :ref:`Cache Group's Latitude ` + :localizationMethods: An array of strings that represents this :ref:`Cache Group's Localization Methods ` + :longitude: A floating point number that defines this :ref:`Cache Group's Longitude ` :monitors: An object containing keys which are the (short) hostnames of Traffic Monitors within this CDN - :fqdn: The FQDN of this Traffic Monitor + :fqdn: The :abbr:`FQDN (Fully Qualified Domain Name)` 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 :term:`Cache Group` to which this Traffic Monitor belongs + :location: A string which is the :ref:`cache-group-name` of the :term:`Cache Group` to which this Traffic Monitor belongs :port: The port number on which this Traffic Monitor listens for incoming HTTP requests - :profile: The :ref:`profile-name` of the :term:`Profile` used by this Traffic Monitor - :status: The health status of this Traffic Monitor + :profile: A string which is the :ref:`profile-name` of the :term:`Profile` used by this Traffic Monitor - .. seealso:: :ref:`health-proto` + .. note:: For legacy reasons, this must always start with "RASCAL-". -:stats: An object containing metadata information regarding the CDN + :status: The health status of this Traffic Monitor - :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 :term:`Snapshot` overwritten by the current *configured state* of the CDN + .. seealso:: :ref:`health-proto` - .. 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`. +: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 :abbr:`FQDN (Fully Qualified Domain Name)` 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 :term:`Snapshot` overwritten by the current *configured state* of the CDN :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 +:trafficRouterLocations: An object containing keys which are the :ref:`names of Cache Groups ` within the CDN which contain Traffic Routers - :backupLocations: An object that describes fallbacks for when this Cache Group is unavailable + :backupLocations: An object that describes this :ref:`Cache Group's Fallbacks ` - :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: + :fallbackToClosest: A string containing a boolean which defines this :ref:`Cache Group's Fallback to Closest ` setting; one of: "false" - Do not fall back on the closest available Cache Group + Do not fall back on the closest available :term:`Cache Group` "true" - Fall back on the closest available Cache Group + Fall back on the closest available :term:`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 + :latitude: A floating point number that defines this :ref:`Cache Group's Latitude ` + :localizationMethods: An array of strings that represents this :ref:`Cache Group's Localization Methods ` + :longitude: A floating point number that defines this :ref:`Cache Group's Longitude ` .. code-block:: http diff --git a/docs/source/api/cdns_routing.rst b/docs/source/api/cdns_routing.rst index d5334e200b..bda64f8c69 100644 --- a/docs/source/api/cdns_routing.rst +++ b/docs/source/api/cdns_routing.rst @@ -21,7 +21,7 @@ ``GET`` ======= -Retrieves the aggregate routing percentages of Cache Groups assigned to any CDN. +Retrieves the aggregate routing percentages of :term:`Cache Groups` assigned to any CDN. :Auth. Required: Yes :Roles Required: None diff --git a/docs/source/api/consistenthash.rst b/docs/source/api/consistenthash.rst index ff835b7fe6..262896470a 100644 --- a/docs/source/api/consistenthash.rst +++ b/docs/source/api/consistenthash.rst @@ -30,7 +30,7 @@ Queries database for an active Traffic Router on a given CDN and sends GET reque Request Structure ----------------- -:regex: The regex to apply to the request path to get a resulting path that will be used for consistent hashing +:regex: The regular expression to apply to the request path to get a resulting path that will be used for consistent hashing :requestPath: The request path to use to test the regular expression against :cdnId: The unique identifier of a CDN that will be used to query for an active Traffic Router diff --git a/docs/source/api/current_stats.rst b/docs/source/api/current_stats.rst index 651fe144b7..bd7d785564 100644 --- a/docs/source/api/current_stats.rst +++ b/docs/source/api/current_stats.rst @@ -48,7 +48,7 @@ Response Structure ------------------ :cdn: The name of the CDN :connections: Current number of TCP connections maintained -:capacity: 85 percent capacity of the CDN in Gbps +:capacity: 85 percent capacity of the CDN in Gps :bandwidth: The total amount of bandwidth in Gbs .. note:: If ``cdn`` name is total and capacity is omitted it represents the aggregate stats across CDNs diff --git a/docs/source/api/deliveryservice_user.rst b/docs/source/api/deliveryservice_user.rst index 0f371d7b19..2660451e46 100644 --- a/docs/source/api/deliveryservice_user.rst +++ b/docs/source/api/deliveryservice_user.rst @@ -29,8 +29,8 @@ Assigns one or more :term:`Delivery Services` to a user. Request Structure ----------------- -:userId: An integral, unique identifier for the user to whom the :term:`Delivery Service`\ (s) identified in ``deliveryServices`` will be assigned -:deliveryServices: An array of integral, unique identifiers for the :term:`Delivery Service`\ (s) being assigned to the user identified by ``userId`` +:userId: An integral, unique identifier for the user to whom the :term:`Delivery Service(s) ` identified in ``deliveryServices`` will be assigned +:deliveryServices: An array of integral, unique identifiers for the :term:`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 @@ -48,7 +48,7 @@ Request Structure Response Structure ------------------ -:userId: The integral, unique identifier of the user to whom the :term:`Delivery Service`\ (s) identified in ``deliveryServices`` are assigned +:userId: The integral, unique identifier of the user to whom the :term:`Delivery Service(s) ` identified in ``deliveryServices`` are assigned :deliveryServices: An array of integral, unique identifiers of :term:`Delivery Services` assigned to the user identified by ``userId`` :replace: If ``true``, any and all existing, conflicting :term:`Delivery Service` assignments were overwritten by this assignment operation diff --git a/docs/source/api/deliveryservices_dnsseckeys_generate.rst b/docs/source/api/deliveryservices_dnsseckeys_generate.rst index 34ec5d8512..45b4f4815c 100644 --- a/docs/source/api/deliveryservices_dnsseckeys_generate.rst +++ b/docs/source/api/deliveryservices_dnsseckeys_generate.rst @@ -21,7 +21,7 @@ ``POST`` ======== -Generates Zone-Signing Key (ZSK) and Key-Signing Key (KSK) keypairs for a CDN and all associated :term:`Delivery Services`. +Generates :abbr:`ZSK (Zone-Signing Key)` and :abbr:`KSK (Key-Signing Key)` keypairs for a CDN and all associated :term:`Delivery Services`. :Auth. Required: Yes :Roles Required: "admin" @@ -29,15 +29,16 @@ Generates Zone-Signing Key (ZSK) and Key-Signing Key (KSK) keypairs for a CDN an Request Structure ----------------- +:effectiveDate: UNIX epoch start date for the signing keys + + .. versionadded:: 1.2 + :key: Name of the CDN +:kskExpirationDays: Expiration (in days) for the :abbr:`KSKs (Key-Signing Keys)` :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 +:zskExpirationDays: Expiration (in days) for the :abbr:`ZSKs (Zone-Signing Keys)` -.. versionchanged:: 1.2 - Added required 'effectiveDate' field to request Response Structure ------------------ diff --git a/docs/source/api/deliveryservices_hostname_name_sslkeys.rst b/docs/source/api/deliveryservices_hostname_name_sslkeys.rst index 68f852ccd6..8ff09043e5 100644 --- a/docs/source/api/deliveryservices_hostname_name_sslkeys.rst +++ b/docs/source/api/deliveryservices_hostname_name_sslkeys.rst @@ -66,7 +66,7 @@ Response Structure :cdn: The CDN of the :term:`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\ [#optional]_ :country: An optional field which, if present, contains the country entered by the user when generating the SSL certificate\ [#optional]_ -:deliveryservice: The 'xml_id' of the :term:`Delivery Service` for which the certificate was generated +:deliveryservice: The string that is :ref:`ds-xmlid` of the :term:`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 an :abbr:`FQDN (Fully Qualified Domain Name)` for DNS :term:`Delivery Services` and a wildcard URL for HTTP :term:`Delivery Services` :organization: An optional field which, if present, contains the organization entered by the user when generating certificate\ [#optional]_ :state: An optional field which, if present, contains the state entered by the user when generating certificate\ [#optional]_ diff --git a/docs/source/api/deliveryservices_id_health.rst b/docs/source/api/deliveryservices_id_health.rst index b06b3d49d1..ef8a042235 100644 --- a/docs/source/api/deliveryservices_id_health.rst +++ b/docs/source/api/deliveryservices_id_health.rst @@ -44,12 +44,12 @@ Response Structure ------------------ :cachegroups: An array of objects that represent the health of each :term:`Cache Group` assigned to this :term:`Delivery Service` - :name: The name of the :term:`Cache Group` represented by this object - :offline: The number of offline :term:`cache servers` within this :term:`Cache Group` - :online: The number of online :term:`cache servers` within this :term:`Cache Group` + :name: A string that is the :ref:`name of the Cache Group ` represented by this object + :offline: The number of OFFLINE :term:`cache servers` within this :term:`Cache Group` + :online: The number of ONLINE :term:`cache servers` within this :term:`Cache Group` -:totalOffline: Total number of offline :term:`cache servers` assigned to this :term:`Delivery Service` -:totalOnline: Total number of online :term:`cache servers` assigned to this :term:`Delivery Service` +:totalOffline: Total number of OFFLINE :term:`cache servers` assigned to this :term:`Delivery Service` +:totalOnline: Total number of ONLINE :term:`cache servers` assigned to this :term:`Delivery Service` .. code-block:: http :caption: Response Example diff --git a/docs/source/api/deliveryservices_id_regexes.rst b/docs/source/api/deliveryservices_id_regexes.rst index a4c51249db..28fee11462 100644 --- a/docs/source/api/deliveryservices_id_regexes.rst +++ b/docs/source/api/deliveryservices_id_regexes.rst @@ -51,7 +51,7 @@ 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 +:type: The integral, unique identifier of the :term:`Type` of this regular expression :typeName: The :term:`Type` of regular expression - determines that against which it will be evaluated .. code-block:: http diff --git a/docs/source/api/deliveryservices_id_regexes_rid.rst b/docs/source/api/deliveryservices_id_regexes_rid.rst index 4546f70297..9e7076e3d1 100644 --- a/docs/source/api/deliveryservices_id_regexes_rid.rst +++ b/docs/source/api/deliveryservices_id_regexes_rid.rst @@ -34,7 +34,7 @@ Request Structure +------+-----------------------------------------------------------------------------------+ | Name | Description | +======+===================================================================================+ - | ID | The integral, unique identifier of the :term:`Delivery Service` being inspected | + | ID | The integral, unique identifier of the :term:`Delivery Service` being inspected | +------+-----------------------------------------------------------------------------------+ | rID | The integral, unique identifier of the routing regular expression being inspected | +------+-----------------------------------------------------------------------------------+ diff --git a/docs/source/api/deliveryservices_id_servers.rst b/docs/source/api/deliveryservices_id_servers.rst index b79faacd90..5d4a824176 100644 --- a/docs/source/api/deliveryservices_id_servers.rst +++ b/docs/source/api/deliveryservices_id_servers.rst @@ -40,11 +40,11 @@ Request Structure Response Structure ------------------ -:cachegroup: The name of the Cache Group to which the server belongs -:cachegroupId: An integral, unique identifier for the Cache Group to which the server belongs +:cachegroup: A string that is the :ref:`name of the Cache Group ` to which the server belongs +:cachegroupId: An integer that is the :ref:`ID of the Cache Group ` to which the server belongs :cdnId: An integral, unique identifier the CDN to which the server belongs :cdnName: The name of the CDN to which the server belongs -:domainName: The domain name part of the Fully Qualified Domain Name (FQDN) of the server +:domainName: The domain name part of the :abbr:`FQDN (Fully Qualified Domain Name)` of the server :guid: Optionally represents an identifier used to uniquely identify the server :hostName: The (short) hostname of the server :httpsPort: The port on which the server listens for incoming HTTPS requests - 443 in most cases @@ -54,7 +54,7 @@ Response Structure :iloIpNetmask: The IPv4 subnet mask of the lights-out-management port\ [2]_ :iloPassword: The password of the of the lights-out-management user - displays as ``******`` unless the requesting user has the 'admin' role)\ [2]_ :iloUsername: The user name for lights-out-management\ [2]_ -:interfaceMtu: The Maximum Transmission Unit (MTU) to configure for ``interfaceName`` +:interfaceMtu: The :abbr:`MTU (Maximum Transmission Unit)` to configure for ``interfaceName`` .. seealso:: `The Wikipedia article on Maximum Transmission Unit `_ @@ -69,8 +69,8 @@ Response Structure :mgmtIpGateway: The IPv4 gateway of the server's management port :mgmtIpNetmask: The IPv4 subnet mask of the server's management port :offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status (will be empty if not offline) -:physLocation: The name of the physical location at which the server resides -:physLocationId: An integral, unique identifier for the physical location at which the server resides +:physLocation: The name of the :term:`Physical Location` at which the server resides +:physLocationId: An integral, unique identifier for the :term:`Physical Location` at which the server resides :profile: The :ref:`profile-name` of the :term:`Profile` assigned to this server :profileDesc: A :ref:`profile-description` of the :term:`Profile` assigned to this server :profileId: The :ref:`profile-id` of the :term:`Profile` assigned to this server diff --git a/docs/source/api/deliveryservices_id_servers_eligible.rst b/docs/source/api/deliveryservices_id_servers_eligible.rst index 05bfcc97ea..cb4d6a886b 100644 --- a/docs/source/api/deliveryservices_id_servers_eligible.rst +++ b/docs/source/api/deliveryservices_id_servers_eligible.rst @@ -23,11 +23,11 @@ ``GET`` ======= -Retrieves properties of Edge-Tier servers eligible for assignment to a particular :term:`Delivery Service`. Eligibility is determined based on the following properties: +Retrieves properties of :term:`Edge-Tier cache servers` eligible for assignment to a particular :term:`Delivery Service`. Eligibility is determined based on the following properties: -1. Server Type: Edge, Origin -2. CDN: Server, :term:`Delivery Service` must belong to the same CDN -3. Server Capabilities: If the :term:`Delivery Service` has :term:`Delivery Service required capabilities`, an edge server must have all defined capabilities +- The name of the server's :term:`Type` must match one of the glob patterns ``EDGE*``, ``ORG*`` +- The server and :term:`Delivery Service` must belong to the same CDN +- If the :term:`Delivery Service` has :ref:`ds-required-capabilities`, an :term:`Edge-tier cache server` must have all of those defined capabilities :Auth. Required: Yes :Roles Required: "admin" or "operations"\ [1]_ @@ -45,11 +45,11 @@ Request Structure Response Structure ------------------ -:cachegroup: The name of the Cache Group to which the server belongs -:cachegroupId: An integral, unique identifier for the Cache Group to which the server belongs +:cachegroup: A string which is the :ref:`Name of the Cache Group ` to which the server belongs +:cachegroupId: An integer that is the :ref:`ID of the Cache Group ` to which the server belongs :cdnId: An integral, unique identifier the CDN to which the server belongs :cdnName: The name of the CDN to which the server belongs -:domainName: The domain name part of the Fully Qualified Domain Name (FQDN) of the server +:domainName: The domain name part of the :abbr:`FQDN (Fully Qualified Domain Name)` of the server :guid: Optionally represents an identifier used to uniquely identify the server :hostName: The (short) hostname of the server :httpsPort: The port on which the server listens for incoming HTTPS requests - 443 in most cases @@ -59,7 +59,7 @@ Response Structure :iloIpNetmask: The IPv4 subnet mask of the lights-out-management port\ [2]_ :iloPassword: The password of the of the lights-out-management user - displays as ``******`` unless the requesting user has the 'admin' role)\ [2]_ :iloUsername: The user name for lights-out-management\ [2]_ -:interfaceMtu: The Maximum Transmission Unit (MTU) to configure for ``interfaceName`` +:interfaceMtu: The :abbr:`MTU (Maximum Transmission Unit)` to configure for ``interfaceName`` .. seealso:: `The Wikipedia article on Maximum Transmission Unit `_ @@ -74,8 +74,8 @@ Response Structure :mgmtIpGateway: The IPv4 gateway of the server's management port :mgmtIpNetmask: The IPv4 subnet mask of the server's management port :offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status (will be empty if not offline) -:physLocation: The name of the physical location at which the server resides -:physLocationId: An integral, unique identifier for the physical location at which the server resides +:physLocation: The name of the :term:`Physical Location` at which the server resides +:physLocationId: An integral, unique identifier for the :term:`Physical Location` at which the server resides :profile: The :ref:`profile-name` of the :term:`Profile` assigned to this server :profileDesc: A :ref:`profile-description` of the :term:`Profile` assigned to this server :profileId: The :ref:`profile-id` of the :term:`Profile` assigned to this server @@ -91,8 +91,8 @@ Response Structure .. seealso:: :ref:`health-proto` :tcpPort: The default port on which the main application listens for incoming TCP connections - 80 in most cases -:type: The name of the type of this server -:typeId: An integral, unique identifier for the type of this server +:type: The name of the :term:`Type` of this server +:typeId: An integral, unique identifier for the :term:`Type` of this server :updPending: ``true`` if the server has updates pending, ``false`` otherwise .. code-block:: json diff --git a/docs/source/api/deliveryservices_id_state.rst b/docs/source/api/deliveryservices_id_state.rst index f3301d2f48..e279d1c08c 100644 --- a/docs/source/api/deliveryservices_id_state.rst +++ b/docs/source/api/deliveryservices_id_state.rst @@ -19,9 +19,6 @@ ``deliveryservices/{{ID}}/state`` ********************************* -.. deprecated:: 1.1 - Use :ref:`to-api-cachegroup_fallbacks` instead to configure Cache Group fallbacks - ``GET`` ======= Retrieves the fail-over state for a :term:`Delivery Service`. diff --git a/docs/source/api/deliveryservices_id_unassigned_servers.rst b/docs/source/api/deliveryservices_id_unassigned_servers.rst index 7ae7a215db..6aa71365a0 100644 --- a/docs/source/api/deliveryservices_id_unassigned_servers.rst +++ b/docs/source/api/deliveryservices_id_unassigned_servers.rst @@ -19,11 +19,11 @@ ``deliveryservices/{{ID}}/unassigned_servers`` ********************************************** -.. caution:: This route does not appear to work properly, and its use is strongly discouraged! Also note that the documentation here is not being updated as a result of this, and may contain out-of-date and/or erroneous information. +.. danger:: This route does not appear to work properly, and its use is strongly discouraged! Also note that the documentation here is not being updated as a result of this, and may contain out-of-date and/or erroneous information. ``GET`` ======= -Retrieves properties of Edge-tier servers not assigned to a :term:`Delivery Service`. +Retrieves properties of :term:`Edge-tier cache servers` **not** assigned to a :term:`Delivery Service`. :Auth. Required: Yes :Roles Required: "admin" or "operations"\ [1]_ @@ -33,16 +33,16 @@ Request Structure ----------------- .. table:: Request Path Parameters - +------+---------------------------------------------------+ - | Name | Description | - +======+===================================================+ - | ID | Delivery service ID. | - +------+---------------------------------------------------+ + +------+---------------------------------------------------------------+ + | Name | Description | + +======+===============================================================+ + | ID | An integral, unique identifier for a :term:`Delivery Service` | + +------+---------------------------------------------------------------+ Response Structure ------------------ -:cachegroup: The cache group name -:cachegroupId: The cache group id +:cachegroup: A string which is the :ref:`Name of the Cache Group ` to which the server belongs +:cachegroupId: An integer that is the :ref:`ID of the Cache Group ` to which the server belongs :cdnId: Id of the CDN to which the server belongs to :cdnName: Name of the CDN to which the server belongs to :domainName: The domain name part of the FQDN of the cache diff --git a/docs/source/api/deliveryservices_xmlid_xmlid_sslkeys_delete.rst b/docs/source/api/deliveryservices_xmlid_xmlid_sslkeys_delete.rst index de9c6ae101..8b0333234d 100644 --- a/docs/source/api/deliveryservices_xmlid_xmlid_sslkeys_delete.rst +++ b/docs/source/api/deliveryservices_xmlid_xmlid_sslkeys_delete.rst @@ -29,11 +29,11 @@ Request Structure ----------------- .. table:: Request Path Parameters - +-------+----------+------------------------------------------------------+ - | Name | Required | Description | - +=======+==========+======================================================+ - | xmlId | yes | The 'xml_id' of the desired :term:`Delivery Service` | - +-------+----------+------------------------------------------------------+ + +-------+----------+-------------------------------------------------------------+ + | Name | Required | Description | + +=======+==========+=============================================================+ + | xmlId | yes | The :ref:`ds-xmlid` of the desired :term:`Delivery Service` | + +-------+----------+-------------------------------------------------------------+ .. table:: Request Query Parameters diff --git a/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_copyfromxmlid_copyfromxmlid.rst b/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_copyfromxmlid_copyfromxmlid.rst index b1c308d143..d7e9730a82 100644 --- a/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_copyfromxmlid_copyfromxmlid.rst +++ b/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_copyfromxmlid_copyfromxmlid.rst @@ -31,13 +31,13 @@ Request Structure ----------------- .. table:: Request Path Parameters - +-----------------+-------------------------------------------------------------------------------+ - | Name | Description | - +=================+===============================================================================+ - | xml_id | The 'xml_id' of the :term:`Delivery Service` *to* which keys will be copied | - +-----------------+-------------------------------------------------------------------------------+ - | copyFrom_xml_id | The 'xml_id' of the :term:`Delivery Service` *from* which keys will be copied | - +-----------------+-------------------------------------------------------------------------------+ + +-----------------+--------------------------------------------------------------------------------------+ + | Name | Description | + +=================+======================================================================================+ + | xml_id | The :ref:`ds-xmlid` of the :term:`Delivery Service` *to* which keys will be copied | + +-----------------+--------------------------------------------------------------------------------------+ + | copyFrom_xml_id | The :ref:`ds-xmlid` of the :term:`Delivery Service` *from* which keys will be copied | + +-----------------+--------------------------------------------------------------------------------------+ Response Structure ------------------ diff --git a/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_generate.rst b/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_generate.rst index 12e9496f30..d42ebbf3ca 100644 --- a/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_generate.rst +++ b/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_generate.rst @@ -33,11 +33,11 @@ Request Structure ----------------- .. table:: Request Path Parameters - +--------+------------------------------------------------------+ - | Name | Description | - +========+======================================================+ - | xml_id | The 'xml_id' of the desired :term:`Delivery Service` | - +--------+------------------------------------------------------+ + +--------+-------------------------------------------------------------+ + | Name | Description | + +========+=============================================================+ + | xml_id | The :ref:`ds-xmlid` of the desired :term:`Delivery Service` | + +--------+-------------------------------------------------------------+ Response Structure ------------------ diff --git a/docs/source/api/divisions_id.rst b/docs/source/api/divisions_id.rst index 5e608e540a..82332ab92f 100644 --- a/docs/source/api/divisions_id.rst +++ b/docs/source/api/divisions_id.rst @@ -23,9 +23,6 @@ ======= Get a specific Division. -.. deprecated:: 1.1 - Use the ``id`` query parameter of the ``GET`` method of :ref:`to-api-divisions` instead. - :Auth. Required: Yes :Roles Required: None :Response Type: Array diff --git a/docs/source/api/divisions_name_regions.rst b/docs/source/api/divisions_name_regions.rst index 1356efac79..7c0c64af7f 100644 --- a/docs/source/api/divisions_name_regions.rst +++ b/docs/source/api/divisions_name_regions.rst @@ -18,12 +18,10 @@ ****************************** ``divisions/{{name}}/regions`` ****************************** -.. deprecated:: 1.1 - Use the ``divisionId`` field in the body of a ``POST`` request to the :ref:`to-api-divisions` endpoint ``POST`` ======== -Creates a new region within the specified division. +Creates a new :term:`Region` within the specified :term:`Division`. :Auth. Required: Yes :Roles Required: "admin" or "operations" diff --git a/docs/source/api/federations_id_deliveryservices.rst b/docs/source/api/federations_id_deliveryservices.rst index 9ea01c6a09..0d26c0254a 100644 --- a/docs/source/api/federations_id_deliveryservices.rst +++ b/docs/source/api/federations_id_deliveryservices.rst @@ -42,7 +42,7 @@ Request Structure +-----------+----------+--------------------------------------------------------------------------------------------------------------------------------------+ | Name | Required | Description | +===========+==========+======================================================================================================================================+ - | dsID | no | Show only the :term:`Delivery Service` that has this integral, unique identifier | + | dsID | no | Show only the :term:`Delivery Service` identified by this integral, unique identifier | +-----------+----------+--------------------------------------------------------------------------------------------------------------------------------------+ | orderby | no | Choose the ordering of the results - must be the name of one of the fields of the objects in the ``response`` | | | | array | diff --git a/docs/source/api/hwinfo.rst b/docs/source/api/hwinfo.rst index b0b5425c2e..97ceb6a827 100644 --- a/docs/source/api/hwinfo.rst +++ b/docs/source/api/hwinfo.rst @@ -27,8 +27,8 @@ :Roles Required: None :Response Type: Array -Request Structure: ------------------- +Request Structure +----------------- .. table:: Request Query Parameters +----------------+----------+---------------------------------------------------------------------------------------------------------------+ @@ -61,7 +61,7 @@ Request Structure: .. caution:: The ``lastUpdated`` query parameter doesn't seem to work properly, and its use is therefore discouraged. -.. code:: http +.. code-block:: http :caption: Request Example GET /api/1.3/hwinfo HTTP/1.1 diff --git a/docs/source/api/isos.rst b/docs/source/api/isos.rst index 0b7c2a97a8..a9fbc27b51 100644 --- a/docs/source/api/isos.rst +++ b/docs/source/api/isos.rst @@ -40,7 +40,7 @@ Request Structure :domainName: The domain part of the system image's Fully Qualified Domain Name (FQDN) :hostName: The host name part of the system image's FQDN :interfaceMtu: A number that specifies the Maximum Transmission Unit (MTU) for the system image's network interface card - the only valid values of which I'm aware are 1500 or 9000, and this should almost always just be 1500 -:interfaceName: An optional string naming the network interface to be used by the generated system image e.g. "bond0", "eth0", etc. If the special name "bond0" is used, a Link Aggregation Control Protocol (LACP) binding configuration will be created and included in the system image +:interfaceName: An optional string naming the network interface to be used by the generated system image e.g. "bond0", "eth0", etc. If the special name "bond0" is used, an :abbr:`LACP (Link Aggregation Control Protocol)` binding configuration will be created and included in the system image .. seealso:: `The Link Aggregation Wikipedia page `_\ . diff --git a/docs/source/api/logs_days_days.rst b/docs/source/api/logs_days_days.rst index db122b2eeb..7b41da5f46 100644 --- a/docs/source/api/logs_days_days.rst +++ b/docs/source/api/logs_days_days.rst @@ -19,9 +19,6 @@ ``logs/{{days}}/days`` ********************** -.. deprecated:: 1.1 - Use :ref:`to-api-logs` with the 'days' query parameter instead - ``GET`` ======= Fetches a list of changes that have been made to the Traffic Control system in the past ``days`` days diff --git a/docs/source/api/origins.rst b/docs/source/api/origins.rst index a35371def4..a3f0653a1c 100644 --- a/docs/source/api/origins.rst +++ b/docs/source/api/origins.rst @@ -35,7 +35,7 @@ Request Structure +-----------------+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Name | Required | Description | +=================+==========+===================================================================================================================================================================+ - | cachegroup | no | Return only :term:`origins` within the :term:`Cache Group` identified by this integral, unique identifier | + | cachegroup | no | Return only :term:`origins` within the :term:`Cache Group` that has this :ref:`cache-group-id` | +-----------------+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | coordinate | no | Return only :term:`origins` located at the geographic coordinates identified by this integral, unique identifier | +-----------------+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -78,11 +78,11 @@ Request Structure Response Structure ------------------ -:cachegroup: The name of the :term:`Cache Group` to which the :term:`origin` belongs -:cachegroupId: An integral, unique identifier for the :term:`Cache Group` to which the :term:`origin` belongs +:cachegroup: A string that is the :ref:`name of the Cache Group ` to which the :term:`origin` belongs +:cachegroupId: An integer that is the :ref:`ID of the Cache Group ` to which the :term:`origin` belongs :coordinate: The name of a coordinate pair that defines the origin's geographic location -:coordinateID: An integral, unique identifier for the coordinate pair that defines the :term:`origin`'s geographic location -:deliveryService: The 'xml_id' of the :term:`Delivery Service` to which the :term:`origin` belongs +:coordinateId: An integral, unique identifier for the coordinate pair that defines the :term:`origin`'s geographic location +:deliveryService: A string that is the :ref:`ds-xmlid` of the :term:`Delivery Service` to which the :term:`origin` belongs :deliveryServiceId: An integral, unique identifier for the :term:`Delivery Service` to which the :term:`origin` belongs :fqdn: The :abbr:`FQDN (Fully Qualified Domain Name)` of the :term:`origin` :id: An integral, unique identifier for this :term:`origin` @@ -149,8 +149,8 @@ Creates a new origin definition. Request Structure ----------------- -:cachegroupId: An optional, integral, unique identifier that identifies a :term:`Cache Group` to which the new :term:`origin` shall belong -:coordinateID: An optional, integral, unique identifier of a coordinate pair that shall define the :term:`origin`'s geographic location +:cachegroupId: An optional, integer which, if present, should be the :ref:`Cache Group ID ` that identifies a :term:`Cache Group` to which the new :term:`origin` shall belong +:coordinateId: An optional, integral, unique identifier of a coordinate pair that shall define the :term:`origin`'s geographic location :deliveryServiceId: The integral, unique identifier of the :term:`Delivery Service` to which the new :term:`origin` shall belong :fqdn: The :abbr:`FQDN (Fully Qualified Domain Name)` of the :term:`origin` :ip6Address: An optional string containing the IPv6 address of the :term:`origin` @@ -189,10 +189,10 @@ Request Structure Response Structure ------------------ -:cachegroup: The name of the :term:`Cache Group` to which the :term:`origin` belongs -:cachegroupId: An integral, unique identifier for the :term:`Cache Group` to which the :term:`origin` belongs +:cachegroup: A string that is the :ref:`name of the Cache Group ` to which the :term:`origin` belongs +:cachegroupId: An integer that is the :ref:`ID of the Cache Group ` to which the :term:`origin` belongs :coordinate: The name of a coordinate pair that defines the origin's geographic location -:coordinateID: An integral, unique identifier for the coordinate pair that defines the :term:`origin`'s geographic location +:coordinateId: An integral, unique identifier for the coordinate pair that defines the :term:`origin`'s geographic location :deliveryService: The 'xml_id' of the :term:`Delivery Service` to which the :term:`origin` belongs :deliveryServiceId: An integral, unique identifier for the :term:`Delivery Service` to which the :term:`origin` belongs :fqdn: The :abbr:`FQDN (Fully Qualified Domain Name)` of the :term:`origin` @@ -267,11 +267,11 @@ Request Structure +------+----------+-------------------------------------------------------------------------------+ | Name | Required | Description | +======+==========+===============================================================================+ - | id | yes | The integral, unique identifier of the :term:`origin` definition being edited | + | id | yes | The integral, unique identifier of the :term:`origin` definition being edited | +------+----------+-------------------------------------------------------------------------------+ -:cachegroupId: An optional, integral, unique identifier that identifies a :term:`Cache Group` to which the :term:`origin` shall belong -:coordinateID: An optional, integral, unique identifier of a coordinate pair that shall define the :term:`origin`'s geographic location +:cachegroupId: An optional, integer which, if present, should be the :ref:`Cache Group ID ` that identifies a :term:`Cache Group` to which the new :term:`origin` shall belong +:coordinateId: An optional, integral, unique identifier of a coordinate pair that shall define the :term:`origin`'s geographic location :deliveryServiceId: The integral, unique identifier of the :term:`Delivery Service` to which the :term:`origin` shall belong :fqdn: The :abbr:`FQDN (Fully Qualified Domain Name)` of the :term:`origin` :ip6Address: An optional string containing the IPv6 address of the :term:`origin` @@ -307,10 +307,10 @@ Request Structure Response Structure ------------------ -:cachegroup: The name of the :term:`Cache Group` to which the :term:`origin` belongs -:cachegroupId: An integral, unique identifier for the :term:`Cache Group` to which the :term:`origin` belongs +:cachegroup: A string that is the :ref:`name of the Cache Group ` to which the :term:`origin` belongs +:cachegroupId: An integer that is the :ref:`ID of the Cache Group ` to which the :term:`origin` belongs :coordinate: The name of a coordinate pair that defines the origin's geographic location -:coordinateID: An integral, unique identifier for the coordinate pair that defines the :term:`origin`'s geographic location +:coordinateId: An integral, unique identifier for the coordinate pair that defines the :term:`origin`'s geographic location :deliveryService: The 'xml_id' of the :term:`Delivery Service` to which the :term:`origin` belongs :deliveryServiceId: An integral, unique identifier for the :term:`Delivery Service` to which the :term:`origin` belongs :fqdn: The :abbr:`FQDN (Fully Qualified Domain Name)` of the :term:`origin` diff --git a/docs/source/api/osversions.rst b/docs/source/api/osversions.rst index db449d57db..6d58025c23 100644 --- a/docs/source/api/osversions.rst +++ b/docs/source/api/osversions.rst @@ -22,7 +22,7 @@ ``GET`` ======= -Gets all available Operating System (OS) versions for ISO generation, as well as the name of the directory where the "kickstarter" files are found. +Gets all available :abbr:`OS (Operating System)` versions for ISO generation, as well as the name of the directory where the "kickstarter" files are found. :Auth. Required: Yes :Roles Required: None diff --git a/docs/source/api/parameterprofile.rst b/docs/source/api/parameterprofile.rst index 7a571e3f4f..af0ae92e4b 100644 --- a/docs/source/api/parameterprofile.rst +++ b/docs/source/api/parameterprofile.rst @@ -18,8 +18,6 @@ ******************** ``parameterprofile`` ******************** -.. deprecated:: 1.1 - Use :ref:`to-api-profileparameters` instead. ``POST`` ======== diff --git a/docs/source/api/parameters_id.rst b/docs/source/api/parameters_id.rst index 32e3a0f490..a9ae02d984 100644 --- a/docs/source/api/parameters_id.rst +++ b/docs/source/api/parameters_id.rst @@ -23,9 +23,6 @@ ======= Gets details about a specific :term:`Parameter` -.. deprecated:: 1.1 - Use the ``id`` query parameter of the :ref:`to-api-parameters` endpoint instead - :Auth. Required: Yes :Roles Required: None :Response Type: Array diff --git a/docs/source/api/parameters_id_profiles.rst b/docs/source/api/parameters_id_profiles.rst index c0d04ce4ee..1d2895574c 100644 --- a/docs/source/api/parameters_id_profiles.rst +++ b/docs/source/api/parameters_id_profiles.rst @@ -18,8 +18,6 @@ ****************************** ``parameters/{{ID}}/profiles`` ****************************** -.. deprecated:: 1.1 - Use the ``param`` query parameter of :ref:`to-api-profiles` instead. ``GET`` ======= diff --git a/docs/source/api/parameters_profile_name.rst b/docs/source/api/parameters_profile_name.rst index ec5200fec5..679ebc2d63 100644 --- a/docs/source/api/parameters_profile_name.rst +++ b/docs/source/api/parameters_profile_name.rst @@ -18,8 +18,6 @@ ******************************* ``parameters/profile/{{name}}`` ******************************* -.. deprecated:: 1.1 - Use :ref:`to-api-profiles-name-name-parameters` instead ``GET`` ======= diff --git a/docs/source/api/parameters_validate.rst b/docs/source/api/parameters_validate.rst index 0680fd1d08..eac46e70ef 100644 --- a/docs/source/api/parameters_validate.rst +++ b/docs/source/api/parameters_validate.rst @@ -18,8 +18,6 @@ *********************** ``parameters/validate`` *********************** -.. deprecated:: 1.1 - To check for the existence of a :term:`Parameter` with a specific :ref:`parameter-name`, :ref:`parameter-value` etc., use the query parameters of the :ref:`to-api-parameters` endpoint instead. ``POST`` ======== diff --git a/docs/source/api/phys_locations.rst b/docs/source/api/phys_locations.rst index 0c791e4c06..3e849e99fe 100644 --- a/docs/source/api/phys_locations.rst +++ b/docs/source/api/phys_locations.rst @@ -21,7 +21,7 @@ ``GET`` ======= -Retrieves physical locations +Retrieves :term:`Physical Locations` :Auth. Required: Yes :Roles Required: None diff --git a/docs/source/api/phys_locations_id.rst b/docs/source/api/phys_locations_id.rst index 7bd0cf12fe..b7b1deb951 100644 --- a/docs/source/api/phys_locations_id.rst +++ b/docs/source/api/phys_locations_id.rst @@ -21,10 +21,7 @@ ``GET`` ======= -Retrieves information about a specific physical location - -.. deprecated:: 1.1 - Use the ``id`` query parameter of the :ref:`to-api-phys_locations` endpoint instead +Retrieves information about a specific :term:`Physical Location` :Auth. Required: Yes :Roles Required: None @@ -121,7 +118,7 @@ Response Structure ``PUT`` ======= -Updates a physical location +Updates a :term:`Physical Location` :Auth. Required: Yes :Roles Required: "admin" or "operations" @@ -131,11 +128,11 @@ Request Structure ----------------- .. table:: Request Path Parameters - +------+--------------------------------------------------------------------------+ - | Name | Description | - +======+==========================================================================+ - | ID | The integral, unique identifier of the physical location being modified | - +------+--------------------------------------------------------------------------+ + +------+----------------------------------------------------------------------------------+ + | Name | Description | + +======+==================================================================================+ + | ID | The integral, unique identifier of the :term:`Physical Location` being modified | + +------+----------------------------------------------------------------------------------+ :address: The physical location's street address :city: The name of the city in which the physical location lies @@ -234,7 +231,7 @@ Response Structure ``DELETE`` ========== -Deletes a physical location +Deletes a :term:`Physical Location` :Auth. Required: Yes :Roles Required: "admin" or "operations" @@ -244,11 +241,11 @@ Request Structure ----------------- .. table:: Request Path Parameters - +------+--------------------------------------------------------------------------+ - | Name | Description | - +======+==========================================================================+ - | ID | The integral, unique identifier of the physical location being modified | - +------+--------------------------------------------------------------------------+ + +------+--------------------------------------------------------------------------------+ + | Name | Description | + +======+================================================================================+ + | ID | The integral, unique identifier of the :term:`Physical Location` being deleted | + +------+--------------------------------------------------------------------------------+ .. code-block:: http :caption: Request Example diff --git a/docs/source/api/phys_locations_trimmed.rst b/docs/source/api/phys_locations_trimmed.rst index 1d113d7b07..c3e33b45bf 100644 --- a/docs/source/api/phys_locations_trimmed.rst +++ b/docs/source/api/phys_locations_trimmed.rst @@ -21,7 +21,7 @@ ``GET`` ======= -Retrieves only the names of physical locations +Retrieves only the names of :term:`Physical Locations`. :Auth. Required: Yes :Roles Required: None @@ -33,7 +33,7 @@ No parameters available Response Structure ------------------ -:name: The name of the physical location +:name: The name of the :term:`Physical Location` .. code-block:: http :caption: Response Example diff --git a/docs/source/api/profileparameters.rst b/docs/source/api/profileparameters.rst index d588ef9a61..625393aaa3 100644 --- a/docs/source/api/profileparameters.rst +++ b/docs/source/api/profileparameters.rst @@ -21,8 +21,6 @@ ``GET`` ======= -.. deprecated:: 1.1 - To get the :term:`Profiles` associated with a particular :term:`Parameter`, use the ``param`` query parameter of :ref:`to-api-profiles` instead. To see the :term:`Parameters` associated with a particular :term:`Profile`, refer to the ``params`` key in the response of a ``GET`` request to :ref:`to-api-profiles-id` instead. Retrieves all :term:`Parameter`/:term:`Profile` assignments. diff --git a/docs/source/api/profiles_id.rst b/docs/source/api/profiles_id.rst index 338baee85a..298a52606c 100644 --- a/docs/source/api/profiles_id.rst +++ b/docs/source/api/profiles_id.rst @@ -21,8 +21,6 @@ ``GET`` ======= -.. deprecated:: 1.1 - Use the ``id`` query parameter of a ``GET`` request to :ref:`to-api-profiles-id` instead. :Auth. Required: Yes :Roles Required: None diff --git a/docs/source/api/profiles_id_parameters.rst b/docs/source/api/profiles_id_parameters.rst index 769abe86b4..53f6d67b5a 100644 --- a/docs/source/api/profiles_id_parameters.rst +++ b/docs/source/api/profiles_id_parameters.rst @@ -21,8 +21,6 @@ ``GET`` ======= -.. deprecated:: 1.1 - Refer to the ``params`` key in the response of :ref:`to-api-profiles-id` instead Retrieves all :term:`Parameters` assigned to the :term:`Profile`. @@ -111,8 +109,6 @@ Response Structure ``POST`` ======== -.. deprecated:: 1.1 - Use :ref:`to-api-profiles-name-name-parameters` instead Associates :term:`Parameters` to a :term:`Profile`. If the :term:`Parameter` does not exist, creates it and associates it to the :term:`Profile`. If the :term:`Parameter` already exists, associates it to the :term:`Profile`. If the :term:`Parameter` is already associated with the :term:`Profile`, keep the association. diff --git a/docs/source/api/profiles_profile_configfiles_ats_filename.rst b/docs/source/api/profiles_profile_configfiles_ats_filename.rst index 015c120cc8..4b3d431d86 100644 --- a/docs/source/api/profiles_profile_configfiles_ats_filename.rst +++ b/docs/source/api/profiles_profile_configfiles_ats_filename.rst @@ -27,7 +27,7 @@ Returns the requested configuration file for download. :Auth. Required: Yes :Roles Required: "operations" -:Response Type: **NOT PRESENT** - endpoint returns custom text/plain response (represents the contents of the requested configuration file) +:Response Type: **NOT PRESENT** - endpoint returns custom :mimetype:`text/plain` response (represents the contents of the requested configuration file) Request Structure ----------------- diff --git a/docs/source/api/regions_id.rst b/docs/source/api/regions_id.rst index 8edc0435d6..e261f22f15 100644 --- a/docs/source/api/regions_id.rst +++ b/docs/source/api/regions_id.rst @@ -21,10 +21,8 @@ ``GET`` ======= -Retrieves a specific region +Retrieves a specific :term:`Region`. -.. deprecated:: 1.1 - Use the ``id`` query parameter of a ``GET`` request to the :ref:`to-api-regions` endpoint :Auth. Required: Yes :Roles Required: None @@ -91,11 +89,11 @@ Response Structure ``PUT`` ======= -Updates a region +Updates a :term:`Region`. - Authentication Required: Yes - - Role(s) Required: admin or oper +:Auth. Required: Yes +:Role(s) Required: "admin" or "operator" +:Response Type: Object Request Structure ----------------- diff --git a/docs/source/api/regions_name_phys_locations.rst b/docs/source/api/regions_name_phys_locations.rst index af1584786d..179018290e 100644 --- a/docs/source/api/regions_name_phys_locations.rst +++ b/docs/source/api/regions_name_phys_locations.rst @@ -18,12 +18,10 @@ *************************************** ``regions/:region_name/phys_locations`` *************************************** -.. deprecated:: 1.1 - Instead specify the ``regionId`` field in the body of a ``POST`` request to :ref:`to-api-phys_locations`. ``POST`` ======== -Creates a new physical location within the specified region. +Creates a new :term:`Physical Location` within the specified :term:`region`. :Auth. Required: Yes :Roles Required: "admin" or "operations" diff --git a/docs/source/api/server_capabilities.rst b/docs/source/api/server_capabilities.rst index 2880953725..20ace27e56 100644 --- a/docs/source/api/server_capabilities.rst +++ b/docs/source/api/server_capabilities.rst @@ -18,11 +18,10 @@ *********************** ``server_capabilities`` *********************** +.. versionadded:: 1.4 ``GET`` ======= -.. versionadded:: 1.4 - Retrieves :term:`Server Capabilities`. :Auth. Required: Yes @@ -79,8 +78,6 @@ Response Structure ``POST`` ======== -.. versionadded:: 1.4 - Create a new :term:`Server Capability`. :Auth. Required: Yes @@ -141,8 +138,6 @@ Response Structure ``DELETE`` ========== -.. versionadded:: 1.4 - Deletes a specific :term:`Server Capability`. :Auth. Required: Yes diff --git a/docs/source/api/servers.rst b/docs/source/api/servers.rst index f5c7ba9884..689decd1be 100644 --- a/docs/source/api/servers.rst +++ b/docs/source/api/servers.rst @@ -34,7 +34,7 @@ Request Structure +------------+----------+-------------------------------------------------------------------------------------------------------------------+ | Name | Required | Description | +============+==========+===================================================================================================================+ - | cachegroup | no | Return only those servers within the :term:`Cache Group` identified by this integral, unique identifier | + | cachegroup | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-id` | +------------+----------+-------------------------------------------------------------------------------------------------------------------+ | dsId | no | Return only those servers assigned to the :term:`Delivery Service` identified by this integral, unique identifier | +------------+----------+-------------------------------------------------------------------------------------------------------------------+ @@ -70,25 +70,24 @@ Request Structure Response Structure ------------------ -:cachegroup: The name of the Cache Group to which this server belongs -:cachegroupId: The integral, unique identifier of the Cache Group to which this server belongs +:cachegroup: A string that is the :ref:`name of the Cache Group ` to which the server belongs +:cachegroupId: An integer that is the :ref:`ID of the Cache Group ` to which the server belongs :cdnId: The integral, unique identifier of the CDN to which the server belongs :cdnName: Name of the CDN to which the server belongs -:domainName: The domain part of the server's Fully Qualified Domain Name (FQDN) +:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)` :guid: An identifier used to uniquely identify the server - .. deprecated:: 1.1 - This is a legacy key which only still exists for compatibility reasons - it should always be ``null`` + .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null`` :hostName: The (short) hostname of the server :httpsPort: The port on which the server listens for incoming HTTPS connections/requests :id: An integral, unique identifier for this server -:iloIpAddress: The IPv4 address of the server's Integrated Lights-Out (ILO) service\ [1]_ -:iloIpGateway: The IPv4 gateway address of the server's ILO service\ [1]_ -:iloIpNetmask: The IPv4 subnet mask of the server's ILO service\ [1]_ -:iloPassword: The password of the of the server's ILO service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' role(s) -:iloUsername: The user name for the server's ILO service\ [1]_ -:interfaceMtu: The Maximum Transmission Unit (MTU) to configured on ``interfaceName`` +:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) ` +:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:interfaceMtu: The :abbr:`MTU (Maximum Transmission Unit)` configured on ``interfaceName`` :interfaceName: The name of the primary network interface used by the server :ip6Address: The IPv6 address and subnet mask of ``interfaceName`` :ip6Gateway: The IPv6 address of the gateway used by ``interfaceName`` @@ -190,8 +189,6 @@ Response Structure } ]} -.. [1] For more information see the `Wikipedia page on Lights-Out management `_\ . - ``POST`` ======== Allows a user to create a new server. @@ -202,17 +199,17 @@ Allows a user to create a new server. Request Structure ----------------- -:cachegroupId: The integral, unique identifier of the Cache Group to which this server shall belong +:cachegroupId: An integer that is the :ref:`ID of the Cache Group ` to which the server shall belong :cdnId: The integral, unique identifier of the CDN to which the server shall belong -:domainName: The domain part of the server's Fully Qualified Domain Name (FQDN) +:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)` :hostName: The (short) hostname of the server :httpsPort: An optional port number on which the server listens for incoming HTTPS connections/requests -:iloIpAddress: An optional IPv4 address of the server's Integrated Lights-Out (ILO) service\ [1]_ -:iloIpGateway: An optional IPv4 gateway address of the server's ILO service\ [1]_ -:iloIpNetmask: An optional IPv4 subnet mask of the server's ILO service\ [1]_ -:iloPassword: An optional string containing the password of the of the server's ILO service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' role(s) -:iloUsername: An optional string containing the user name for the server's ILO service\ [1]_ -:interfaceMtu: The Maximum Transmission Unit (MTU) to configured on ``interfaceName`` +:iloIpAddress: An optional IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloIpGateway: An optional IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloIpNetmask: An optional IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloPassword: An optional string containing the password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) ` +:iloUsername: An optional string containing the user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:interfaceMtu: The :abbr:`MTU (Maximum Transmission Unit)` configured on ``interfaceName`` .. note:: In virtually all cases this ought to be 1500. Further note that the only acceptable values are 1500 and 9000. @@ -289,25 +286,24 @@ Request Structure Response Structure ------------------ -:cachegroup: The name of the Cache Group to which this server belongs -:cachegroupId: The integral, unique identifier of the Cache Group to which this server belongs +:cachegroup: A string that is the :ref:`name of the Cache Group ` to which the server belongs +:cachegroupId: An integer that is the :ref:`ID of the Cache Group ` to which the server belongs :cdnId: The integral, unique identifier of the CDN to which the server belongs :cdnName: Name of the CDN to which the server belongs -:domainName: The domain part of the server's Fully Qualified Domain Name (FQDN) +:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)` :guid: An identifier used to uniquely identify the server - .. deprecated:: 1.1 - This is a legacy key which only still exists for compatibility reasons - it should always be ``null`` + .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null`` :hostName: The (short) hostname of the server :httpsPort: The port on which the server listens for incoming HTTPS connections/requests :id: An integral, unique identifier for this server -:iloIpAddress: The IPv4 address of the server's Integrated Lights-Out (ILO) service\ [1]_ -:iloIpGateway: The IPv4 gateway address of the server's ILO service\ [1]_ -:iloIpNetmask: The IPv4 subnet mask of the server's ILO service\ [1]_ -:iloPassword: The password of the of the server's ILO service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' role(s) -:iloUsername: The user name for the server's ILO service\ [1]_ -:interfaceMtu: The Maximum Transmission Unit (MTU) to configured on ``interfaceName`` +:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :abbr:`Role(s) ` +:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:interfaceMtu: The :abbr:`MTU (Maximum Transmission Unit)` configured on ``interfaceName`` :interfaceName: The name of the primary network interface used by the server :ip6Address: The IPv6 address and subnet mask of ``interfaceName`` :ip6Gateway: The IPv6 address of the gateway used by ``interfaceName`` @@ -319,8 +315,8 @@ Response Structure :mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management' :mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management' :offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status -:physLocation: The name of the physical location where the server resides -:physLocationId: An integral, unique identifier for the physical location where the server resides +:physLocation: The name of the :term:`Physical Location` where the server resides +:physLocationId: An integral, unique identifier for the :term:`Physical Location` where the server resides :profile: The :ref:`profile-name` of the :term:`Profile` used by this server :profileDesc: A :ref:`profile-description` of the :term:`Profile` used by this server :profileId: The :ref:`profile-id` the :term:`Profile` used by this server @@ -412,3 +408,5 @@ Response Structure "xmppId": "test", "xmppPasswd": null }} + +.. [1] For more information see the `Wikipedia page on Lights-Out management `_\ . diff --git a/docs/source/api/servers_hostname_name_details.rst b/docs/source/api/servers_hostname_name_details.rst index 7c4b5093c9..d64e85dbdb 100644 --- a/docs/source/api/servers_hostname_name_details.rst +++ b/docs/source/api/servers_hostname_name_details.rst @@ -18,8 +18,6 @@ ************************************* ``servers/hostname/{{name}}/details`` ************************************* -.. deprecated:: 1.1 - Use the ``hostName`` query parameter of the :ref:`to-api-servers` endpoint instead. ``GET`` ======= @@ -41,24 +39,23 @@ Request Structure Response Structure ------------------ -:cachegroup: The name of the Cache Group to which this server belongs +:cachegroup: A string that is the :ref:`name of the Cache Group ` to which the server belongs :cdnName: Name of the CDN to which the server belongs :deliveryservices: An array of integral, unique identifiers for :term:`Delivery Services` to which this server belongs -:domainName: The domain part of the server's Fully Qualified Domain Name (FQDN) +:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)` :guid: An identifier used to uniquely identify the server - .. deprecated:: 1.1 - This is a legacy key which only still exists for compatibility reasons - it should always be ``null`` + .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null`` :hostName: The (short) hostname of the server :httpsPort: The port on which the server listens for incoming HTTPS connections/requests :id: An integral, unique identifier for this server -:iloIpAddress: The IPv4 address of the server's Integrated Lights-Out (ILO) service\ [1]_ -:iloIpGateway: The IPv4 gateway address of the server's ILO service\ [1]_ -:iloIpNetmask: The IPv4 subnet mask of the server's ILO service\ [1]_ -:iloPassword: The password of the of the server's ILO service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' role(s) -:iloUsername: The user name for the server's ILO service\ [1]_ -:interfaceMtu: The Maximum Transmission Unit (MTU) to configured on ``interfaceName`` +:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) ` +:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:interfaceMtu: The :abbr:`MTU (Maximum Transmission Unit)` to configured on ``interfaceName`` :interfaceName: The name of the primary network interface used by the server :ip6Address: The IPv6 address and subnet mask of ``interfaceName`` :ip6Gateway: The IPv6 address of the gateway used by ``interfaceName`` diff --git a/docs/source/api/servers_id.rst b/docs/source/api/servers_id.rst index 38a27b1ae1..7eb936be4e 100644 --- a/docs/source/api/servers_id.rst +++ b/docs/source/api/servers_id.rst @@ -21,9 +21,6 @@ ``GET`` ======= -.. deprecated:: 1.1 - Use the ``id`` query parameter of a ``GET`` request to :ref:`to-api-servers` instead. - Retrieves properties of a specific server. :Auth. Required: Yes @@ -70,15 +67,14 @@ Request Structure Response Structure ------------------ -:cachegroup: The name of the Cache Group to which this server belongs -:cachegroupId: The integral, unique identifier of the Cache Group to which this server belongs +:cachegroup: A string that is the :ref:`name of the Cache Group ` to which the server belongs +:cachegroupId: An integer that is the :ref:`ID of the Cache Group ` to which the server belongs :cdnId: The integral, unique identifier of the CDN to which the server belongs :cdnName: Name of the CDN to which the server belongs :domainName: The domain part of the server's Fully Qualified Domain Name (FQDN) :guid: An identifier used to uniquely identify the server - .. deprecated:: 1.1 - This is a legacy key which only still exists for compatibility reasons - it should always be ``null`` + .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null`` :hostName: The (short) hostname of the server :httpsPort: The port on which the server listens for incoming HTTPS connections/requests @@ -210,17 +206,17 @@ Request Structure | ID | The integral, unique identifier of a server | +------+---------------------------------------------+ -:cachegroupId: The integral, unique identifier of the Cache Group to which this server shall belong +:cachegroupId: An integer that is the :ref:`ID of the Cache Group ` to which the server shall belong :cdnId: The integral, unique identifier of the CDN to which the server shall belong -:domainName: The domain part of the server's Fully Qualified Domain Name (FQDN) +:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)` :hostName: The (short) hostname of the server :httpsPort: An optional port number on which the server listens for incoming HTTPS connections/requests -:iloIpAddress: An optional IPv4 address of the server's Integrated Lights-Out (ILO) service\ [1]_ -:iloIpGateway: An optional IPv4 gateway address of the server's ILO service\ [1]_ -:iloIpNetmask: An optional IPv4 subnet mask of the server's ILO service\ [1]_ -:iloPassword: An optional string containing the password of the of the server's ILO service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' role(s) -:iloUsername: An optional string containing the user name for the server's ILO service\ [1]_ -:interfaceMtu: The Maximum Transmission Unit (MTU) to configured on ``interfaceName`` +:iloIpAddress: An optional IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloIpGateway: An optional IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloIpNetmask: An optional IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:iloPassword: An optional string containing the password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :abbr:`Role(s) ` +:iloUsername: An optional string containing the user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_ +:interfaceMtu: The :abbr:`MTU (Maximum Transmission Unit)` configured on ``interfaceName`` .. note:: In virtually all cases this ought to be 1500. Further note that the only acceptable values are 1500 and 9000. @@ -297,15 +293,14 @@ Request Structure Response Structure ------------------ -:cachegroup: The name of the Cache Group to which this server belongs -:cachegroupId: The integral, unique identifier of the Cache Group to which this server belongs +:cachegroup: A string that is the :ref:`name of the Cache Group ` to which the server belongs +:cachegroupId: An integer that is the :ref:`ID of the Cache Group ` to which the server belongs :cdnId: The integral, unique identifier of the CDN to which the server belongs :cdnName: Name of the CDN to which the server belongs -:domainName: The domain part of the server's Fully Qualified Domain Name (FQDN) +:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)` :guid: An identifier used to uniquely identify the server - .. deprecated:: 1.1 - This is a legacy key which only still exists for compatibility reasons - it should always be ``null`` + .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null`` :hostName: The (short) hostname of the server :httpsPort: The port on which the server listens for incoming HTTPS connections/requests diff --git a/docs/source/api/servers_id_status.rst b/docs/source/api/servers_id_status.rst index 242f8c76de..1d91b5bcd5 100644 --- a/docs/source/api/servers_id_status.rst +++ b/docs/source/api/servers_id_status.rst @@ -18,8 +18,6 @@ ************************* ``servers/{{ID}}/status`` ************************* -.. deprecated:: 1.1 - Use the ``PUT`` method of :ref:`to-api-servers-id` instead. ``PUT`` ======= diff --git a/docs/source/api/servers_server_configfiles_ats.rst b/docs/source/api/servers_server_configfiles_ats.rst index c4d2328e38..6a7820f1d1 100644 --- a/docs/source/api/servers_server_configfiles_ats.rst +++ b/docs/source/api/servers_server_configfiles_ats.rst @@ -27,7 +27,7 @@ Gets a list of the configuration files used by ``server`` :Auth. Required: Yes :Roles Required: "operations" -:Response Type: **NOT PRESENT** - endpoint returns custom application/json response +:Response Type: **NOT PRESENT** - endpoint returns custom :mimetype:`application/json` response Request Structure ----------------- diff --git a/docs/source/api/servers_server_configfiles_ats_filename.rst b/docs/source/api/servers_server_configfiles_ats_filename.rst index 50b3474a39..f64e668a98 100644 --- a/docs/source/api/servers_server_configfiles_ats_filename.rst +++ b/docs/source/api/servers_server_configfiles_ats_filename.rst @@ -27,7 +27,7 @@ Returns the requested configuration file for download. :Auth. Required: Yes :Roles Required: "operations" -:Response Type: **NOT PRESENT** - endpoint returns custom text/plain response (represents the contents of the requested configuration file) +:Response Type: **NOT PRESENT** - endpoint returns custom :mimetype:`text/plain` response (represents the contents of the requested configuration file) Request Structure ----------------- diff --git a/docs/source/api/servers_totals.rst b/docs/source/api/servers_totals.rst index 83ef951b87..2853e2de5f 100644 --- a/docs/source/api/servers_totals.rst +++ b/docs/source/api/servers_totals.rst @@ -21,7 +21,7 @@ ``GET`` ======= -Retrieves a count of each type of server across all CDNs. +Retrieves a count of each :term:`Type` of server across all CDNs. :Auth. Required: Yes :Roles Required: None @@ -34,7 +34,7 @@ No parameters available. Response Structure ------------------ :count: The number of servers of this type configured in this instance of Traffic Ops -:type: The name of the type servers herein counted +:type: The name of the :term:`Type` servers herein counted .. code-block:: http :caption: Response Example diff --git a/docs/source/api/staticdnsentries.rst b/docs/source/api/staticdnsentries.rst index c777e59166..4c82792eb4 100644 --- a/docs/source/api/staticdnsentries.rst +++ b/docs/source/api/staticdnsentries.rst @@ -36,11 +36,11 @@ Request Structure +===================+==========+============================================================================================================================================+ | address | no | Return only static DNS entries that operate on this address/:abbr:`CNAME (Canonical Name)` | +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+ - | cachegroup | no | Return only static DNS entries assigned to this :term:`Cache Group` | + | cachegroup | no | Return only static DNS entries assigned to the :term:`Cache Group` that has this :ref:`cache-group-name` | +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+ - | cachegroupId | no | Return only static DNS entries assigned to the :term:`Cache Group` identified by this integral, unique identifier | + | cachegroupId | no | Return only static DNS entries assigned to the :term:`Cache Group` that has this :ref:`cache-group-id` | +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+ - | deliveryservice | no | Return only static DNS entries that apply within the domain of the :term:`Delivery Service` with this 'xml_id' | + | deliveryservice | no | Return only static DNS entries that apply within the domain of the :term:`Delivery Service` with this :ref:`ds-xmlid` | +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+ | deliveryserviceId | no | Return only static DNS entries that apply within the domain of the :term:`Delivery Service` identified by this integral, unique identifier | +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+ @@ -75,12 +75,12 @@ Request Structure Response Structure ------------------ -:address: If ``typeId`` identifies a ``CNAME`` type record, this is the Canonical Name (CNAME) of the server, otherwise it is the IP address to which ``host`` shall be resolved -:cachegroup: An optional string containing the name of a Cache Group which will service this static DNS entry +:address: If ``typeId`` identifies a ``CNAME`` type record, this is the Canonical Name (CNAME) of the server, otherwise it is the IP address to which ``host`` shall be resolved +:cachegroup: An optional string containing the :ref:`Name of a Cache Group ` which will service this static DNS entry .. note:: This field has no effect, and is not used by any part of Traffic Control. It exists for legacy compatibility reasons. -:cachegroupId: An optional, integral, unique identifier of a Cache Group which will service this static DNS entry +:cachegroupId: An optional, integer that is the :ref:`ID of a Cache Group ` which will service this static DNS entry .. note:: This field has no effect, and is not used by any part of Traffic Control. It exists for legacy compatibility reasons. @@ -88,9 +88,9 @@ Response Structure :deliveryserviceId: The integral, unique identifier of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active :host: If ``typeId`` identifies a ``CNAME`` type record, this is an alias for the CNAME of the server, otherwise it is the Fully Qualified Domain Name (FQDN) which shall resolve to ``address`` :id: An integral, unique identifier for this static DNS entry -:ttl: The Time To Live (TTL) of this static DNS entry in seconds +:ttl: The :abbr:`TTL (Time To Live)` of this static DNS entry in seconds :type: The name of the type of this static DNS entry -:typeId: The integral, unique identifier of the type of this static DNS entry +:typeId: The integral, unique identifier of the :term:`Type` of this static DNS entry .. code-block:: http :caption: Response Example @@ -135,15 +135,15 @@ Creates a new, static DNS entry. Request Structure ----------------- -:address: If ``typeId`` identifies a ``CNAME`` type record, this is the Canonical Name (CNAME) of the server, otherwise it is the IP address to which ``host`` shall be resolved -:cachegroupId: An optional, integral, unique identifier of a Cache Group which will service this static DNS entry +:address: If ``typeId`` identifies a ``CNAME`` type record, this is the Canonical Name (CNAME) of the server, otherwise it is the IP address to which ``host`` shall be resolved +:cachegroupId: An optional, integer that is the :ref:`ID of a Cache Group ` which will service this static DNS entry .. note:: This field has no effect, and is not used by any part of Traffic Control. It exists for legacy compatibility reasons. :deliveryserviceId: The integral, unique identifier of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active -:host: If ``typeId`` identifies a ``CNAME`` type record, this is an alias for the CNAME of the server, otherwise it is the Fully Qualified Domain Name (FQDN) which shall resolve to ``address`` -:ttl: The Time To Live (TTL) of this static DNS entry in seconds -:typeId: The integral, unique identifier of the type of this static DNS entry +:host: If ``typeId`` identifies a ``CNAME`` type record, this is an alias for the CNAME of the server, otherwise it is the :abbr:`FQDN (Fully Qualified Domain Name)` which shall resolve to ``address`` +:ttl: The :term:`TTL (Time To Live)` of this static DNS entry in seconds +:typeId: The integral, unique identifier of the :term:`Type` of this static DNS entry .. code-block:: http :caption: Request Example @@ -167,11 +167,11 @@ Request Structure Response Structure ------------------ :address: If ``typeId`` identifies a ``CNAME`` type record, this is the Canonical Name (CNAME) of the server, otherwise it is the IP address to which ``host`` shall be resolved -:cachegroup: An optional string containing the name of a Cache Group which will service this static DNS entry +:cachegroup: An optional string containing the :ref:`Name of a Cache Group ` which will service this static DNS entry .. note:: This field has no effect, and is not used by any part of Traffic Control. It exists for legacy compatibility reasons. -:cachegroupId: An optional, integral, unique identifier of a Cache Group which will service this static DNS entry +:cachegroupId: An optional, integer that is the :ref:`ID of a Cache Group ` which will service this static DNS entry .. note:: This field has no effect, and is not used by any part of Traffic Control. It exists for legacy compatibility reasons. @@ -179,9 +179,9 @@ Response Structure :deliveryserviceId: The integral, unique identifier of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active :host: If ``typeId`` identifies a ``CNAME`` type record, this is an alias for the CNAME of the server, otherwise it is the Fully Qualified Domain Name (FQDN) which shall resolve to ``address`` :id: An integral, unique identifier for this static DNS entry -:ttl: The Time To Live (TTL) of this static DNS entry in seconds -:type: The name of the type of this static DNS entry -:typeId: The integral, unique identifier of the type of this static DNS entry +:ttl: The :abbr:`TTL (Time To Live)` of this static DNS entry in seconds +:type: The name of the :term:`Type` of this static DNS entry +:typeId: The integral, unique identifier of the :term:`Type` of this static DNS entry .. code-block:: http :caption: Response Example @@ -224,9 +224,9 @@ Response Structure Updates a static DNS entry. -Authentication Required: Yes - -Role(s) Required: admin or oper +:Auth. Required: Yes +:Role(s) Required: "admin" or "operator" +:Response Type: Object Request Structure ----------------- @@ -239,14 +239,14 @@ Request Structure +------+-------------------------------------------------------------------+ :address: If ``typeId`` identifies a ``CNAME`` type record, this is the Canonical Name (CNAME) of the server, otherwise it is the IP address to which ``host`` shall be resolved -:cachegroupId: An optional, integral, unique identifier of a Cache Group which will service this static DNS entry +:cachegroupId: An optional, integer that is the :ref:`ID of a Cache Group ` which will service this static DNS entry .. note:: This field has no effect, and is not used by any part of Traffic Control. It exists for legacy compatibility reasons. :deliveryserviceId: The integral, unique identifier of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active :host: If ``typeId`` identifies a ``CNAME`` type record, this is an alias for the CNAME of the server, otherwise it is the Fully Qualified Domain Name (FQDN) which shall resolve to ``address`` -:ttl: The Time To Live (TTL) of this static DNS entry in seconds -:typeId: The integral, unique identifier of the type of this static DNS entry +:ttl: The :abbr:`TTL (Time To Live)` of this static DNS entry in seconds +:typeId: The integral, unique identifier of the :term:`Type` of this static DNS entry .. code-block:: http :caption: Request Example @@ -269,22 +269,22 @@ Request Structure Response Structure ------------------ -:address: If ``typeId`` identifies a ``CNAME`` type record, this is the Canonical Name (CNAME) of the server, otherwise it is the IP address to which ``host`` shall be resolved -:cachegroup: An optional string containing the name of a Cache Group which will service this static DNS entry +:address: If ``typeId`` identifies a ``CNAME`` type record, this is the Canonical Name (CNAME) of the server, otherwise it is the IP address to which ``host`` shall be resolved +:cachegroup: An optional string containing the :ref:`Name of a Cache Group ` which will service this static DNS entry .. note:: This field has no effect, and is not used by any part of Traffic Control. It exists for legacy compatibility reasons. -:cachegroupId: An optional, integral, unique identifier of a Cache Group which will service this static DNS entry +:cachegroupId: An optional, integer that is the :ref:`ID of a Cache Group ` which will service this static DNS entry .. note:: This field has no effect, and is not used by any part of Traffic Control. It exists for legacy compatibility reasons. :deliveryservice: The name of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active :deliveryserviceId: The integral, unique identifier of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active -:host: If ``typeId`` identifies a ``CNAME`` type record, this is an alias for the CNAME of the server, otherwise it is the Fully Qualified Domain Name (FQDN) which shall resolve to ``address`` +:host: If ``typeId`` identifies a ``CNAME`` type record, this is an alias for the CNAME of the server, otherwise it is the :abbr:`FQDN (Fully Qualified Domain Name)` which shall resolve to ``address`` :id: An integral, unique identifier for this static DNS entry -:ttl: The Time To Live (TTL) of this static DNS entry in seconds -:type: The name of the type of this static DNS entry -:typeId: The integral, unique identifier of the type of this static DNS entry +:ttl: The :abbr:`TTL (Time To Live)` of this static DNS entry in seconds +:type: The name of the :term:`Type` of this static DNS entry +:typeId: The integral, unique identifier of the :term:`Type` of this static DNS entry .. code-block:: http :caption: Response Example diff --git a/docs/source/api/statuses.rst b/docs/source/api/statuses.rst index 5a7e24632d..93d410384e 100644 --- a/docs/source/api/statuses.rst +++ b/docs/source/api/statuses.rst @@ -68,7 +68,7 @@ Response Structure ------------------ :description: A short description of the status :id: The integral, unique identifier of this status -:lastUpdated: The date and time at which this status was last modified, in ISO format +:lastUpdated: The date and time at which this status was last modified, in an ISO-like format :name: The name of the status .. code-block:: http diff --git a/docs/source/api/statuses_id.rst b/docs/source/api/statuses_id.rst index 3d8da52852..52ed556cf5 100644 --- a/docs/source/api/statuses_id.rst +++ b/docs/source/api/statuses_id.rst @@ -18,8 +18,6 @@ ******************* ``statuses/{{ID}}`` ******************* -.. deprecated:: 1.1 - Use the ``id`` query parameter of :ref:`to-api-statuses-id` instead ``GET`` ======= @@ -71,7 +69,7 @@ Response Structure ------------------ :description: A short description of the status :id: The integral, unique identifier of this status -:lastUpdated: The date and time at which this status was last modified, in ISO format +:lastUpdated: The date and time at which this status was last modified, in an ISO-like format :name: The name of the status .. code-block:: http diff --git a/docs/source/api/steering_id_targets.rst b/docs/source/api/steering_id_targets.rst index e259eb0851..75ad4f527e 100644 --- a/docs/source/api/steering_id_targets.rst +++ b/docs/source/api/steering_id_targets.rst @@ -68,13 +68,13 @@ Request Structure Response Structure ------------------ -:deliveryService: The 'xml_id' of the steering :term:`Delivery Service` +:deliveryService: A string that is the :ref:`ds-xmlid` of the steering :term:`Delivery Service` :deliveryServiceId: An integral, unique identifier for the steering :term:`Delivery Service` -:target: The 'xml_id' of this target :term:`Delivery Service` +:target: A string that is the :ref:`ds-xmlid` of this target :term:`Delivery Service` :targetId: An integral, unique identifier for this target :term:`Delivery Service` :type: The routing type of this target :term:`Delivery Service` -:typeId: An integral, unique identifier for the routing type of this target :term:`Delivery Service` -:value: The 'weight' attributed to this steering target +:typeId: An integral, unique identifier for the :ref:`routing type ` of this target :term:`Delivery Service` +:value: The 'weight' attributed to this steering target as an integer .. code-block:: http :caption: Response Example @@ -144,13 +144,13 @@ Request Structure Response Structure ------------------ -:deliveryService: The 'xml_id' of the steering :term:`Delivery Service` +:deliveryService: A string that is the :ref:`ds-xmlid` of the steering :term:`Delivery Service` :deliveryServiceId: An integral, unique identifier for the steering :term:`Delivery Service` -:target: The 'xml_id' of the newly added target :term:`Delivery Service` -:targetId: An integral, unique identifier for the newly added target :term:`Delivery Service` -:type: The routing type of the newly added target :term:`Delivery Service` -:typeId: An integral, unique identifier for the routing type of the newly added target :term:`Delivery Service` -:value: The 'weight' attributed to the new steering target +:target: A string that is the :ref:`ds-xmlid` of this target :term:`Delivery Service` +:targetId: An integral, unique identifier for this target :term:`Delivery Service` +:type: The routing type of this target :term:`Delivery Service` +:typeId: An integral, unique identifier for the :ref:`routing type ` of this target :term:`Delivery Service` +:value: The 'weight' attributed to this steering target as an integer .. code-block:: http :caption: Response Example diff --git a/docs/source/api/steering_id_targets_targetID.rst b/docs/source/api/steering_id_targets_targetID.rst index be7ff2dc39..de94e24d8f 100644 --- a/docs/source/api/steering_id_targets_targetID.rst +++ b/docs/source/api/steering_id_targets_targetID.rst @@ -21,10 +21,7 @@ ``GET`` ======= -.. deprecated:: 1.1 - Use the ``target`` query parameter of a ``GET`` request to the :ref:`to-api-steering-id-targets` endpoint instead. - -Get a single target for a specific STEERING :term:`Delivery Service`. +Get a single target for a specific STEERING-:ref:`ds-types` :term:`Delivery Service`. :Auth. Required: Yes :Roles Required: None @@ -64,13 +61,13 @@ Request Structure Response Structure ------------------ -:deliveryService: The 'xml_id' of the steering :term:`Delivery Service` +:deliveryService: A string that is the :ref:`ds-xmlid` of the steering :term:`Delivery Service` :deliveryServiceId: An integral, unique identifier for the steering :term:`Delivery Service` -:target: The 'xml_id' of this target :term:`Delivery Service` +:target: A string that is the :ref:`ds-xmlid` of this target :term:`Delivery Service` :targetId: An integral, unique identifier for this target :term:`Delivery Service` :type: The routing type of this target :term:`Delivery Service` -:typeId: An integral, unique identifier for the routing type of this target :term:`Delivery Service` -:value: The 'weight' attributed to this steering target +:typeId: An integral, unique identifier for the :ref:`routing type ` of this target :term:`Delivery Service` +:value: The 'weight' attributed to this steering target as an integer .. code-block:: http :caption: Response Example @@ -119,7 +116,7 @@ Request Structure | targetID | The integral, unique identifier of a :term:`Delivery Service` which is a target of the :term:`Delivery Service` identified by ``ID`` | +----------+--------------------------------------------------------------------------------------------------------------------------------------+ -:typeId: The integral, unique identifier of the routing type of the target :term:`Delivery Service` +:typeId: The integral, unique identifier of the :ref:`routing type ` of the target :term:`Delivery Service` :value: The 'weight' which shall be attributed to the target :term:`Delivery Service` .. code-block:: http @@ -140,13 +137,13 @@ Request Structure Response Structure ------------------ -:deliveryService: The 'xml_id' of the steering :term:`Delivery Service` +:deliveryService: A string that is the :ref:`ds-xmlid` of the steering :term:`Delivery Service` :deliveryServiceId: An integral, unique identifier for the steering :term:`Delivery Service` -:target: The 'xml_id' of this target :term:`Delivery Service` +:target: A string that is the :ref:`ds-xmlid` of this target :term:`Delivery Service` :targetId: An integral, unique identifier for this target :term:`Delivery Service` -:type: The new routing type of this target :term:`Delivery Service` -:typeId: An integral, unique identifier for the new routing type of this target :term:`Delivery Service` -:value: The new 'weight' attributed to this steering target +:type: The routing type of this target :term:`Delivery Service` +:typeId: An integral, unique identifier for the :ref:`routing type ` of this target :term:`Delivery Service` +:value: The 'weight' attributed to this steering target as an integer .. code-block:: http :caption: Response Example diff --git a/docs/source/api/tenants.rst b/docs/source/api/tenants.rst index 924214e781..927ccfd96c 100644 --- a/docs/source/api/tenants.rst +++ b/docs/source/api/tenants.rst @@ -68,11 +68,11 @@ Request Structure Response Structure ------------------ -:active: A boolean which indicates whether or not the tenant is active -:id: The integral, unique identifier of this tenant -:name: This tenant's name -:parentId: The integral, unique identifier of this tenant's parent -:parentName: The name of the parent of this tenant +:active: A boolean which indicates whether or not the :term:`Tenant` is active +:id: The integral, unique identifier of this :term:`Tenant` +:name: This :term:`Tenant`'s name +:parentId: The integral, unique identifier of this :term:`Tenant`'s parent +:parentName: The name of the parent of this :term:`Tenant` .. code-block:: http :caption: Response Example diff --git a/docs/source/api/tenants_id.rst b/docs/source/api/tenants_id.rst index 0348e943d2..eed896942a 100644 --- a/docs/source/api/tenants_id.rst +++ b/docs/source/api/tenants_id.rst @@ -21,10 +21,7 @@ ``GET`` ======= -.. deprecated:: 1.1 - Use the ``id`` query parameter of a ``GET`` request to :ref:`to-api-tenants` instead. - -Get a specific tenant. +Get a specific :term:`Tenant`. :Auth. Required: Yes :Roles Required: None @@ -51,10 +48,10 @@ Request Structure Response Structure ------------------ -:active: A boolean which indicates whether or not the tenant is active -:id: The integral, unique identifier of this tenant -:name: This tenant's name -:parentId: The integral, unique identifier of this tenant's parent +:active: A boolean which indicates whether or not the :term:`Tenant` is active +:id: The integral, unique identifier of this :term:`Tenant` +:name: This :term:`Tenant`'s name +:parentId: The integral, unique identifier of this :term:`Tenant`'s parent .. code-block:: http :caption: Response Example diff --git a/docs/source/api/to_extensions.rst b/docs/source/api/to_extensions.rst index ed5670b4f2..78a191a7f9 100644 --- a/docs/source/api/to_extensions.rst +++ b/docs/source/api/to_extensions.rst @@ -54,7 +54,7 @@ Response Structure .. note:: This field has meaning only for "Check Extensions" -:type: The type of extension - there are a set number of allowed values which are not recorded anywhere at the time of this writing +:type: The :term:`Type` of extension - there are a set number of allowed values which are not recorded anywhere at the time of this writing :version: A (hopefully) semantic version number describing the version of the plugin .. code-block:: http @@ -130,7 +130,7 @@ Request Structure .. note:: This field has meaning only for "Check Extensions" -:type: The type of extension - there are a set number of allowed values which are not recorded anywhere at the time of this writing +:type: The :term:`Type` of extension - there are a set number of allowed values which are not recorded anywhere at the time of this writing :version: A (hopefully) semantic version number describing the version of the plugin .. code-block:: http diff --git a/docs/source/api/traffic_monitor_stats.rst b/docs/source/api/traffic_monitor_stats.rst index 0046a8cba8..16a018a67b 100644 --- a/docs/source/api/traffic_monitor_stats.rst +++ b/docs/source/api/traffic_monitor_stats.rst @@ -18,16 +18,13 @@ ************************* ``traffic_monitor/stats`` ************************* -.. deprecated:: TrafficControl 3.0.0 - This endpoint was used by the now-deprecated Traffic Ops UI, and will likely be removed in the future! - .. 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`` ======= :Auth. Required: Yes :Roles Required: None -:Response Type: **NOT PRESENT** - this endpoint returns a special, custom JSON response +:Response Type: **NOT PRESENT** - this endpoint returns a special, custom :mimetype:`application/json` response Request Structure ----------------- diff --git a/docs/source/api/types.rst b/docs/source/api/types.rst index 04ad6714e2..9001bf6752 100644 --- a/docs/source/api/types.rst +++ b/docs/source/api/types.rst @@ -21,7 +21,7 @@ ``GET`` ======= -Retrieves all of the types of things configured in Traffic Ops. Yes, that is as specific as a description of a 'type' can be. +Retrieves all of the :term:`Types` of things configured in Traffic Ops. Yes, that is as specific as a description of a 'type' can be. :Auth. Required: Yes :Roles Required: None diff --git a/docs/source/api/types_id.rst b/docs/source/api/types_id.rst index d4b9bf8696..be25332ae4 100644 --- a/docs/source/api/types_id.rst +++ b/docs/source/api/types_id.rst @@ -21,9 +21,6 @@ ``GET`` ======= -.. deprecated:: 1.1 - Use the ``id`` query parameter of a ``GET`` request to the :ref:`to-api-types` endpoint instead. - :Auth. Required: Yes :Roles Required: None :Response Type: Array diff --git a/docs/source/api/types_trimmed.rst b/docs/source/api/types_trimmed.rst index 9603407aee..25c31de4f1 100644 --- a/docs/source/api/types_trimmed.rst +++ b/docs/source/api/types_trimmed.rst @@ -18,12 +18,12 @@ ***************** ``types/trimmed`` ***************** -.. deprecated:: 1.1 - A type is not a large object. Just get the names from :ref:`to-api-types` instead. ``GET`` ======= -Retrieves only the names of all of the types of things configured in Traffic Ops. Yes, that is as specific as a description of a 'type' can be. +Retrieves only the names of all of the :term:`Types` of things configured in Traffic Ops. Yes, that is as specific as a description of a 'type' can be. + +.. warning:: This endpoint is of limited use because it doesn't tell you what the type of each :term:`Type` is, which describes the types of objects that it can describe. No, I did not just have a stroke while writing this. :Auth. Required: Yes :Roles Required: None diff --git a/docs/source/api/user_current.rst b/docs/source/api/user_current.rst index 034b4046e8..c122c960f7 100644 --- a/docs/source/api/user_current.rst +++ b/docs/source/api/user_current.rst @@ -21,9 +21,6 @@ ``GET`` ======= -.. deprecated:: 1.4 - As a username is needed to log in, any administrator or application must necessarily know the current username at any given time. Thus, use the ``username`` query parameter of a ``GET`` request to :ref:`to-api-users` instead. - Retrieves the profile for the authenticated user. :Auth. Required: Yes diff --git a/docs/source/api/user_login_oauth.rst b/docs/source/api/user_login_oauth.rst index 1bfe2b94c0..69a8e876b5 100644 --- a/docs/source/api/user_login_oauth.rst +++ b/docs/source/api/user_login_oauth.rst @@ -22,8 +22,7 @@ ``POST`` ======== - -Authentication of a user by exchanging a code for an encrypted JSON Web Token from an OAuth service. Traffic Ops will ``POST`` to the authCodeTokenUrl to exchange the code for an encrypted JSON Web Token. It will then decode and validate the token, validate the key set domain, and send back a session cookie. +Authentication of a user by exchanging a code for an encrypted JSON Web Token from an OAuth service. Traffic Ops will ``POST`` to the ``authCodeTokenUrl`` to exchange the code for an encrypted JSON Web Token. It will then decode and validate the token, validate the key set domain, and send back a session cookie. :Auth. Required: No :Roles Required: None diff --git a/docs/source/api/users_id.rst b/docs/source/api/users_id.rst index 7b9f46b679..15b480c128 100644 --- a/docs/source/api/users_id.rst +++ b/docs/source/api/users_id.rst @@ -21,9 +21,6 @@ ``GET`` ======= -.. deprecated:: 1.4 - Use the ``id`` query parameter of a ``GET`` request to the :ref:`to-api-users` endpoint instead. - Retrieves a specific user. :Auth. Required: Yes diff --git a/docs/source/development/traffic_router/traffic_router_api.rst b/docs/source/development/traffic_router/traffic_router_api.rst index 38be8aedde..d537adcfda 100644 --- a/docs/source/development/traffic_router/traffic_router_api.rst +++ b/docs/source/development/traffic_router/traffic_router_api.rst @@ -165,7 +165,7 @@ Request Structure Response Structure ------------------ -:locations: An array of the names of :term:`Cache Groups` to which this Traffic Router is capable of routing client traffic +:locations: An array of strings that are the :ref:`Names of Cache Groups ` to which this Traffic Router is capable of routing client traffic .. code-block:: http :caption: Response Example @@ -232,11 +232,11 @@ Request Structure ----------------- .. table:: Request Path Parameters - +------------+------------------------------------------------------------------------------------------------------------+ - | Name | Description | - +============+============================================================================================================+ - | cachegroup | The name of a :term:`Cache Group` of which a list of constituent :term:`cache servers` will be retrieved | - +------------+------------------------------------------------------------------------------------------------------------+ + +------------+------------------------------------------------------------------------------------------------------------------------------+ + | Name | Description | + +============+==============================================================================================================================+ + | cachegroup | The :ref:`Name of a Cache Group ` of which a list of constituent :term:`cache servers` will be retrieved | + +------------+------------------------------------------------------------------------------------------------------------------------------+ .. code-block:: http @@ -428,13 +428,13 @@ Request Structure ----------------- .. table:: Request Query Parameters - +-------------------+----------+--------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===================+==========+==============================================================================================================+ - | deliveryServiceId | yes | The integral, unique identifier?/'xml_id'?/name? of a :term:`Delivery Service` served by this Traffic Router | - +-------------------+----------+--------------------------------------------------------------------------------------------------------------+ - | cacheLocationId | yes | The name of a :term:`Cache Group` to which this Traffic Router is capable of routing client traffic | - +-------------------+----------+--------------------------------------------------------------------------------------------------------------+ + +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ + | Name | Required | Description | + +===================+==========+================================================================================================================================+ + | deliveryServiceId | yes | The integral, unique identifier?/'xml_id'?/name? of a :term:`Delivery Service` served by this Traffic Router | + +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ + | cacheLocationId | yes | The :ref:`Name of a Cache Group ` to which this Traffic Router is capable of routing client traffic | + +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ Response Structure ------------------ @@ -462,7 +462,7 @@ TBD ``/crs/deepcoveragezone/cachelocation`` ======================================= -The resulting :term:`Cache Group` using deep coverage zone file (deep caching) for a given client IP and :term:`Delivery Service`. +The resulting :term:`Cache Group` using the :term:`Deep Coverage Zone File` (deep caching) for a given client IP and :term:`Delivery Service`. Request Structure ----------------- diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst index b3788e5691..fa3faa3208 100644 --- a/docs/source/glossary.rst +++ b/docs/source/glossary.rst @@ -38,24 +38,15 @@ Glossary Cache Group Cache Groups - A group of caching HTTP proxy servers that together create a combined larger cache using consistent hashing. Traffic Router treats all servers in a :dfn:`Cache Group` as though they are in the same :term:`Physical Location`, though they are in fact only in the same general area. A :dfn:`Cache Group` has one single set of geographical coordinates even if the :term:`cache servers` that make up the :dfn:`Cache Group` are actually in :term:`Physical Locations`. The :term:`cache servers` in a :dfn:`Cache Group` are not aware of the other :term:`cache servers` in the group - there is no clustering software or communications between :term:`cache servers` in a :dfn:`Cache Group`. + A group of caching HTTP proxy servers that together create a combined larger cache using consistent hashing. Traffic Router treats all servers in a :dfn:`Cache Group` as though they are in the same geographic location, though they are in fact only in the same general area. A :dfn:`Cache Group` has one single set of geographical coordinates even if the :term:`cache servers` that make up the :dfn:`Cache Group` are actually in :term:`Physical Locations`. The :term:`cache servers` in a :dfn:`Cache Group` are not aware of the other :term:`cache servers` in the group - there is no clustering software or communications between :term:`cache servers` in a :dfn:`Cache Group`. - There are two basic types of :dfn:`Cache Groups`: EDGE_LOC and MID_LOC ("LOC" being short for "location" - a holdover from when :dfn:`Cache Groups` were called "Cache Locations). Traffic Control is a two-tiered system, where the clients get directed to the Edge-tier (EDGE_LOC) :dfn:`Cache Group`. On cache miss, the :term:`cache server` in the Edge-tier :dfn:`Cache Group` obtains content from a Mid-tier (MID_LOC) :dfn:`Cache Group`, rather than the origin, which is shared with multiple Edge-tier :dfn:`Cache Groups`. Edge-tier :dfn:`Cache Groups` are configured to have a single "parent" :dfn:`Cache Group`, but in general Mid-tier :dfn:`Cache Groups` have many "children". + There are two basic types of :dfn:`Cache Groups`: EDGE_LOC and MID_LOC ("LOC" being short for "location" - a holdover from when :dfn:`Cache Groups` were called "Cache Locations). Traffic Control is a two-tiered system, where the clients get directed to the Edge-tier (EDGE_LOC) :dfn:`Cache Group`. On cache miss, the :term:`cache server` in the Edge-tier :dfn:`Cache Group` obtains content from a Mid-tier (MID_LOC) :dfn:`Cache Group`, rather than the origin, which is shared with multiple Edge-tier :dfn:`Cache Groups`. Edge-tier :dfn:`Cache Groups` are usually configured to have a single "parent" :dfn:`Cache Group`, but in general Mid-tier :dfn:`Cache Groups` have many "children". .. Note:: Often the Edge-tier to Mid-tier relationship is based on network distance, and does not necessarily match the geographic distance. .. seealso:: A :dfn:`Cache Group` serves a particular part of the network as defined in the :term:`Coverage Zone File` (or :term:`Deep Coverage Zone File`, when applicable). - Consider the example CDN in :numref:`fig-cg_hierarchy`. Here some country/province/region has been divided into quarters: Northeast, Southeast, Northwest, and Southwest. The arrows in the diagram indicate the flow of requests. If a client in the Northwest, for example, were to make a request to the :term:`Delivery Service`, it would first be directed to some :term:`cache server` in the "Northwest" Edge-tier :dfn:`Cache Group`. Should the requested content not be in cache, the Edge-tier server will select a parent from the "West" :dfn:`Cache Group` and pass the request up, caching the result for future use. All Mid-tier :dfn:`Cache Groups` (usually) answer to a single :term:`origin` that provides canonical content. If requested content is not in the Mid-tier cache, then the request will be passed up to the :term:`origin` and the result cached. - - .. _fig-cg_hierarchy: - - .. figure:: ./cg_hierarchy.* - :align: center - :width: 60% - :alt: An illustration of Cache Group hierarchy - - An example CDN that shows the hierarchy between four Edge-tier :dfn:`Cache Groups`, two Mid-tier :dfn:`Cache Groups`, and one Origin + .. seealso:: For a more complete description of Cache Groups, see the :ref:`cache-groups` overview section. content routing Directing clients (or client systems) to a particular location or device in a location for optimal delivery of content See also :ref:`http-cr` and :ref:`dns-cr`. diff --git a/docs/source/overview/cache_groups.rst b/docs/source/overview/cache_groups.rst index fbf57c3e4e..53efabd33d 100644 --- a/docs/source/overview/cache_groups.rst +++ b/docs/source/overview/cache_groups.rst @@ -15,10 +15,28 @@ .. _cache-groups: -*********************************** -Regions, Locations and Cache Groups -*********************************** -All servers have to have a :term:`Physical Location`, which defines their geographic latitude and longitude. Each :term:`Physical Location` is part of a :term:`Region`, and each :term:`Region` is part of a :term:`Division`. For example, ``Denver`` could be the name of a :term:`Physical Location` in the ``Mile High`` :term:`Region` and that :term:`Region` could be part of the ``West`` :term:`Division`. The hierarchy between these terms is illustrated graphically in :ref:`topography-hierarchy`. +************ +Cache Groups +************ +A :dfn:`Cache Group` is - ostensibly - exactly what it sounds like it is: a group of :term:`cache servers`. More specifically, every server in a Traffic Control CDN must be in a Cache Group (even if they are not actually :term:`cache servers`). Typically a Cache Group is representative of the available :term:`cache servers` within a specific geographical location. Despite that :term:`cache servers` have their own :term:`Physical Locations`, when :term:`cache servers` are chosen to serve content to a client based on geographic location the geographic location actually used for comparisons is that for the Cache Group that contains it, not the geographic location of the :term:`cache server` itself. + +The most typical :ref:`Types ` of Cache Groups are EDGE_LOC_ which contain :term:`Edge-tier cache servers` and MID_LOC_ which contain :term:`Mid-tier cache servers`. The latter are each designated as a Parent_ of one or more of the former to fill out the two-tiered caching hierarchy of an :abbr:`ATC (Apache Traffic Control)` CDN. + +Consider the example CDN in :numref:`fig-cg_hierarchy`. Here some country/province/region has been divided into quarters: Northeast, Southeast, Northwest, and Southwest. The arrows in the diagram indicate the flow of requests. If a client in the Northwest, for example, were to make a request to the :term:`Delivery Service`, it would first be directed to some :term:`cache server` in the "Northwest" Edge-tier :dfn:`Cache Group`. Should the requested content not be in cache, the Edge-tier server will select a parent from the "West" :dfn:`Cache Group` and pass the request up, caching the result for future use. All Mid-tier :dfn:`Cache Groups` (usually) answer to a single :term:`origin` that provides canonical content. If requested content is not in the Mid-tier cache, then the request will be passed up to the :term:`origin` and the result cached. + +.. _fig-cg_hierarchy: + +.. figure:: images/cg_hierarchy.* + :align: center + :width: 60% + :alt: An illustration of Cache Group hierarchy + + An example CDN that shows the hierarchy between four Edge-tier :dfn:`Cache Groups`, two Mid-tier :dfn:`Cache Groups`, and one Origin + + +Regions, Divisions, and Locations +================================= +In addition to being in a Cache Group, all servers have to have a :term:`Physical Location`, which defines their geographic latitude and longitude. Each :term:`Physical Location` is part of a :term:`Region`, and each :term:`Region` is part of a :term:`Division`. For example, ``Denver`` could be the name of a :term:`Physical Location` in the ``Mile High`` :term:`Region` and that :term:`Region` could be part of the ``West`` :term:`Division`. The hierarchy between these terms is illustrated graphically in :ref:`topography-hierarchy`. .. _topography-hierarchy: @@ -31,4 +49,273 @@ All servers have to have a :term:`Physical Location`, which defines their geogra To create these structures in Traffic Portal, first make at least one :term:`Division` under :menuselection:`Topology --> Divisions`. Next enter the desired :term:`Region`\ (s) in :menuselection:`Topology --> Regions`, referencing the earlier-entered :term:`Division`\ (s). Finally, enter the desired :term:`Physical Location`\ (s) in :menuselection:`Topology --> Phys Locations`, referencing the earlier-entered :term:`Region`\ (s). -All servers also have to be part of a :term:`Cache Group`. A :term:`Cache Group` is a logical grouping of cache servers, that don't have to be in the same :term:`Physical Location` (in fact, usually a :term:`Cache Group` is spread across minimally two :term:`Physical Locations` for redundancy purposes), but share geographical coordinates for content routing purposes. +A Cache Group is a logical grouping of cache servers, that don't have to be in the same :term:`Physical Location` (in fact, usually a Cache Group is spread across minimally two :term:`Physical Locations` for redundancy purposes), but share geographical coordinates for content routing purposes. There is no strict requirement that :term:`cache servers` in a Cache Group share a :term:`Physical Location`, :term:`Region`, or :term:`Division`. This may be confusing at first as there are a few places in code, interfaces, or even documentation where Cache Groups are referred to as "Cache Locations" or even erroneously as "Physical Locations". + +Properties +========== +Cache Groups are modeled several times over, in the Traffic Ops database, in Traffic Portal forms and tables, in the legacy Perl Traffic Ops codebase, and several times for various :ref:`to-api` versions in the new Go Traffic Ops codebase. Go-specific data structures can be found in `the project's GoDoc documentation `_. Rather than application-specific definitions, what follows is an attempt at consolidating all of the different properties and names of properties of Cache Group objects throughout the :abbr:`ATC (Apache Traffic Control)` suite. The names of these fields are typically chosen as the most human-readable and/or most commonly-used names for the fields, and when reading please note that in many cases these names will appear camelCased or snake_cased to be machine-readable. Any aliases of these fields that are not merely case transformations of the indicated, canonical names will be noted in a table of aliases. + +.. seealso:: The API reference for Cache Group-related endpoints such as :ref:`to-api-cachegroups` contains definitions of the Cache Group object(s) returned and/or accepted by those endpoints. + +.. _cache-group-asns: + +ASNs +---- +A Cache group can have zero or more :abbr:`ASNs (Autonomous System Numbers)` assigned to it, which is used to classify traffic that passes through a CDN. These are typically not represented on a Cache Group object itself, but rather as a separate object indicating the relationship, e.g. in the requests and responses of the :ref:`to-api-asns` endpoint. + +.. seealso:: `The Autonomous System Wikipedia page `_ for an explanation of what an :abbr:`ASN (Autonomous System Number)` actually is. + +.. _cache-group-coordinate: + +Coordinate +---------- +.. tip:: Normally, one need not interact with this. In most contexts, this property of a Cache Group is not even exposed, but instead the Cache Group's Latitude_ and Longitude_ are exposed and should be directly manipulated. + +The :dfn:`Coordinate` of a Cache Group defines the geographic coordinates of a Cache Group that is used for routing clients based on geographic location. It is also used to determine the "closest" Cache Group to another for the purposes of `Fallback to Closest`_. + +Typically, this is expressed as an integral, unique identifier for the "Coordinate" object bound to the Cache Group that defines its geographic location, but occasionally it may appear as the name of that "Coordinate" object. + +.. note:: When a new Cache Group is created, it is not necessary to first create a "Coordinate" object where it may reside. Instead, "Coordinates" are created automatically to reflect the Latitude_ and Longitude_ given to the newly created Cache Group. The name of the generated "Coordinate" will conform to the pattern :samp:`from_cachegroup_{Name}` where ``Name`` is the Cache Group's Name_. Because of this, creating new Cache Groups will fail if a "Coordinate" with a name matching that pattern already exists. + +.. _cache-group-fallbacks: + +Fallbacks +--------- +:dfn:`Fallbacks` are a group of zero or more Cache Groups to be considered for routing when a Cache Group becomes unavailable due to high load or excessive maintenance. These are normally represented by an array of each Cache Group's ID_, but may occasionally appear as the Name_ or `Short Name`_ of each Cache Group. + +This set is consulted before `Fallback to Closest`_ is taken into consideration. + +.. seealso:: :ref:`health-proto` + +.. table:: Aliases + + +-----------------------+-------------------------------------------+---------------------------------------------------------------------------------------------------------------+ + | Name | Use(s) | Type(s) | + +=======================+===========================================+===============================================================================================================+ + | Failover Cache Groups | Traffic Portal forms - but **not** tables | List or array of :ref:`Names ` as strings | + +-----------------------+-------------------------------------------+---------------------------------------------------------------------------------------------------------------+ + | backupLocations | In CDN :term:`Snapshots` | A sub-object called "list" which is a list or array of Cache Group :ref:`Names ` as strings | + +-----------------------+-------------------------------------------+---------------------------------------------------------------------------------------------------------------+ + | BackupCacheGroups | Traffic Router source code | A List of strings that are the :ref:`Names ` of Cache Groups | + +-----------------------+-------------------------------------------+---------------------------------------------------------------------------------------------------------------+ + +.. _cache-group-fallback-to-closest: + +Fallback to Closest +------------------- +This is a boolean field which, when ``true`` (``True``, ``TRUE`` etc.) causes routing to "fall back" on the nearest Cache Group - geographically - when this Cache Group becomes unavailable due to high load and/or excessive maintenance. + +When this *is* a "true" value, the closest Cache Group will be chosen if and only if any set of Fallbacks_ configured on the Cache Group has already been exhausted and no available Cache Groups were found.. + +.. seealso:: :ref:`health-proto` + +.. table:: Aliases + + +--------------------------+----------------------+----------------------------------------+ + | Name | Use(s) | Type(s) | + +==========================+======================+========================================+ + | Fallback to Geo Failover | Traffic Portal forms | Unchanged (``bool``, ``Boolean`` etc.) | + +--------------------------+----------------------+----------------------------------------+ + +.. _cache-group-id: + +ID +-- +All Cache Groups have an integral, unique identifier that is mainly used to reference it in the :ref:`to-api`. + +Despite that a Cache Group's Name_ must be unique, this is the identifier most commonly used to represent a unique Cache Group in most contexts throughout :abbr:`ATC (Apache Traffic Control)`. One notable exception is in CDN :term:`Snapshots` and in routing configuration used by Traffic Router. + +.. _cache-group-latitude: + +Latitude +-------- +The Cache Group's geomagnetic latitude for use in routing and for the purposes of `Fallback to Closest`_. + +.. table:: Aliases + + +-----------------------+----------------------+----------------------------------------+ + | Name | Use(s) | Type(s) | + +=======================+======================+========================================+ + | Geo Magnetic Latitude | Traffic Portal forms | Unchanged (``number``, ``float`` etc.) | + +-----------------------+----------------------+----------------------------------------+ + +.. _cache-group-localization-methods: + +Localization Methods +-------------------- +The :dfn:`Localization Methods` of a Cache Group define the methods by which Traffic Router is allowed to route clients to :term:`cache servers` within this Cache Group. This is a collection of the allowed methods, and the values in the collection are restricted to the following. + +- "Coverage Zone File" (alias ``CZ`` in source code, database entries, and :ref:`to-api` requests/responses) allows Traffic Router to direct clients to this Cache Group if they were assigned a geographic location by looking up their IP address in the :term:`Coverage Zone File`. +- "Deep Coverage Zone File" (alias ``DEEP_CZ`` in source code, database entries, and :ref:`to-api` requests/responses) was intended to allow Traffic Router to direct clients to this Cache Group if they were assigned a geographic location by looking up their IP addresses in the :term:`Deep Coverage Zone File`. However, it **has no effect at all**. This option therefore will not appear in Traffic Portal forms. + + .. warning:: In order to make use of "deep caching" for a :term:`Delivery Service`, all that is required is that :term:`Delivery Service` has :ref:`ds-deep-caching` enabled. If that is done and a :term:`cache server` appears in the :term:`Deep Coverage Zone File` then clients can and will be routed using that method. There is no way to disable this behavior on a Cache Group (or otherwise) basis, and the precensce or absence of ``DEEP_CZ`` in a Cache Group's Localization Methods has no meaning. + +- "Geo-IP Database" (alias ``GEO`` in source code, database entries, and :ref:`to-api` requests/responses) allows Traffic Router direct clients to this Cache Group if the client's IP was looked up in a provided IP address-to-geographic location mapping database to provide their geographic location. + +If none of these localization methods are in the set of allowed methods on a Cache Group, it is assumed that *clients should be allowed to be routed to that Cache Group regardless of the method used to determine their geographic location*. + +This property only has meaning for Cache Groups containing :term:`Edge-tier cache servers`. Which is to say (one would hope) that it only has meaning for EDGE_LOC_ Cache Groups. + +.. table:: Aliases + + +------------------------------+--------------------------------------------------+-----------------------------------------------------+ + | Name | Use(s) | Type(s) | + +==============================+==================================================+=====================================================+ + | Enabled Localization Methods | Traffic Portal forms, Traffic Router source code | Unchanged (``Set``, ``Array`` etc.) | + +------------------------------+--------------------------------------------------+-----------------------------------------------------+ + +.. _cache-group-longitude: + +Longitude +--------- +The Cache Group's geomagnetic longitude for use in routing and for the purposes of `Fallback to Closest`_. + +.. table:: Aliases + + +------------------------+----------------------+----------------------------------------+ + | Name | Use(s) | Type(s) | + +========================+======================+========================================+ + | Geo Magnetic Longitude | Traffic Portal forms | Unchanged (``number``, ``float`` etc.) | + +------------------------+----------------------+----------------------------------------+ + + +.. _cache-group-name: + +Name +---- +A unique, human-friendly name for the Cache Group, with no special character restrictions or length limit. + +Though this property must be unique for all Cache Groups, ID_ is more commonly used as a unique identifier for a Cache Group in most contexts. + +.. table:: Aliases + + +------------+-----------------------+--------------------------------------+ + | Name | Use(s) | Type(s) | + +============+=======================+======================================+ + | locationID | CDN :term:`Snapshots` | Unchanged (``str``, ``String`` etc.) | + +------------+-----------------------+--------------------------------------+ + +.. _cache-group-parent: + +Parent +------ +A Cache Group can have a :dfn:`parent` Cache Group which has different meanings based on the Cache Group's Type_. + +- An EDGE_LOC_ Cache Group's parent must be a MID_LOC_ Cache Group. When configuration files are generated for :term:`Edge-tier cache servers`, their :term:`parents` (different from a Cache Group parent) will be selected from the :term:`Mid-tier cache servers` contained within the Cache Group that is the parent of their containing Cache Group. +- A MID_LOC_ Cache Group's parent must be an ORG_LOC_ Cache Group. However, if any given MID_LOC_ *either* **doesn't** *have a parent, or* **does** *and it's an* ORG_LOC_, *then* **all** ORG_LOC_ *Cache Groups* - **even across CDNs** - *will be considered the parents of that* MID_LOC_ *Cache Group*. This parent relationship only has any meaning in the context of "multi-site-origins", as they are unnecessary in other scenarios. + + .. seealso:: :ref:`multi-site-origin-qht` + +- For all other Cache Group :ref:`Types `, parent relationships have no meaningful semantics. + +.. danger:: There is no safeguard in the data model or :ref:`to-api` that ensures these relationships hold. If they are violated, the resulting CDN behavior is undefined - and almost certainly undesirable. + +:dfn:`Parents` are typically represented by their ID_, but may occasionally appear as their Name_. + +.. seealso:: `The Apache Traffic Server documentation for the "parent.config" configuration file `_. :abbr:`ATC (Apache Traffic Control)` parentage relationships boil down to the ``parent`` field of that configuration file, which sets the :term:`parents` of :term:`cache servers`. + +.. table:: Aliases + + +----------------------+---------------------------------------------------------------------------------+---------------------------------------------+ + | Name | Use(s) | Type(s) | + +======================+=================================================================================+=============================================+ + | Parent Cache Group | Traffic Portal forms and tables | Unchanged (``str``, ``String`` etc.) | + +----------------------+---------------------------------------------------------------------------------+---------------------------------------------+ + | ParentCacheGroupID | Traffic Ops database, Traffic Ops Go code, :ref:`to-api` requests and responses | Positive integer (``int``, ``bigint`` etc.) | + +----------------------+---------------------------------------------------------------------------------+---------------------------------------------+ + | ParentCacheGroupName | Traffic Ops database, Traffic Ops Go code, :ref:`to-api` requests and responses | Unchanged (``str``, ``String`` etc.) | + +----------------------+---------------------------------------------------------------------------------+---------------------------------------------+ + +.. _cache-group-parameters: + +Parameters +---------- +For unknown reasons, it's possible to assign :term:`Parameters` to Cache Groups. This has no attached semantics respected by :abbr:`ATC (Apache Traffic Server)`, and exists today only for compatibility purposes. + +These are nearly always represented as a collection of :ref:`Parameter IDs ` but occasionally they can be expressed as full :term:`Parameter` objects. + +.. table:: Aliases + + +----------------------+----------------------------------------------------------------+-------------------------------------------------------------------------------------+ + | Name | Use(s) | Type(s) | + +======================+================================================================+=====================================================================================+ + | cachegroupParameters | Certain :ref:`to-api` responses, sometimes in internal Go code | Usually a tuple of associative information like a Cache Group ID and a Parameter ID | + +----------------------+----------------------------------------------------------------+-------------------------------------------------------------------------------------+ + +.. _cache-group-secondary-parent: + +Secondary Parent +---------------- +A :dfn:`secondary parent` of a Cache Group is used for fall-back purposes on a :term:`cache server`-to-:term:`cache server` basis after routing has already occurred (in contrast with Fallbacks_ and `Fallback to Closest`_ which operate at the routing step on a Cache Group-to-Cache Group basis). + +For an explanation of what it means for one Cache Group to be the Parent_ of another, refer to the Parent_ section. + +.. seealso:: `The Apache Traffic Server documentation for the "parent.config" configuration file `_. :abbr:`ATC (Apache Traffic Control)` secondary parentage relationships boil down to the ``secondary_parent`` field of that configuration file, which sets the "secondary parents" of :term:`cache servers`. + +.. table:: Aliases + + +--------------------------------+---------------------------------------------------------------------------------+---------------------------------------------+ + | Name | Use(s) | Type(s) | + +================================+=================================================================================+=============================================+ + | Secondary Parent Cache Group | Traffic Portal forms and tables | Unchanged (``str``, ``String`` etc.) | + +--------------------------------+---------------------------------------------------------------------------------+---------------------------------------------+ + | SecondaryParentCacheGroupID | Traffic Ops database, Traffic Ops Go code, :ref:`to-api` requests and responses | Positive integer (``int``, ``bigint`` etc.) | + +--------------------------------+---------------------------------------------------------------------------------+---------------------------------------------+ + | SecondaryParentCacheGroupName | Traffic Ops database, Traffic Ops Go code, :ref:`to-api` requests and responses | Unchanged (``str``, ``String`` etc.) | + +--------------------------------+---------------------------------------------------------------------------------+---------------------------------------------+ + +.. _cache-group-servers: + +Servers +------- +The primary purpose of a Cache Group is to contain servers. In most scenarios it is implied or assumed that the servers are :term:`cache servers`, but this is not required and in fact it is not by any means uncommon for the contained servers to be of some other arbitrary :term:`Type`. + +A Cache Group can have zero or more assigned servers, and each server can belong to at most one Cache Group. + +.. _cache-group-short-name: + +Short Name +---------- +This is typically an abbreviation of the Cache Group's Name_. The main difference is that it isn't required to be unique. + +.. _cache-group-type: + +Type +---- +A Cache Group's :term:`Type` determines what kind of servers it contains. Note that there's no real restriction on the kinds of servers that a Cache Group can contain, and this :term:`Type` serves as more of a guide in certain contexts. The :term:`Types` available by default are described in this section. + +.. tip:: Because :term:`Types` are mutable, the actual :term:`Types` that can describe Cache Groups cannot be completely or precisely defined. However, there are no good reasons of which this author can think to modify or delete the default :term:`Types` herein described, and honestly the good reasons to even merely add to their ranks are likely few. + +.. table:: Aliases + + +-----------+-----------------------------------------------------------------------------+----------------------------------------------+ + | Name | Use(s) | Type(s) | + +===========+=============================================================================+==============================================+ + | Type ID | Traffic Ops client and server Go code, :ref:`to-api` requests and responses | positive integer (``int``, ``bigint``, etc.) | + +-----------+-----------------------------------------------------------------------------+----------------------------------------------+ + | Type Name | :ref:`to-api` requests and responses, Traffic Ops database | unchanged (``string``, ``String`` etc.) | + +-----------+-----------------------------------------------------------------------------+----------------------------------------------+ + + +EDGE_LOC +"""""""" +This :term:`Type` of Cache Group contains :term:`Edge-tier cache servers`. + +MID_LOC +""""""" +This :term:`Type` of Cache Group contains :term:`Mid-tier cache servers` + +ORG_LOC +""""""" +This :term:`Type` of Cache Group contains :term:`origins`. The primary purpose of these is to group :term:`origins` for the purposes of "multi-site-origins", and it's suggested that if that doesn't meet your use-case that these be mostly avoided. In general, it's not strictly necessary to create :term:`origin` *servers* in ATC at all, unless you have to support "multi-site-origins". + +.. seealso:: :ref:`multi-site-origin-qht` + +TC_LOC +"""""" +A catch-all :term:`Type` of Cache Group that's meant to house infrastructure servers that gain no special semantics based on the Cache Group containing them, e.g. Traffic Portal instances. + +TR_LOC +"""""" +This :term:`Type` of Cache Group is meant specifically to contain Traffic Router instances. + diff --git a/docs/source/cg_hierarchy.png b/docs/source/overview/images/cg_hierarchy.png similarity index 100% rename from docs/source/cg_hierarchy.png rename to docs/source/overview/images/cg_hierarchy.png diff --git a/docs/source/cg_hierarchy.svg b/docs/source/overview/images/cg_hierarchy.svg similarity index 100% rename from docs/source/cg_hierarchy.svg rename to docs/source/overview/images/cg_hierarchy.svg