diff --git a/docs/source/admin/quick_howto/federations.rst b/docs/source/admin/quick_howto/federations.rst index e6d6cf76e1..b509cf5902 100644 --- a/docs/source/admin/quick_howto/federations.rst +++ b/docs/source/admin/quick_howto/federations.rst @@ -48,7 +48,7 @@ Configure Federations .. code-block:: shell :caption: Example cURL Command - curl -i -XPOST "http://localhost:3000/api/2.0/user/login" -H "Content-Type: application/json" -d '{ "u": "federation_user1", "p": "password" }' + curl -i -XPOST "http://localhost:3000/api/4.0/user/login" -H "Content-Type: application/json" -d '{ "u": "federation_user1", "p": "password" }' .. code-block:: http :caption: Example API Response @@ -74,7 +74,7 @@ Configure Federations .. code-block:: shell :caption: Example cURL Command - curl -ki -H "Cookie: mojolicious=eyJleHBpcmVzIjoxNDQ5MTA1MTI2LCJhdXRoX2RhdGEiOiJmZWRlcmF0aW9uX3VzZXIxIn0---06b4f870d809d82a91433e92eae8320875c3e8b0;" -XPUT 'http://localhost:3000/api/2.0/federations' -d ' + curl -ki -H "Cookie: mojolicious=eyJleHBpcmVzIjoxNDQ5MTA1MTI2LCJhdXRoX2RhdGEiOiJmZWRlcmF0aW9uX3VzZXIxIn0---06b4f870d809d82a91433e92eae8320875c3e8b0;" -XPUT 'http://localhost:3000/api/4.0/federations' -d ' {"federations": [ { "deliveryService": "images-c1", "mappings": diff --git a/docs/source/admin/traffic_router.rst b/docs/source/admin/traffic_router.rst index be53afdc1b..a3761072d1 100644 --- a/docs/source/admin/traffic_router.rst +++ b/docs/source/admin/traffic_router.rst @@ -249,7 +249,7 @@ Much of a Traffic Router's configuration can be obtained through the :term:`Para +-----------------------------------------+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ | api.auth.url | CRConfig.json | The URL of the authentication endpoint of the :ref:`to-api` (:ref:`to-api-user-login`). The actual | | | | :abbr:`FQDN (Fully Qualified Domain Name)` can be subsituted with ``${tmHostname}`` to have Traffic Router automatically fill it in, | - | | | e.g. ``https://${tmHostname}/api/2.0/user/login``. | + | | | e.g. ``https://${tmHostname}/api/4.0/user/login``. | +-----------------------------------------+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ | consistent.dns.routing | CRConfig.json | Control whether :ref:`DNS-routed ` :term:`Delivery Services` use `Consistent Hashing`. May improve performance if set to | | | | "true"; defaults to "false". | diff --git a/docs/source/admin/traffic_vault.rst b/docs/source/admin/traffic_vault.rst index f29067c04c..f8319a699b 100644 --- a/docs/source/admin/traffic_vault.rst +++ b/docs/source/admin/traffic_vault.rst @@ -361,4 +361,4 @@ After Riak has been configured to use Riak Search, permissions still need need t curl --tlsv1.1 --tls-max 1.1 -kvs "https://admin:password@trafficvault.infra.ciab.test:8088/search/query/sslkeys?wt=json&q=cdn:CDN-in-a-Box" # Verify using the Traffic Ops API - curl -Lvs -H "Cookie: $COOKIE" https://trafficops.infra.ciab.test/api/2.0/cdns/name/mycdn/sslkeys + curl -Lvs -H "Cookie: $COOKIE" https://trafficops.infra.ciab.test/api/4.0/cdns/name/mycdn/sslkeys diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst index 967aee2952..db4d5cf060 100644 --- a/docs/source/api/index.rst +++ b/docs/source/api/index.rst @@ -22,7 +22,7 @@ The Traffic Ops API provides programmatic access to read and write Traffic Contr How to Read this Documentation ============================== -Each endpoint for each version is on its own page, titled with the request path. The request paths shown on each endpoint's page are - unless otherwise noted - only usable by being appended to the request path prefix ``/api//`` where ```` is the API version being requested. The API versions officially supported as of the time of this writing are 1.1, 1.2, 1.3, 1.4, 1.5, 2.0. All endpoints are documented as though they were being used in version 1.5 in the version 1 documentation and version 2.0 in the version 2 documentation. If an endpoint or request method of an endpoint is only available after a specific version, that will be noted next to the method or endpoint name. If changes were made to the structure of an endpoint's input or output, the version number and nature of the change will be noted. +Each endpoint for each version is on its own page, titled with the request path. The request paths shown on each endpoint's page are - unless otherwise noted - only usable by being appended to the request path prefix ``/api//`` where ```` is the API version being requested. The API versions officially supported as of the time of this writing are 3.0, 3.1, and 4.0. All endpoints are documented as though they were being used in version 3.1 in the version 3 documentation and version 4.0 in the version 4 documentation. If an endpoint or request method of an endpoint is only available after a specific version, that will be noted next to the method or endpoint name. If changes were made to the structure of an endpoint's input or output, the version number and nature of the change will be noted. Every endpoint is documented with a section for each method, containing the subsections "Request Structure" and "Response Structure" which identify all properties and structure of the Request to and Response from the endpoint. Before these subsections, three key pieces of information will be provided: @@ -111,11 +111,11 @@ Using API Endpoints Example Session --------------- -A user makes a request to the ``/api/2.0/asns`` endpoint. +A user makes a request to the ``/api/4.0/asns`` endpoint. .. code-block:: http - GET /api/2.0/asns HTTP/1.1 + GET /api/4.0/asns HTTP/1.1 Accept: application/json Host: trafficops.infra.ciab.test User-Agent: example @@ -136,11 +136,11 @@ The response JSON indicates an authentication error. } ]} -To authenticate, the user sends a POST request containing their login information to the ``/api/2.0/user/login`` endpoint. +To authenticate, the user sends a POST request containing their login information to the ``/api/4.0/user/login`` endpoint. .. code-block:: http - POST /api/2.0/user/login HTTP/1.1 + POST /api/4.0/user/login HTTP/1.1 User-Agent: example Host: trafficops.infra.ciab.test Accept: application/json @@ -169,11 +169,11 @@ Traffic Ops responds with a Mojolicious cookie to be used for future requests, a } ]} -Using this cookie, the user can now access their original target - the ``/api/2.0/asns`` endpoint... +Using this cookie, the user can now access their original target - the ``/api/4.0/asns`` endpoint... .. code-block:: http - GET /api/2.0/asns HTTP/1.1 + GET /api/4.0/asns HTTP/1.1 Accept: application/json Cookie: mojolicious=...; Host: trafficops.infra.ciab.test @@ -281,7 +281,7 @@ The most common errors returned by Traffic Ops are: When a server-side error occurs, the API will return a ``500 INTERNAL SERVER ERROR`` response. .. code-block:: http - :caption: Example Response to ``GET /api/2.0/servers``. (when a server error such as a postgres failure occured) + :caption: Example Response to ``GET /api/4.0/servers``. (when a server error such as a postgres failure occured) HTTP/1.1 500 Internal Server Error Access-Control-Allow-Credentials: true @@ -309,23 +309,13 @@ TrafficOps Native Client Libraries ================================== TrafficOps client libraries are available in Java, Go and Python. You can read (very little) more about them in the client README at :atc-file:`traffic_control/clients`. -API V2 Routes -============= -API routes available in version 2. - -.. deprecated:: ATCv6 - Traffic Ops API version 2 is deprecated in favor of version 3. - -.. toctree:: - :maxdepth: 4 - :glob: - - v2/* - API V3 Routes ============= API routes available in version 3. +.. deprecated:: ATCv7 + Traffic Ops API version 3 is deprecated in favor of version 4. + .. toctree:: :maxdepth: 4 :glob: @@ -336,8 +326,6 @@ API V4 Routes ============= API routes available in version 4. -.. danger:: API version 4 is *unstable*, meaning that breaking changes can occur at any time. Use at your own peril! - .. toctree:: :maxdepth: 4 :glob: diff --git a/docs/source/api/v2/about.rst b/docs/source/api/v2/about.rst deleted file mode 100644 index 4969d031da..0000000000 --- a/docs/source/api/v2/about.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-about: - -*********** -``about`` -*********** - -``GET`` -======= - -Returns info about the Traffic Ops build that is currently running, generated at startup. The output will be the same until the Traffic Ops :ref:`version changes `. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -No parameters available. - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/about HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - -Response Structure ------------------- -:commitHash: The `Git `_ commit hash that Traffic Ops was built at. -:commits: The number of commits in the branch of the commit that Traffic Ops was built at, including that commit. Calculated by running ``git rev-list HEAD | wc -l``. -:goVersion: The version of `Go `_ that was used to build Traffic Ops. -:release: The major version of CentOS or Red Hat Enterprise Linux that the build environment was running. -:name: The human-readable name of the `RPM `_ file. -:RPMVersion: The entire name of the RPM file, excluding the file extension. -:Version: The version of :abbr:`ATC (Apache Traffic Control)` that this version of Traffic Control belongs to. - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 19:35:28 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 7SVQsddCUVRs+sineziRGR6OyMli7XLZbjxyMQgW6E506bh5thMOuttPFT7aJckDcgT45PlhexycwlApOHI4Vw== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 24 Feb 2020 18:35:28 GMT - Content-Length: 145 - - { - "commitHash": "1c9a2e9c", - "commits": "10555", - "goVersion": "go1.11.13", - "release": "el7", - "name": "traffic_ops", - "RPMVersion": "traffic_ops-4.0.0-10555.1c9a2e9c.el7", - "Version": "4.0.0" - } diff --git a/docs/source/api/v2/api_capabilities.rst b/docs/source/api/v2/api_capabilities.rst deleted file mode 100644 index dd677237f6..0000000000 --- a/docs/source/api/v2/api_capabilities.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-api_capabilities: - -******************** -``api_capabilities`` -******************** -.. deprecated:: 3.1 - -Deals with the capabilities that may be associated with API endpoints and methods. These capabilities are assigned to :term:`Roles`, of which a user may have one or more. Capabilities support "wildcarding" or "globbing" using asterisks to group multiple routes into a single capability - -``GET`` -======= -Get all API-capability mappings. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +----------------+----------+--------+------------------------------------+ - | Name | Required | Type | Description | - +================+==========+========+====================================+ - | capability | no | string | Capability name | - +----------------+----------+--------+------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/api_capabilities?capability=types-write HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:capability: Capability name -:httpMethod: An HTTP request method, practically one of: - - - ``GET`` - - ``POST`` - - ``PUT`` - - ``PATCH`` - - ``DELETE`` - -:httpRoute: The request route for which this capability applies - relative to the Traffic Ops server's URL -:id: An integer which uniquely identifies this capability -:lastUpdated: The time at which this capability was last updated, in :ref:`non-rfc-datetime` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Thu, 01 Nov 2018 14:45:24 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: wptErtIop/AfTTQ+1MZdA2YpPXEOuLFfrPQvvaHqO/uX5fRruOVYW+7p8JTrtH1xg1WN+x6FnjQnSHuWwcpyJg== - Content-Length: 393 - - { "response": [ - { - "httpMethod": "POST", - "lastUpdated": "2018-11-01 14:10:22.794114+00", - "httpRoute": "types", - "id": 261, - "capability": "types-write" - }, - { - "httpMethod": "PUT", - "lastUpdated": "2018-11-01 14:10:22.795917+00", - "httpRoute": "types/*", - "id": 262, - "capability": "types-write" - }, - { - "httpMethod": "DELETE", - "lastUpdated": "2018-11-01 14:10:22.799748+00", - "httpRoute": "types/*", - "id": 263, - "capability": "types-write" - } - ]} diff --git a/docs/source/api/v2/asns.rst b/docs/source/api/v2/asns.rst deleted file mode 100644 index b1447827c8..0000000000 --- a/docs/source/api/v2/asns.rst +++ /dev/null @@ -1,294 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - - -.. _to-api-v2-asns: - -******** -``asns`` -******** -.. seealso:: `The Autonomous System Wikipedia page `_ for an explanation of what an :abbr:`ASN (Autonomous System Number)` actually is. - -``GET`` -======= -List all :abbr:`ASNs (Autonomous System Numbers)`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------------+----------+-----------------------------------------------------------------------------------------------------+ - | Parameter | Required | Description | - +============+==========+=====================================================================================================+ - | 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. | - +------------+----------+-----------------------------------------------------------------------------------------------------+ - | id | no | The integral, unique identifier of the desired | - | | | :abbr:`ASN (Autonomous System Number)`-to-:term:`Cache Group` association | - +------------+----------+-----------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/asns HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - -Response Structure ------------------- -: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 :ref:`non-rfc-datetime` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - 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: Mon, 02 Dec 2019 21:51:14 GMT - Content-Length: 128 - - { "response": [ - { - "asn": 1, - "cachegroup": "TRAFFIC_ANALYTICS", - "cachegroupId": 1, - "id": 1, - "lastUpdated": "2019-12-02 21:49:08+00" - } - ]} - - - -``POST`` -======== -Creates a new :abbr:`ASN (Autonomous System Number)`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -: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 :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/2.0/asns HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - Content-Length: 29 - - {"asn": 1, "cachegroupId": 1} - - -Response Structure ------------------- -: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 :ref:`non-rfc-datetime` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - 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: Mon, 02 Dec 2019 21:49:08 GMT - Content-Length: 150 - - { "alerts": [ - { - "text": "asn was created.", - "level": "success" - } - ], - "response": { - "asn": 1, - "cachegroup": null, - "cachegroupId": 1, - "id": 1, - "lastUpdated": "2019-12-02 21:49:08+00" - }} - -``PUT`` -======= -Updates an existing :abbr:`ASN (Autonomous System Number)`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -:asn: The value of the new :abbr:`ASN (Autonomous System Number)`. -:cachegroup: 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. If you do not pass this field, the cachegroup will be ``null``. -:cachegroupId: The integral, unique identifier of the status of the :term:`Cache Group`. - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/asns?id=1 HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - Content-Length: 53 - - { - "asn": 1, - "cachegroup": "TRAFFIC_OPS", - "cachegroupId": 2 - } - -Response Structure ------------------- -: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 :ref:`non-rfc-datetime` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 25 Feb 2020 07:21:10 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: MjvwJg6AFbdqGPlAhK+2pfiN+VFjzgeNnhXoMVbh6+fRQYKeej6CCj3x09hwOl4uhp9d9RySrE/CQ3+L1b2VGQ== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 25 Feb 2020 06:21:10 GMT - Content-Length: 164 - - { - "alerts": [ - { - "text": "asn was updated.", - "level": "success" - } - ], - "response": { - "asn": 1, - "cachegroup": "TRAFFIC_OPS", - "cachegroupId": 2, - "id": 1, - "lastUpdated": "2020-02-25 06:21:10+00" - } - } - -``DELETE`` ----------- -Deletes an existing :abbr:`ASN (Autonomous System Number)`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/asns?id=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 ------------------- - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 25 Feb 2020 08:27:33 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: Woz8NSHIYVpX4V5X4xZWZIX1hvGL2uian7nUhjZ8F23Nb9RWQRMIg/cc+1vXEzkT/ehKV9t11FKRLX+avSae0g== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 25 Feb 2020 07:27:33 GMT - Content-Length: 83 - - { - "alerts": [ - { - "text": "asn was deleted.", - "level": "success" - } - ] - } diff --git a/docs/source/api/v2/asns_id.rst b/docs/source/api/v2/asns_id.rst deleted file mode 100644 index 463b327692..0000000000 --- a/docs/source/api/v2/asns_id.rst +++ /dev/null @@ -1,153 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - - -.. _to-api-v2-asns-id: - -*************** -``asns/{{id}}`` -*************** -.. seealso:: `The Autonomous System Wikipedia page `_ for an explanation of what an :abbr:`ASN (Autonomous System Number)` actually is. - -``PUT`` -======= -Allows user to edit an existing :abbr:`ASN (Autonomous System Number)`-to-:term:`Cache Group` association. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -: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 - - -.. table:: Request Path Parameters - - +------+----------+--------------------------------------------------------------------------------------------------------------------------+ - | 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/2.0/asns/1 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 29 - Content-Type: application/x-www-form-urlencoded - - {"asn": 2, "cachegroupId": 1} - -Response Structure ------------------- -:asn: 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 :ref:`non-rfc-datetime` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: /83P4LJVsrQx9BKHFxo5pbhQMlB4o3a9v3PpkspyOJcpNx1S/GJhCPpiANBki547sbY+0vTq76IriHZ4GYp8bA== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 08 Nov 2018 14:37:39 GMT - Content-Length: 160 - - { "alerts": [ - { - "text": "asn was updated.", - "level": "success" - } - ], - "response": { - "asn": 2, - "cachegroup": null, - "cachegroupId": 1, - "id": 1, - "lastUpdated": "2018-11-08 14:37:39+00" - }} - -``DELETE`` -========== -Deletes an association between an :abbr:`ASN (Autonomous System Number)` and a :term:`Cache Group`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+----------+--------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +======+==========+==========================================================================================================================+ - | id | yes | The integral, unique identifier of the desired :abbr:`ASN (Autonomous System Number)`-to-:term:`Cache Group` association | - +------+----------+--------------------------------------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/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 ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - 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: Mon, 02 Dec 2019 22:06:24 GMT - Content-Length: 81 - - { "alerts": [ - { - "text": "asn was deleted.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/cache_stats.rst b/docs/source/api/v2/cache_stats.rst deleted file mode 100644 index e5c4551c7b..0000000000 --- a/docs/source/api/v2/cache_stats.rst +++ /dev/null @@ -1,170 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - - -.. _to-api-v2-cache_stats: - -*************** -``cache_stats`` -*************** -Retrieves detailed, aggregated statistics for caches in a specific CDN. - -.. seealso:: This gives an aggregate of statistics for *all caches* within a particular CDN and time range. For statistics basic statistics from all caches regardless of CDN and at the current time, use :ref:`to-api-caches-stats`. - -``GET`` -------- -Retrieves statistics about the caches within the CDN - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Query Parameters - - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +=====================+===================+===========================================================================================================================================================================================+ - | cdnName | yes | The name of a CDN. Results will represent caches within this CDN | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | endDate | yes | The date and time until which statistics shall be aggregated in :rfc:`3339` format (with or without sub-second precision), the number of nanoseconds since the Unix | - | | | Epoch, or in the same, proprietary format as the ``lastUpdated`` fields prevalent throughout the Traffic Ops API | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | exclude | no | Either "series" to omit the data series from the result, or "summary" to omit the summary data from the result - directly corresponds to fields in the | - | | | `Response Structure`_ | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | interval | no | Specifies the interval within which data will be "bucketed"; e.g. when requesting data from 2019-07-25T00:00:00Z to 2019-07-25T23:59:59Z with an interval of "1m", | - | | | the resulting data series (assuming it is not excluded) should contain | - | | | :math:`24\frac{\mathrm{hours}}{\mathrm{day}}\times60\frac{\mathrm{minutes}}{\mathrm{hour}}\times1\mathrm{day}\times1\frac{\mathrm{minute}}{\mathrm{data point}}=1440\mathrm{data\;points}`| - | | | The allowed values for this parameter are valid InfluxQL duration literal strings matching :regexp:`^\d+[mhdw]$` | - | | | | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | limit | no | A natural number indicating the maximum amount of data points should be returned in the ``series`` object | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | metricType | yes | The metric type being reported - one of: 'connections', 'bandwidth', 'maxkbps' | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | offset | no | A natural number of data points to drop from the beginning of the returned data set | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | orderby | no | Though one struggles to imagine why, this can be used to specify "time" to sort data points by their "time" (which is the default behavior) | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | startDate | yes | The date and time from which statistics shall be aggregated in :rfc:`3339` format (with or without sub-second precision), the number of nanoseconds since the Unix | - | | | Epoch, or in the same, proprietary format as the ``lastUpdated`` fields prevalent throughout the Traffic Ops API | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -.. _v2-cache_stats-get-request-example: -.. code-block:: http - :caption: Request Example - - GET /api/2.0/cache_stats?cdnName=CDN&endDate=2019-10-28T20:49:00Z&metricType=bandwidth&startDate=2019-10-28T20:45:00Z HTTP/1.1 - User-Agent: python-requests/2.20.1 - Accept-Encoding: gzip, deflate - Accept: application/json;timestamp=unix, application/json;timestamp=rfc;q=0.9, application/json;q=0.8, */*;q=0.7 - Connection: keep-alive - Cookie: mojolicious=... - -Content Format -"""""""""""""" -It's important to note in :ref:`v2-cache_stats-get-request-example` the use of a complex "Accept" header. This endpoint accepts two special media types in the "Accept" header that instruct it on how to format the timestamps associated with the returned data. Specifically, Traffic Ops will recognize the special, optional, non-standard parameter of :mimetype:`application/json`: ``timestamp``. The values of this parameter are restricted to one of - -rfc - Returned timestamps will be formatted according to :rfc:`3339` (no sub-second precision). -unix - Returned timestamps will be formatted as the number of nanoseconds since the Unix Epoch (midnight on January 1\ :sup:`st` 1970 UTC). - - .. impl-detail:: The endpoint passes back nanoseconds, specifically, because that is the form used both by InfluxDB, which is used to store the data being served, and Go's standard library. Clients may need to convert the value to match their own standard libraries - e.g. the :js:class:`Date` class in Javascript expects milliseconds. - -The default behavior - when only e.g. :mimetype:`application/json` or :mimetype:`*/*` is given - is to use :rfc:`3339` formatting. It will, however, respect quality parameters. It is suggested that clients request timestamps they can handle specifically, rather than relying on this default behavior, as it **is subject to change** and is in fact **expected to invert in the next major release** as string-based time formats become deprecated. - -.. seealso:: For more information on the "Accept" HTTP header, consult `its dedicated page on MDN `_. - -Response Structure ------------------- -:series: An object containing the actual data series and information necessary for working with it. - - :columns: This is an array of names of the columns of the data contained in the "values" array - should always be ``["time", "sum_count"]`` - :count: The number of data points contained in the "values" array - :name: The name of the data set. Should always match :samp:`{metric}.ds.1min` where ``metric`` is the requested ``metricType`` - :values: The actual array of data points. Each represents a length of time specified by the ``interval`` query parameter - - :time: The time at which the measurement was taken. This corresponds to the *beginning* of the interval. This time comes in the format of either an :rfc:`3339`-formatted string, or a number containing the number of nanoseconds since the Unix Epoch depending on the "Accept" header sent by the client, according to the rules outlined in `Content Format`_. - :value: The value of the requested ``metricType`` at the time given by ``time``. This will always be a floating point number, unless no data is available for the data interval, in which case it will be ``null`` - -:summary: A summary of the data contained in the "series" object - - :average: The arithmetic mean of the data's values - :count: The number of measurements taken within the requested timespan. This is, in general, **not** the same as the ``count`` field of the ``series`` object, as it reflects the number of underlying, un-"bucketed" data points, and is therefore dependent on the implementation of Traffic Stats. - :fifthPercentile: Data points with values less than or equal to this number constitute the "bottom" 5% of the data set - :max: The maximum value that can be found in the requested data set - :min: The minimum value that can be found in the requested data set - :ninetyEighthPercentile: Data points with values greater than or equal to this number constitute the "top" 2% of the data set - :ninetyFifthPercentile: Data points with values greater than or equal to this number constitute the "top" 5% of the data set - - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-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: p4asf1n7fXGtgpW/dWgolJWdXjwDcCjyvjOPFqkckbgoXGUHEj5/wlz7brlQ48t3ZnOWCqOlbsu2eSiBssBtUQ== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 28 Oct 2019 20:49:51 GMT - - { "response": { - "series": { - "columns": [ - "time", - "sum_count" - ], - "count": 4, - "name": "bandwidth.cdn.1min", - "tags": { - "cdn": "CDN-in-a-Box" - }, - "values": [ - [ - 1572295500000000000, - null - ], - [ - 1572295560000000000, - 113.66666666666666 - ], - [ - 1572295620000000000, - 108.83333333333334 - ], - [ - 1572295680000000000, - 113 - ] - ] - }, - "summary": { - "average": 111.83333333333333, - "count": 3, - "fifthPercentile": 0, - "max": 113.66666666666666, - "min": 108.83333333333334, - "ninetyEighthPercentile": 113.66666666666666, - "ninetyFifthPercentile": 113.66666666666666 - } - }} diff --git a/docs/source/api/v2/cachegroupparameters.rst b/docs/source/api/v2/cachegroupparameters.rst deleted file mode 100644 index 472fdac8b3..0000000000 --- a/docs/source/api/v2/cachegroupparameters.rst +++ /dev/null @@ -1,191 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cachegroupparameters: - -************************ -``cachegroupparameters`` -************************ - -.. deprecated:: ATCv6 - -``GET`` -======= - -Extract information about the :ref:`cache-group-parameters` associated with :term:`Cache Groups`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Response Structure ------------------- -.. table:: Request Query Parameters - - +-------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +=============+==========+======================================================================================================================================+ - | cachegroup | no | Show only the :ref:`cache-group-parameters` with the :term:`Cache Group` identified by this integral, unique identifier | - +-------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+ - | parameter | no | Show only the :ref:`cache-group-parameters` with the :term:`Parameter` 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``. | - +-------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+ - -Response Structure ------------------- -:cachegroupParameters: An array of identifying information for the :ref:`cache-group-parameters` of :term:`Cache Groups` - - :cachegroup: A string containing the :ref:`cache-group-name` of the :term:`Cache Group` - :last_updated: Date and time of last modification in :ref:`non-rfc-datetime` - :parameter: An integer that is the :term:`Parameter`'s :ref:`parameter-id` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Wed, 14 Nov 2018 18:24:12 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: PZyh09NeYYy4sXSv+Bfov0v32EuEk/1y7/B+4fyvhbcPxWQ650NXBDpAe8IsmYZQYVRB03xlBtc33bo3Ixunbg== - Content-Length: 124 - - { "response": { - "cachegroupParameters": [ - { - "parameter": 124, - "last_updated": "2018-11-14 18:23:40.488853+00", - "cachegroup": "test" - } - ] - }} - -.. deprecated:: ATCv6 - -``POST`` -======== -Assign :term:`Parameter`\ (s) to :term:`Cache Group`\ (s). - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Array - -Request Structure ------------------ -This endpoint accepts two formats for the request payload: - -Single Object Format - For assigning a single :term:`Parameter` to a single :term:`Cache Group` -Array Format - For making multiple assignments of :term:`Parameters` to :term:`Cache Groups` simultaneously - -Single Object Format -"""""""""""""""""""" - -: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 - - POST /api/2.0/cachegroupparameters HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 39 - Content-Type: application/json - - { - "cacheGroupId": 8, - "parameterId": 124 - } - -Array Format -"""""""""""" - -: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 - - POST /api/2.0/cachegroupparameters HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 39 - Content-Type: application/json - - [{ - "cacheGroupId": 8, - "parameterId": 124 - }, - { - "cacheGroupId": 8, - "parameterId": 125 - }] - -Response Structure ------------------- -:cacheGroupId: An integer that is the :ref:`cache-group-id` of the :term:`Cache Group` to which a :term:`Parameter` has been assigned -:parameterId: An integer that is the :ref:`parameter-id` of the :term:`Parameter` which has been assigned - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Wed, 14 Nov 2018 15:47:49 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: wCv388wFaSjgFLCnI9dchlcyGxaVr8IhBAG25F+rpI2/azCswEYTcVBSlYOg6NxTQRzGkluMvn67jI6rV+vNsQ== - Content-Length: 136 - - { "alerts": [ - { - "level": "success", - "text": "Cachegroup parameter associations were created." - } - ], - "response": [ - { - "cacheGroupId": 8, - "parameterId": 124 - } - ]} diff --git a/docs/source/api/v2/cachegroupparameters_id_parameterID.rst b/docs/source/api/v2/cachegroupparameters_id_parameterID.rst deleted file mode 100644 index 98d3862133..0000000000 --- a/docs/source/api/v2/cachegroupparameters_id_parameterID.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cachegroupparameters-id-parameterID: - -*********************************************** -``cachegroupparameters/{{ID}}/{{parameterID}}`` -*********************************************** - -.. deprecated:: ATCv6 - -``DELETE`` -========== -Dissociate a :term:`Parameter` with a :term:`Cache Group` - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +-------------+----------------------------------------------------------------------------------------------------------------+ - | 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 - - DELETE /api/2.0/cachegroupparameters/8/124 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Wed, 14 Nov 2018 18:26:40 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: Cuj+ZPAKsDLp4FpbJDcwsWY0yVQAi1Um1CWraeTIQEMlyJSBEm17oKQWDjzTrvqqV8Prhu3gzlcHoVPzEpbQ1Q== - Content-Length: 84 - - { "alerts": [ - { - "level": "success", - "text": "cachegroup parameter was deleted." - } - ]} diff --git a/docs/source/api/v2/cachegroups.rst b/docs/source/api/v2/cachegroups.rst deleted file mode 100644 index f07c740688..0000000000 --- a/docs/source/api/v2/cachegroups.rst +++ /dev/null @@ -1,236 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cachegroups: - -*************** -``cachegroups`` -*************** - -``GET`` -======= -Extract information about :term:`Cache Groups`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------+----------+--------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+==========================================================================================================================+ - | id | no | Return the only :term:`Cache Group` that has this id | - +-----------+----------+--------------------------------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/cachegroups?type=23 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - - -Response Structure ------------------- -: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]_ -: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 :ref:`non-rfc-datetime` -:latitude: A floating-point :ref:`cache-group-latitude` for the :term:`Cache Group` -:localizationMethods: An array of :ref:`cache-group-localization-methods` as strings -: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'. - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: oV6ifEgoFy+v049tVjSsRdWQf4bxjrUvIYfDdgpUtlxiC7gzCv31m5bXQ8EUBW4eg2hfYM+BsGvJpnNDZB7pUg== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 07 Nov 2018 19:46:36 GMT - Content-Length: 379 - - { "response": [ - { - "id": 7, - "name": "CDN_in_a_Box_Edge", - "shortName": "ciabEdge", - "latitude": 38.897663, - "longitude": -77.036574, - "parentCachegroupName": "CDN_in_a_Box_Mid", - "parentCachegroupId": 6, - "secondaryParentCachegroupName": null, - "secondaryParentCachegroupId": null, - "fallbackToClosest": [], - "localizationMethods": [], - "typeName": "EDGE_LOC", - "typeId": 23, - "lastUpdated": "2018-11-07 14:45:43+00", - "fallbacks": [] - } - ]} - - -``POST`` -======== -Creates a :term:`Cache Group` - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -: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]_ -: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``. - -: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) - - .. 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 :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 - - POST /api/2.0/cachegroups HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 252 - Content-Type: application/json - - { - "name": "test", - "shortName": "test", - "latitude": 0, - "longitude": 0, - "fallbackToClosest": true, - "localizationMethods": [ - "DEEP_CZ", - "CZ", - "GEO" - ], - "typeId": 23, - } - -Response Structure ------------------- -: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]_ -: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 :ref:`non-rfc-datetime` -:latitude: A floating-point :ref:`cache-group-latitude` for the :term:`Cache Group` -:localizationMethods: An array of :ref:`cache-group-localization-methods` as strings -: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 - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: YvZlh3rpfl3nBq6SbNVhbkt3IvckbB9amqGW2JhLxWK9K3cxjBq5J2sIHBUhrLKUhE9afpxtvaYrLRxjt1/YMQ== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 07 Nov 2018 22:11:50 GMT - Content-Length: 379 - - { "alerts": [ - { - "text": "cachegroup was created.", - "level": "success" - } - ], - "response": { - "id": 8, - "name": "test", - "shortName": "test", - "latitude": 0, - "longitude": 0, - "parentCachegroupName": null, - "parentCachegroupId": null, - "secondaryParentCachegroupName": null, - "secondaryParentCachegroupId": null, - "fallbackToClosest": true, - "localizationMethods": [ - "DEEP_CZ", - "CZ", - "GEO" - ], - "typeName": "EDGE_LOC", - "typeId": 23, - "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`. diff --git a/docs/source/api/v2/cachegroups_id.rst b/docs/source/api/v2/cachegroups_id.rst deleted file mode 100644 index e99357e09c..0000000000 --- a/docs/source/api/v2/cachegroups_id.rst +++ /dev/null @@ -1,193 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cachegroups-id: - -********************** -``cachegroups/{{ID}}`` -********************** - -``PUT`` -======= -Update :term:`Cache Group` - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +-----------+----------------------------------------------------+ - | 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 strings that are the :ref:`Names ` of other :term:`Cache Groups` which will be the :ref:`cache-group-fallbacks`\ [#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``. - -: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) - - .. 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 :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 - - PUT /api/2.0/cachegroups/8 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 118 - Content-Type: application/json - - { - "latitude": 0.0, - "longitude": 0.0, - "name": "test", - "fallbacks": [], - "fallbackToClosest": true, - "shortName": "test", - "typeId": 23, - "localizationMethods": ["GEO"] - } - -Response Structure ------------------- -: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]_ -: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 :ref:`non-rfc-datetime` -:latitude: A floating-point :ref:`cache-group-latitude` for the :term:`Cache Group` -:localizationMethods: An array of :ref:`cache-group-localization-methods` as strings -: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 - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: t1W65/2kj25QyHt0Ib0xpBaAR2sXu2kOsRZ49WjKZp/AK5S1YWhX7VNWCuUGiN1VNM4QRNqODC/7ewhYDFUncA== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 14 Nov 2018 19:14:28 GMT - Content-Length: 385 - - { "alerts": [ - { - "text": "cachegroup was updated.", - "level": "success" - } - ], - "response": { - "id": 8, - "name": "test", - "shortName": "test", - "latitude": 0, - "longitude": 0, - "parentCachegroupName": null, - "parentCachegroupId": null, - "secondaryParentCachegroupName": null, - "secondaryParentCachegroupId": null, - "fallbacks": [], - "fallbackToClosest": true, - "localizationMethods": [ - "GEO" - ], - "typeName": "EDGE_LOC", - "typeId": 23, - "lastUpdated": "2018-11-14 19:14:28+00" - }} - - -``DELETE`` -========== -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" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +-----------+------------------------------------------------------------------+ - | Parameter | Description | - +===========+==================================================================+ - | ID | The :ref:`cache-group-id` of a :term:`Cache Group` to be deleted | - +-----------+------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/cachegroups/42 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 5jZBgO7h1eNF70J/cmlbi3Hf9KJPx+WLMblH/pSKF3FWb/10GUHIN35ZOB+lN5LZYCkmk3izGbTFkiruG8I41Q== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 14 Nov 2018 20:31:04 GMT - Content-Length: 57 - - { "alerts": [ - { - "text": "cachegroup was deleted.", - "level": "success" - } - ]} - -.. [#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`. diff --git a/docs/source/api/v2/cachegroups_id_deliveryservices.rst b/docs/source/api/v2/cachegroups_id_deliveryservices.rst deleted file mode 100644 index 6b79d727a9..0000000000 --- a/docs/source/api/v2/cachegroups_id_deliveryservices.rst +++ /dev/null @@ -1,93 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cachegroups-id-deliveryservices: - -*************************************** -``cachegroups/{{ID}}/deliveryservices`` -*************************************** - -``POST`` -======== -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" -:Response Type: Object - -Request Structure ------------------ -.. table::Request Path Parameters - - +------+-----------------------------------------------------------------------------------+ - | 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 :ref:`Cache Group's servers ` are being assigned - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/cachegroups/8/deliveryservices HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 25 - Content-Type: application/json - - {"deliveryServices": [2]} - -Response Structure ------------------- -: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 - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: j/yH0gvJoaGjiLZU/0MA8o5He20O4aJ5wh1eF9ex6F6IBO1liM9Wk9RkWCw7sdiUHoy13/mf7gDntisZwzP7yw== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 14 Nov 2018 19:54:17 GMT - Content-Length: 183 - - { "alerts": [ - { - "text": "Delivery services successfully assigned to all the servers of cache group 8.", - "level": "success" - } - ], - "response": { - "id": 8, - "serverNames": [ - "foo" - ], - "deliveryServices": [ - 2 - ] - }} - diff --git a/docs/source/api/v2/cachegroups_id_parameters.rst b/docs/source/api/v2/cachegroups_id_parameters.rst deleted file mode 100644 index 4cf3a5a554..0000000000 --- a/docs/source/api/v2/cachegroups_id_parameters.rst +++ /dev/null @@ -1,99 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cachegroups-id-parameters: - -********************************* -``cachegroups/{{ID}}/parameters`` -********************************* - -.. deprecated:: ATCv6 - -``GET`` -======= -Gets all of a :ref:`Cache Group's parameters `. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-------------+----------+---------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +=============+==========+===============================================================================================================+ - | 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 | - +-------------+----------+---------------------------------------------------------------------------------------------------------------+ - | 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``. | - +-------------+----------+---------------------------------------------------------------------------------------------------------------+ - -.. table:: Request Path Parameters - - +-----------+----------------------------------------------------------+ - | Parameter | Description | - +===========+==========================================================+ - | ID | The :ref:`cache-group-id` of a :term:`Cache Group` | - +-----------+----------------------------------------------------------+ - - -Response Structure ------------------- -:configFile: The :term:`Parameter`'s :ref:`parameter-config-file` -:id: The :term:`Parameter`'s :ref:`parameter-id` -:lastUpdated: The date and time at which this :term:`Parameter` was last updated, in :ref:`non-rfc-datetime` -:name: :ref:`parameter-name` of the :term:`Parameter` -:secure: A boolean value describing whether or not the :term:`Parameter` is :ref:`parameter-secure` -:value: The :term:`Parameter`'s :ref:`parameter-value` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Wed, 14 Nov 2018 19:56:23 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: DfqPtySzVMpnBYqVt/45sSRG/1pRTlQdIcYuQZ0CQt79QSHLzU5e4TbDqht6ntvNP041LimKsj5RzPlPX1n6tg== - Content-Length: 135 - - { "response": [ - { - "lastUpdated": "2018-11-14 18:22:43.754786+00", - "value": "foobar", - "secure": false, - "name": "foo", - "id": 124, - "configFile": "bar" - } - ]} diff --git a/docs/source/api/v2/cachegroups_id_queue_update.rst b/docs/source/api/v2/cachegroups_id_queue_update.rst deleted file mode 100644 index 44dbd1ee63..0000000000 --- a/docs/source/api/v2/cachegroups_id_queue_update.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cachegroups-id-queue_update: - -*********************************** -``cachegroups/{{ID}}/queue_update`` -*********************************** - -``POST`` -======== -: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" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+------------------------------------------------------------------------------------------------------------+ - | 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]_ -:cdnId: The integral, unique identifier for the CDN in need of :term:`Queue Updates`, or a "dequeue" thereof\ [#required]_ - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/cachegroups/8/queue_update HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 42 - Content-Type: application/json - - {"action": "queue", "cdn": "CDN-in-a-Box"} - - -Response Structure ------------------- -:action: The action processed, one of "queue" or "dequeue" -: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 :ref:`Cache Group's servers ` which are also assigned to the CDN specified in the ``"cdn"`` field - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: UAcP7LrflU1RnfR4UqbQrJczlk5rkrcLOtTXJTFvIUXxK1EklZkHkE4vewjDaVIhJJ6YQg8jmPGQpr+x1RHabw== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 14 Nov 2018 20:19:46 GMT - Content-Length: 115 - - { "response": { - "cachegroupName": "test", - "action": "queue", - "serverNames": [ - "foo" - ], - "cdn": "CDN-in-a-Box", - "cachegroupID": 8 - }} - -.. [#required] Either 'cdn' or 'cdnID' *must* be in the request data (but not both). diff --git a/docs/source/api/v2/caches_stats.rst b/docs/source/api/v2/caches_stats.rst deleted file mode 100644 index 351b519e3b..0000000000 --- a/docs/source/api/v2/caches_stats.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - - -.. _to-api-v2-caches-stats: - -**************** -``caches/stats`` -**************** -An API endpoint that returns cache statistics using the :ref:`tm-api`. - -.. seealso:: This gives a set of basic statistics for *all* :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`` -======= -Retrieves cache stats from Traffic Monitor. Also includes rows for aggregates. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -No parameters available. - -Response Structure ------------------- -:cachegroup: 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 :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 :term:`cache server` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Wed, 14 Nov 2018 20:25:01 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: DqbLgitanS8q81/qKC1i+ImMiEMF+SW4G9rb79FWdeWcgwFjL810tlTRp1nNNfHV+tajgjyK+wMHobqVyaNEfA== - Content-Length: 133 - - { "response": [ - { - "profile": "ALL", - "connections": 0, - "ip": null, - "status": "ALL", - "healthy": true, - "kbps": 0, - "hostname": "ALL", - "cachegroup": "ALL" - } - ]} diff --git a/docs/source/api/v2/capabilities.rst b/docs/source/api/v2/capabilities.rst deleted file mode 100644 index fdec90cf75..0000000000 --- a/docs/source/api/v2/capabilities.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-capabilities: - -**************** -``capabilities`` -**************** -.. deprecated:: 3.1 - -``GET`` -======= -Get all capabilities. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------+----------+---------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+=====================================================================================================================+ - | name | no | Return only the capability that has this name | - +-----------+----------+---------------------------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/capabilities?name=test HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:name: Name of the capability -:description: Describes the permissions covered by the capability. -:lastUpdated: Date and time of the last update made to this capability, in :ref:`non-rfc-datetime` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Vary: Accept-Encoding - Transfer-Encoding: chunked - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: c18+GtX2ZI8PoCSwuAzBhl+6w3vDpKQTa/cDJC0WHxdpguOL378KBxGWW5PCSyZfJUb7wPyOL5qKMn6NNTufhg== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 15 Aug 2019 17:20:20 GMT - Content-Length: 161 - - { "response": [ - { - "description": "This is only a test. If this were a real capability, it might do something", - "lastUpdated": "2019-08-15 17:18:03+00", - "name": "test" - } - ]} diff --git a/docs/source/api/v2/cdns.rst b/docs/source/api/v2/cdns.rst deleted file mode 100644 index fb0a75c9f6..0000000000 --- a/docs/source/api/v2/cdns.rst +++ /dev/null @@ -1,165 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns: - -******** -``cdns`` -******** -Extract information about all CDNs - -``GET`` -======= -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ - -.. table:: Request Query Parameters - - +---------------+----------+-----------------------------------------------------------------------------------+ - | Parameter | Required | Description | - +===============+==========+===================================================================================+ - | domainName | no | Return only the CDN that has this domain name | - +---------------+----------+-----------------------------------------------------------------------------------+ - | dnssecEnabled | no | Return only the CDNs that are either dnssec enabled or not | - +---------------+----------+-----------------------------------------------------------------------------------+ - | id | no | Return only the CDN that has this id | - +---------------+----------+-----------------------------------------------------------------------------------+ - | name | no | Return only the CDN that has this name | - +---------------+----------+-----------------------------------------------------------------------------------+ - | 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``. | - +---------------+----------+-----------------------------------------------------------------------------------+ - -Response Structure ------------------- -:dnssecEnabled: ``true`` if DNSSEC is enabled on this CDN, otherwise ``false`` -:domainName: Top Level Domain name within which this CDN operates -:id: The integral, unique identifier for the CDN -:lastUpdated: Date and time when the CDN was last modified in :ref:`non-rfc-datetime` -:name: The name of the CDN - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: z9P1NkxGebPncUhaChDHtYKYI+XVZfhE6Y84TuwoASZFIMfISELwADLpvpPTN+wwnzBfREksLYn+0313QoBWhA== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 14 Nov 2018 20:46:57 GMT - Content-Length: 237 - - { "response": [ - { - "dnssecEnabled": false, - "domainName": "-", - "id": 1, - "lastUpdated": "2018-11-14 18:21:06+00", - "name": "ALL" - }, - { - "dnssecEnabled": false, - "domainName": "mycdn.ciab.test", - "id": 2, - "lastUpdated": "2018-11-14 18:21:14+00", - "name": "CDN-in-a-Box" - } - ]} - - -``POST`` -======== -Allows user to create a CDN - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -:dnssecEnabled: If ``true``, this CDN will use DNSSEC, if ``false`` it will not -:domainName: The top-level domain (TLD) belonging to the new CDN -:name: Name of the new CDN - -.. code-block:: http - :caption: Request Structure - - POST /api/2.0/cdns HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 63 - Content-Type: application/json - - {"name": "test", "domainName": "quest", "dnssecEnabled": false} - -Response Structure ------------------- -:dnssecEnabled: ``true`` if the CDN uses DNSSEC, ``false`` otherwise -:domainName: The top-level domain (TLD) assigned to the newly created CDN -:id: An integral, unique identifier for the newly created CDN -:name: The newly created CDN's name - - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 1rZRlOfQioGRrEb4nCfjGGx7y3Ub2h7BZ4z6NbhcY4acPslKSUNM8QLjWTVwLU4WpkfJNxcoyy8NlKULFrY9Bg== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 14 Nov 2018 20:49:28 GMT - Content-Length: 174 - - { "alerts": [ - { - "text": "cdn was created.", - "level": "success" - } - ], - "response": { - "dnssecEnabled": false, - "domainName": "quest", - "id": 3, - "lastUpdated": "2018-11-14 20:49:28+00", - "name": "test" - }} diff --git a/docs/source/api/v2/cdns_capacity.rst b/docs/source/api/v2/cdns_capacity.rst deleted file mode 100644 index f3c712a81d..0000000000 --- a/docs/source/api/v2/cdns_capacity.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-capacity: - -***************** -``cdns/capacity`` -***************** - -``GET`` -======= -Retrieves the aggregate capacity percentages of all :term:`Cache Groups` for a given CDN. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -No parameters available. - -Response Structure ------------------- -:availablePercent: The percent of available (unused) bandwidth to 64 bits of precision\ [1]_ -:unavailablePercent: The percent of unavailable (used) bandwidth to 64 bits of precision\ [1]_ -:utilizedPercent: The percent of bandwidth currently in use to 64 bits of precision\ [1]_ -:maintenancePercent: The percent of bandwidth being used for administrative or analytical processes internal to the CDN to 64 bits of precision\ [1]_ - -.. code-block:: json - :caption: Response Example - - { "response": { - "availablePercent": 89.0939840205533, - "unavailablePercent": 0, - "utilizedPercent": 10.9060020300395, - "maintenancePercent": 0.0000139494071146245 - }} - -.. [1] Following `IEEE 754 `_ diff --git a/docs/source/api/v2/cdns_dnsseckeys_generate.rst b/docs/source/api/v2/cdns_dnsseckeys_generate.rst deleted file mode 100644 index b23e63fc26..0000000000 --- a/docs/source/api/v2/cdns_dnsseckeys_generate.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-dnsseckeys-generate: - -**************************** -``cdns/dnsseckeys/generate`` -**************************** - -``POST`` -======== -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" -:Response Type: Object (string) - -Request Structure ------------------ -:effectiveDate: An optional string containing the date and time at which the newly-generated :abbr:`ZSK (Zone-Signing Key)` and :abbr:`KSK (Key-Signing Key)` become effective, in :RFC:`3339` format. Defaults to the current time if not specified. -:key: Name of the CDN -:kskExpirationDays: Expiration (in days) for the :abbr:`KSKs (Key-Signing Keys)` -:ttl: Time, in seconds, for which the keypairs shall remain valid -:zskExpirationDays: Expiration (in days) for the :abbr:`ZSKs (Zone-Signing Keys)` - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/cdns/dnsseckeys/generate HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - Content-Length: 130 - - { - "key": "CDN-in-a-Box", - "kskExpirationDays": 1095, - "ttl": 3600, - "zskExpirationDays": 1095 - } - - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 19:42:15 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: O9SPWzeMNFgg6I/PPeXittBIhdh3/zUKK1NwNlYIM9SszSrk0h/Dfz7tnwgnA7h/s6M4eYBJxykDpCfVC7xpeg== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 24 Feb 2020 18:42:15 GMT - Content-Length: 89 - - { - "response": "Successfully created dnssec keys for CDN-in-a-Box" - } diff --git a/docs/source/api/v2/cdns_dnsseckeys_refresh.rst b/docs/source/api/v2/cdns_dnsseckeys_refresh.rst deleted file mode 100644 index 77c82cb326..0000000000 --- a/docs/source/api/v2/cdns_dnsseckeys_refresh.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-dnsseckeys-refresh: - -*************************** -``cdns/dnsseckeys/refresh`` -*************************** - -``GET`` -======= -Refresh the DNSSEC keys for all CDNs. This call initiates a background process to refresh outdated keys, and immediately returns a response that the process has started. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: Object (string) - -Request Structure ------------------ -No parameters available - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Wed, 14 Nov 2018 21:37:30 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: Uwl+924m6Ye3NraFP+RBpldkhcNTTDyXHZbzRaYV95p9tP56Z61gckeKSr1oQIkNXjXcCsDN5Dmum7Zk1AR6Hw== - Content-Length: 69 - - { - "response": "Checking DNSSEC keys for refresh in the background" - } diff --git a/docs/source/api/v2/cdns_domains.rst b/docs/source/api/v2/cdns_domains.rst deleted file mode 100644 index 7a5a5b7fa6..0000000000 --- a/docs/source/api/v2/cdns_domains.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-domains: - -**************** -``cdns/domains`` -**************** - -``GET`` -======= -Gets a list of domains and their related Traffic Router :term:`Profiles` for all CDNs. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -No parameters available. - -Response Structure ------------------- -:domainName: The :abbr:`TLD (Top-Level Domain)` assigned to this CDN -:parameterId: The :ref:`parameter-id` for the :term:`Parameter` that sets this :abbr:`TLD (Top-Level Domain)` on the Traffic Router -:profileDescription: A short, human-readable description of the Traffic Router's profile -:profileId: The :ref:`profile-id` of the :term:`Profile` assigned to the Traffic Router responsible for serving ``domainName`` -:profileName: The :ref:`profile-name` of the :term:`Profile` assigned to the Traffic Router responsible for serving ``domainName`` - -.. code-block:: json - :caption: Response Example - - { "response": [ - { - "profileId": 12, - "parameterId": -1, - "profileName": "CCR_CIAB", - "profileDescription": "Traffic Router for CDN-In-A-Box", - "domainName": "mycdn.ciab.test" - } - ]} diff --git a/docs/source/api/v2/cdns_health.rst b/docs/source/api/v2/cdns_health.rst deleted file mode 100644 index 2dfb57cd6c..0000000000 --- a/docs/source/api/v2/cdns_health.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-health: - -*************** -``cdns/health`` -*************** -Extract health information from all :term:`Cache Groups` across all CDNs - -.. seealso:: :ref:`health-proto` - -``GET`` -======= -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -No parameters available - -Response Structure ------------------- -:cachegroups: An array of objects describing the health of each Cache Group - - :name: The name of the Cache Group - :offline: The number of OFFLINE caches in the Cache Group - :online: The number of ONLINE caches in the Cache Group - -:totalOffline: Total number of OFFLINE caches across all Cache Groups which are assigned to any CDN -:totalOnline: Total number of ONLINE caches across all Cache Groups which are assigned to any CDN - -.. code-block:: json - :caption: Response Example - - { "response": { - "totalOffline": 0, - "totalOnline": 1, - "cachegroups": [ - { - "offline": 0, - "name": "CDN_in_a_Box_Edge", - "online": 1 - } - ] - }} diff --git a/docs/source/api/v2/cdns_id.rst b/docs/source/api/v2/cdns_id.rst deleted file mode 100644 index afb676c4ff..0000000000 --- a/docs/source/api/v2/cdns_id.rst +++ /dev/null @@ -1,135 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-id: - -*************** -``cdns/{{ID}}`` -*************** - -``PUT`` -======= -Allows a user to edit a specific CDN - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------------+ - | Name | Description | - +======+===================================================+ - | ID | Integral, unique identifier for the CDN to update | - +------+---------------------------------------------------+ - -:dnssecEnabled: If ``true``, this CDN will use DNSSEC, if ``false`` it will not -:domainName: The top-level domain (TLD) belonging to the CDN -:name: Name of the new CDN - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/cdns/3 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 63 - Content-Type: application/json - - {"name": "quest", "domainName": "test", "dnssecEnabled": false} - -Response Structure ------------------- -:dnssecEnabled: ``true`` if the CDN uses DNSSEC, ``false`` otherwise -:domainName: The top-level domain (TLD) assigned to the newly created CDN -:id: An integral, unique identifier for the newly created CDN -:name: The newly created CDN's name - - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: sI1hzBwG+/VAzoFY20kqGFA2RgrUOThtMeeJqk0ZxH3TRxTWuA8BetACct/XICC3n7hPDLlRVpwckEyBdyJkXg== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 14 Nov 2018 20:54:33 GMT - Content-Length: 174 - - { "alerts": [ - { - "text": "cdn was updated.", - "level": "success" - } - ], - "response": { - "dnssecEnabled": false, - "domainName": "test", - "id": 4, - "lastUpdated": "2018-11-14 20:54:33+00", - "name": "quest" - }} - -``DELETE`` -========== -Allows a user to delete a specific CDN - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+------------------------------------------------------+ - | Name | Description | - +======+======================================================+ - | ID | The integral, unique identifier of the CDN to delete | - +------+------------------------------------------------------+ - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: Zy4cJN6BEct4ltFLN4e296mM8XnzOs0EQ3/jp4TA3L+g8qtkI0WrL+ThcFq4xbJPU+KHVDSi+b0JBav3xsYPqQ== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 14 Nov 2018 20:51:23 GMT - Content-Length: 58 - - { "alerts": [ - { - "text": "cdn was deleted.", - "level": "success" - } - ]} - diff --git a/docs/source/api/v2/cdns_id_queue_update.rst b/docs/source/api/v2/cdns_id_queue_update.rst deleted file mode 100644 index 1496a1e90a..0000000000 --- a/docs/source/api/v2/cdns_id_queue_update.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-id-queue_update: - -**************************** -``cdns/{{ID}}/queue_update`` -**************************** - -``POST`` -======== -:term:`Queue` or "dequeue" updates for all servers assigned to a specific CDN. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------------------------------------+ - | Name | Description | - +======+===========================================================================+ - | ID | The integral, unique identifier for the CDN on which to (de)queue updates | - +------+---------------------------------------------------------------------------+ - -:action: One of "queue" or "dequeue" as appropriate - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/cdns/2/queue_update HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 19 - Content-Type: application/json - - {"action": "queue"} - -Response Structure ------------------- -:action: The action processed, either ``"queue"`` or ``"dequeue"`` -:cdnId: The integral, unique identifier for the CDN on which :term:`Queue Updates` was performed or cleared - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: rBpFfrrP+9IFkwsRloEM+v+I8MuBZDXqFu+WUTGtRGypnAn2gHooPoNQRyVvJGjyIQrLXLvqjEtve+lH2Tj4uw== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 14 Nov 2018 21:02:07 GMT - Content-Length: 41 - - { "response": { - "action": "queue", - "cdnId": 2 - }} diff --git a/docs/source/api/v2/cdns_name_configs_monitoring.rst b/docs/source/api/v2/cdns_name_configs_monitoring.rst deleted file mode 100644 index 1e7cf8181a..0000000000 --- a/docs/source/api/v2/cdns_name_configs_monitoring.rst +++ /dev/null @@ -1,248 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-name-configs-monitoring: - -************************************ -``cdns/{{name}}/configs/monitoring`` -************************************ - -.. seealso:: :ref:`health-proto` - -``GET`` -======= -Retrieves information concerning the monitoring configuration for a specific CDN. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+------------------------------------------------------------------------+ - | Name | Description | - +======+========================================================================+ - | name | The name of the CDN for which monitoring configuration will be fetched | - +------+------------------------------------------------------------------------+ - -Response Structure ------------------- -:cacheGroups: An array of objects representing each of the :term:`Cache Groups` being monitored within this CDN - - :coordinates: An object representing the geographic location of this :term:`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: A string that is this :ref:`Cache Group's name ` - -:config: A collection of parameters used to configure the monitoring behaviour of Traffic Monitor - - :health.polling.interval: An interval in milliseconds on which to poll for cache statistics - :heartbeat.polling.interval: An interval in milliseconds on which to poll for health statistics. If missing, defaults to ``health.polling.interval``. - :tm.polling.interval: The interval at which to poll for configuration updates - -:deliveryServices: An array of objects representing each :term:`Delivery Service` provided by this CDN - - :hostRegexes: An array of strings which are the Delivery Service's HOST_REGEXP-type regexes - :status: The :term:`Delivery Service`'s status - :topology: A string that is the name of the Delivery Service's :term:`Topology` (if assigned one) - :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 - :type: A string that is the Delivery Service's type category (``"HTTP"`` or ``"DNS"``) - :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: 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" - - .. 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 ` - -:topologies: A map of :term:`Topology` names to objects - - :nodes: An array of strings which are the names of the EDGE_LOC-type cache groups in the topology - -:trafficMonitors: An array of objects representing each Traffic Monitor that monitors this CDN (this is used by Traffic Monitor's "peer polling" function) - - :cachegroup: The name of the :term:`Cache Group` to which this Traffic Monitor belongs - :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 IPv4 address of this Traffic Monitor - :port: The port on which this Traffic Monitor listens for incoming connections - :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 :term:`Cache Group` to which this :term:`cache server` belongs - :deliveryServices: An array of objects which contain the XML IDs of the delivery services to which this cache server is assigned (this field is omitted entirely if no delivery services are assigned to this cache server) - - :xmlId: A string which is the XML ID of the delivery service - - :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 :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 - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: uLR+tRoqR8SYO38j3DV9wQ+IkJ7Kf+MCoFkcWZtsgbpLJ+0S6f+IiI8laNVeDgrM/P23MAQ6BSepm+EJRl1AXQ== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 14 Nov 2018 21:09:31 GMT - Transfer-Encoding: chunked - - { "response": { - "topologies": { - "example-topology": { - "nodes": [ - "CDN_in_a_Box_Edge" - ] - } - }, - "trafficServers": [ - { - "profile": "ATS_EDGE_TIER_CACHE", - "status": "REPORTED", - "ip": "172.16.239.100", - "ip6": "fc01:9400:1000:8::100", - "port": 80, - "cacheGroup": "CDN_in_a_Box_Edge", - "hostname": "edge", - "fqdn": "edge.infra.ciab.test", - "interfacename": "eth0", - "type": "EDGE", - "hashid": "edge" - }, - { - "profile": "ATS_MID_TIER_CACHE", - "status": "REPORTED", - "ip": "172.16.239.120", - "ip6": "fc01:9400:1000:8::120", - "port": 80, - "cacheGroup": "CDN_in_a_Box_Mid", - "hostname": "mid", - "fqdn": "mid.infra.ciab.test", - "interfacename": "eth0", - "type": "MID", - "hashid": "mid" - } - ], - "trafficMonitors": [ - { - "profile": "RASCAL-Traffic_Monitor", - "status": "ONLINE", - "ip": "172.16.239.40", - "ip6": "fc01:9400:1000:8::40", - "port": 80, - "cachegroup": "CDN_in_a_Box_Edge", - "hostname": "trafficmonitor", - "fqdn": "trafficmonitor.infra.ciab.test" - } - ], - "cacheGroups": [ - { - "name": "CDN_in_a_Box_Mid", - "coordinates": { - "latitude": 38.897663, - "longitude": -77.036574 - } - }, - { - "name": "CDN_in_a_Box_Edge", - "coordinates": { - "latitude": 38.897663, - "longitude": -77.036574 - } - } - ], - "profiles": [ - { - "name": "CCR_CIAB", - "type": "CCR", - "parameters": null - }, - { - "name": "ATS_EDGE_TIER_CACHE", - "type": "EDGE", - "parameters": { - "health.connection.timeout": 2000, - "health.polling.url": "http://${hostname}/_astats?application=&inf.name=${interface_name}", - "health.threshold.availableBandwidthInKbps": ">1750000", - "health.threshold.loadavg": "25.0", - "health.threshold.queryTime": 1000, - "history.count": 30 - } - }, - { - "name": "ATS_MID_TIER_CACHE", - "type": "MID", - "parameters": { - "health.connection.timeout": 2000, - "health.polling.url": "http://${hostname}/_astats?application=&inf.name=${interface_name}", - "health.threshold.availableBandwidthInKbps": ">1750000", - "health.threshold.loadavg": "25.0", - "health.threshold.queryTime": 1000, - "history.count": 30 - } - } - ], - "deliveryServices": [ - { - "xmlId": "example-ds", - "totalTpsThreshold": 0, - "status": "REPORTED", - "totalKbpsThreshold": 0, - "type": "DNS", - "topology": "example-topology", - "hostRegexes": [ - ".*\\.example-ds\\..*" - ] - } - ], - "config": { - "health.polling.interval": 6000, - "heartbeat.polling.interval": 3000, - "peers.polling.interval": 3000, - "tm.polling.interval": 2000 - } - }} diff --git a/docs/source/api/v2/cdns_name_dnsseckeys_ksk_generate.rst b/docs/source/api/v2/cdns_name_dnsseckeys_ksk_generate.rst deleted file mode 100644 index 6eb51b3ae4..0000000000 --- a/docs/source/api/v2/cdns_name_dnsseckeys_ksk_generate.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-name-dnsseckeys-ksk-generate: - -***************************************** -``cdns/{{name}}/dnsseckeys/ksk/generate`` -***************************************** - -``POST`` -======== -Generates a new :abbr:`KSK (Key-Signing Key)` for a specific CDN. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: Object (string) - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+----------+-----------------------------------------------------------------------------------+ - | Name | Required | Description | - +======+==========+===================================================================================+ - | name | yes | The name of the CDN for which the :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 ------------------- -.. code-block:: json - :caption: Response Example - - { "response": "Successfully generated ksk dnssec keys for my-cdn-name" } diff --git a/docs/source/api/v2/cdns_name_federations.rst b/docs/source/api/v2/cdns_name_federations.rst deleted file mode 100644 index 0e60126728..0000000000 --- a/docs/source/api/v2/cdns_name_federations.rst +++ /dev/null @@ -1,195 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-name-federations: - -***************************** -``cdns/{{name}}/federations`` -***************************** - -``GET`` -======= -Retrieves a list of federations in use by a specific CDN. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Path Parameters - - +-----------+---------------------------------------------------------------------------------------------------------------+ - | Name | Description | - +===========+===============================================================================================================+ - | name | The name of the CDN for which federations will be listed | - +-----------+---------------------------------------------------------------------------------------------------------------+ - -.. table:: Request Query Parameters - - +-----------+---------------------------------------------------------------------------------------------------------------+ - | Name | Description | - +===========+===============================================================================================================+ - | id | Return only the federation that has this id | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | orderby | Choose the ordering of the results - must be the name of one of the fields of the objects in the ``response`` | - | | array | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | sortOrder | Changes the order of sorting. Either ascending (default or "asc") or descending ("desc") | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | limit | Choose the maximum number of results to return | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | offset | The number of results to skip before beginning to return results. Must use in conjunction with limit | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | page | 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 - - GET /api/2.0/cdns/CDN-in-a-Box/federations HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:cname: The Canonical Name (CNAME) used by the federation -:deliveryService: An object with keys that provide identifying information for the :term:`Delivery Service` using this federation - - :id: The integral, unique identifier for the :term:`Delivery Service` - :xmlId: The :term:`Delivery Service`'s uniquely identifying 'xml_id' - -:description: An optionally-present field containing a description of the field - - .. note:: This key will only be present if the description was provided when the federation was created. Refer to the ``POST`` method of this endpoint to see how federations can be created. - -:lastUpdated: The date and time at which this federation was last modified, in :ref:`non-rfc-datetime` -:ttl: Time to Live (TTL) for the ``cname``, in hours - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - access-control-allow-credentials: true - access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - access-control-allow-methods: POST,GET,OPTIONS,PUT,DELETE - access-control-allow-origin: * - content-type: application/json - set-cookie: mojolicious=...; Path=/; HttpOnly - whole-content-sha512: SJA7G+7G5KcOfCtnE3Dq5DCobWtGRUKSppiDkfLZoG5+paq4E1aZGqUb6vGVsd+TpPg75MLlhyqfdfCHnhLX/g== - x-server-name: traffic_ops_golang/ - content-length: 170 - date: Wed, 05 Dec 2018 00:35:40 GMT - - { "response": [ - { - "id": 1, - "cname": "test.quest.", - "ttl": 48, - "description": "A test federation", - "lastUpdated": "2018-12-05 00:05:16+00", - "deliveryService": { - "id": 1, - "xmlId": "demo1" - } - } - ]} - -``POST`` -======== -Creates a new federation. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+----------------------------------------------------------------+ - | Name | Description | - +======+================================================================+ - | name | The name of the CDN for which a new federation will be created | - +------+----------------------------------------------------------------+ - -:cname: The Canonical Name (CNAME) used by the federation - - .. note:: The CNAME must end with a "``.``" - -:description: An optional description of the federation -:ttl: Time to Live (TTL) for the name record used for ``cname`` - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/cdns/CDN-in-a-Box/federations HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 72 - Content-Type: application/json - - { - "cname": "test.quest.", - "ttl": 48, - "description": "A test federation" - } - - -Response Structure ------------------- -:cname: The Canonical Name (CNAME) used by the federation -:description: An optionally-present field containing a description of the field - - .. note:: This key will only be present if the description was provided when the federation was created - -:lastUpdated: The date and time at which this federation was last modified, in :ref:`non-rfc-datetime` -:ttl: Time to Live (TTL) for the ``cname``, in hours - - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - access-control-allow-credentials: true - access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - access-control-allow-methods: POST,GET,OPTIONS,PUT,DELETE - access-control-allow-origin: * - content-type: application/json - set-cookie: mojolicious=...; Path=/; HttpOnly - whole-content-sha512: rRsWAIhXzVlj8Hy+8aFjp4Jo1QGTK49m0N1AP5QDyyAZ1TfNIdgtcgiuehu7FiN1IPWRFiv6D9CygFYKGcVDOw== - x-server-name: traffic_ops_golang/ - content-length: 192 - date: Wed, 05 Dec 2018 00:05:16 GMT - - { "alerts": [ - { - "text": "cdnfederation was created.", - "level": "success" - } - ], - "response": { - "id": 1, - "cname": "test.quest.", - "ttl": 48, - "description": "A test federation", - "lastUpdated": "2018-12-05 00:05:16+00" - }} diff --git a/docs/source/api/v2/cdns_name_federations_id.rst b/docs/source/api/v2/cdns_name_federations_id.rst deleted file mode 100644 index 86380073c2..0000000000 --- a/docs/source/api/v2/cdns_name_federations_id.rst +++ /dev/null @@ -1,158 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-name-federations-id: - -************************************ -``cdns/{{name}}/federations/{{ID}}`` -************************************ - -``PUT`` -======= -Updates a federation. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-------------------------------------------------------------------------------------+ - | Name | Description | - +======+=====================================================================================+ - | name | The name of the CDN for which the federation identified by ``ID`` will be inspected | - +------+-------------------------------------------------------------------------------------+ - | ID | An integral, unique identifier for the federation to be inspected | - +------+-------------------------------------------------------------------------------------+ - -:cname: The Canonical Name (CNAME) used by the federation - - .. note:: The CNAME must end with a "``.``" - -:description: An optional description of the federation -:ttl: Time to Live (TTL) for the name record used for ``cname`` - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/cdns/CDN-in-a-Box/federations/1 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 33 - Content-Type: application/json - - { - "cname": "foo.bar.", - "ttl": 48 - } - - -Response Structure ------------------- -:cname: The Canonical Name (CNAME) used by the federation -:description: An optionally-present field containing a description of the field - - .. note:: This key will only be present if the description was provided when the federation was created - -:lastUpdated: The date and time at which this federation was last modified, in :ref:`non-rfc-datetime` -:ttl: Time to Live (TTL) for the ``cname``, in hours - - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - access-control-allow-credentials: true - access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - access-control-allow-methods: POST,GET,OPTIONS,PUT,DELETE - access-control-allow-origin: * - content-type: application/json - set-cookie: mojolicious=...; Path=/; HttpOnly - whole-content-sha512: qcjfQ+gDjNxYQ1aq+dlddgrkFWnkFYxsFF+SHDqqH0uVHBVksmU0aTFgltozek/u6wbrGoR1LFf9Fr1C1SbigA== - x-server-name: traffic_ops_golang/ - content-length: 174 - date: Wed, 05 Dec 2018 01:03:40 GMT - - { "alerts": [ - { - "text": "cdnfederation was updated.", - "level": "success" - } - ], - "response": { - "id": 1, - "cname": "foo.bar.", - "ttl": 48, - "description": null, - "lastUpdated": "2018-12-05 01:03:40+00" - }} - - -``DELETE`` -========== -Deletes a specific federation. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-------------------------------------------------------------------------------------+ - | Name | Description | - +======+=====================================================================================+ - | name | The name of the CDN for which the federation identified by ``ID`` will be inspected | - +------+-------------------------------------------------------------------------------------+ - | ID | An integral, unique identifier for the federation to be inspected | - +------+-------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/cdns/CDN-in-a-Box/federations/1 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - access-control-allow-credentials: true - access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - access-control-allow-methods: POST,GET,OPTIONS,PUT,DELETE - access-control-allow-origin: * - content-type: application/json - set-cookie: mojolicious=...; Path=/; HttpOnly - whole-content-sha512: Cnkfj6dmzTD3if9oiDq33tqf7CnAflKK/SPgqJyfu6HUfOjLJOgKIZvkcs2wWY6EjLVdw5qsatsd4FPoCyjvcw== - x-server-name: traffic_ops_golang/ - content-length: 68 - date: Wed, 05 Dec 2018 01:17:24 GMT - - { "alerts": [ - { - "text": "cdnfederation was deleted.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/cdns_name_health.rst b/docs/source/api/v2/cdns_name_health.rst deleted file mode 100644 index 3c08b88c8d..0000000000 --- a/docs/source/api/v2/cdns_name_health.rst +++ /dev/null @@ -1,89 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-name-health: - -************************ -``cdns/{{name}}/health`` -************************ - -``GET`` -======= -Retrieves the health of all :term:`Cache Groups` for a given CDN. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-------------------------------------------------------+ - | Name | Description | - +======+=======================================================+ - | name | The name of the CDN for which health will be reported | - +------+-------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/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: 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 :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 - - 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: 108 - Content-Type: application/json - Date: Tue, 03 Dec 2019 21:33:59 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; expires=Wed, 04 Dec 2019 01:33:59 GMT; path=/; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: KpXViXeAgch58ueQqdyU8NuINBw1EUedE6Rv2ewcLUajJp6kowdbVynpwW7XiSvAyHdtClIOuT3OkhIimghzSA== - - { "response": { - "totalOffline": 0, - "totalOnline": 1, - "cachegroups": [ - { - "offline": 0, - "name": "CDN_in_a_Box_Edge", - "online": 1 - } - ] - }} diff --git a/docs/source/api/v2/cdns_name_name.rst b/docs/source/api/v2/cdns_name_name.rst deleted file mode 100644 index 2b4e0ff90c..0000000000 --- a/docs/source/api/v2/cdns_name_name.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-name-name: - -********************** -``cdns/name/{{name}}`` -********************** - -``DELETE`` -========== -Allows a user to delete a CDN by name - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------+ - | Name | Description | - +======+=============================================+ - | name | The name of the CDN to be deleted | - +------+---------------------------------------------+ - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: Zy4cJN6BEct4ltFLN4e296mM8XnzOs0EQ3/jp4TA3L+g8qtkI0WrL+ThcFq4xbJPU+KHVDSi+b0JBav3xsYPqQ== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 14 Nov 2018 20:59:22 GMT - Content-Length: 58 - - { "alerts": [ - { - "text": "cdn was deleted.", - "level": "success" - } - ]} - diff --git a/docs/source/api/v2/cdns_name_name_dnsseckeys.rst b/docs/source/api/v2/cdns_name_name_dnsseckeys.rst deleted file mode 100644 index 2d0c9b14b0..0000000000 --- a/docs/source/api/v2/cdns_name_name_dnsseckeys.rst +++ /dev/null @@ -1,140 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-name-name-dnsseckeys: - -********************************* -``cdns/name/{{name}}/dnsseckeys`` -********************************* - -``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 :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" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+----------------------------------------------------+ - | Name | Description | - +======+====================================================+ - | name | The name of the CDN for which keys will be fetched | - +------+----------------------------------------------------+ - -Response Structure ------------------- -:name: The name of the CDN or :term:`Delivery Service` to which the enclosed keys belong - - :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 - :name: The name of the domain for which this key will be used - :private: Encoded private key - :public: Encoded public key - :ttl: The time for which the key should be trusted by the client - - :ksk: The long-term :abbr:`KSK (Key-Signing Key)` - - :dsRecord: An optionally present object containing information about the algorithm used to generate the key - - :algorithm: The name of the algorithm used to generate the key - :digest: A hash of the DNSKEY record - :digestType: The type of hash algorithm used to create the value of ``digest`` - - :expirationDate: A Unix epoch timestamp (in seconds) representing the date and time whereupon the key will expire - :inceptionDate: A Unix epoch timestamp (in seconds) representing the date and time when the key was created - :name: The name of the domain for which this key will be used - :private: Encoded private key - :public: Encoded public key - :ttl: The time for which the key should be trusted by the client - -.. code-block:: json - :caption: Response Example - - { "response": { - "cdn1": { - "zsk": { - "ttl": "60", - "inceptionDate": "1426196750", - "private": "zsk private key", - "public": "zsk public key", - "expirationDate": "1428788750", - "name": "foo.kabletown.com." - }, - "ksk": { - "name": "foo.kabletown.com.", - "expirationDate": "1457732750", - "public": "ksk public key", - "private": "ksk private key", - "inceptionDate": "1426196750", - "ttl": "60", - "dsRecord": { - "algorithm": "5", - "digestType": "2", - "digest": "abc123def456" - } - } - }, - "ds-01": { - "zsk": { - "ttl": "60", - "inceptionDate": "1426196750", - "private": "zsk private key", - "public": "zsk public key", - "expirationDate": "1428788750", - "name": "ds-01.foo.kabletown.com." - }, - "ksk": { - "name": "ds-01.foo.kabletown.com.", - "expirationDate": "1457732750", - "public": "ksk public key", - "private": "ksk private key", - "inceptionDate": "1426196750" - } - } - }} - -``DELETE`` -========== -Delete DNSSEC keys for a CDN and all associated :term:`Delivery Services`. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: Object (string) - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-----------------------------------------------------------+ - | Name | Description | - +======+===========================================================+ - | name | The name of the CDN for which DNSSEC keys will be deleted | - +------+-----------------------------------------------------------+ - -Response Structure ------------------- -.. code-block:: json - :caption: Response Example - - { - "response": "Successfully deleted dnssec keys for test" - } - diff --git a/docs/source/api/v2/cdns_name_name_sslkeys.rst b/docs/source/api/v2/cdns_name_name_sslkeys.rst deleted file mode 100644 index 1539d1444d..0000000000 --- a/docs/source/api/v2/cdns_name_name_sslkeys.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-name-name-sslkeys: - -****************************** -``cdns/name/{{name}}/sslkeys`` -****************************** - -``GET`` -======= -Returns SSL certificates for all :term:`Delivery Services` that are a part of the CDN. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+----------------------------------------------------+ - | Name | Description | - +======+====================================================+ - | name | The name of the CDN for which keys will be fetched | - +------+----------------------------------------------------+ - -Response Structure ------------------- -:certificate: An object representing The SSL keys used for the :term:`Delivery Service` identified by ``deliveryservice`` - - :key: Base 64-encoded private key for SSL certificate - :crt: Base 64-encoded SSL 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 - - { "response": [ - { - "deliveryservice": "ds1", - "certificate": { - "crt": "base64encodedcrt1", - "key": "base64encodedkey1" - } - }, - { - "deliveryservice": "ds2", - "certificate": { - "crt": "base64encodedcrt2", - "key": "base64encodedkey2" - } - } - ]} diff --git a/docs/source/api/v2/cdns_name_snapshot.rst b/docs/source/api/v2/cdns_name_snapshot.rst deleted file mode 100644 index cbf4117d69..0000000000 --- a/docs/source/api/v2/cdns_name_snapshot.rst +++ /dev/null @@ -1,546 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-name-snapshot: - -************************** -``cdns/{{name}}/snapshot`` -************************** -.. caution:: This page is a stub! Much of it may be missing or just downright wrong - it needs a lot of love from people with the domain knowledge required to update it. - -``GET`` -======= -Retrieves the *current* :term:`Snapshot` for a CDN, which represents the current *operating state* of the CDN, **not** the current *configuration* of the CDN. The contents of this :term:`Snapshot` are currently used by Traffic Monitor and Traffic Router. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+--------------------------------------------------------------------+ - | Name | Description | - +======+====================================================================+ - | name | The name of the CDN for which a :term:`Snapshot` shall be returned | - +------+--------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/cdns/CDN-in-a-Box/snapshot HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:config: An object containing basic configurations on the actual CDN object - - :api.cache-control.max-age: A string containing an integer which specifies the value of ``max-age`` in the :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" - - "false" - The "round-robin" method will be used to define DNS routing - "true" - A consistent hashing method will be used to define DNS routing - - :coveragezone.polling.interval: A string containing an integer which specifies the interval, in seconds, on which Traffic Routers should check for a new Coverage Zone file - :coveragezone.polling.url: The URL where a :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 - :dnssec.init.timeout: An integer that defines the number of minutes to allow for zone generation, this bounds the zone priming activity - :dnssec.enabled: A string that tells whether or not the CDN uses DNSSEC; one of: - - "false" - DNSSEC is not used within this CDN - "true" - DNSSEC is used within this CDN - - :domain_name: 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 - :geolocation.polling.url: The URL where Traffic Control components can request IP-to-geographic-location mapping database files - :keystore.maintenance.interval: A string containing an integer which specifies the interval, in seconds, on which Traffic Routers should refresh their zone caches - :neustar.polling.interval: A string containing an integer which specifies the interval, in seconds, on which other Traffic Control components should check for new "Neustar" databases - :neustar.polling.url: The URL where Traffic Control components can request "Neustar" databases - :soa: An object defining the :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 :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``. - - .. seealso:: `The Wikipedia page on Start of Authority records `_. - - :steeringmapping.polling.interval: A string containing an integer which specifies the interval, in seconds, on which Traffic Control components should check for new steering mappings - :ttls: An object that contains keys which are types of DNS records that have values which are strings containing integers that specify the time for which a response to the specific type of record request should remain valid - :zonemanager.cache.maintenance.interval: A configuration option for the ZoneManager Java class of Traffic Router - :zonemanager.threadpool.scale: A configuration option for the ZoneManager Java class of Traffic Router - -:contentRouters: An object containing keys which are the (short) hostnames of the Traffic Routers that serve requests for :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: 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: 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 :term:`Edge-tier cache servers` in the CDN; the values corresponding to those keys are routing information for said servers - - :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 :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 :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 - :interfaceName: The name of the main network interface device used by this :term:`cache server` - :ip6: The server's IPv6 address - :ip: The server's IPv4 address - :locationId: This field is exactly the same as ``cacheGroup`` and only exists for legacy compatibility reasons - :port: The port on which this :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 to this :term:`cache server`; one of: - - 0 - Do not route traffic to this server - 1 - Route traffic to this server normally - - :status: This :term:`cache server`'s status - - .. seealso:: :ref:`health-proto` - - :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 :term:`Edge-tier cache server` - MID - This is a :term:`Mid-tier cache server` - -: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 :ref:`ds-anonymous-blocking` is set on this :term:`Delivery Service`; one of: - - "true" - Anonymized IP addresses are blocked by this :term:`Delivery Service` - "false" - Anonymized IP addresses are not blocked by this :term:`Delivery Service` - - .. seealso:: :ref:`anonymous_blocking-qht` - - :consistentHashQueryParameters: A set of query parameters that Traffic Router should consider when determining a consistent hash for a given client request. - - :consistentHashRegex: An optional regular expression that will ensure clients are consistently routed to a :term:`cache server` based on matches to it. - - :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` - - .. seealso:: :ref:`ds-geo-limit` - - :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 :term:`cache servers` in which the response to a single request URL will be stored - - .. 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 :term:`cache servers` chosen for content dispersion are chosen randomly or based on a consistent hash of the request URL; one of: - - "false" - :term:`cache servers` will be chosen consistently - "true" - :term:`cache servers` will be chosen at random - - :domains: An array of domains served by this :term:`Delivery Service` - :ecsEnabled: A string containing a boolean from :ref:`ds-ecs` that tells whether EDNS0 client subnet is enabled on this :term:`Delivery Service`; one of: - - "false" - EDNS0 client subnet is not enabled on this :term:`Delivery Service` - "true" - EDNS0 client subnet is enabled on 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 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` - "true" - IPv6 traffic will be routed by this :term:`Delivery Service` - - :matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this :term:`Delivery Service` - - :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped) - :setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs - :type: The 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 :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 :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 :term:`Coverage Zone File` (and/or possibly the :term:`Deep Coverage Zone File`) and the IP-to-geographic-location database - - :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 - - :acceptHttps: A string containing a boolean that tells whether HTTPS requests should be normally serviced by this :term:`Delivery Service`; one of: - - "false" - Refuse to service HTTPS requests - "true" - Service HTTPS requests normally - - :redirectToHttps: A string containing a boolean that tells whether HTTP requests ought to be re-directed to use HTTPS; one of: - - "false" - Do not redirect unencrypted traffic; service it normally - "true" - Respond to HTTP requests with instructions to use HTTPS instead - - .. 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` - "true" - Regional Geographic Blocking is used by this :term:`Delivery Service` - - .. seealso:: :ref:`regionalgeo-qht` - - :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 :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``. - - .. seealso:: `The Wikipedia page on Start of Authority records `_. - - :sslEnabled: A string containing a boolean that tells whether this :term:`Delivery Service` uses SSL; one of: - - "false" - SSL is not used by this :term:`Delivery Service` - "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 :term:`Cache Groups` within the CDN - - :backupLocations: An object that describes this :ref:`Cache Group's Fallbacks ` - - :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 :term:`Cache Group` - "true" - Fall back on the closest available :term:`Cache Group` - - :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: 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 :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: 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: 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-". - - :status: The health status of this Traffic Monitor - - .. seealso:: :ref:`health-proto` - -:stats: An object containing metadata information regarding the CDN - - :CDN_name: The name of this CDN - :date: The UNIX epoch timestamp date in the Traffic Ops server's own timezone - :tm_host: The :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 - .. deprecated:: ATCv6 - - This information should never be used; instead all tools and (especially) components **must** use the documented API. This field was removed in APIv4 - - :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 :ref:`names of Cache Groups ` within the CDN which contain Traffic Routers - - :backupLocations: An object that describes this :ref:`Cache Group's Fallbacks ` - - :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 :term:`Cache Group` - "true" - Fall back on the closest available :term:`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 - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 220bc4XXwaj+s7ODd3QAF5leGj06lnApiN5E8H/B2RgxSphnQIfnwy6WWbBDjonWXPV1IWDCjBMO+rR+lAabMg== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 12 Dec 2018 17:36:25 GMT - Transfer-Encoding: chunked - - { "response": { - "config": { - "api.cache-control.max-age": "10", - "certificates.polling.interval": "300000", - "consistent.dns.routing": "true", - "coveragezone.polling.interval": "3600000", - "coveragezone.polling.url": "https://trafficops.infra.ciab.test:443/coverage-zone.json", - "dnssec.dynamic.response.expiration": "300s", - "dnssec.enabled": "false", - "domain_name": "mycdn.ciab.test", - "federationmapping.polling.interval": "60000", - "federationmapping.polling.url": "https://${toHostname}/api/2.0/federations", - "geolocation.polling.interval": "86400000", - "geolocation.polling.url": "https://trafficops.infra.ciab.test:443/GeoLite2-City.mmdb.gz", - "keystore.maintenance.interval": "300", - "neustar.polling.interval": "86400000", - "neustar.polling.url": "https://trafficops.infra.ciab.test:443/neustar.tar.gz", - "soa": { - "admin": "twelve_monkeys", - "expire": "604800", - "minimum": "30", - "refresh": "28800", - "retry": "7200" - }, - "steeringmapping.polling.interval": "60000", - "ttls": { - "A": "3600", - "AAAA": "3600", - "DNSKEY": "30", - "DS": "30", - "NS": "3600", - "SOA": "86400" - }, - "zonemanager.cache.maintenance.interval": "300", - "zonemanager.threadpool.scale": "0.50" - }, - "contentServers": { - "edge": { - "cacheGroup": "CDN_in_a_Box_Edge", - "fqdn": "edge.infra.ciab.test", - "hashCount": 999, - "hashId": "edge", - "httpsPort": 443, - "interfaceName": "eth0", - "ip": "172.16.239.100", - "ip6": "fc01:9400:1000:8::100", - "locationId": "CDN_in_a_Box_Edge", - "port": 80, - "profile": "ATS_EDGE_TIER_CACHE", - "status": "REPORTED", - "type": "EDGE", - "deliveryServices": { - "demo1": [ - "edge.demo1.mycdn.ciab.test" - ] - }, - "routingDisabled": 0 - }, - "mid": { - "cacheGroup": "CDN_in_a_Box_Mid", - "fqdn": "mid.infra.ciab.test", - "hashCount": 999, - "hashId": "mid", - "httpsPort": 443, - "interfaceName": "eth0", - "ip": "172.16.239.120", - "ip6": "fc01:9400:1000:8::120", - "locationId": "CDN_in_a_Box_Mid", - "port": 80, - "profile": "ATS_MID_TIER_CACHE", - "status": "REPORTED", - "type": "MID", - "routingDisabled": 0 - } - }, - "contentRouters": { - "trafficrouter": { - "api.port": "3333", - "secure.api.port": "3443", - "fqdn": "trafficrouter.infra.ciab.test", - "httpsPort": 443, - "ip": "172.16.239.60", - "ip6": "fc01:9400:1000:8::60", - "location": "CDN_in_a_Box_Edge", - "port": 80, - "profile": "CCR_CIAB", - "status": "ONLINE" - } - }, - "deliveryServices": { - "demo1": { - "anonymousBlockingEnabled": "false", - "coverageZoneOnly": "false", - "dispersion": { - "limit": 1, - "shuffled": "true" - }, - "domains": [ - "demo1.mycdn.ciab.test" - ], - "geolocationProvider": "maxmindGeolocationService", - "matchsets": [ - { - "protocol": "HTTP", - "matchlist": [ - { - "regex": ".*\\.demo1\\..*", - "match-type": "HOST" - } - ] - } - ], - "missLocation": { - "lat": 42, - "long": -88 - }, - "protocol": { - "acceptHttps": "false", - "redirectToHttps": "false" - }, - "regionalGeoBlocking": "false", - "soa": { - "admin": "traffic_ops", - "expire": "604800", - "minimum": "30", - "refresh": "28800", - "retry": "7200" - }, - "sslEnabled": "false", - "ttls": { - "A": "", - "AAAA": "", - "NS": "3600", - "SOA": "86400" - }, - "ip6RoutingEnabled": "true", - "ecsEnabled": "false", - "routingName": "video", - "deepCachingType": "NEVER" - } - }, - "edgeLocations": { - "CDN_in_a_Box_Edge": { - "latitude": 38.897663, - "longitude": -77.036574, - "backupLocations": { - "fallbackToClosest": "true" - }, - "localizationMethods": [ - "GEO", - "CZ", - "DEEP_CZ" - ] - } - }, - "trafficRouterLocations": { - "CDN_in_a_Box_Edge": { - "latitude": 38.897663, - "longitude": -77.036574, - "backupLocations": { - "fallbackToClosest": "false" - }, - "localizationMethods": [ - "GEO", - "CZ", - "DEEP_CZ" - ] - } - }, - "monitors": { - "trafficmonitor": { - "fqdn": "trafficmonitor.infra.ciab.test", - "httpsPort": 443, - "ip": "172.16.239.40", - "ip6": "fc01:9400:1000:8::40", - "location": "CDN_in_a_Box_Edge", - "port": 80, - "profile": "RASCAL-Traffic_Monitor", - "status": "ONLINE" - } - }, - "stats": { - "CDN_name": "CDN-in-a-Box", - "date": 1544635937, - "tm_host": "trafficops.infra.ciab.test", - "tm_path": "/api/2.0/snapshot/CDN-in-a-Box", - "tm_user": "admin", - "tm_version": "traffic_ops-3.0.0-9813.8ad7bd8e.el7" - } - }} - -.. [#httpOnly] These only apply to HTTP-:ref:`routed ` :term:`Delivery Services` diff --git a/docs/source/api/v2/cdns_name_snapshot_new.rst b/docs/source/api/v2/cdns_name_snapshot_new.rst deleted file mode 100644 index 05c7cb3cd2..0000000000 --- a/docs/source/api/v2/cdns_name_snapshot_new.rst +++ /dev/null @@ -1,550 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-name-snapshot-new: - -****************************** -``cdns/{{name}}/snapshot/new`` -****************************** - -``GET`` -======= -Retrieves the *pending* :term:`Snapshot` for a CDN, which represents the current *configuration* of the CDN, **not** the current *operating state* of the CDN. The contents of this :term:`Snapshot` are currently used by Traffic Monitor and Traffic Router. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+--------------------------------------------------------------------+ - | Name | Description | - +======+====================================================================+ - | name | The name of the CDN for which a :term:`Snapshot` shall be returned | - +------+--------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/cdns/CDN-in-a-Box/snapshot/new HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:config: An object containing basic configurations on the actual CDN object - - :api.cache-control.max-age: A string containing an integer which specifies the value of ``max-age`` in the :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" - - "false" - The "round-robin" method will be used to define DNS routing - "true" - A consistent hashing method will be used to define DNS routing - - :coveragezone.polling.interval: A string containing an integer which specifies the interval, in seconds, on which Traffic Routers should check for a new Coverage Zone file - :coveragezone.polling.url: The URL where a :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 - :dnssec.init.timeout: An integer that defines the number of minutes to allow for zone generation, this bounds the zone priming activity - :dnssec.enabled: A string that tells whether or not the CDN uses DNSSEC; one of: - - "false" - DNSSEC is not used within this CDN - "true" - DNSSEC is used within this CDN - - :domain_name: 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 - :geolocation.polling.url: The URL where Traffic Control components can request IP-to-geographic-location mapping database files - :keystore.maintenance.interval: A string containing an integer which specifies the interval, in seconds, on which Traffic Routers should refresh their zone caches - :neustar.polling.interval: A string containing an integer which specifies the interval, in seconds, on which other Traffic Control components should check for new "Neustar" databases - :neustar.polling.url: The URL where Traffic Control components can request "Neustar" databases - :soa: An object defining the :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 :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``. - - .. seealso:: `The Wikipedia page on Start of Authority records `_. - - :steeringmapping.polling.interval: A string containing an integer which specifies the interval, in seconds, on which Traffic Control components should check for new steering mappings - :ttls: An object that contains keys which are types of DNS records that have values which are strings containing integers that specify the time for which a response to the specific type of record request should remain valid - :zonemanager.cache.maintenance.interval: A configuration option for the ZoneManager Java class of Traffic Router - :zonemanager.threadpool.scale: A configuration option for the ZoneManager Java class of Traffic Router - -:contentRouters: An object containing keys which are the (short) hostnames of the Traffic Routers that serve requests for :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: 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: 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 :term:`Edge-tier cache servers` in the CDN; the values corresponding to those keys are routing information for said servers - - :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 :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 :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 - :interfaceName: The name of the main network interface device used by this :term:`cache server` - :ip6: The server's IPv6 address - :ip: The server's IPv4 address - :locationId: This field is exactly the same as ``cacheGroup`` and only exists for legacy compatibility reasons - :port: The port on which this :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 to this :term:`cache server`; one of: - - 0 - Do not route traffic to this server - 1 - Route traffic to this server normally - - :status: This :term:`cache server`'s status - - .. seealso:: :ref:`health-proto` - - :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 :term:`Edge-tier cache server` - MID - This is a :term:`Mid-tier cache server` - -: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 :ref:`ds-anonymous-blocking` is set on this :term:`Delivery Service`; one of: - - "true" - Anonymized IP addresses are blocked by this :term:`Delivery Service` - "false" - Anonymized IP addresses are not blocked by this :term:`Delivery Service` - - .. seealso:: :ref:`anonymous_blocking-qht` - - :consistentHashQueryParameters: A set of query parameters that Traffic Router should consider when determining a consistent hash for a given client request. - - :consistentHashRegex: An optional regular expression that will ensure clients are consistently routed to a :term:`cache server` based on matches to it. - - :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` - - .. seealso:: :ref:`ds-geo-limit` - - :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 :term:`cache servers` in which the response to a single request URL will be stored - - .. 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 :term:`cache servers` chosen for content dispersion are chosen randomly or based on a consistent hash of the request URL; one of: - - "false" - :term:`cache servers` will be chosen consistently - "true" - :term:`cache servers` will be chosen at random - - :domains: An array of domains served by this :term:`Delivery Service` - :ecsEnabled: A string containing a boolean from :ref:`ds-ecs` that tells whether EDNS0 client subnet is enabled on this :term:`Delivery Service`; one of: - - "false" - EDNS0 client subnet is not enabled on this :term:`Delivery Service` - "true" - EDNS0 client subnet is enabled on 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 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` - "true" - IPv6 traffic will be routed by this :term:`Delivery Service` - - :matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this :term:`Delivery Service` - - :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped) - :setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs - :type: The 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 :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 :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 :term:`Coverage Zone File` (and/or possibly the :term:`Deep Coverage Zone File`) and the IP-to-geographic-location database - - :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 - - :acceptHttps: A string containing a boolean that tells whether HTTPS requests should be normally serviced by this :term:`Delivery Service`; one of: - - "false" - Refuse to service HTTPS requests - "true" - Service HTTPS requests normally - - :redirectToHttps: A string containing a boolean that tells whether HTTP requests ought to be re-directed to use HTTPS; one of: - - "false" - Do not redirect unencrypted traffic; service it normally - "true" - Respond to HTTP requests with instructions to use HTTPS instead - - .. 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` - "true" - Regional Geographic Blocking is used by this :term:`Delivery Service` - - .. seealso:: :ref:`regionalgeo-qht` - - :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 :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``. - - .. seealso:: `The Wikipedia page on Start of Authority records `_. - - :sslEnabled: A string containing a boolean that tells whether this :term:`Delivery Service` uses SSL; one of: - - "false" - SSL is not used by this :term:`Delivery Service` - "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 :term:`Cache Groups` within the CDN - - :backupLocations: An object that describes this :ref:`Cache Group's Fallbacks ` - - :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 :term:`Cache Group` - "true" - Fall back on the closest available :term:`Cache Group` - - :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: 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 :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: 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: 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-". - - :status: The health status of this Traffic Monitor - - .. seealso:: :ref:`health-proto` - -:stats: An object containing metadata information regarding the CDN - - :CDN_name: The name of this CDN - :date: The UNIX epoch timestamp date in the Traffic Ops server's own timezone - :tm_host: The :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 - - .. deprecated:: ATCv6 - - This information should never be used; instead all tools and (especially) components **must** use the documented API. This field was removed in APIv4 - - :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 :ref:`names of Cache Groups ` within the CDN which contain Traffic Routers - - :backupLocations: An object that describes this :ref:`Cache Group's Fallbacks ` - - :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 :term:`Cache Group` - "true" - Fall back on the closest available :term:`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 - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: MWzgAYngmU1IEIxRa0C6VfY+MMuu7T9OCiIj1Aul58pA7J7DiS6r8wjVRVVW8W2Eu2V9BC7OEacR1fQyuIsRWg== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 12 Dec 2018 21:41:48 GMT - Transfer-Encoding: chunked - - { "response": { - "config": { - "api.cache-control.max-age": "10", - "certificates.polling.interval": "300000", - "consistent.dns.routing": "true", - "coveragezone.polling.interval": "3600000", - "coveragezone.polling.url": "https://trafficops.infra.ciab.test:443/coverage-zone.json", - "dnssec.dynamic.response.expiration": "300s", - "dnssec.enabled": "false", - "domain_name": "mycdn.ciab.test", - "federationmapping.polling.interval": "60000", - "federationmapping.polling.url": "https://${toHostname}/api/2.0/federations", - "geolocation.polling.interval": "86400000", - "geolocation.polling.url": "https://trafficops.infra.ciab.test:443/GeoLite2-City.mmdb.gz", - "keystore.maintenance.interval": "300", - "neustar.polling.interval": "86400000", - "neustar.polling.url": "https://trafficops.infra.ciab.test:443/neustar.tar.gz", - "soa": { - "admin": "twelve_monkeys", - "expire": "604800", - "minimum": "30", - "refresh": "28800", - "retry": "7200" - }, - "steeringmapping.polling.interval": "60000", - "ttls": { - "A": "3600", - "AAAA": "3600", - "DNSKEY": "30", - "DS": "30", - "NS": "3600", - "SOA": "86400" - }, - "zonemanager.cache.maintenance.interval": "300", - "zonemanager.threadpool.scale": "0.50" - }, - "contentServers": { - "edge": { - "cacheGroup": "CDN_in_a_Box_Edge", - "fqdn": "edge.infra.ciab.test", - "hashCount": 999, - "hashId": "edge", - "httpsPort": 443, - "interfaceName": "eth0", - "ip": "172.16.239.100", - "ip6": "fc01:9400:1000:8::100", - "locationId": "CDN_in_a_Box_Edge", - "port": 80, - "profile": "ATS_EDGE_TIER_CACHE", - "status": "REPORTED", - "type": "EDGE", - "deliveryServices": { - "demo1": [ - "edge.demo1.mycdn.ciab.test" - ] - }, - "routingDisabled": 0 - }, - "mid": { - "cacheGroup": "CDN_in_a_Box_Mid", - "fqdn": "mid.infra.ciab.test", - "hashCount": 999, - "hashId": "mid", - "httpsPort": 443, - "interfaceName": "eth0", - "ip": "172.16.239.120", - "ip6": "fc01:9400:1000:8::120", - "locationId": "CDN_in_a_Box_Mid", - "port": 80, - "profile": "ATS_MID_TIER_CACHE", - "status": "REPORTED", - "type": "MID", - "routingDisabled": 0 - } - }, - "contentRouters": { - "trafficrouter": { - "api.port": "3333", - "secure.api.port": "3443", - "fqdn": "trafficrouter.infra.ciab.test", - "httpsPort": 443, - "ip": "172.16.239.60", - "ip6": "fc01:9400:1000:8::60", - "location": "CDN_in_a_Box_Edge", - "port": 80, - "profile": "CCR_CIAB", - "status": "ONLINE" - } - }, - "deliveryServices": { - "demo1": { - "anonymousBlockingEnabled": "false", - "coverageZoneOnly": "false", - "dispersion": { - "limit": 1, - "shuffled": "true" - }, - "domains": [ - "demo1.mycdn.ciab.test" - ], - "geolocationProvider": "maxmindGeolocationService", - "matchsets": [ - { - "protocol": "HTTP", - "matchlist": [ - { - "regex": ".*\\.demo1\\..*", - "match-type": "HOST" - } - ] - } - ], - "missLocation": { - "lat": 42, - "long": -88 - }, - "protocol": { - "acceptHttps": "false", - "redirectToHttps": "false" - }, - "regionalGeoBlocking": "false", - "soa": { - "admin": "traffic_ops", - "expire": "604800", - "minimum": "30", - "refresh": "28800", - "retry": "7200" - }, - "sslEnabled": "false", - "ttls": { - "A": "", - "AAAA": "", - "NS": "3600", - "SOA": "86400" - }, - "ip6RoutingEnabled": "true", - "ecsEnabled": "false", - "routingName": "video", - "deepCachingType": "NEVER" - } - }, - "edgeLocations": { - "CDN_in_a_Box_Edge": { - "latitude": 38.897663, - "longitude": -77.036574, - "backupLocations": { - "fallbackToClosest": "true", - "list": [ - "test" - ] - }, - "localizationMethods": [ - "GEO", - "CZ", - "DEEP_CZ" - ] - } - }, - "trafficRouterLocations": { - "CDN_in_a_Box_Edge": { - "latitude": 38.897663, - "longitude": -77.036574, - "backupLocations": { - "fallbackToClosest": "false" - }, - "localizationMethods": [ - "GEO", - "CZ", - "DEEP_CZ" - ] - } - }, - "monitors": { - "trafficmonitor": { - "fqdn": "trafficmonitor.infra.ciab.test", - "httpsPort": 443, - "ip": "172.16.239.40", - "ip6": "fc01:9400:1000:8::40", - "location": "CDN_in_a_Box_Edge", - "port": 80, - "profile": "RASCAL-Traffic_Monitor", - "status": "ONLINE" - } - }, - "stats": { - "CDN_name": "CDN-in-a-Box", - "date": 1544650908, - "tm_host": "cache1.example.com:6443", - "tm_path": "api/2.0/snapshot/CDN-in-a-Box", - "tm_user": "admin", - "tm_version": "traffic_ops-3.0.0-9813.8ad7bd8e.el7" - } - }} - -.. [#httpOnly] These only apply to HTTP-:ref:`routed ` :term:`Delivery Services` diff --git a/docs/source/api/v2/cdns_routing.rst b/docs/source/api/v2/cdns_routing.rst deleted file mode 100644 index 12bee30133..0000000000 --- a/docs/source/api/v2/cdns_routing.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-cdns-routing: - -**************** -``cdns/routing`` -**************** - -``GET`` -======= -Retrieves the aggregated routing percentages across all CDNs. This is accomplished by polling stats from all online Traffic Routers via the ``/crs/stats`` route. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -No parameters available - -Response Structure ------------------- -:cz: The percent of requests to online Traffic Routers that were satisfied by a :term:`Coverage Zone File` -:deepCz: The percent of requests to online Traffic Routers that were satisfied by a :term:`Deep Coverage Zone File` -:dsr: The percent of requests to online Traffic Routers that were satisfied by sending the client to an overflow :term:`Delivery Service` -:err: The percent of requests to online Traffic Routers that resulted in an error -:fed: The percent of requests to online Traffic Routers that were satisfied by sending the client to a federated CDN -:geo: The percent of requests to online Traffic Routers that were satisfied using 3rd party geographic IP mapping -:miss: The percent of requests to online Traffic Routers that could not be satisfied -:regionalAlternate: The percent of requests to online Traffic Routers that were satisfied by sending the client to the alternate, Regional Geo-blocking URL -:regionalDenied: The percent of requests to online Traffic Routers that were denied due to geographic location policy -:staticRoute: The percent of requests to online Traffic Routers that were satisfied with :ref:`ds-static-dns-entries` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Wed, 14 Nov 2018 21:29:32 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: 7LjytwKyRzSKM4cRIol4OMIJxApFpTWJaSK73rbtUIQdASZjI64XxLVzZP0OGRU7XeJ22YKUyQ30qbKHDRv7FQ== - Content-Length: 130 - - { "response": { - "cz": 79, - "deepCz": 0.50, - "dsr": 0, - "err": 0, - "fed": 0.25, - "geo": 20, - "miss": 0.25, - "regionalAlternate": 0, - "regionalDenied": 0, - "staticRoute": 0 - }} diff --git a/docs/source/api/v2/consistenthash.rst b/docs/source/api/v2/consistenthash.rst deleted file mode 100644 index b50371b911..0000000000 --- a/docs/source/api/v2/consistenthash.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-consistenthash: - -****************** -``consistenthash`` -****************** -Test Pattern-Based Consistent Hashing for a :term:`Delivery Service` using a regular expression and a request path - -``POST`` -======== -Queries database for an active Traffic Router on a given CDN and sends GET request to get the resulting path to consistent hash with a given regex and request path. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -: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 - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/consistenthash HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.54.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 80 - Content-Type: application/x-www-form-urlencoded - - {"regex":"/.*?(/.*?/).*?(m3u8)","requestPath":"/test/path/asset.m3u8","cdnId":2} - -Response Structure ------------------- -:resultingPathToConsistentHash: The resulting path that Traffic Router will use for consistent hashing -:consistentHashRegex: The regex used by Traffic Router derived from POST 'regex' parameter -:requestPath: The request path used by Traffic Router to test regex against - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: QMDFOnUfqH4TcZ4YnUQyqnXDier0YiUMIfwBGDcT7ySjw9uASBGsLQW35lpnKFi4as0vYlHuSSGpe4hHGsladQ== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 12 Feb 2019 21:32:05 GMT - Content-Length: 142 - - { "response": { - "resultingPathToConsistentHash":"/path/m3u8", - "consistentHashRegex":"/.*?(/.*?/).*?(m3u8)", - "requestPath":"/test/path/asset.m3u8" - }} diff --git a/docs/source/api/v2/coordinates.rst b/docs/source/api/v2/coordinates.rst deleted file mode 100644 index a2668c4e99..0000000000 --- a/docs/source/api/v2/coordinates.rst +++ /dev/null @@ -1,307 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-coordinates: - -*************** -``coordinates`` -*************** - -``GET`` -======= -Gets a list of all coordinates in the Traffic Ops database - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+===============================================================================================================+ - | id | no | Return only coordinates that have this integral, unique identifier | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | name | no | Return only coordinates with this name | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | 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``. | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - -Response Structure ------------------- -:id: Integral, unique, identifier for this coordinate pair -:lastUpdated: The time and date at which this entry was last updated, in a ``ctime``-like format -:latitude: Latitude of the coordinate -:longitude: Longitude of the coordinate -:name: The name of the coordinate - typically this just reflects the name of the Cache Group for which the coordinate was created - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: Y2vxC3hpxIg6aRNBBT7i2hbAViIJp+dJoqHIzu3acFM+vGay/I5E+eZYOC9RY8hcJPrKNXysZOD8DOb9KsFgaw== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 14 Nov 2018 21:32:28 GMT - Content-Length: 942 - - { "response": [ - { - "id": 1, - "name": "from_cachegroup_TRAFFIC_ANALYTICS", - "latitude": 38.897663, - "longitude": -77.036574, - "lastUpdated": "2018-10-24 16:07:04+00" - }, - { - "id": 2, - "name": "from_cachegroup_TRAFFIC_OPS", - "latitude": 38.897663, - "longitude": -77.036574, - "lastUpdated": "2018-10-24 16:07:04+00" - }, - { - "id": 3, - "name": "from_cachegroup_TRAFFIC_OPS_DB", - "latitude": 38.897663, - "longitude": -77.036574, - "lastUpdated": "2018-10-24 16:07:04+00" - }, - { - "id": 4, - "name": "from_cachegroup_TRAFFIC_PORTAL", - "latitude": 38.897663, - "longitude": -77.036574, - "lastUpdated": "2018-10-24 16:07:04+00" - }, - { - "id": 5, - "name": "from_cachegroup_TRAFFIC_STATS", - "latitude": 38.897663, - "longitude": -77.036574, - "lastUpdated": "2018-10-24 16:07:04+00" - }, - { - "id": 6, - "name": "from_cachegroup_CDN_in_a_Box_Mid", - "latitude": 38.897663, - "longitude": -77.036574, - "lastUpdated": "2018-10-24 16:07:04+00" - }, - { - "id": 7, - "name": "from_cachegroup_CDN_in_a_Box_Edge", - "latitude": 38.897663, - "longitude": -77.036574, - "lastUpdated": "2018-10-24 16:07:05+00" - } - ]} - -``POST`` -======== -Creates a new coordinate pair - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -:name: The name of the new coordinate -:latitude: The desired latitude of the new coordinate (must be on the interval [-180, 180]) -:longitude: The desired longitude of the new coordinate (must be on the interval [-90, 90]) - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/coordinates HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 47 - Content-Type: application/json - - {"name": "test", "latitude": 0, "longitude": 0} - -Response Structure ------------------- -:id: Integral, unique, identifier for the newly created coordinate pair -:lastUpdated: The time and date at which this entry was last updated, in a ``ctime``-like format -:latitude: Latitude of the newly created coordinate -:longitude: Longitude of the newly created coordinate -:name: The name of the coordinate - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 7pWdeZyIIXE1P7o/JVon+5eSCbDw+FGamAzdXzWHXJ8IhF+Vh+/tWFCkzHYw3rP2kBVwZu+gqLffjQpBCMjt7A== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 15 Nov 2018 17:48:55 GMT - Content-Length: 165 - - { "alerts": [ - { - "text": "coordinate was created.", - "level": "success" - } - ], - "response": { - "id": 9, - "name": "test", - "latitude": 0, - "longitude": 0, - "lastUpdated": "2018-11-15 17:48:55+00" - }} - - -``PUT`` -======= -Updates a coordinate - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------+----------+------------------------------------------------------------+ - | Name | Required | Description | - +======+==========+============================================================+ - | id | yes | The integral, unique identifier of the coordinate to edit | - +------+----------+------------------------------------------------------------+ - -:name: The name of the new coordinate -:latitude: The desired new latitude of the coordinate (must be on the interval [-180, 180]) -:longitude: The desired new longitude of the coordinate (must be on the interval [-90, 90]) - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/coordinates?id=9 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 48 - Content-Type: application/json - - {"name": "quest", "latitude": 0, "longitude": 0} - -Response Structure ------------------- -:id: Integral, unique, identifier for the coordinate pair -:lastUpdated: The time and date at which this entry was last updated, in a ``ctime``-like format -:latitude: Latitude of the coordinate -:longitude: Longitude of the coordinate -:name: The name of the coordinate - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: zd03Uvbnv8EbSZZ75Xp5tnnYStZsZTdyPxXnoqK4QZ5WhELLPL8iHlRfOaiLTbrUWUeJ8ue2HRz6aBS/iXCCGA== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 15 Nov 2018 17:54:30 GMT - Content-Length: 166 - - { "alerts": [ - { - "text": "coordinate was updated.", - "level": "success" - } - ], - "response": { - "id": 9, - "name": "quest", - "latitude": 0, - "longitude": 0, - "lastUpdated": "2018-11-15 17:54:30+00" - }} - -``DELETE`` -========== -Deletes a coordinate - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------+----------+-------------------------------------------------------------+ - | Name | Required | Description | - +======+==========+=============================================================+ - | id | yes | The integral, unique identifier of the coordinate to delete | - +------+----------+-------------------------------------------------------------+ - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 82x/Wdckqgk4LN5LIlZfBJ26xkDrUVUGDjs5QFa/Lzap7dU3OZkjv8XW41xeFYj8PDmxHIpb7hiVObvLaxnEDA== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 15 Nov 2018 17:57:42 GMT - Content-Length: 65 - - { "alerts": [ - { - "text": "coordinate was deleted.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/current_stats.rst b/docs/source/api/v2/current_stats.rst deleted file mode 100644 index 4b33da7a06..0000000000 --- a/docs/source/api/v2/current_stats.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - - -.. _to-api-v2-current-stats: - -***************** -``current_stats`` -***************** -An API endpoint that returns current statistics for each CDN and an aggregate across them all. - -``GET`` -======= -Retrieves current stats for each CDN. Also includes aggregate stats across them. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -No parameters available. - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/current_stats HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:cdn: The name of the CDN -:connections: Current number of TCP connections maintained -: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 - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=; Path=/; HttpOnly - Whole-Content-Sha512: Rs3wgd7v5dP0bOQs4I3J1q6mnWIMSM2AKSAWirK1kymvDYOoFISArF7Kkypgy10I34yn7FtFdMh6U7ABaS1Tjw== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 14 Nov 2019 15:35:31 GMT - Content-Length: 138 - - {"response": { - "currentStats": [ - { - "bandwidth": null, - "capacity": null, - "cdn": "ALL", - "connections": null - }, - { - "bandwidth": 0.000104, - "capacity": 17, - "cdn": "CDN-in-a-Box", - "connections": 4 - }, - { - "bandwidth": 0.000104, - "cdn": "total", - "connections": 4 - } - ] - }} diff --git a/docs/source/api/v2/dbdump.rst b/docs/source/api/v2/dbdump.rst deleted file mode 100644 index efef537b14..0000000000 --- a/docs/source/api/v2/dbdump.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-dbdump: - -********** -``dbdump`` -********** -.. caution:: This is an extremely dangerous thing to do, as it exposes the entirety of the database, including possibly sensitive information. Administrators and systems engineers are advised to instead use database-specific tools to make server transitions more securely. - -Dumps the Traffic Ops database as an SQL script that should recreate its schema and contents exactly. - -.. impl-detail:: The script is output using the :manpage:`pg_dump(1)` utility, and is thus compatible for use with the :manpage:`pg_restore(1)` utility. - -``GET`` -======= -Fetches the database dump. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: ``undefined`` - outputs an SQL script, not JSON - -Request Structure ------------------ -No parameters available - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/dbdump HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/sql - Content-Disposition: attachment - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: YwvPB0ZToyzT8ilBnDlWWdwV+E3f2Xgus1OKrkNaipQqgrw5zGwq0rC1U9TZ8Zl6kAGcRZgCYnr1EWfHXpJRkg== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 09 Sep 2019 21:08:28 GMT - Transfer-Encoding: chunked - - -- Actual text omitted - it's huge diff --git a/docs/source/api/v2/deliveryservice_request_comments.rst b/docs/source/api/v2/deliveryservice_request_comments.rst deleted file mode 100644 index 8d3697bcee..0000000000 --- a/docs/source/api/v2/deliveryservice_request_comments.rst +++ /dev/null @@ -1,321 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservice_request_comments: - -************************************ -``deliveryservice_request_comments`` -************************************ - -``GET`` -======= -Gets delivery service request comments. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ - -.. table:: Request Query Parameters - - +--------------------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +==========================+==========+=====================================================================================================================================================+ - | author | no | Filter for :ref:`Delivery Service Request ` comments submitted by the user identified by this username | - +--------------------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ - | authorId | no | Filter for :ref:`Delivery Service Request ` comments submitted by the user identified by this integral, unique identifier | - +--------------------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ - | deliveryServiceRequestId | no | Filter for :ref:`Delivery Service Request ` comments submitted for the delivery service identified by this integral, unique identifier | - +--------------------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ - | id | no | Filter for the :ref:`Delivery Service Request ` comment identified by this integral, unique identifier | - +--------------------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/deliveryservice_request_comments HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - -Response Structure ------------------- -:author: The username of the user who created the comment. -:authorId: The integral, unique identifier of the user who created the comment. -:deliveryServiceRequestId: The integral, unique identifier of the :term:`Delivery Service Request` that the comment was posted on. -:id: The integral, unique identifier of the :term:`DSR` comment. -:lastUpdated: The date and time at which the user was last modified, in :ref:`non-rfc-datetime` -:value: The text of the comment that was posted. -:xmlId: This is the ``xmlId`` value that you provided in the request. - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 21:00:26 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: RaJZS1XFJ4oIxVKyyDjTuoQY7gPOmm5EuIL4AgHpyQpuaaNviw0XhGC4V/AKf/Ws6zXLgIUc4OyvMsTxnrilww== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 24 Feb 2020 20:00:26 GMT - Content-Length: 207 - - { - "response": [ - { - "authorId": 2, - "author": "admin", - "deliveryServiceRequestId": 2, - "id": 3, - "lastUpdated": "2020-02-24 19:59:46+00", - "value": "Changing to a different origin for now.", - "xmlId": "demo1" - }, - { - "authorId": 2, - "author": "admin", - "deliveryServiceRequestId": 2, - "id": 4, - "lastUpdated": "2020-02-24 19:59:55+00", - "value": "Using HTTPS.", - "xmlId": "demo1" - } - ] - } - -``POST`` -======== -Allows user to create a :term:`Delivery Service Request` comment. - -:Auth. Required: Yes -:Roles Required: "admin", "Federation", "operations", "Portal", or "Steering" -:Response Type: Object - -Request Structure ------------------ -:deliveryServiceRequestId: The integral, unique identifier of the delivery service that you are commenting on. -:value: The comment text itself. -:xmlId: This can be any string. It is not validated or used, though it is returned in the response. - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/deliveryservice_request_comments HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - Content-Length: 111 - - { - "deliveryServiceRequestId": 2, - "value": "Does anyone have time to review my delivery service request?" - } - -Response Structure ------------------- -:author: The username of the user who created the comment. -:authorId: The integral, unique identifier of the user who created the comment. -:deliveryServiceRequestId: The integral, unique identifier of the :term:`Delivery Service Request` that the comment was posted on. -:id: The integral, unique identifier of the :term:`DSR` comment. -:lastUpdated: The date and time at which the user was last modified, in :ref:`non-rfc-datetime` -:value: The text of the comment that was posted. -:xmlId: This is the ``xmlId`` value that you provided in the request. - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 21:02:20 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: LiakFP6L7PrnFO5kLXftx7WQoKn3bGpIJT5N15PvNG2sHridRMV3k23eRJM66ET0LcRfMOrQgRiydE+XgA8h0A== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 24 Feb 2020 20:02:20 GMT - Content-Length: 223 - - { - "alerts": [ - { - "text": "deliveryservice_request_comment was created.", - "level": "success" - } - ], - "response": { - "authorId": 2, - "author": null, - "deliveryServiceRequestId": 2, - "id": 6, - "lastUpdated": "2020-02-24 20:02:20+00", - "value": "Does anyone have time to review my delivery service request?", - "xmlId": null - } - } - -``PUT`` -======= -Updates a delivery service request comment. - -:Auth. Required: Yes -:Roles Required: "admin", "Federation", "operations", "Portal", or "Steering" -:Response Type: Object - - -Request Structure ------------------ -:deliveryServiceRequestId: The integral, unique identifier of the :term:`Delivery Service Request` that the comment was posted on. -:value: The comment text itself. -:xmlId: This can be any string. It is not validated or used, though it is returned in the response. - -.. table:: Request Query Parameters - - +-----------+----------+-----------------------------------------------------------------------------------+ - | Parameter | Required | Description | - +===========+==========+===================================================================================+ - | id | yes | The integral, unique identifier of the :term:`Delivery Service Request` comment | - | | | that you wish to update. | - +-----------+----------+-----------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/deliveryservice_request_comments?id=6 HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - Content-Length: 166 - - { - "deliveryServiceRequestId": 2, - "value": "Update: We no longer need this, feel free to reject.\n\nDoes anyone have time to review my delivery service request?" - } - -Response Structure ------------------- -:author: The username of the user who created the comment. -:authorId: The integral, unique identifier of the user who created the comment. -:deliveryServiceRequestId: The integral, unique identifier of the :term:`Delivery Service Request` that the comment was posted on. -:id: The integral, unique identifier of the :term:`DSR` comment. -:lastUpdated: The date and time at which the user was last modified, in :ref:`non-rfc-datetime` -:value: The text of the comment that was posted. -:xmlId: This is the ``xmlId`` value that you provided in the request. - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 21:05:46 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: RalS34imPw7c42nlnu5eTuv6FSxuGcAvxEdeIyNma1zpE3ZojAMFbhj8qi1s+hOVDYybfFPzMz82c+xc1qrMHg== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 24 Feb 2020 20:05:46 GMT - Content-Length: 255 - - { - "alerts": [ - { - "text": "deliveryservice_request_comment was updated.", - "level": "success" - } - ], - "response": { - "authorId": null, - "author": null, - "deliveryServiceRequestId": 2, - "id": 6, - "lastUpdated": "2020-02-24 20:05:46+00", - "value": "Update: We no longer need this, feel free to reject.\n\nDoes anyone have time to review my delivery service request?", - "xmlId": null - } - } - -``DELETE`` -========== -Deletes a delivery service request comment. - -:Auth. Required: Yes -:Roles Required: "admin", "Federation", "operations", "Portal", or "Steering" -:Response Type: ``undefined`` - -Request Structure ------------------ - -.. table:: Request Query Parameters - - +-----------+----------+-----------------------------------------------------------------------------------+ - | Parameter | Required | Description | - +===========+==========+===================================================================================+ - | id | yes | The integral, unique identifier of the :term:`Delivery Service Request` comment | - | | | that you wish to delete. | - +-----------+----------+-----------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/deliveryservice_request_comments?id=6 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 ------------------- - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 21:07:40 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: lOpGzqeIh/1JAx85mz3MI/5A1i1g5beTSLtfvgcfQmCjNKQvOMs/4TLviuVzOCRrEIPmNcjy35tmvfxwlv7RMQ== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 24 Feb 2020 20:07:40 GMT - Content-Length: 101 - - { - "alerts": [ - { - "text": "deliveryservice_request_comment was deleted.", - "level": "success" - } - ] - } diff --git a/docs/source/api/v2/deliveryservice_requests.rst b/docs/source/api/v2/deliveryservice_requests.rst deleted file mode 100644 index fb7bc7a1dd..0000000000 --- a/docs/source/api/v2/deliveryservice_requests.rst +++ /dev/null @@ -1,1154 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservice-requests: - -**************************** -``deliveryservice_requests`` -**************************** - -``GET`` -======= -Retrieves :ref:`ds_requests`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+=========================================================================================================================================+ - | assignee | no | Filter for :ref:`ds_requests` that are assigned to the user identified by this username. | - +-----------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | assigneeId| no | Filter for :ref:`ds_requests` that are assigned to the user identified by this integral, unique identifier | - +-----------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | author | no | Filter for :ref:`ds_requests` submitted by the user identified by this username | - +-----------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | authorId | no | Filter for :ref:`ds_requests` submitted by the user identified by this integral, unique identifier | - +-----------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | changeType| no | Filter for :ref:`ds_requests` of the change type specified. Can be ``create``, ``update``, or ``delete``. | - +-----------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | createdAt | no | Filter for :ref:`ds_requests` created on a certain date/time. Value must be :rfc:`3339` compliant. Eg. ``2019-09-19T19:35:38.828535Z`` | - +-----------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | id | no | Filter for the :ref:`Delivery Service Request ` identified by this integral, unique identifier. | - +-----------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | status | no | Filter for :ref:`ds_requests` whose status is the status specified. The status can be ``draft``, ``submitted``, ``pending``, | - | | | ``rejected``, or ``complete``. | - +-----------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | xmlId | no | Filter for :ref:`ds_requests` that have the given :ref:`ds-xmlid`. | - +-----------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | 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``. | - +-----------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - -.. versionadded:: ATCv6 - The ``createdAt`` query parameter was added to this in endpoint across all API versions in :abbr:`ATC (Apache Traffic Control)` version 6.0.0. - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/deliveryservice_requests?status=draft HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - -Response Structure ------------------- -:author: The username of the user who created the Delivery Service Request. -:authorId: The integral, unique identifier assigned to the author -:changeType: The change type of the :term:`DSR `. It can be ``create``, ``update``, or ``delete``.... -:createdAt: The date and time at which the :term:`DSR ` was created, in :ref:`non-rfc-datetime`. -:deliveryService: The delivery service that the :term:`DSR ` is requesting to update. - - :active: A boolean that defines :ref:`ds-active`. - :anonymousBlockingEnabled: A boolean that defines :ref:`ds-anonymous-blocking` - :cacheurl: A :ref:`ds-cacheurl` - - .. deprecated:: ATCv3.0 - This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later - - :ccrDnsTtl: The :ref:`ds-dns-ttl` - named "ccrDnsTtl" for legacy reasons - :cdnId: The integral, unique identifier of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs - :cdnName: Name of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs - :checkPath: A :ref:`ds-check-path` - :consistentHashQueryParams: An array of :ref:`ds-consistent-hashing-qparams` - :consistentHashRegex: A :ref:`ds-consistent-hashing-regex` - :deepCachingType: The :ref:`ds-deep-caching` setting for this :term:`Delivery Service` - :displayName: The :ref:`ds-display-name` - :dnsBypassCname: A :ref:`ds-dns-bypass-cname` - :dnsBypassIp: A :ref:`ds-dns-bypass-ip` - :dnsBypassIp6: A :ref:`ds-dns-bypass-ipv6` - :dnsBypassTtl: The :ref:`ds-dns-bypass-ttl` - :dscp: A :ref:`ds-dscp` to be used within the :term:`Delivery Service` - :ecsEnabled: A boolean that defines the :ref:`ds-ecs` setting on this :term:`Delivery Service` - :edgeHeaderRewrite: A set of :ref:`ds-edge-header-rw-rules` - :exampleURLs: An array of :ref:`ds-example-urls` - :fqPacingRate: The :ref:`ds-fqpr` - :geoLimit: An integer that defines the :ref:`ds-geo-limit` - :geoLimitCountries: A string containing a comma-separated list defining the :ref:`ds-geo-limit-countries`\ [#geolimit]_ - :geoLimitRedirectUrl: A :ref:`ds-geo-limit-redirect-url`\ [#geolimit]_ - :geoProvider: The :ref:`ds-geo-provider` - :globalMaxMbps: The :ref:`ds-global-max-mbps` - :globalMaxTps: The :ref:`ds-global-max-tps` - :httpBypassFqdn: A :ref:`ds-http-bypass-fqdn` - :id: An integral, unique identifier for this :term:`Delivery Service` - :infoUrl: An :ref:`ds-info-url` - :initialDispersion: The :ref:`ds-initial-dispersion` - :ipv6RoutingEnabled: A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service` - :lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in :ref:`non-rfc-datetime` - :logsEnabled: A boolean that defines the :ref:`ds-logs-enabled` setting on this :term:`Delivery Service` - :longDesc: The :ref:`ds-longdesc` of this :term:`Delivery Service` - :longDesc1: An optional field containing the 2nd long description of this :term:`Delivery Service` - :longDesc2: An optional field containing the 3rd long description of this :term:`Delivery Service` - :matchList: The :term:`Delivery Service`'s :ref:`ds-matchlist` - - :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped) - :setNumber: An integer that provides explicit ordering of :ref:`ds-matchlist` items - this is used as a priority ranking by Traffic Router, and is not guaranteed to correspond to the ordering of items in the array. - :type: The type of match performed using ``pattern``. - - :maxDnsAnswers: The :ref:`ds-max-dns-answers` allowed for this :term:`Delivery Service` - :maxOriginConnections: The :ref:`ds-max-origin-connections` - :midHeaderRewrite: A set of :ref:`ds-mid-header-rw-rules` - :missLat: The :ref:`ds-geo-miss-default-latitude` used by this :term:`Delivery Service` - :missLong: The :ref:`ds-geo-miss-default-longitude` used by this :term:`Delivery Service` - :multiSiteOrigin: A boolean that defines the use of :ref:`ds-multi-site-origin` by this :term:`Delivery Service` - :orgServerFqdn: The :ref:`ds-origin-url` - :originShield: A :ref:`ds-origin-shield` string - :profileDescription: The :ref:`profile-description` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated - :profileId: An optional :ref:`profile-id` of a :ref:`ds-profile` with which this :term:`Delivery Service` shall be associated - :profileName: The :ref:`profile-name` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated - :protocol: An integral, unique identifier that corresponds to the :ref:`ds-protocol` used by this :term:`Delivery Service` - :qstringIgnore: An integral, unique identifier that corresponds to the :ref:`ds-qstring-handling` setting on this :term:`Delivery Service` - :rangeRequestHandling: An integral, unique identifier that corresponds to the :ref:`ds-range-request-handling` setting on this :term:`Delivery Service` - :regexRemap: A :ref:`ds-regex-remap` - :regionalGeoBlocking: A boolean defining the :ref:`ds-regionalgeo` setting on this :term:`Delivery Service` - :remapText: :ref:`ds-raw-remap` - :routingName: The :ref:`ds-routing-name` of this :term:`Delivery Service` - :signed: ``true`` if and only if ``signingAlgorithm`` is not ``null``, ``false`` otherwise - :signingAlgorithm: Either a :ref:`ds-signing-algorithm` or ``null`` to indicate URL/URI signing is not implemented on this :term:`Delivery Service` - :sslKeyVersion: This integer indicates the :ref:`ds-ssl-key-version` - :tenant: The name of the :term:`Tenant` who owns this :term:`Origin` - :tenantId: The integral, unique identifier of the :ref:`ds-tenant` who owns this :term:`Delivery Service` - :trRequestHeaders: If defined, this defines the :ref:`ds-tr-req-headers` used by Traffic Router for this :term:`Delivery Service` - :trResponseHeaders: If defined, this defines the :ref:`ds-tr-resp-headers` used by Traffic Router for this :term:`Delivery Service` - :type: The :ref:`ds-types` of this :term:`Delivery Service` - :typeId: The integral, unique identifier of the :ref:`ds-types` of this :term:`Delivery Service` - :xmlId: This :term:`Delivery Service`'s :ref:`ds-xmlid` - -:id: The integral, unique identifier assigned to the :term:`DSR ` -:lastEditedBy: The username of user who last edited this :term:`DSR ` -:lastEditedById: The integral, unique identifier assigned to the user who last edited this :term:`DSR ` -:lastUpdated: The date and time at which the :term:`DSR ` was last updated, in :ref:`non-rfc-datetime`. -:status: The status of the request. Can be "draft", "submitted", "rejected", "pending", or "complete". - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 20:14:07 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: UBp3nklJr2x2cAW/TKbhXMVJH6+OduxUaEBGbX4P7IahDk3VkaTd9LsQj01zgFEnZLwHrikpwFfNlUO32RAZOA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 24 Feb 2020 19:14:07 GMT - Content-Length: 872 - - { - "response": [ - { - "authorId": 2, - "author": "admin", - "changeType": "update", - "createdAt": "2020-02-24 19:11:12+00", - "id": 1, - "lastEditedBy": "admin", - "lastEditedById": 2, - "lastUpdated": "2020-02-24 19:11:12+00", - "deliveryService": { - "active": false, - "anonymousBlockingEnabled": false, - "cacheurl": null, - "ccrDnsTtl": null, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "checkPath": null, - "displayName": "Demo 1", - "dnsBypassCname": null, - "dnsBypassIp": null, - "dnsBypassIp6": null, - "dnsBypassTtl": null, - "dscp": 0, - "edgeHeaderRewrite": null, - "geoLimit": 0, - "geoLimitCountries": null, - "geoLimitRedirectURL": null, - "geoProvider": 0, - "globalMaxMbps": null, - "globalMaxTps": null, - "httpBypassFqdn": null, - "id": 1, - "infoUrl": null, - "initialDispersion": 1, - "ipv6RoutingEnabled": true, - "lastUpdated": "0001-01-01 00:00:00+00", - "logsEnabled": true, - "longDesc": "Apachecon North America 2018", - "longDesc1": null, - "longDesc2": null, - "matchList": [ - { - "type": "HOST_REGEXP", - "setNumber": 0, - "pattern": ".*\\.demo1\\..*" - } - ], - "maxDnsAnswers": null, - "midHeaderRewrite": null, - "missLat": 42, - "missLong": -88, - "multiSiteOrigin": false, - "originShield": null, - "orgServerFqdn": "http://origin.infra.ciab.test", - "profileDescription": null, - "profileId": null, - "profileName": null, - "protocol": 2, - "qstringIgnore": 0, - "rangeRequestHandling": 0, - "regexRemap": null, - "regionalGeoBlocking": false, - "remapText": null, - "routingName": "video", - "signed": false, - "sslKeyVersion": 1, - "tenantId": 1, - "type": "HTTP", - "typeId": 1, - "xmlId": "demo1", - "exampleURLs": [ - "http://video.demo1.mycdn.ciab.test", - "https://video.demo1.mycdn.ciab.test" - ], - "deepCachingType": "NEVER", - "fqPacingRate": null, - "signingAlgorithm": null, - "tenant": "root", - "trResponseHeaders": null, - "trRequestHeaders": null, - "consistentHashRegex": null, - "consistentHashQueryParams": [ - "abc", - "pdq", - "xxx", - "zyx" - ], - "maxOriginConnections": 0, - "ecsEnabled": false - }, - "status": "draft" - } - ] - } - -.. _to-api-v2-deliveryservice-requests-post: - -``POST`` -======== - -.. note:: This route does NOT do the same thing as :ref:`POST deliveryservices/request `. - -Creates a new :term:`Delivery Service Request`. - -:Auth. Required: Yes -:Roles Required: "admin", "Federation", "operations", "Portal", or "Steering" -:Response Type: Object - -Request Structure ------------------ -:changeType: The action that you want to perform on the delivery service. It can be "create", "update", or "delete". -:status: The status of your request. Can be "draft", "submitted", "rejected", "pending", or "complete". -:deliveryService: The :term:`Delivery Service` that you have submitted for review as part of this request. - - :active: A boolean that defines :ref:`ds-active`. - :anonymousBlockingEnabled: A boolean that defines :ref:`ds-anonymous-blocking` - :cacheurl: A :ref:`ds-cacheurl` - - .. deprecated:: ATCv3.0 - This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later - - :ccrDnsTtl: The :ref:`ds-dns-ttl` - named "ccrDnsTtl" for legacy reasons - :cdnId: The integral, unique identifier of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs - :cdnName: Name of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs - :checkPath: A :ref:`ds-check-path` - :consistentHashQueryParams: An array of :ref:`ds-consistent-hashing-qparams` - :consistentHashRegex: A :ref:`ds-consistent-hashing-regex` - :deepCachingType: The :ref:`ds-deep-caching` setting for this :term:`Delivery Service` - :displayName: The :ref:`ds-display-name` - :dnsBypassCname: A :ref:`ds-dns-bypass-cname` - :dnsBypassIp: A :ref:`ds-dns-bypass-ip` - :dnsBypassIp6: A :ref:`ds-dns-bypass-ipv6` - :dnsBypassTtl: The :ref:`ds-dns-bypass-ttl` - :dscp: A :ref:`ds-dscp` to be used within the :term:`Delivery Service` - :ecsEnabled: A boolean that defines the :ref:`ds-ecs` setting on this :term:`Delivery Service` - :edgeHeaderRewrite: A set of :ref:`ds-edge-header-rw-rules` - :exampleURLs: An array of :ref:`ds-example-urls` - :fqPacingRate: The :ref:`ds-fqpr` - :geoLimit: An integer that defines the :ref:`ds-geo-limit` - :geoLimitCountries: A string containing a comma-separated list defining the :ref:`ds-geo-limit-countries`\ [#geolimit]_ - :geoLimitRedirectUrl: A :ref:`ds-geo-limit-redirect-url`\ [#geolimit]_ - :geoProvider: The :ref:`ds-geo-provider` - :globalMaxMbps: The :ref:`ds-global-max-mbps` - :globalMaxTps: The :ref:`ds-global-max-tps` - :httpBypassFqdn: A :ref:`ds-http-bypass-fqdn` - :id: An integral, unique identifier for this :term:`Delivery Service` - :infoUrl: An :ref:`ds-info-url` - :initialDispersion: The :ref:`ds-initial-dispersion` - :ipv6RoutingEnabled: A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service` - :lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in :ref:`non-rfc-datetime` - :logsEnabled: A boolean that defines the :ref:`ds-logs-enabled` setting on this :term:`Delivery Service` - :longDesc: The :ref:`ds-longdesc` of this :term:`Delivery Service` - :longDesc1: An optional field containing the 2nd long description of this :term:`Delivery Service` - :longDesc2: An optional field containing the 3rd long description of this :term:`Delivery Service` - :matchList: The :term:`Delivery Service`'s :ref:`ds-matchlist` - - :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped) - :setNumber: An integer that provides explicit ordering of :ref:`ds-matchlist` items - this is used as a priority ranking by Traffic Router, and is not guaranteed to correspond to the ordering of items in the array. - :type: The type of match performed using ``pattern``. - - :maxDnsAnswers: The :ref:`ds-max-dns-answers` allowed for this :term:`Delivery Service` - :maxOriginConnections: The :ref:`ds-max-origin-connections` - :midHeaderRewrite: A set of :ref:`ds-mid-header-rw-rules` - :missLat: The :ref:`ds-geo-miss-default-latitude` used by this :term:`Delivery Service` - :missLong: The :ref:`ds-geo-miss-default-longitude` used by this :term:`Delivery Service` - :multiSiteOrigin: A boolean that defines the use of :ref:`ds-multi-site-origin` by this :term:`Delivery Service` - :orgServerFqdn: The :ref:`ds-origin-url` - :originShield: A :ref:`ds-origin-shield` string - :profileDescription: The :ref:`profile-description` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated - :profileId: An optional :ref:`profile-id` of a :ref:`ds-profile` with which this :term:`Delivery Service` shall be associated - :profileName: The :ref:`profile-name` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated - :protocol: An integral, unique identifier that corresponds to the :ref:`ds-protocol` used by this :term:`Delivery Service` - :qstringIgnore: An integral, unique identifier that corresponds to the :ref:`ds-qstring-handling` setting on this :term:`Delivery Service` - :rangeRequestHandling: An integral, unique identifier that corresponds to the :ref:`ds-range-request-handling` setting on this :term:`Delivery Service` - :regexRemap: A :ref:`ds-regex-remap` - :regionalGeoBlocking: A boolean defining the :ref:`ds-regionalgeo` setting on this :term:`Delivery Service` - :remapText: :ref:`ds-raw-remap` - :routingName: The :ref:`ds-routing-name` of this :term:`Delivery Service` - :signed: ``true`` if and only if ``signingAlgorithm`` is not ``null``, ``false`` otherwise - :signingAlgorithm: Either a :ref:`ds-signing-algorithm` or ``null`` to indicate URL/URI signing is not implemented on this :term:`Delivery Service` - :sslKeyVersion: This integer indicates the :ref:`ds-ssl-key-version` - :tenant: The name of the :term:`Tenant` who owns this :term:`Origin` - :tenantId: The integral, unique identifier of the :ref:`ds-tenant` who owns this :term:`Delivery Service` - :trRequestHeaders: If defined, this defines the :ref:`ds-tr-req-headers` used by Traffic Router for this :term:`Delivery Service` - :trResponseHeaders: If defined, this defines the :ref:`ds-tr-resp-headers` used by Traffic Router for this :term:`Delivery Service` - :type: The :ref:`ds-types` of this :term:`Delivery Service` - :typeId: The integral, unique identifier of the :ref:`ds-types` of this :term:`Delivery Service` - :xmlId: This :term:`Delivery Service`'s :ref:`ds-xmlid` - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/deliveryservice_requests HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - Content-Length: 1979 - - { - "changeType": "update", - "status": "draft", - "deliveryService": { - "active": false, - "anonymousBlockingEnabled": false, - "cacheurl": null, - "ccrDnsTtl": null, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "checkPath": null, - "displayName": "Demo 1", - "dnsBypassCname": null, - "dnsBypassIp": null, - "dnsBypassIp6": null, - "dnsBypassTtl": null, - "dscp": 0, - "edgeHeaderRewrite": null, - "geoLimit": 0, - "geoLimitCountries": null, - "geoLimitRedirectURL": null, - "geoProvider": 0, - "globalMaxMbps": null, - "globalMaxTps": null, - "httpBypassFqdn": null, - "id": 1, - "infoUrl": null, - "initialDispersion": 1, - "ipv6RoutingEnabled": true, - "lastUpdated": "2020-02-13 16:43:54+00", - "logsEnabled": true, - "longDesc": "Apachecon North America 2018", - "longDesc1": null, - "longDesc2": null, - "matchList": [ - { - "type": "HOST_REGEXP", - "setNumber": 0, - "pattern": ".*\\.demo1\\..*" - } - ], - "maxDnsAnswers": null, - "midHeaderRewrite": null, - "missLat": 42, - "missLong": -88, - "multiSiteOrigin": false, - "originShield": null, - "orgServerFqdn": "http://origin.infra.ciab.test", - "profileDescription": null, - "profileId": null, - "profileName": null, - "protocol": 2, - "qstringIgnore": 0, - "rangeRequestHandling": 0, - "regexRemap": null, - "regionalGeoBlocking": false, - "remapText": null, - "routingName": "video", - "signed": false, - "sslKeyVersion": 1, - "tenantId": 1, - "type": "HTTP", - "typeId": 1, - "xmlId": "demo1", - "exampleURLs": [ - "http://video.demo1.mycdn.ciab.test", - "https://video.demo1.mycdn.ciab.test" - ], - "deepCachingType": "NEVER", - "fqPacingRate": null, - "signingAlgorithm": null, - "tenant": "root", - "trResponseHeaders": null, - "trRequestHeaders": null, - "consistentHashRegex": null, - "consistentHashQueryParams": [ - "abc", - "pdq", - "xxx", - "zyx" - ], - "maxOriginConnections": 0, - "ecsEnabled": false - } - } - - -Response Structure ------------------- -:author: The username of the user who created the Delivery Service Request. -:authorId: The integral, unique identifier assigned to the author -:changeType: The change type of the :term:`DSR `. It can be ``create``, ``update``, or ``delete``.... -:createdAt: The date and time at which the :term:`DSR ` was created, in :ref:`non-rfc-datetime`. -:deliveryService: The delivery service that the :term:`DSR ` is requesting to update. - - :active: A boolean that defines :ref:`ds-active`. - :anonymousBlockingEnabled: A boolean that defines :ref:`ds-anonymous-blocking` - :cacheurl: A :ref:`ds-cacheurl` - - .. deprecated:: ATCv3.0 - This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later - - :ccrDnsTtl: The :ref:`ds-dns-ttl` - named "ccrDnsTtl" for legacy reasons - :cdnId: The integral, unique identifier of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs - :cdnName: Name of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs - :checkPath: A :ref:`ds-check-path` - :consistentHashQueryParams: An array of :ref:`ds-consistent-hashing-qparams` - :consistentHashRegex: A :ref:`ds-consistent-hashing-regex` - :deepCachingType: The :ref:`ds-deep-caching` setting for this :term:`Delivery Service` - :displayName: The :ref:`ds-display-name` - :dnsBypassCname: A :ref:`ds-dns-bypass-cname` - :dnsBypassIp: A :ref:`ds-dns-bypass-ip` - :dnsBypassIp6: A :ref:`ds-dns-bypass-ipv6` - :dnsBypassTtl: The :ref:`ds-dns-bypass-ttl` - :dscp: A :ref:`ds-dscp` to be used within the :term:`Delivery Service` - :ecsEnabled: A boolean that defines the :ref:`ds-ecs` setting on this :term:`Delivery Service` - :edgeHeaderRewrite: A set of :ref:`ds-edge-header-rw-rules` - :exampleURLs: An array of :ref:`ds-example-urls` - :fqPacingRate: The :ref:`ds-fqpr` - :geoLimit: An integer that defines the :ref:`ds-geo-limit` - :geoLimitCountries: A string containing a comma-separated list defining the :ref:`ds-geo-limit-countries`\ [#geolimit]_ - :geoLimitRedirectUrl: A :ref:`ds-geo-limit-redirect-url`\ [#geolimit]_ - :geoProvider: The :ref:`ds-geo-provider` - :globalMaxMbps: The :ref:`ds-global-max-mbps` - :globalMaxTps: The :ref:`ds-global-max-tps` - :httpBypassFqdn: A :ref:`ds-http-bypass-fqdn` - :id: An integral, unique identifier for this :term:`Delivery Service` - :infoUrl: An :ref:`ds-info-url` - :initialDispersion: The :ref:`ds-initial-dispersion` - :ipv6RoutingEnabled: A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service` - :lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in :ref:`non-rfc-datetime` - :logsEnabled: A boolean that defines the :ref:`ds-logs-enabled` setting on this :term:`Delivery Service` - :longDesc: The :ref:`ds-longdesc` of this :term:`Delivery Service` - :longDesc1: An optional field containing the 2nd long description of this :term:`Delivery Service` - :longDesc2: An optional field containing the 3rd long description of this :term:`Delivery Service` - :matchList: The :term:`Delivery Service`'s :ref:`ds-matchlist` - - :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped) - :setNumber: An integer that provides explicit ordering of :ref:`ds-matchlist` items - this is used as a priority ranking by Traffic Router, and is not guaranteed to correspond to the ordering of items in the array. - :type: The type of match performed using ``pattern``. - - :maxDnsAnswers: The :ref:`ds-max-dns-answers` allowed for this :term:`Delivery Service` - :maxOriginConnections: The :ref:`ds-max-origin-connections` - :midHeaderRewrite: A set of :ref:`ds-mid-header-rw-rules` - :missLat: The :ref:`ds-geo-miss-default-latitude` used by this :term:`Delivery Service` - :missLong: The :ref:`ds-geo-miss-default-longitude` used by this :term:`Delivery Service` - :multiSiteOrigin: A boolean that defines the use of :ref:`ds-multi-site-origin` by this :term:`Delivery Service` - :orgServerFqdn: The :ref:`ds-origin-url` - :originShield: A :ref:`ds-origin-shield` string - :profileDescription: The :ref:`profile-description` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated - :profileId: An optional :ref:`profile-id` of a :ref:`ds-profile` with which this :term:`Delivery Service` shall be associated - :profileName: The :ref:`profile-name` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated - :protocol: An integral, unique identifier that corresponds to the :ref:`ds-protocol` used by this :term:`Delivery Service` - :qstringIgnore: An integral, unique identifier that corresponds to the :ref:`ds-qstring-handling` setting on this :term:`Delivery Service` - :rangeRequestHandling: An integral, unique identifier that corresponds to the :ref:`ds-range-request-handling` setting on this :term:`Delivery Service` - :regexRemap: A :ref:`ds-regex-remap` - :regionalGeoBlocking: A boolean defining the :ref:`ds-regionalgeo` setting on this :term:`Delivery Service` - :remapText: :ref:`ds-raw-remap` - :routingName: The :ref:`ds-routing-name` of this :term:`Delivery Service` - :signed: ``true`` if and only if ``signingAlgorithm`` is not ``null``, ``false`` otherwise - :signingAlgorithm: Either a :ref:`ds-signing-algorithm` or ``null`` to indicate URL/URI signing is not implemented on this :term:`Delivery Service` - :sslKeyVersion: This integer indicates the :ref:`ds-ssl-key-version` - :tenant: The name of the :term:`Tenant` who owns this :term:`Origin` - :tenantId: The integral, unique identifier of the :ref:`ds-tenant` who owns this :term:`Delivery Service` - :trRequestHeaders: If defined, this defines the :ref:`ds-tr-req-headers` used by Traffic Router for this :term:`Delivery Service` - :trResponseHeaders: If defined, this defines the :ref:`ds-tr-resp-headers` used by Traffic Router for this :term:`Delivery Service` - :type: The :ref:`ds-types` of this :term:`Delivery Service` - :typeId: The integral, unique identifier of the :ref:`ds-types` of this :term:`Delivery Service` - :xmlId: This :term:`Delivery Service`'s :ref:`ds-xmlid` - -:id: The integral, unique identifier assigned to the :term:`DSR ` -:lastEditedBy: The username of user who last edited this :term:`DSR ` -:lastEditedById: The integral, unique identifier assigned to the user who last edited this :term:`DSR ` -:lastUpdated: The date and time at which the :term:`DSR ` was last updated, in :ref:`non-rfc-datetime`. -:status: The status of the request. Can be "draft", "submitted", "rejected", "pending", or "complete". - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 20:11:12 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: aWIrFTwUGnLq56WNZPL/FgOi/NwAVUtOy4iqjFPwx4gj7RMZ6+nd++bQKIiasBl8ytAY0WmFvNnmm30Fq9mLpA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 24 Feb 2020 19:11:12 GMT - Content-Length: 901 - - { - "alerts": [ - { - "text": "deliveryservice_request was created.", - "level": "success" - } - ], - "response": { - "authorId": 2, - "author": null, - "changeType": "update", - "createdAt": null, - "id": 1, - "lastEditedBy": null, - "lastEditedById": 2, - "lastUpdated": "2020-02-24 19:11:12+00", - "deliveryService": { - "active": false, - "anonymousBlockingEnabled": false, - "cacheurl": null, - "ccrDnsTtl": null, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "checkPath": null, - "displayName": "Demo 1", - "dnsBypassCname": null, - "dnsBypassIp": null, - "dnsBypassIp6": null, - "dnsBypassTtl": null, - "dscp": 0, - "edgeHeaderRewrite": null, - "geoLimit": 0, - "geoLimitCountries": null, - "geoLimitRedirectURL": null, - "geoProvider": 0, - "globalMaxMbps": null, - "globalMaxTps": null, - "httpBypassFqdn": null, - "id": 1, - "infoUrl": null, - "initialDispersion": 1, - "ipv6RoutingEnabled": true, - "lastUpdated": "0001-01-01 00:00:00+00", - "logsEnabled": true, - "longDesc": "Apachecon North America 2018", - "longDesc1": null, - "longDesc2": null, - "matchList": [ - { - "type": "HOST_REGEXP", - "setNumber": 0, - "pattern": ".*\\.demo1\\..*" - } - ], - "maxDnsAnswers": null, - "midHeaderRewrite": null, - "missLat": 42, - "missLong": -88, - "multiSiteOrigin": false, - "originShield": null, - "orgServerFqdn": "http://origin.infra.ciab.test", - "profileDescription": null, - "profileId": null, - "profileName": null, - "protocol": 2, - "qstringIgnore": 0, - "rangeRequestHandling": 0, - "regexRemap": null, - "regionalGeoBlocking": false, - "remapText": null, - "routingName": "video", - "signed": false, - "sslKeyVersion": 1, - "tenantId": 1, - "type": "HTTP", - "typeId": 1, - "xmlId": "demo1", - "exampleURLs": [ - "http://video.demo1.mycdn.ciab.test", - "https://video.demo1.mycdn.ciab.test" - ], - "deepCachingType": "NEVER", - "fqPacingRate": null, - "signingAlgorithm": null, - "tenant": "root", - "trResponseHeaders": null, - "trRequestHeaders": null, - "consistentHashRegex": null, - "consistentHashQueryParams": [ - "abc", - "pdq", - "xxx", - "zyx" - ], - "maxOriginConnections": 0, - "ecsEnabled": false - }, - "status": "draft" - } - } - -``PUT`` -======= - -Updates an existing :ref:`Delivery Service Request `. - -:Auth. Required: Yes -:Roles Required: "admin", "Federation", "operations", "Portal", or "Steering" -:Response Type: Object - -Request Structure ------------------ -:author: The username of the user who created the Delivery Service Request. -:authorId: The integral, unique identifier assigned to the author -:changeType: The change type of the :term:`DSR `. It can be ``create``, ``update``, or ``delete``.... -:deliveryService: The delivery service that the :term:`DSR ` is requesting to update. - - :active: A boolean that defines :ref:`ds-active`. - :anonymousBlockingEnabled: A boolean that defines :ref:`ds-anonymous-blocking` - :cacheurl: A :ref:`ds-cacheurl` - - .. deprecated:: ATCv3.0 - This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later - - :ccrDnsTtl: The :ref:`ds-dns-ttl` - named "ccrDnsTtl" for legacy reasons - :cdnId: The integral, unique identifier of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs - :cdnName: Name of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs - :checkPath: A :ref:`ds-check-path` - :consistentHashQueryParams: An array of :ref:`ds-consistent-hashing-qparams` - :consistentHashRegex: A :ref:`ds-consistent-hashing-regex` - :deepCachingType: The :ref:`ds-deep-caching` setting for this :term:`Delivery Service` - :displayName: The :ref:`ds-display-name` - :dnsBypassCname: A :ref:`ds-dns-bypass-cname` - :dnsBypassIp: A :ref:`ds-dns-bypass-ip` - :dnsBypassIp6: A :ref:`ds-dns-bypass-ipv6` - :dnsBypassTtl: The :ref:`ds-dns-bypass-ttl` - :dscp: A :ref:`ds-dscp` to be used within the :term:`Delivery Service` - :ecsEnabled: A boolean that defines the :ref:`ds-ecs` setting on this :term:`Delivery Service` - :edgeHeaderRewrite: A set of :ref:`ds-edge-header-rw-rules` - :exampleURLs: An array of :ref:`ds-example-urls` - :fqPacingRate: The :ref:`ds-fqpr` - :geoLimit: An integer that defines the :ref:`ds-geo-limit` - :geoLimitCountries: A string containing a comma-separated list defining the :ref:`ds-geo-limit-countries`\ [#geolimit]_ - :geoLimitRedirectUrl: A :ref:`ds-geo-limit-redirect-url`\ [#geolimit]_ - :geoProvider: The :ref:`ds-geo-provider` - :globalMaxMbps: The :ref:`ds-global-max-mbps` - :globalMaxTps: The :ref:`ds-global-max-tps` - :httpBypassFqdn: A :ref:`ds-http-bypass-fqdn` - :id: An integral, unique identifier for this :term:`Delivery Service` - :infoUrl: An :ref:`ds-info-url` - :initialDispersion: The :ref:`ds-initial-dispersion` - :ipv6RoutingEnabled: A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service` - :lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in :ref:`non-rfc-datetime` - :logsEnabled: A boolean that defines the :ref:`ds-logs-enabled` setting on this :term:`Delivery Service` - :longDesc: The :ref:`ds-longdesc` of this :term:`Delivery Service` - :longDesc1: An optional field containing the 2nd long description of this :term:`Delivery Service` - :longDesc2: An optional field containing the 3rd long description of this :term:`Delivery Service` - :matchList: The :term:`Delivery Service`'s :ref:`ds-matchlist` - - :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped) - :setNumber: An integer that provides explicit ordering of :ref:`ds-matchlist` items - this is used as a priority ranking by Traffic Router, and is not guaranteed to correspond to the ordering of items in the array. - :type: The type of match performed using ``pattern``. - - :maxDnsAnswers: The :ref:`ds-max-dns-answers` allowed for this :term:`Delivery Service` - :maxOriginConnections: The :ref:`ds-max-origin-connections` - :midHeaderRewrite: A set of :ref:`ds-mid-header-rw-rules` - :missLat: The :ref:`ds-geo-miss-default-latitude` used by this :term:`Delivery Service` - :missLong: The :ref:`ds-geo-miss-default-longitude` used by this :term:`Delivery Service` - :multiSiteOrigin: A boolean that defines the use of :ref:`ds-multi-site-origin` by this :term:`Delivery Service` - :orgServerFqdn: The :ref:`ds-origin-url` - :originShield: A :ref:`ds-origin-shield` string - :profileDescription: The :ref:`profile-description` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated - :profileId: An optional :ref:`profile-id` of a :ref:`ds-profile` with which this :term:`Delivery Service` shall be associated - :profileName: The :ref:`profile-name` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated - :protocol: An integral, unique identifier that corresponds to the :ref:`ds-protocol` used by this :term:`Delivery Service` - :qstringIgnore: An integral, unique identifier that corresponds to the :ref:`ds-qstring-handling` setting on this :term:`Delivery Service` - :rangeRequestHandling: An integral, unique identifier that corresponds to the :ref:`ds-range-request-handling` setting on this :term:`Delivery Service` - :regexRemap: A :ref:`ds-regex-remap` - :regionalGeoBlocking: A boolean defining the :ref:`ds-regionalgeo` setting on this :term:`Delivery Service` - :remapText: :ref:`ds-raw-remap` - :routingName: The :ref:`ds-routing-name` of this :term:`Delivery Service` - :signed: ``true`` if and only if ``signingAlgorithm`` is not ``null``, ``false`` otherwise - :signingAlgorithm: Either a :ref:`ds-signing-algorithm` or ``null`` to indicate URL/URI signing is not implemented on this :term:`Delivery Service` - :sslKeyVersion: This integer indicates the :ref:`ds-ssl-key-version` - :tenant: The name of the :term:`Tenant` who owns this :term:`Origin` - :tenantId: The integral, unique identifier of the :ref:`ds-tenant` who owns this :term:`Delivery Service` - :trRequestHeaders: If defined, this defines the :ref:`ds-tr-req-headers` used by Traffic Router for this :term:`Delivery Service` - :trResponseHeaders: If defined, this defines the :ref:`ds-tr-resp-headers` used by Traffic Router for this :term:`Delivery Service` - :type: The :ref:`ds-types` of this :term:`Delivery Service` - :typeId: The integral, unique identifier of the :ref:`ds-types` of this :term:`Delivery Service` - :xmlId: This :term:`Delivery Service`'s :ref:`ds-xmlid` - -:id: The integral, unique identifier assigned to the :term:`DSR ` -:status: The status of the request. Can be "draft", "submitted", "rejected", "pending", or "complete". - -.. table:: Request Query Parameters - - +-----------+----------+------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+==========================================================================================+ - | id | yes | The integral, unique identifier of the :ref:`Delivery Service Request ` that| - | | | you want to update. | - +-----------+----------+------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/deliveryservice_requests?id=1 HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - Content-Length: 2256 - - { - "authorId": 2, - "author": "admin", - "changeType": "update", - "createdAt": "2020-02-24 19:11:12+00", - "id": 1, - "lastEditedBy": "admin", - "lastEditedById": 2, - "lastUpdated": "2020-02-24 19:33:26+00", - "deliveryService": { - "active": false, - "anonymousBlockingEnabled": false, - "cacheurl": null, - "ccrDnsTtl": null, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "checkPath": null, - "displayName": "Demo 1", - "dnsBypassCname": null, - "dnsBypassIp": null, - "dnsBypassIp6": null, - "dnsBypassTtl": null, - "dscp": 0, - "edgeHeaderRewrite": null, - "geoLimit": 0, - "geoLimitCountries": null, - "geoLimitRedirectURL": null, - "geoProvider": 0, - "globalMaxMbps": null, - "globalMaxTps": null, - "httpBypassFqdn": null, - "id": 1, - "infoUrl": null, - "initialDispersion": 1, - "ipv6RoutingEnabled": true, - "lastUpdated": "0001-01-01 00:00:00+00", - "logsEnabled": true, - "longDesc": "Apachecon North America 2018", - "longDesc1": null, - "longDesc2": null, - "matchList": [ - { - "type": "HOST_REGEXP", - "setNumber": 0, - "pattern": ".*\\.demo1\\..*" - } - ], - "maxDnsAnswers": null, - "midHeaderRewrite": null, - "missLat": 42, - "missLong": -88, - "multiSiteOrigin": false, - "originShield": null, - "orgServerFqdn": "http://origin.infra.ciab.test", - "profileDescription": null, - "profileId": null, - "profileName": null, - "protocol": 2, - "qstringIgnore": 0, - "rangeRequestHandling": 0, - "regexRemap": null, - "regionalGeoBlocking": false, - "remapText": null, - "routingName": "video", - "signed": false, - "sslKeyVersion": 1, - "tenantId": 1, - "type": "HTTP", - "typeId": 1, - "xmlId": "demo1", - "exampleURLs": [ - "http://video.demo1.mycdn.ciab.test", - "https://video.demo1.mycdn.ciab.test" - ], - "deepCachingType": "NEVER", - "fqPacingRate": null, - "signingAlgorithm": null, - "tenant": "root", - "trResponseHeaders": "", - "trRequestHeaders": null, - "consistentHashRegex": null, - "consistentHashQueryParams": [ - "abc", - "pdq", - "xxx", - "zyx" - ], - "maxOriginConnections": 0, - "ecsEnabled": false - }, - "status": "submitted" - } - -Response Structure ------------------- -:author: The username of the user who created the Delivery Service Request. -:authorId: The integral, unique identifier assigned to the author -:changeType: The change type of the :term:`DSR `. It can be ``create``, ``update``, or ``delete``.... -:createdAt: The date and time at which the :term:`DSR ` was created, in :ref:`non-rfc-datetime`. -:deliveryService: The delivery service that the :term:`DSR ` is requesting to update. - - :active: A boolean that defines :ref:`ds-active`. - :anonymousBlockingEnabled: A boolean that defines :ref:`ds-anonymous-blocking` - :cacheurl: A :ref:`ds-cacheurl` - - .. deprecated:: ATCv3.0 - This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later - - :ccrDnsTtl: The :ref:`ds-dns-ttl` - named "ccrDnsTtl" for legacy reasons - :cdnId: The integral, unique identifier of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs - :cdnName: Name of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs - :checkPath: A :ref:`ds-check-path` - :consistentHashQueryParams: An array of :ref:`ds-consistent-hashing-qparams` - :consistentHashRegex: A :ref:`ds-consistent-hashing-regex` - :deepCachingType: The :ref:`ds-deep-caching` setting for this :term:`Delivery Service` - :displayName: The :ref:`ds-display-name` - :dnsBypassCname: A :ref:`ds-dns-bypass-cname` - :dnsBypassIp: A :ref:`ds-dns-bypass-ip` - :dnsBypassIp6: A :ref:`ds-dns-bypass-ipv6` - :dnsBypassTtl: The :ref:`ds-dns-bypass-ttl` - :dscp: A :ref:`ds-dscp` to be used within the :term:`Delivery Service` - :ecsEnabled: A boolean that defines the :ref:`ds-ecs` setting on this :term:`Delivery Service` - :edgeHeaderRewrite: A set of :ref:`ds-edge-header-rw-rules` - :exampleURLs: An array of :ref:`ds-example-urls` - :fqPacingRate: The :ref:`ds-fqpr` - :geoLimit: An integer that defines the :ref:`ds-geo-limit` - :geoLimitCountries: A string containing a comma-separated list defining the :ref:`ds-geo-limit-countries`\ [#geolimit]_ - :geoLimitRedirectUrl: A :ref:`ds-geo-limit-redirect-url`\ [#geolimit]_ - :geoProvider: The :ref:`ds-geo-provider` - :globalMaxMbps: The :ref:`ds-global-max-mbps` - :globalMaxTps: The :ref:`ds-global-max-tps` - :httpBypassFqdn: A :ref:`ds-http-bypass-fqdn` - :id: An integral, unique identifier for this :term:`Delivery Service` - :infoUrl: An :ref:`ds-info-url` - :initialDispersion: The :ref:`ds-initial-dispersion` - :ipv6RoutingEnabled: A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service` - :lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in :ref:`non-rfc-datetime` - :logsEnabled: A boolean that defines the :ref:`ds-logs-enabled` setting on this :term:`Delivery Service` - :longDesc: The :ref:`ds-longdesc` of this :term:`Delivery Service` - :longDesc1: An optional field containing the 2nd long description of this :term:`Delivery Service` - :longDesc2: An optional field containing the 3rd long description of this :term:`Delivery Service` - :matchList: The :term:`Delivery Service`'s :ref:`ds-matchlist` - - :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped) - :setNumber: An integer that provides explicit ordering of :ref:`ds-matchlist` items - this is used as a priority ranking by Traffic Router, and is not guaranteed to correspond to the ordering of items in the array. - :type: The type of match performed using ``pattern``. - - :maxDnsAnswers: The :ref:`ds-max-dns-answers` allowed for this :term:`Delivery Service` - :maxOriginConnections: The :ref:`ds-max-origin-connections` - :midHeaderRewrite: A set of :ref:`ds-mid-header-rw-rules` - :missLat: The :ref:`ds-geo-miss-default-latitude` used by this :term:`Delivery Service` - :missLong: The :ref:`ds-geo-miss-default-longitude` used by this :term:`Delivery Service` - :multiSiteOrigin: A boolean that defines the use of :ref:`ds-multi-site-origin` by this :term:`Delivery Service` - :orgServerFqdn: The :ref:`ds-origin-url` - :originShield: A :ref:`ds-origin-shield` string - :profileDescription: The :ref:`profile-description` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated - :profileId: An optional :ref:`profile-id` of a :ref:`ds-profile` with which this :term:`Delivery Service` shall be associated - :profileName: The :ref:`profile-name` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated - :protocol: An integral, unique identifier that corresponds to the :ref:`ds-protocol` used by this :term:`Delivery Service` - :qstringIgnore: An integral, unique identifier that corresponds to the :ref:`ds-qstring-handling` setting on this :term:`Delivery Service` - :rangeRequestHandling: An integral, unique identifier that corresponds to the :ref:`ds-range-request-handling` setting on this :term:`Delivery Service` - :regexRemap: A :ref:`ds-regex-remap` - :regionalGeoBlocking: A boolean defining the :ref:`ds-regionalgeo` setting on this :term:`Delivery Service` - :remapText: :ref:`ds-raw-remap` - :routingName: The :ref:`ds-routing-name` of this :term:`Delivery Service` - :signed: ``true`` if and only if ``signingAlgorithm`` is not ``null``, ``false`` otherwise - :signingAlgorithm: Either a :ref:`ds-signing-algorithm` or ``null`` to indicate URL/URI signing is not implemented on this :term:`Delivery Service` - :sslKeyVersion: This integer indicates the :ref:`ds-ssl-key-version` - :tenant: The name of the :term:`Tenant` who owns this :term:`Origin` - :tenantId: The integral, unique identifier of the :ref:`ds-tenant` who owns this :term:`Delivery Service` - :trRequestHeaders: If defined, this defines the :ref:`ds-tr-req-headers` used by Traffic Router for this :term:`Delivery Service` - :trResponseHeaders: If defined, this defines the :ref:`ds-tr-resp-headers` used by Traffic Router for this :term:`Delivery Service` - :type: The :ref:`ds-types` of this :term:`Delivery Service` - :typeId: The integral, unique identifier of the :ref:`ds-types` of this :term:`Delivery Service` - :xmlId: This :term:`Delivery Service`'s :ref:`ds-xmlid` - -:id: The integral, unique identifier assigned to the :term:`DSR ` -:lastEditedBy: The username of user who last edited this :term:`DSR ` -:lastEditedById: The integral, unique identifier assigned to the user who last edited this :term:`DSR ` -:lastUpdated: The date and time at which the :term:`DSR ` was last updated, in :ref:`non-rfc-datetime`. -:status: The status of the request. Can be "draft", "submitted", "rejected", "pending", or "complete". - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 20:36:16 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: +W0vFm96yFkZUJqa0GAX7uzIpRKh/ohyBm0uH3egpiERTcxy5OfVVtoP3h8Ee2teLu8KFooDYXJ6rpQg6UhbNQ== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 24 Feb 2020 19:36:16 GMT - Content-Length: 913 - - { - "alerts": [ - { - "text": "deliveryservice_request was updated.", - "level": "success" - } - ], - "response": { - "authorId": 0, - "author": "admin", - "changeType": "update", - "createdAt": "0001-01-01 00:00:00+00", - "id": 1, - "lastEditedBy": "admin", - "lastEditedById": 2, - "lastUpdated": "2020-02-24 19:36:16+00", - "deliveryService": { - "active": false, - "anonymousBlockingEnabled": false, - "cacheurl": null, - "ccrDnsTtl": null, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "checkPath": null, - "displayName": "Demo 1", - "dnsBypassCname": null, - "dnsBypassIp": null, - "dnsBypassIp6": null, - "dnsBypassTtl": null, - "dscp": 0, - "edgeHeaderRewrite": null, - "geoLimit": 0, - "geoLimitCountries": null, - "geoLimitRedirectURL": null, - "geoProvider": 0, - "globalMaxMbps": null, - "globalMaxTps": null, - "httpBypassFqdn": null, - "id": 1, - "infoUrl": null, - "initialDispersion": 1, - "ipv6RoutingEnabled": true, - "lastUpdated": "0001-01-01 00:00:00+00", - "logsEnabled": true, - "longDesc": "Apachecon North America 2018", - "longDesc1": null, - "longDesc2": null, - "matchList": [ - { - "type": "HOST_REGEXP", - "setNumber": 0, - "pattern": ".*\\.demo1\\..*" - } - ], - "maxDnsAnswers": null, - "midHeaderRewrite": null, - "missLat": 42, - "missLong": -88, - "multiSiteOrigin": false, - "originShield": null, - "orgServerFqdn": "http://origin.infra.ciab.test", - "profileDescription": null, - "profileId": null, - "profileName": null, - "protocol": 2, - "qstringIgnore": 0, - "rangeRequestHandling": 0, - "regexRemap": null, - "regionalGeoBlocking": false, - "remapText": null, - "routingName": "video", - "signed": false, - "sslKeyVersion": 1, - "tenantId": 1, - "type": "HTTP", - "typeId": 1, - "xmlId": "demo1", - "exampleURLs": [ - "http://video.demo1.mycdn.ciab.test", - "https://video.demo1.mycdn.ciab.test" - ], - "deepCachingType": "NEVER", - "fqPacingRate": null, - "signingAlgorithm": null, - "tenant": "root", - "trResponseHeaders": "", - "trRequestHeaders": null, - "consistentHashRegex": null, - "consistentHashQueryParams": [ - "abc", - "pdq", - "xxx", - "zyx" - ], - "maxOriginConnections": 0, - "ecsEnabled": false - }, - "status": "submitted" - } - } - - -``DELETE`` -========== -Deletes a :term:`Delivery Service Request`. - -:Auth. Required: Yes -:Roles Required: "admin", "Federation", "operations", "Portal", or "Steering" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------+----------+------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+==========================================================================================+ - | id | yes | The integral, unique identifier of the :ref:`Delivery Service Request ` that| - | | | you want to delete. | - +-----------+----------+------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/deliveryservice_requests?id=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 ------------------- - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 20:48:55 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: jNCbNo8Tw+JMMaWpAYQgntSXPq2Xuj+n2zSEVRaDQFWMV1SYbT9djes6SPdwiBoKq6W0lNE04hOE92jBVcjtEw== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 24 Feb 2020 19:48:55 GMT - Content-Length: 96 - - { - "alerts": [ - { - "text": "deliveryservice_request was deleted.", - "level": "success" - } - ] - } - -.. [#geoLimit] These fields must be defined if and only if ``geoLimit`` is non-zero diff --git a/docs/source/api/v2/deliveryservice_requests_id_assign.rst b/docs/source/api/v2/deliveryservice_requests_id_assign.rst deleted file mode 100644 index f7d2c6dd7e..0000000000 --- a/docs/source/api/v2/deliveryservice_requests_id_assign.rst +++ /dev/null @@ -1,259 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservice_requests-id-assign: - -****************************************** -``deliveryservice_requests/{{ID}}/assign`` -****************************************** -Assign a :term:`Delivery Service Request` to a user. - -``PUT`` -======= -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -:id: The integral, unique identifier assigned to the :term:`DSR ` -:assignee: The username of the user to whom the :term:`Delivery Service Request` is assigned. - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/deliveryservice_requests/1/assign HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - Content-Length: 28 - - { - "id": 1, - "assigneeId": 2 - } - -Response Structure ------------------- -:assignee: The username of the user to whom the :term:`Delivery Service Request` is assigned. -:author: The author of the :term:`Delivery Service Request` -:authorId: The integral, unique identifier assigned to the author -:changeType: The change type of the :term:`DSR `. It can be ``create``, ``update``, or ``delete``.... -:createdAt: The date and time at which the :term:`DSR ` was created, in :ref:`non-rfc-datetime`. -:deliveryService: The delivery service that the :term:`DSR ` is requesting to update. - - :active: A boolean that defines :ref:`ds-active`. - :anonymousBlockingEnabled: A boolean that defines :ref:`ds-anonymous-blocking` - :cacheurl: A :ref:`ds-cacheurl` - - .. deprecated:: ATCv3.0 - This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later - - :ccrDnsTtl: The :ref:`ds-dns-ttl` - named "ccrDnsTtl" for legacy reasons - :cdnId: The integral, unique identifier of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs - :cdnName: Name of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs - :checkPath: A :ref:`ds-check-path` - :consistentHashQueryParams: An array of :ref:`ds-consistent-hashing-qparams` - :consistentHashRegex: A :ref:`ds-consistent-hashing-regex` - :deepCachingType: The :ref:`ds-deep-caching` setting for this :term:`Delivery Service` - :displayName: The :ref:`ds-display-name` - :dnsBypassCname: A :ref:`ds-dns-bypass-cname` - :dnsBypassIp: A :ref:`ds-dns-bypass-ip` - :dnsBypassIp6: A :ref:`ds-dns-bypass-ipv6` - :dnsBypassTtl: The :ref:`ds-dns-bypass-ttl` - :dscp: A :ref:`ds-dscp` to be used within the :term:`Delivery Service` - :ecsEnabled: A boolean that defines the :ref:`ds-ecs` setting on this :term:`Delivery Service` - :edgeHeaderRewrite: A set of :ref:`ds-edge-header-rw-rules` - :exampleURLs: An array of :ref:`ds-example-urls` - :fqPacingRate: The :ref:`ds-fqpr` - :geoLimit: An integer that defines the :ref:`ds-geo-limit` - :geoLimitCountries: A string containing a comma-separated list defining the :ref:`ds-geo-limit-countries`\ [#geolimit]_ - :geoLimitRedirectUrl: A :ref:`ds-geo-limit-redirect-url`\ [#geolimit]_ - :geoProvider: The :ref:`ds-geo-provider` - :globalMaxMbps: The :ref:`ds-global-max-mbps` - :globalMaxTps: The :ref:`ds-global-max-tps` - :httpBypassFqdn: A :ref:`ds-http-bypass-fqdn` - :id: An integral, unique identifier for this :term:`Delivery Service` - :infoUrl: An :ref:`ds-info-url` - :initialDispersion: The :ref:`ds-initial-dispersion` - :ipv6RoutingEnabled: A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service` - :lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in :ref:`non-rfc-datetime` - :logsEnabled: A boolean that defines the :ref:`ds-logs-enabled` setting on this :term:`Delivery Service` - :longDesc: The :ref:`ds-longdesc` of this :term:`Delivery Service` - :longDesc1: An optional field containing the 2nd long description of this :term:`Delivery Service` - :longDesc2: An optional field containing the 3rd long description of this :term:`Delivery Service` - :matchList: The :term:`Delivery Service`'s :ref:`ds-matchlist` - - :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped) - :setNumber: An integer that provides explicit ordering of :ref:`ds-matchlist` items - this is used as a priority ranking by Traffic Router, and is not guaranteed to correspond to the ordering of items in the array. - :type: The type of match performed using ``pattern``. - - :maxDnsAnswers: The :ref:`ds-max-dns-answers` allowed for this :term:`Delivery Service` - :maxOriginConnections: The :ref:`ds-max-origin-connections` - :midHeaderRewrite: A set of :ref:`ds-mid-header-rw-rules` - :missLat: The :ref:`ds-geo-miss-default-latitude` used by this :term:`Delivery Service` - :missLong: The :ref:`ds-geo-miss-default-longitude` used by this :term:`Delivery Service` - :multiSiteOrigin: A boolean that defines the use of :ref:`ds-multi-site-origin` by this :term:`Delivery Service` - :orgServerFqdn: The :ref:`ds-origin-url` - :originShield: A :ref:`ds-origin-shield` string - :profileDescription: The :ref:`profile-description` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated - :profileId: An optional :ref:`profile-id` of a :ref:`ds-profile` with which this :term:`Delivery Service` shall be associated - :profileName: The :ref:`profile-name` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated - :protocol: An integral, unique identifier that corresponds to the :ref:`ds-protocol` used by this :term:`Delivery Service` - :qstringIgnore: An integral, unique identifier that corresponds to the :ref:`ds-qstring-handling` setting on this :term:`Delivery Service` - :rangeRequestHandling: An integral, unique identifier that corresponds to the :ref:`ds-range-request-handling` setting on this :term:`Delivery Service` - :regexRemap: A :ref:`ds-regex-remap` - :regionalGeoBlocking: A boolean defining the :ref:`ds-regionalgeo` setting on this :term:`Delivery Service` - :remapText: :ref:`ds-raw-remap` - :routingName: The :ref:`ds-routing-name` of this :term:`Delivery Service` - :signed: ``true`` if and only if ``signingAlgorithm`` is not ``null``, ``false`` otherwise - :signingAlgorithm: Either a :ref:`ds-signing-algorithm` or ``null`` to indicate URL/URI signing is not implemented on this :term:`Delivery Service` - :sslKeyVersion: This integer indicates the :ref:`ds-ssl-key-version` - :tenant: The name of the :term:`Tenant` who owns this :term:`Origin` - :tenantId: The integral, unique identifier of the :ref:`ds-tenant` who owns this :term:`Delivery Service` - :trRequestHeaders: If defined, this defines the :ref:`ds-tr-req-headers` used by Traffic Router for this :term:`Delivery Service` - :trResponseHeaders: If defined, this defines the :ref:`ds-tr-resp-headers` used by Traffic Router for this :term:`Delivery Service` - :type: The :ref:`ds-types` of this :term:`Delivery Service` - :typeId: The integral, unique identifier of the :ref:`ds-types` of this :term:`Delivery Service` - :xmlId: This :term:`Delivery Service`'s :ref:`ds-xmlid` - -:id: The integral, unique identifier assigned to the :term:`DSR ` -:lastEditedBy: The username of user who last edited this :term:`DSR ` -:lastEditedById: The integral, unique identifier assigned to the user who last edited this :term:`DSR ` -:lastUpdated: The date and time at which the :term:`DSR ` was last updated, in :ref:`non-rfc-datetime`. -:status: The status of the request. Can be "draft", "submitted", "rejected", "pending", or "complete". - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Sun, 23 Feb 2020 14:45:51 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: h7uBZHLQtRYbOSOR5AtQQrZ4uMeEWivWNT74fCf6WtLbAMwGpRrMjNmBYKduv48DEnRqG6WVM/4nBu3AkCUqPw== - X-Server-Name: traffic_ops_golang/ - Date: Sun, 23 Feb 2020 13:45:51 GMT - Content-Length: 931 - - { - "alerts": [ - { - "text": "deliveryservice_request was updated.", - "level": "success" - } - ], - "response": { - "assigneeId": 2, - "assignee": "admin", - "authorId": 2, - "author": "admin", - "changeType": "update", - "createdAt": "2020-02-23 11:06:00+00", - "id": 1, - "lastEditedBy": "admin", - "lastEditedById": 2, - "lastUpdated": "2020-02-23 13:45:51+00", - "deliveryService": { - "active": true, - "anonymousBlockingEnabled": false, - "cacheurl": null, - "ccrDnsTtl": null, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "checkPath": null, - "displayName": "Demo 2", - "dnsBypassCname": null, - "dnsBypassIp": null, - "dnsBypassIp6": null, - "dnsBypassTtl": null, - "dscp": 0, - "edgeHeaderRewrite": null, - "geoLimit": 0, - "geoLimitCountries": null, - "geoLimitRedirectURL": null, - "geoProvider": 0, - "globalMaxMbps": null, - "globalMaxTps": null, - "httpBypassFqdn": null, - "id": 1, - "infoUrl": null, - "initialDispersion": 1, - "ipv6RoutingEnabled": true, - "lastUpdated": "0001-01-01 00:00:00+00", - "logsEnabled": true, - "longDesc": "Apachecon North America 2018", - "longDesc1": null, - "longDesc2": null, - "matchList": [ - { - "type": "HOST_REGEXP", - "setNumber": 0, - "pattern": ".*\\.demo1\\..*" - } - ], - "maxDnsAnswers": null, - "midHeaderRewrite": null, - "missLat": 42, - "missLong": -88, - "multiSiteOrigin": false, - "originShield": null, - "orgServerFqdn": "http://origin.infra.ciab.test", - "profileDescription": null, - "profileId": null, - "profileName": null, - "protocol": 2, - "qstringIgnore": 0, - "rangeRequestHandling": 0, - "regexRemap": null, - "regionalGeoBlocking": false, - "remapText": null, - "routingName": "video", - "signed": false, - "sslKeyVersion": null, - "tenantId": 1, - "type": "HTTP", - "typeId": 1, - "xmlId": "demo1", - "exampleURLs": [ - "http://video.demo1.mycdn.ciab.test", - "https://video.demo1.mycdn.ciab.test" - ], - "deepCachingType": "NEVER", - "fqPacingRate": null, - "signingAlgorithm": null, - "tenant": "root", - "trResponseHeaders": null, - "trRequestHeaders": null, - "consistentHashRegex": null, - "consistentHashQueryParams": [ - "abc", - "pdq", - "xxx", - "zyx" - ], - "maxOriginConnections": 0, - "ecsEnabled": false - }, - "status": "submitted" - } - } - -.. [#geoLimit] These fields must be defined if and only if ``geoLimit`` is non-zero diff --git a/docs/source/api/v2/deliveryservice_requests_id_status.rst b/docs/source/api/v2/deliveryservice_requests_id_status.rst deleted file mode 100644 index 48394b81fd..0000000000 --- a/docs/source/api/v2/deliveryservice_requests_id_status.rst +++ /dev/null @@ -1,260 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservice_requests-id-status: - -****************************************** -``deliveryservice_requests/{{ID}}/status`` -****************************************** -Sets the status of a :term:`Delivery Service Request`. - -``PUT`` -======= -:Auth. Required: Yes -:Roles Required: "admin", "Federation", "operations", "Portal", or "Steering" -:Response Type: Object - -Request Structure ------------------ -:id: The integral, unique identifier assigned to the :term:`DSR ` -:status: The status of the `DSR `. Can be "draft", "submitted", "rejected", "pending", or "complete". - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/deliveryservice_requests/1/status HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - Content-Length: 28 - - { - "id": 1, - "status": "rejected" - } - -Response Structure ------------------- -:assignee: The username of the user to whom the :term:`Delivery Service Request` is assigned. -:assigneeId: The integral, unique identifier of the user to whom the :term:`Delivery Service Request` is assigned. -:author: The author of the :term:`Delivery Service Request` -:authorId: The integral, unique identifier assigned to the author -:changeType: The change type of the :term:`DSR `. It can be ``create``, ``update``, or ``delete``.... -:createdAt: The date and time at which the :term:`DSR ` was created, in :ref:`non-rfc-datetime`. -:deliveryService: The delivery service that the :term:`DSR ` is requesting to update. - - :active: A boolean that defines :ref:`ds-active`. - :anonymousBlockingEnabled: A boolean that defines :ref:`ds-anonymous-blocking` - :cacheurl: A :ref:`ds-cacheurl` - - .. deprecated:: ATCv3.0 - This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later - - :ccrDnsTtl: The :ref:`ds-dns-ttl` - named "ccrDnsTtl" for legacy reasons - :cdnId: The integral, unique identifier of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs - :cdnName: Name of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs - :checkPath: A :ref:`ds-check-path` - :consistentHashQueryParams: An array of :ref:`ds-consistent-hashing-qparams` - :consistentHashRegex: A :ref:`ds-consistent-hashing-regex` - :deepCachingType: The :ref:`ds-deep-caching` setting for this :term:`Delivery Service` - :displayName: The :ref:`ds-display-name` - :dnsBypassCname: A :ref:`ds-dns-bypass-cname` - :dnsBypassIp: A :ref:`ds-dns-bypass-ip` - :dnsBypassIp6: A :ref:`ds-dns-bypass-ipv6` - :dnsBypassTtl: The :ref:`ds-dns-bypass-ttl` - :dscp: A :ref:`ds-dscp` to be used within the :term:`Delivery Service` - :ecsEnabled: A boolean that defines the :ref:`ds-ecs` setting on this :term:`Delivery Service` - :edgeHeaderRewrite: A set of :ref:`ds-edge-header-rw-rules` - :exampleURLs: An array of :ref:`ds-example-urls` - :fqPacingRate: The :ref:`ds-fqpr` - :geoLimit: An integer that defines the :ref:`ds-geo-limit` - :geoLimitCountries: A string containing a comma-separated list defining the :ref:`ds-geo-limit-countries`\ [#geolimit]_ - :geoLimitRedirectUrl: A :ref:`ds-geo-limit-redirect-url`\ [#geolimit]_ - :geoProvider: The :ref:`ds-geo-provider` - :globalMaxMbps: The :ref:`ds-global-max-mbps` - :globalMaxTps: The :ref:`ds-global-max-tps` - :httpBypassFqdn: A :ref:`ds-http-bypass-fqdn` - :id: An integral, unique identifier for this :term:`Delivery Service` - :infoUrl: An :ref:`ds-info-url` - :initialDispersion: The :ref:`ds-initial-dispersion` - :ipv6RoutingEnabled: A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service` - :lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in :ref:`non-rfc-datetime` - :logsEnabled: A boolean that defines the :ref:`ds-logs-enabled` setting on this :term:`Delivery Service` - :longDesc: The :ref:`ds-longdesc` of this :term:`Delivery Service` - :longDesc1: An optional field containing the 2nd long description of this :term:`Delivery Service` - :longDesc2: An optional field containing the 3rd long description of this :term:`Delivery Service` - :matchList: The :term:`Delivery Service`'s :ref:`ds-matchlist` - - :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped) - :setNumber: An integer that provides explicit ordering of :ref:`ds-matchlist` items - this is used as a priority ranking by Traffic Router, and is not guaranteed to correspond to the ordering of items in the array. - :type: The type of match performed using ``pattern``. - - :maxDnsAnswers: The :ref:`ds-max-dns-answers` allowed for this :term:`Delivery Service` - :maxOriginConnections: The :ref:`ds-max-origin-connections` - :midHeaderRewrite: A set of :ref:`ds-mid-header-rw-rules` - :missLat: The :ref:`ds-geo-miss-default-latitude` used by this :term:`Delivery Service` - :missLong: The :ref:`ds-geo-miss-default-longitude` used by this :term:`Delivery Service` - :multiSiteOrigin: A boolean that defines the use of :ref:`ds-multi-site-origin` by this :term:`Delivery Service` - :orgServerFqdn: The :ref:`ds-origin-url` - :originShield: A :ref:`ds-origin-shield` string - :profileDescription: The :ref:`profile-description` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated - :profileId: An optional :ref:`profile-id` of a :ref:`ds-profile` with which this :term:`Delivery Service` shall be associated - :profileName: The :ref:`profile-name` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated - :protocol: An integral, unique identifier that corresponds to the :ref:`ds-protocol` used by this :term:`Delivery Service` - :qstringIgnore: An integral, unique identifier that corresponds to the :ref:`ds-qstring-handling` setting on this :term:`Delivery Service` - :rangeRequestHandling: An integral, unique identifier that corresponds to the :ref:`ds-range-request-handling` setting on this :term:`Delivery Service` - :regexRemap: A :ref:`ds-regex-remap` - :regionalGeoBlocking: A boolean defining the :ref:`ds-regionalgeo` setting on this :term:`Delivery Service` - :remapText: :ref:`ds-raw-remap` - :routingName: The :ref:`ds-routing-name` of this :term:`Delivery Service` - :signed: ``true`` if and only if ``signingAlgorithm`` is not ``null``, ``false`` otherwise - :signingAlgorithm: Either a :ref:`ds-signing-algorithm` or ``null`` to indicate URL/URI signing is not implemented on this :term:`Delivery Service` - :sslKeyVersion: This integer indicates the :ref:`ds-ssl-key-version` - :tenant: The name of the :term:`Tenant` who owns this :term:`Origin` - :tenantId: The integral, unique identifier of the :ref:`ds-tenant` who owns this :term:`Delivery Service` - :trRequestHeaders: If defined, this defines the :ref:`ds-tr-req-headers` used by Traffic Router for this :term:`Delivery Service` - :trResponseHeaders: If defined, this defines the :ref:`ds-tr-resp-headers` used by Traffic Router for this :term:`Delivery Service` - :type: The :ref:`ds-types` of this :term:`Delivery Service` - :typeId: The integral, unique identifier of the :ref:`ds-types` of this :term:`Delivery Service` - :xmlId: This :term:`Delivery Service`'s :ref:`ds-xmlid` - -:id: The integral, unique identifier assigned to the :term:`DSR ` -:lastEditedBy: The username of user who last edited this :term:`DSR ` -:lastEditedById: The integral, unique identifier assigned to the user who last edited this :term:`DSR ` -:lastUpdated: The date and time at which the :term:`DSR ` was last updated, in :ref:`non-rfc-datetime`. -:status: The status of the request. Can be "draft", "submitted", "rejected", "pending", or "complete". - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Sun, 23 Feb 2020 15:54:53 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: C8Nhciy1jv5X7CGgHwAnLp1qmLIzHq+4dvlAApb3cFSz5V2dABl7+N1Z4ndzB7GertB7rNLP31pVcat8vEz6rA== - X-Server-Name: traffic_ops_golang/ - Date: Sun, 23 Feb 2020 14:54:53 GMT - Content-Length: 930 - - { - "alerts": [ - { - "text": "deliveryservice_request was updated.", - "level": "success" - } - ], - "response": { - "assigneeId": 2, - "assignee": "admin", - "authorId": 2, - "author": "admin", - "changeType": "update", - "createdAt": "2020-02-23 11:06:00+00", - "id": 1, - "lastEditedBy": "admin", - "lastEditedById": 2, - "lastUpdated": "2020-02-23 14:54:53+00", - "deliveryService": { - "active": true, - "anonymousBlockingEnabled": false, - "cacheurl": null, - "ccrDnsTtl": null, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "checkPath": null, - "displayName": "Demo 2", - "dnsBypassCname": null, - "dnsBypassIp": null, - "dnsBypassIp6": null, - "dnsBypassTtl": null, - "dscp": 0, - "edgeHeaderRewrite": null, - "geoLimit": 0, - "geoLimitCountries": null, - "geoLimitRedirectURL": null, - "geoProvider": 0, - "globalMaxMbps": null, - "globalMaxTps": null, - "httpBypassFqdn": null, - "id": 1, - "infoUrl": null, - "initialDispersion": 1, - "ipv6RoutingEnabled": true, - "lastUpdated": "0001-01-01 00:00:00+00", - "logsEnabled": true, - "longDesc": "Apachecon North America 2018", - "longDesc1": null, - "longDesc2": null, - "matchList": [ - { - "type": "HOST_REGEXP", - "setNumber": 0, - "pattern": ".*\\.demo1\\..*" - } - ], - "maxDnsAnswers": null, - "midHeaderRewrite": null, - "missLat": 42, - "missLong": -88, - "multiSiteOrigin": false, - "originShield": null, - "orgServerFqdn": "http://origin.infra.ciab.test", - "profileDescription": null, - "profileId": null, - "profileName": null, - "protocol": 2, - "qstringIgnore": 0, - "rangeRequestHandling": 0, - "regexRemap": null, - "regionalGeoBlocking": false, - "remapText": null, - "routingName": "video", - "signed": false, - "sslKeyVersion": null, - "tenantId": 1, - "type": "HTTP", - "typeId": 1, - "xmlId": "demo1", - "exampleURLs": [ - "http://video.demo1.mycdn.ciab.test", - "https://video.demo1.mycdn.ciab.test" - ], - "deepCachingType": "NEVER", - "fqPacingRate": null, - "signingAlgorithm": null, - "tenant": "root", - "trResponseHeaders": null, - "trRequestHeaders": null, - "consistentHashRegex": null, - "consistentHashQueryParams": [ - "abc", - "pdq", - "xxx", - "zyx" - ], - "maxOriginConnections": 0, - "ecsEnabled": false - }, - "status": "rejected" - } - } - -.. [#geoLimit] These fields must be defined if and only if ``geoLimit`` is non-zero diff --git a/docs/source/api/v2/deliveryservice_stats.rst b/docs/source/api/v2/deliveryservice_stats.rst deleted file mode 100644 index b98677afbe..0000000000 --- a/docs/source/api/v2/deliveryservice_stats.rst +++ /dev/null @@ -1,183 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservice_stats: - -************************* -``deliveryservice_stats`` -************************* - -``GET`` -======= -Retrieves time-aggregated statistics on a specific :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: None\ [#tenancy]_ -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Query Parameters - - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +=====================+===================+===========================================================================================================================================================================================+ - | deliveryService | yes\ [#ds-param]_ | Either the :ref:`ds-xmlid` of a :term:`Delivery Service` for which statistics will be aggregated or the integral, unique identifier of said :term:`Delivery Service` | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | deliveryServiceName | yes\ [#ds-param]_ | The :ref:`ds-xmlid` of the :term:`Delivery Service` for which statistics will be aggregated | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | endDate | yes | The date and time until which statistics shall be aggregated in :rfc:`3339` format (with or without sub-second precision), the number of nanoseconds since the Unix | - | | | Epoch, or in the same, proprietary format as the ``lastUpdated`` fields prevalent throughout the Traffic Ops API | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | exclude | no | Either "series" to omit the data series from the result, or "summary" to omit the summary data from the result - directly corresponds to fields in the | - | | | `Response Structure`_ | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | interval | no | Specifies the interval within which data will be "bucketed"; e.g. when requesting data from 2019-07-25T00:00:00Z to 2019-07-25T23:59:59Z with an interval of "1m", | - | | | the resulting data series (assuming it is not excluded) should contain | - | | | :math:`24\frac{\mathrm{hours}}{\mathrm{day}}\times60\frac{\mathrm{minutes}}{\mathrm{hour}}\times1\mathrm{day}\times1\frac{\mathrm{minute}}{\mathrm{data point}}=1440\mathrm{data\;points}`| - | | | The allowed values for this parameter are valid InfluxQL duration literal strings matching :regexp:`^\d+[mhdw]$` | - | | | | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | limit | no | A natural number indicating the maximum amount of data points should be returned in the ``series`` object | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | metricType | yes | The metric type being reported - one of: | - | | | | - | | | kbps | - | | | The total traffic rate in kilobytes per second served by the :term:`Delivery Service` | - | | | tps_total | - | | | The total traffic rate in transactions per second served by the :term:`Delivery Service` | - | | | tps_2xx | - | | | The total traffic rate in transactions per second serviced with 200-299 HTTP status codes | - | | | tps_3xx | - | | | The total traffic rate in transactions per second serviced with 300-399 HTTP status codes | - | | | tps_4xx | - | | | The total traffic rate in transactions per second serviced with 400-499 HTTP status codes | - | | | tps_5xx | - | | | The total traffic rate in transactions per second serviced with 500-599 HTTP status codes | - | | | | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | offset | no | A natural number of data points to drop from the beginning of the returned data set | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | orderby | no | Though one struggles to imagine why, this can be used to specify "time" to sort data points by their "time" (which is the default behavior) | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | startDate | yes | The date and time from which statistics shall be aggregated in :rfc:`3339` format (with or without sub-second precision), the number of nanoseconds since the Unix | - | | | Epoch, or in the same, proprietary format as the ``lastUpdated`` fields prevalent throughout the Traffic Ops API | - +---------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -.. _v2-deliveryservice_stats-get-request-example: -.. code-block:: http - :caption: Request Example - - GET /api/2.0/deliveryservice_stats?deliveryServiceName=demo1&startDate=2019-07-22T17:55:00Z&endDate=2019-07-22T17:56:00.000Z&metricType=tps_total HTTP/1.1 - User-Agent: python-requests/2.20.1 - Accept-Encoding: gzip, deflate - Accept: application/json;timestamp=unix, application/json;timestamp=rfc;q=0.9, application/json;q=0.8, */*;q=0.7 - Connection: keep-alive - Cookie: mojolicious=... - -Content Format -"""""""""""""" -It's important to note in :ref:`v2-deliveryservice_stats-get-request-example` the use of a complex "Accept" header. This endpoint accepts two special media types in the "Accept" header that instruct it on how to format the timestamps associated with the returned data. Specifically, Traffic Ops will recognize the special, optional, non-standard parameter of :mimetype:`application/json`: ``timestamp``. The values of this parameter are restricted to one of - -rfc - Returned timestamps will be formatted according to :rfc:`3339` (no sub-second precision). -unix - Returned timestamps will be formatted as the number of nanoseconds since the Unix Epoch (midnight on January 1\ :sup:`st` 1970 UTC). - - .. impl-detail:: The endpoint passes back nanoseconds, specifically, because that is the form used both by InfluxDB, which is used to store the data being served, and Go's standard library. Clients may need to convert the value to match their own standard libraries - e.g. the :js:class:`Date` class in Javascript expects milliseconds. - -The default behavior - when only e.g. :mimetype:`application/json` or :mimetype:`*/*` is given - is to use :rfc:`3339` formatting. It will, however, respect quality parameters. It is suggested that clients request timestamps they can handle specifically, rather than relying on this default behavior, as it **is subject to change** and is in fact **expected to invert in the next major release** as string-based time formats become deprecated. - -.. seealso:: For more information on the "Accept" HTTP header, consult `its dedicated page on MDN `_. - -Response Structure ------------------- -:series: An object containing the actual data series and information necessary for working with it. - - :columns: This is an array of names of the columns of the data contained in the "values" array - should always be ``["time", "sum_count"]`` - :count: The number of data points contained in the "values" array - :name: The name of the data set. Should always match :samp:`{metric}.ds.1min` where ``metric`` is the requested ``metricType`` - :values: The actual array of data points. Each represents a length of time specified by the ``interval`` query parameter - - :time: The time at which the measurement was taken. This corresponds to the *beginning* of the interval. This time comes in the format of either an :rfc:`3339`-formatted string, or a number containing the number of nanoseconds since the Unix Epoch depending on the "Accept" header sent by the client, according to the rules outlined in `Content Format`_. - :value: The value of the requested ``metricType`` at the time given by ``time``. This will always be a floating point number, unless no data is available for the data interval, in which case it will be ``null`` - -:summary: An object containing summary statistics describing the data series - - :average: The arithmetic mean of the data's values - :count: The number of measurements taken within the requested timespan. This is, in general, **not** the same as the ``count`` field of the ``series`` object, as it reflects the number of underlying, un-"bucketed" data points, and is therefore dependent on the implementation of Traffic Stats. - :fifthPercentile: Data points with values less than or equal to this number constitute the "bottom" 5% of the data set - :max: The maximum value that can be found in the requested data set - :min: The minimum value that can be found in the requested data set - :ninetyEighthPercentile: Data points with values greater than or equal to this number constitute the "top" 2% of the data set - :ninetyFifthPercentile: Data points with values greater than or equal to this number constitute the "top" 5% of the data set - :totalKiloBytes: When the ``metricType`` requested is ``kbps``, this will contain the total number of kilobytes transferred by the :term:`Delivery Service` within the requested time window. Note that fractional amounts are possible, as the data transfer rate will almost certainly not be cleanly divided by the requested time range. - :totalTransactions: When the ``metricType`` requested is **not** ``kbps``, this will contain the total number of transactions completed by the :term:`Delivery Service` within the requested time window. Note that fractional amounts are possible, as the transaction rate will almost certainly not be cleanly divided by the requested time range. - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-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: zXJGjcYuu6HxWINVp8HA1gL31J3ukry5wCsTDNxtP/waC6rSD8h10KJ9jEAtRzJ9owOSVPvKaA/2bRu/QeuCpQ== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 22 Jul 2019 17:57:14 GMT - Transfer-Encoding: chunked - - { "response": { - "series": { - "columns": [ - "time", - "sum_count" - ], - "count": 2, - "name": "tps_total.ds.1min", - "tags": { - "cachegroup": "total" - }, - "values": [ - [ - 1563818100000000000, - 0 - ], - [ - 1563818160000000000, - 0 - ] - ] - }, - "source": "TrafficStats", - "summary": { - "average": 0, - "count": 2, - "fifthPercentile": 0, - "max": 0, - "min": 0, - "ninetyEighthPercentile": 0, - "ninetyFifthPercentile": 0, - "totalKiloBytes": null, - "totalTransactions": 0 - }, - "version": "1.2" - }} - -.. [#tenancy] This endpoint respects :term:`Tenancy`, and users whose :term:`Tenant` does not have access to a :term:`Delivery Service` will be unable to view the statistics of said :term:`Delivery Service`. -.. [#ds-param] Either ``deliveryServiceName`` or ``deliveryService`` *must* be present, but if both are ``deliveryServiceName`` will be used and ``deliveryService`` will be ignored. diff --git a/docs/source/api/v2/deliveryservices.rst b/docs/source/api/v2/deliveryservices.rst deleted file mode 100644 index 164c018173..0000000000 --- a/docs/source/api/v2/deliveryservices.rst +++ /dev/null @@ -1,528 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices: - -******************** -``deliveryservices`` -******************** - -``GET`` -======= -Retrieves :term:`Delivery Services` - -:Auth. Required: Yes -:Roles Required: None\ [#tenancy]_ -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +--------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +==============+==========+=========================================================================================================================================+ - | cdn | no | Show only the :term:`Delivery Services` belonging to the :ref:`ds-cdn` identified by this integral, unique identifier | - +--------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | id | no | Show only the :term:`Delivery Service` that has this integral, unique identifier | - +--------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | logsEnabled | no | Show only the :term:`Delivery Services` that have :ref:`ds-logs-enabled` set or not based on this boolean | - +--------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | profile | no | Return only :term:`Delivery Services` using the :term:`Profile` that has this :ref:`profile-id` | - +--------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | tenant | no | Show only the :term:`Delivery Services` belonging to the :term:`Tenant` identified by this integral, unique identifier | - +--------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | type | no | Return only :term:`Delivery Services` of the :term:`Delivery Service` :ref:`ds-types` identified by this integral, unique identifier | - +--------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | accessibleTo | no | Return the :term:`Delivery Services` accessible from a :term:`Tenant` *or it's children* identified by this integral, unique identifier | - +--------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - | xmlId | no | Show only the :term:`Delivery Service` that has this text-based, 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``. | - +--------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------+ - -Response Structure ------------------- -:active: A boolean that defines :ref:`ds-active`. -:anonymousBlockingEnabled: A boolean that defines :ref:`ds-anonymous-blocking` -:cacheurl: A :ref:`ds-cacheurl` - - .. deprecated:: ATCv3.0 - This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later - -:ccrDnsTtl: The :ref:`ds-dns-ttl` - named "ccrDnsTtl" for legacy reasons -:cdnId: The integral, unique identifier of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs -:cdnName: Name of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs -:checkPath: A :ref:`ds-check-path` -:consistentHashRegex: A :ref:`ds-consistent-hashing-regex` -:consistentHashQueryParams: An array of :ref:`ds-consistent-hashing-qparams` -:deepCachingType: The :ref:`ds-deep-caching` setting for this :term:`Delivery Service` -:displayName: The :ref:`ds-display-name` -:dnsBypassCname: A :ref:`ds-dns-bypass-cname` -:dnsBypassIp: A :ref:`ds-dns-bypass-ip` -:dnsBypassIp6: A :ref:`ds-dns-bypass-ipv6` -:dnsBypassTtl: The :ref:`ds-dns-bypass-ttl` -:dscp: A :ref:`ds-dscp` to be used within the :term:`Delivery Service` -:ecsEnabled: A boolean that defines the :ref:`ds-ecs` setting on this :term:`Delivery Service` -:edgeHeaderRewrite: A set of :ref:`ds-edge-header-rw-rules` -:exampleURLs: An array of :ref:`ds-example-urls` -:fqPacingRate: The :ref:`ds-fqpr` -:geoLimit: An integer that defines the :ref:`ds-geo-limit` -:geoLimitCountries: A string containing a comma-separated list defining the :ref:`ds-geo-limit-countries` -:geoLimitRedirectUrl: A :ref:`ds-geo-limit-redirect-url` -:geoProvider: The :ref:`ds-geo-provider` -:globalMaxMbps: The :ref:`ds-global-max-mbps` -:globalMaxTps: The :ref:`ds-global-max-tps` -:httpBypassFqdn: A :ref:`ds-http-bypass-fqdn` -:id: An integral, unique identifier for this :term:`Delivery Service` -:infoUrl: An :ref:`ds-info-url` -:initialDispersion: The :ref:`ds-initial-dispersion` -:ipv6RoutingEnabled: A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service` -:lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in :ref:`non-rfc-datetime` -:logsEnabled: A boolean that defines the :ref:`ds-logs-enabled` setting on this :term:`Delivery Service` -:longDesc: The :ref:`ds-longdesc` of this :term:`Delivery Service` -:longDesc1: The 2nd long description of this :term:`Delivery Service` -:longDesc2: the 3rd long description of this :term:`Delivery Service` -:matchList: The :term:`Delivery Service`'s :ref:`ds-matchlist` - - :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped) - :setNumber: An integer that provides explicit ordering of :ref:`ds-matchlist` items - this is used as a priority ranking by Traffic Router, and is not guaranteed to correspond to the ordering of items in the array. - :type: The type of match performed using ``pattern``. - -:maxDnsAnswers: The :ref:`ds-max-dns-answers` allowed for this :term:`Delivery Service` -:maxOriginConnections: The :ref:`ds-max-origin-connections` -:midHeaderRewrite: A set of :ref:`ds-mid-header-rw-rules` -:missLat: The :ref:`ds-geo-miss-default-latitude` used by this :term:`Delivery Service` -:missLong: The :ref:`ds-geo-miss-default-longitude` used by this :term:`Delivery Service` -:multiSiteOrigin: A boolean that defines the use of :ref:`ds-multi-site-origin` by this :term:`Delivery Service` -:orgServerFqdn: The :ref:`ds-origin-url` -:originShield: A :ref:`ds-origin-shield` string -:profileDescription: The :ref:`profile-description` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated -:profileId: The :ref:`profile-id` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated -:profileName: The :ref:`profile-name` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated -:protocol: An integral, unique identifier that corresponds to the :ref:`ds-protocol` used by this :term:`Delivery Service` -:qstringIgnore: An integral, unique identifier that corresponds to the :ref:`ds-qstring-handling` setting on this :term:`Delivery Service` -:rangeRequestHandling: An integral, unique identifier that corresponds to the :ref:`ds-range-request-handling` setting on this :term:`Delivery Service` -:regexRemap: A :ref:`ds-regex-remap` -:regionalGeoBlocking: A boolean defining the :ref:`ds-regionalgeo` setting on this :term:`Delivery Service` -:remapText: :ref:`ds-raw-remap` -:signed: ``true`` if and only if ``signingAlgorithm`` is not ``null``, ``false`` otherwise -:signingAlgorithm: Either a :ref:`ds-signing-algorithm` or ``null`` to indicate URL/URI signing is not implemented on this :term:`Delivery Service` -:rangeSliceBlockSize: An integer that defines the byte block size for the ATS Slice Plugin. It can only and must be set if ``rangeRequestHandling`` is set to 3. -:sslKeyVersion: This integer indicates the :ref:`ds-ssl-key-version` -:tenantId: The integral, unique identifier of the :ref:`ds-tenant` who owns this :term:`Delivery Service` -:trRequestHeaders: If defined, this defines the :ref:`ds-tr-req-headers` used by Traffic Router for this :term:`Delivery Service` -:trResponseHeaders: If defined, this defines the :ref:`ds-tr-resp-headers` used by Traffic Router for this :term:`Delivery Service` -:type: The :ref:`ds-types` of this :term:`Delivery Service` -:typeId: The integral, unique identifier of the :ref:`ds-types` of this :term:`Delivery Service` -:xmlId: This :term:`Delivery Service`'s :ref:`ds-xmlid` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: mCLMjvACRKHNGP/OSx4javkOtxxzyiDdQzsV78IamUhVmvyKyKaCeOKRmpsG69w+nhh3OkPZ6e9MMeJpcJSKcA== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 15 Nov 2018 19:04:29 GMT - Transfer-Encoding: chunked - - { "response": [{ - "active": true, - "anonymousBlockingEnabled": false, - "cacheurl": null, - "ccrDnsTtl": null, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "checkPath": null, - "displayName": "Demo 1", - "dnsBypassCname": null, - "dnsBypassIp": null, - "dnsBypassIp6": null, - "dnsBypassTtl": null, - "dscp": 0, - "edgeHeaderRewrite": null, - "geoLimit": 0, - "geoLimitCountries": null, - "geoLimitRedirectURL": null, - "geoProvider": 0, - "globalMaxMbps": null, - "globalMaxTps": null, - "httpBypassFqdn": null, - "id": 1, - "infoUrl": null, - "initialDispersion": 1, - "ipv6RoutingEnabled": true, - "lastUpdated": "2019-05-15 14:32:05+00", - "logsEnabled": true, - "longDesc": "Apachecon North America 2018", - "longDesc1": null, - "longDesc2": null, - "matchList": [ - { - "type": "HOST_REGEXP", - "setNumber": 0, - "pattern": ".*\\.demo1\\..*" - } - ], - "maxDnsAnswers": null, - "midHeaderRewrite": null, - "missLat": 42, - "missLong": -88, - "multiSiteOrigin": false, - "originShield": null, - "orgServerFqdn": "http://origin.infra.ciab.test", - "profileDescription": null, - "profileId": null, - "profileName": null, - "protocol": 2, - "qstringIgnore": 0, - "rangeRequestHandling": 0, - "regexRemap": null, - "regionalGeoBlocking": false, - "remapText": null, - "routingName": "video", - "signed": false, - "sslKeyVersion": null, - "tenantId": 1, - "type": "HTTP", - "typeId": 1, - "xmlId": "demo1", - "exampleURLs": [ - "http://video.demo1.mycdn.ciab.test", - "https://video.demo1.mycdn.ciab.test" - ], - "deepCachingType": "NEVER", - "fqPacingRate": null, - "signingAlgorithm": null, - "tenant": "root", - "trResponseHeaders": null, - "trRequestHeaders": null, - "consistentHashRegex": null, - "consistentHashQueryParams": [ - "abc", - "pdq", - "xxx", - "zyx" - ], - "maxOriginConnections": 0, - "ecsEnabled": false, - "rangeSliceBlockSize": null - }]} - - -``POST`` -======== -Allows users to create :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations"\ [#tenancy]_ -:Response Type: Array - -Request Structure ------------------ -:active: A boolean that defines :ref:`ds-active`. -:anonymousBlockingEnabled: A boolean that defines :ref:`ds-anonymous-blocking` -:cacheurl: A :ref:`ds-cacheurl` - - .. deprecated:: ATCv3.0 - This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later - -:ccrDnsTtl: The :ref:`ds-dns-ttl` - named "ccrDnsTtl" for legacy reasons -:cdnId: The integral, unique identifier of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs -:checkPath: A :ref:`ds-check-path` -:consistentHashRegex: A :ref:`ds-consistent-hashing-regex` -:consistentHashQueryParams: An array of :ref:`ds-consistent-hashing-qparams` -:deepCachingType: The :ref:`ds-deep-caching` setting for this :term:`Delivery Service` -:displayName: The :ref:`ds-display-name` -:dnsBypassCname: A :ref:`ds-dns-bypass-cname` -:dnsBypassIp: A :ref:`ds-dns-bypass-ip` -:dnsBypassIp6: A :ref:`ds-dns-bypass-ipv6` -:dnsBypassTtl: The :ref:`ds-dns-bypass-ttl` -:dscp: A :ref:`ds-dscp` to be used within the :term:`Delivery Service` -:ecsEnabled: A boolean that defines the :ref:`ds-ecs` setting on this :term:`Delivery Service` -:edgeHeaderRewrite: A set of :ref:`ds-edge-header-rw-rules` -:fqPacingRate: The :ref:`ds-fqpr` -:geoLimit: An integer that defines the :ref:`ds-geo-limit` -:geoLimitCountries: A string containing a comma-separated list defining the :ref:`ds-geo-limit-countries`\ [#geolimit]_ -:geoLimitRedirectUrl: A :ref:`ds-geo-limit-redirect-url`\ [#geolimit]_ -:geoProvider: The :ref:`ds-geo-provider` -:globalMaxMbps: The :ref:`ds-global-max-mbps` -:globalMaxTps: The :ref:`ds-global-max-tps` -:httpBypassFqdn: A :ref:`ds-http-bypass-fqdn` -:infoUrl: An :ref:`ds-info-url` -:initialDispersion: The :ref:`ds-initial-dispersion` -:ipv6RoutingEnabled: A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service` -:logsEnabled: A boolean that defines the :ref:`ds-logs-enabled` setting on this :term:`Delivery Service` -:longDesc: The :ref:`ds-longdesc` of this :term:`Delivery Service` -:longDesc1: An optional field containing the 2nd long description of this :term:`Delivery Service` -:longDesc2: An optional field containing the 3rd long description of this :term:`Delivery Service` -:maxDnsAnswers: The :ref:`ds-max-dns-answers` allowed for this :term:`Delivery Service` -:maxOriginConnections: The :ref:`ds-max-origin-connections` -:midHeaderRewrite: A set of :ref:`ds-mid-header-rw-rules` -:missLat: The :ref:`ds-geo-miss-default-latitude` used by this :term:`Delivery Service` -:missLong: The :ref:`ds-geo-miss-default-longitude` used by this :term:`Delivery Service` -:multiSiteOrigin: A boolean that defines the use of :ref:`ds-multi-site-origin` by this :term:`Delivery Service` -:orgServerFqdn: The :ref:`ds-origin-url` -:originShield: A :ref:`ds-origin-shield` string -:profileId: An optional :ref:`profile-id` of a :ref:`ds-profile` with which this :term:`Delivery Service` shall be associated -:protocol: An integral, unique identifier that corresponds to the :ref:`ds-protocol` used by this :term:`Delivery Service` -:qstringIgnore: An integral, unique identifier that corresponds to the :ref:`ds-qstring-handling` setting on this :term:`Delivery Service` -:rangeRequestHandling: An integral, unique identifier that corresponds to the :ref:`ds-range-request-handling` setting on this :term:`Delivery Service` -:regexRemap: A :ref:`ds-regex-remap` -:regionalGeoBlocking: A boolean defining the :ref:`ds-regionalgeo` setting on this :term:`Delivery Service` -:remapText: :ref:`ds-raw-remap` -:signed: ``true`` if and only if ``signingAlgorithm`` is not ``null``, ``false`` otherwise -:signingAlgorithm: Either a :ref:`ds-signing-algorithm` or ``null`` to indicate URL/URI signing is not implemented on this :term:`Delivery Service` -:rangeSliceBlockSize: An integer that defines the byte block size for the ATS Slice Plugin. It can only and must be set if ``rangeRequestHandling`` is set to 3. It can only be between (inclusive) 262144 (256KB) - 33554432 (32MB). -:sslKeyVersion: This integer indicates the :ref:`ds-ssl-key-version` -:tenantId: The integral, unique identifier of the :ref:`ds-tenant` who owns this :term:`Delivery Service` -:trRequestHeaders: If defined, this defines the :ref:`ds-tr-req-headers` used by Traffic Router for this :term:`Delivery Service` -:trResponseHeaders: If defined, this defines the :ref:`ds-tr-resp-headers` used by Traffic Router for this :term:`Delivery Service` -:type: The :ref:`ds-types` of this :term:`Delivery Service` -:typeId: The integral, unique identifier of the :ref:`ds-types` of this :term:`Delivery Service` -:xmlId: This :term:`Delivery Service`'s :ref:`ds-xmlid` - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/deliveryservices HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 761 - Content-Type: application/json - - { - "active": false, - "anonymousBlockingEnabled": false, - "cdnId": 2, - "deepCachingType": "NEVER", - "displayName": "test", - "dscp": 0, - "ecsEnabled": true, - "geoLimit": 0, - "geoProvider": 0, - "initialDispersion": 1, - "ipv6RoutingEnabled": false, - "logsEnabled": true, - "longDesc": "A Delivery Service created expressly for API documentation examples", - "missLat": 0, - "missLong": 0, - "maxOriginConnections": 0, - "multiSiteOrigin": false, - "orgServerFqdn": "http://origin.infra.ciab.test", - "protocol": 0, - "qstringIgnore": 0, - "rangeRequestHandling": 0, - "regionalGeoBlocking": false, - "routingName": "test", - "signed": false, - "tenant": "root", - "tenantId": 1, - "typeId": 1, - "xmlId": "test" - } - - -Response Structure ------------------- -:active: A boolean that defines :ref:`ds-active`. -:anonymousBlockingEnabled: A boolean that defines :ref:`ds-anonymous-blocking` -:cacheurl: A :ref:`ds-cacheurl` - - .. deprecated:: ATCv3.0 - This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later - -:ccrDnsTtl: The :ref:`ds-dns-ttl` - named "ccrDnsTtl" for legacy reasons -:cdnId: The integral, unique identifier of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs -:cdnName: Name of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs -:checkPath: A :ref:`ds-check-path` -:consistentHashRegex: A :ref:`ds-consistent-hashing-regex` -:consistentHashQueryParams: An array of :ref:`ds-consistent-hashing-qparams` -:deepCachingType: The :ref:`ds-deep-caching` setting for this :term:`Delivery Service` -:displayName: The :ref:`ds-display-name` -:dnsBypassCname: A :ref:`ds-dns-bypass-cname` -:dnsBypassIp: A :ref:`ds-dns-bypass-ip` -:dnsBypassIp6: A :ref:`ds-dns-bypass-ipv6` -:dnsBypassTtl: The :ref:`ds-dns-bypass-ttl` -:dscp: A :ref:`ds-dscp` to be used within the :term:`Delivery Service` -:ecsEnabled: A boolean that defines the :ref:`ds-ecs` setting on this :term:`Delivery Service` -:edgeHeaderRewrite: A set of :ref:`ds-edge-header-rw-rules` -:exampleURLs: An array of :ref:`ds-example-urls` -:fqPacingRate: The :ref:`ds-fqpr` -:geoLimit: An integer that defines the :ref:`ds-geo-limit` -:geoLimitCountries: A string containing a comma-separated list defining the :ref:`ds-geo-limit-countries` -:geoLimitRedirectUrl: A :ref:`ds-geo-limit-redirect-url` -:geoProvider: The :ref:`ds-geo-provider` -:globalMaxMbps: The :ref:`ds-global-max-mbps` -:globalMaxTps: The :ref:`ds-global-max-tps` -:httpBypassFqdn: A :ref:`ds-http-bypass-fqdn` -:id: An integral, unique identifier for this :term:`Delivery Service` -:infoUrl: An :ref:`ds-info-url` -:initialDispersion: The :ref:`ds-initial-dispersion` -:ipv6RoutingEnabled: A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service` -:lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in :ref:`non-rfc-datetime` -:logsEnabled: A boolean that defines the :ref:`ds-logs-enabled` setting on this :term:`Delivery Service` -:longDesc: The :ref:`ds-longdesc` of this :term:`Delivery Service` -:longDesc1: The 2nd long description of this :term:`Delivery Service` -:longDesc2: the 3rd long description of this :term:`Delivery Service` -:matchList: The :term:`Delivery Service`'s :ref:`ds-matchlist` - - :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped) - :setNumber: An integer that provides explicit ordering of :ref:`ds-matchlist` items - this is used as a priority ranking by Traffic Router, and is not guaranteed to correspond to the ordering of items in the array. - :type: The type of match performed using ``pattern``. - -:maxDnsAnswers: The :ref:`ds-max-dns-answers` allowed for this :term:`Delivery Service` -:maxOriginConnections: The :ref:`ds-max-origin-connections` -:midHeaderRewrite: A set of :ref:`ds-mid-header-rw-rules` -:missLat: The :ref:`ds-geo-miss-default-latitude` used by this :term:`Delivery Service` -:missLong: The :ref:`ds-geo-miss-default-longitude` used by this :term:`Delivery Service` -:multiSiteOrigin: A boolean that defines the use of :ref:`ds-multi-site-origin` by this :term:`Delivery Service` -:orgServerFqdn: The :ref:`ds-origin-url` -:originShield: A :ref:`ds-origin-shield` string -:profileDescription: The :ref:`profile-description` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated -:profileId: The :ref:`profile-id` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated -:profileName: The :ref:`profile-name` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated -:protocol: An integral, unique identifier that corresponds to the :ref:`ds-protocol` used by this :term:`Delivery Service` -:qstringIgnore: An integral, unique identifier that corresponds to the :ref:`ds-qstring-handling` setting on this :term:`Delivery Service` -:rangeRequestHandling: An integral, unique identifier that corresponds to the :ref:`ds-range-request-handling` setting on this :term:`Delivery Service` -:regexRemap: A :ref:`ds-regex-remap` -:regionalGeoBlocking: A boolean defining the :ref:`ds-regionalgeo` setting on this :term:`Delivery Service` -:remapText: :ref:`ds-raw-remap` -:signed: ``true`` if and only if ``signingAlgorithm`` is not ``null``, ``false`` otherwise -:signingAlgorithm: Either a :ref:`ds-signing-algorithm` or ``null`` to indicate URL/URI signing is not implemented on this :term:`Delivery Service` -:rangeSliceBlockSize: An integer that defines the byte block size for the ATS Slice Plugin. It can only and must be set if ``rangeRequestHandling`` is set to 3. -:sslKeyVersion: This integer indicates the :ref:`ds-ssl-key-version` -:tenantId: The integral, unique identifier of the :ref:`ds-tenant` who owns this :term:`Delivery Service` -:trRequestHeaders: If defined, this defines the :ref:`ds-tr-req-headers` used by Traffic Router for this :term:`Delivery Service` -:trResponseHeaders: If defined, this defines the :ref:`ds-tr-resp-headers` used by Traffic Router for this :term:`Delivery Service` -:type: The :ref:`ds-types` of this :term:`Delivery Service` -:typeId: The integral, unique identifier of the :ref:`ds-types` of this :term:`Delivery Service` -:xmlId: This :term:`Delivery Service`'s :ref:`ds-xmlid` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: SVveQ5hGwfPv8N5APUskwLOzwrTUVA+z8wuFLsSLCr1/vVnFJJ0VQOGMUctg1NbqhAuQ795MJmuuAaAwR8dSOQ== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 19 Nov 2018 19:45:49 GMT - Content-Length: 1404 - - { "alerts": [ - { - "text": "Deliveryservice creation was successful.", - "level": "success" - } - ], - "response": [ - { - "active": false, - "anonymousBlockingEnabled": false, - "cacheurl": null, - "ccrDnsTtl": null, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "checkPath": null, - "displayName": "test", - "dnsBypassCname": null, - "dnsBypassIp": null, - "dnsBypassIp6": null, - "dnsBypassTtl": null, - "dscp": 0, - "edgeHeaderRewrite": null, - "geoLimit": 0, - "geoLimitCountries": null, - "geoLimitRedirectURL": null, - "geoProvider": 0, - "globalMaxMbps": null, - "globalMaxTps": null, - "httpBypassFqdn": null, - "id": 2, - "infoUrl": null, - "initialDispersion": 1, - "ipv6RoutingEnabled": false, - "lastUpdated": "2018-11-19 19:45:49+00", - "logsEnabled": true, - "longDesc": "A Delivery Service created expressly for API documentation examples", - "longDesc1": null, - "longDesc2": null, - "matchList": [ - { - "type": "HOST_REGEXP", - "setNumber": 0, - "pattern": ".*\\.test\\..*" - } - ], - "maxDnsAnswers": null, - "maxOriginConnections": 0, - "midHeaderRewrite": null, - "missLat": -1, - "missLong": -1, - "multiSiteOrigin": false, - "originShield": null, - "orgServerFqdn": "http://origin.infra.ciab.test", - "profileDescription": null, - "profileId": null, - "profileName": null, - "protocol": 0, - "qstringIgnore": 0, - "rangeRequestHandling": 0, - "regexRemap": null, - "regionalGeoBlocking": false, - "remapText": null, - "routingName": "test", - "signed": false, - "sslKeyVersion": null, - "tenantId": 1, - "type": "HTTP", - "typeId": 1, - "xmlId": "test", - "exampleURLs": [ - "http://test.test.mycdn.ciab.test" - ], - "deepCachingType": "NEVER", - "signingAlgorithm": null, - "tenant": "root", - "ecsEnabled": true, - "rangeSliceBlockSize": null - } - ]} - -.. [#tenancy] Only those :term:`Delivery Services` assigned to :term:`Tenants` that are the requesting user's :term:`Tenant` or children thereof will appear in the output of a ``GET`` request, and the same constraints are placed on the allowed values of the ``tenantId`` field of a ``POST`` request to create a new :term:`Delivery Service` -.. [#geoLimit] These fields must be defined if and only if ``geoLimit`` is non-zero diff --git a/docs/source/api/v2/deliveryservices_id.rst b/docs/source/api/v2/deliveryservices_id.rst deleted file mode 100644 index f21595e9f1..0000000000 --- a/docs/source/api/v2/deliveryservices_id.rst +++ /dev/null @@ -1,213 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-id: - -*************************** -``deliveryservices/{{ID}}`` -*************************** - -``PUT`` -======= -Allows users to edit an existing :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations"\ [#tenancy]_ -:Response Type: **NOT PRESENT** - Despite returning a ``200 OK`` response (rather than e.g. a ``204 NO CONTENT`` response), this endpoint does **not** return a representation of the modified resource in its payload, and instead returns nothing - not even a success message. - -Request Structure ------------------ -:active: A boolean that defines :ref:`ds-active`. -:anonymousBlockingEnabled: A boolean that defines :ref:`ds-anonymous-blocking` -:cacheurl: A :ref:`ds-cacheurl` - - .. deprecated:: ATCv3.0 - This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later - -:ccrDnsTtl: The :ref:`ds-dns-ttl` - named "ccrDnsTtl" for legacy reasons -:cdnId: The integral, unique identifier of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs -:checkPath: A :ref:`ds-check-path` -:consistentHashRegex: A :ref:`ds-consistent-hashing-regex` -:consistentHashQueryParams: An array of :ref:`ds-consistent-hashing-qparams` -:deepCachingType: The :ref:`ds-deep-caching` setting for this :term:`Delivery Service` -:displayName: The :ref:`ds-display-name` -:dnsBypassCname: A :ref:`ds-dns-bypass-cname` -:dnsBypassIp: A :ref:`ds-dns-bypass-ip` -:dnsBypassIp6: A :ref:`ds-dns-bypass-ipv6` -:dnsBypassTtl: The :ref:`ds-dns-bypass-ttl` -:dscp: A :ref:`ds-dscp` to be used within the :term:`Delivery Service` -:ecsEnabled: A boolean that defines the :ref:`ds-ecs` setting on this :term:`Delivery Service` -:edgeHeaderRewrite: A set of :ref:`ds-edge-header-rw-rules` -:fqPacingRate: The :ref:`ds-fqpr` -:geoLimit: An integer that defines the :ref:`ds-geo-limit` -:geoLimitCountries: A string containing a comma-separated list defining the :ref:`ds-geo-limit-countries`\ [#geolimit]_ -:geoLimitRedirectUrl: A :ref:`ds-geo-limit-redirect-url`\ [#geolimit]_ -:geoProvider: The :ref:`ds-geo-provider` -:globalMaxMbps: The :ref:`ds-global-max-mbps` -:globalMaxTps: The :ref:`ds-global-max-tps` -:httpBypassFqdn: A :ref:`ds-http-bypass-fqdn` -:infoUrl: An :ref:`ds-info-url` -:initialDispersion: The :ref:`ds-initial-dispersion` -:ipv6RoutingEnabled: A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service` -:logsEnabled: A boolean that defines the :ref:`ds-logs-enabled` setting on this :term:`Delivery Service` -:longDesc: The :ref:`ds-longdesc` of this :term:`Delivery Service` -:longDesc1: An optional field containing the 2nd long description of this :term:`Delivery Service` -:longDesc2: An optional field containing the 3rd long description of this :term:`Delivery Service` -:maxDnsAnswers: The :ref:`ds-max-dns-answers` allowed for this :term:`Delivery Service` -:maxOriginConnections: The :ref:`ds-max-origin-connections` -:midHeaderRewrite: A set of :ref:`ds-mid-header-rw-rules` -:missLat: The :ref:`ds-geo-miss-default-latitude` used by this :term:`Delivery Service` -:missLong: The :ref:`ds-geo-miss-default-longitude` used by this :term:`Delivery Service` -:multiSiteOrigin: A boolean that defines the use of :ref:`ds-multi-site-origin` by this :term:`Delivery Service` -:orgServerFqdn: The :ref:`ds-origin-url` -:originShield: A :ref:`ds-origin-shield` string -:profileId: An optional :ref:`profile-id` of the :ref:`ds-profile` with which this :term:`Delivery Service` will be associated -:protocol: An integral, unique identifier that corresponds to the :ref:`ds-protocol` used by this :term:`Delivery Service` -:qstringIgnore: An integral, unique identifier that corresponds to the :ref:`ds-qstring-handling` setting on this :term:`Delivery Service` -:rangeRequestHandling: An integral, unique identifier that corresponds to the :ref:`ds-range-request-handling` setting on this :term:`Delivery Service` -:regexRemap: A :ref:`ds-regex-remap` -:regionalGeoBlocking: A boolean defining the :ref:`ds-regionalgeo` setting on this :term:`Delivery Service` -:remapText: :ref:`ds-raw-remap` -:routingName: The :ref:`ds-routing-name` of this :term:`Delivery Service` -:signed: ``true`` if and only if ``signingAlgorithm`` is not ``null``, ``false`` otherwise -:signingAlgorithm: Either a :ref:`ds-signing-algorithm` or ``null`` to indicate URL/URI signing is not implemented on this :term:`Delivery Service` -:rangeSliceBlockSize: An integer that defines the byte block size for the ATS Slice Plugin. It can only and must be set if ``rangeRequestHandling`` is set to 3. It can only be between (inclusive) 262144 (256KB) - 33554432 (32MB). -:sslKeyVersion: This integer indicates the :ref:`ds-ssl-key-version` -:tenantId: The integral, unique identifier of the :ref:`ds-tenant` who owns this :term:`Delivery Service` -:trRequestHeaders: If defined, this defines the :ref:`ds-tr-req-headers` used by Traffic Router for this :term:`Delivery Service` -:trResponseHeaders: If defined, this defines the :ref:`ds-tr-resp-headers` used by Traffic Router for this :term:`Delivery Service` -:typeId: The integral, unique identifier of the :ref:`ds-types` of this :term:`Delivery Service` -:xmlId: This :term:`Delivery Service`'s :ref:`ds-xmlid` - - .. note:: While this field **must** be present, it is **not** allowed to change; this must be the same as the ``xml_id`` the :term:`Delivery Service` already has. This should almost never be different from the :term:`Delivery Service`'s ``displayName``. - - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/deliveryservices/1 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 761 - Content-Type: application/json - - { - "active": true, - "anonymousBlockingEnabled": false, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "deepCachingType": "NEVER", - "displayName": "demo", - "dscp": 0, - "ecsEnabled": true, - "geoLimit": 0, - "geoProvider": 0, - "initialDispersion": 1, - "ipv6RoutingEnabled": false, - "lastUpdated": "2018-11-14 18:21:17+00", - "logsEnabled": true, - "longDesc": "A Delivery Service created expressly for API documentation examples", - "missLat": -1, - "missLong": -1, - "multiSiteOrigin": false, - "orgServerFqdn": "http://origin.infra.ciab.test", - "protocol": 0, - "qstringIgnore": 0, - "rangeRequestHandling": 0, - "regionalGeoBlocking": false, - "routingName": "video", - "signed": false, - "tenant": "root", - "tenantId": 1, - "typeId": 1, - "xmlId": "demo1" - } - - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: z4PhNX7vuL3xVChQ1m2AB9Yg5AULVxXcg/SpIdNs6c5H0NE8XYXysP+DGNKHfuwvY7kxvUdBeoGlODJ6+SfaPg== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 20 Nov 2018 14:12:25 GMT - Content-Length: 0 - Content-Type: text/plain; charset=utf-8 - - -``DELETE`` -========== -Deletes the target :term:`Delivery Service` - -:Auth. Required: Yes -:Roles Required: "admin" or "operations"\ [#tenancy]_ -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-------------------------------------------------------------------------------+ - | Name | Description | - +======+===============================================================================+ - | ID | The integral, unique identifier of the :term:`Delivery Service` to be deleted | - +------+-------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/deliveryservices/2 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: w9NlQpJJEl56r6iYq/fk8o5WfAXeUS5XR9yDHvKUgPO8lYEo8YyftaSF0MPFseeOk60dk6kQo+MLYTDIAhhRxw== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 20 Nov 2018 14:56:37 GMT - Content-Length: 57 - - { "alerts": [ - { - "text": "ds was deleted.", - "level": "success" - } - ]} - - -.. [#tenancy] Only those :term:`Delivery Services` assigned to :term:`Tenants` that are the requesting user's :term:`Tenant` or children thereof will appear in the output of a ``GET`` request, and the same constraints are placed on the allowed values of the ``tenantId`` field of a ``PUT`` request to update a new :term:`Delivery Service`. Furthermore, the only :term:`Delivery Services` a user may delete are those assigned to a :term:`Tenant` that is either the same :term:`Tenant` as the user's :term:`Tenant`, or a descendant thereof. -.. [#geoLimit] These fields must be defined if and only if ``geoLimit`` is non-zero diff --git a/docs/source/api/v2/deliveryservices_id_capacity.rst b/docs/source/api/v2/deliveryservices_id_capacity.rst deleted file mode 100644 index b9f65927ff..0000000000 --- a/docs/source/api/v2/deliveryservices_id_capacity.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-id-capacity: - -************************************ -``deliveryservices/{{ID}}/capacity`` -************************************ - -.. seealso:: :ref:`health-proto` - -``GET`` -======= -Retrieves the usage percentages of a servers associated with a :term:`Delivery Service` - -:Auth. Required: Yes -:Roles Required: None\ [#tenancy]_ -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+------------------------------------------------------------------------------+ - | Name | Description | - +======+==============================================================================+ - | ID | The integral, unique identifier for the :term:`Delivery Service` of interest | - +------+------------------------------------------------------------------------------+ - -Response Structure ------------------- -:availablePercent: The percent of servers assigned to this :term:`Delivery Service` that is available - the allowed traffic level in terms of data per time period for all :term:`cache servers` that remains unused -:unavailablePercent: The percent of servers assigned to this :term:`Delivery Service` that is unavailable - the allowed traffic level in terms of data per time period for all :term:`cache servers` that can't be used because the servers are deemed unhealthy -:utilizedPercent: The percent of servers assigned to this :term:`Delivery Service` that is currently in use - the allowed traffic level in terms of data per time period that is currently devoted to servicing requests -:maintenancePercent: The percent of servers assigned to this :term:`Delivery Service` that is unavailable due to server maintenance - the allowed traffic level in terms of data per time period that is unavailable because servers have intentionally been marked offline by administrators - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Thu, 15 Nov 2018 14:41:27 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: ++dFR9V1c60CHGNwMjX6JSFEjHreXcL4QnhTO3hiv04ByY379aLpL4OrOzX2bPgJgpR94+f6jZ0+iDIyTMwtFQ== - Content-Length: 134 - - { "response": { - "availablePercent": 99.9993696969697, - "unavailablePercent": 0, - "utilizedPercent": 0.00063030303030303, - "maintenancePercent": 0 - }} - -.. [#tenancy] Users will only be able to see capacity details for the :term:`Delivery Services` their :term:`Tenant` is allowed to see. diff --git a/docs/source/api/v2/deliveryservices_id_health.rst b/docs/source/api/v2/deliveryservices_id_health.rst deleted file mode 100644 index dd0405bc71..0000000000 --- a/docs/source/api/v2/deliveryservices_id_health.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-id-health: - -********************************** -``deliveryservices/{{ID}}/health`` -********************************** - -.. seealso:: :ref:`health-proto` - -``GET`` -======= -Retrieves the health of all :term:`Cache Groups` assigned to a particular :term:`Delivery Service` - -:Auth. Required: Yes -:Roles Required: None\ [#tenancy]_ -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+------------------------------------------------------------------------------------------------------------+ - | Name | Description | - +======+============================================================================================================+ - | ID | The integral, unique identifier of the Delivery service for which :term:`Cache Groups` will be displayed | - +------+------------------------------------------------------------------------------------------------------------+ - - -Response Structure ------------------- -:cachegroups: An array of objects that represent the health of each :term:`Cache Group` assigned to this :term:`Delivery Service` - - :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` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Thu, 15 Nov 2018 14:43:43 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: KpXViXeAgch58ueQqdyU8NuINBw1EUedE6Rv2ewcLUajJp6kowdbVynpwW7XiSvAyHdtClIOuT3OkhIimghzSA== - Content-Length: 115 - - { "response": { - "totalOffline": 0, - "totalOnline": 1, - "cachegroups": [ - { - "offline": 0, - "name": "CDN_in_a_Box_Edge", - "online": 1 - } - ] - }} - -.. [#tenancy] Users will only be able to see :term:`Cache Group` health details for the :term:`Delivery Services` their :term:`Tenant` is allowed to see. diff --git a/docs/source/api/v2/deliveryservices_id_regexes.rst b/docs/source/api/v2/deliveryservices_id_regexes.rst deleted file mode 100644 index 6ed7b67e79..0000000000 --- a/docs/source/api/v2/deliveryservices_id_regexes.rst +++ /dev/null @@ -1,178 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-id-regexes: - -*********************************** -``deliveryservices/{{ID}}/regexes`` -*********************************** - -``GET`` -======= -Retrieves routing regular expressions for a specific :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: None\ [#tenancy]_ -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------------------------------------------+ - | Name | Description | - +======+=================================================================================+ - | ID | The integral, unique identifier of the :term:`Delivery Service` being inspected | - +------+---------------------------------------------------------------------------------+ - -.. table:: Request Query Parameters - - +-------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +=============+==========+======================================================================================================================================+ - | id | no | Show only the :term:`Delivery Service` regular expression that has this integral, unique identifier | - +-------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/deliveryservices/1/regexes HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:id: The integral, unique identifier of this regular expression -:pattern: The actual regular expression - ``\``\ s are escaped -:setNumber: The order in which the regular expression is evaluated against requests -:type: The integral, unique identifier of the :term:`Type` of this regular expression -:typeName: The :term:`Type` of regular expression - determines that against which it will be evaluated - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: fW9Fde4WRpp2ShRAC41P9s/PhU71LI/SEzHgYjGqfzhk45wq0kpaWy76JvPfLpowY8eDTp8Y8TL5rNGEc+bM+A== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 27 Nov 2018 20:56:43 GMT - Content-Length: 100 - - { "response": [ - { - "id": 1, - "type": 31, - "typeName": "HOST_REGEXP", - "setNumber": 0, - "pattern": ".*\\.demo1\\..*" - } - ]} - - -``POST`` -======== -Creates a routing regular expression for a :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations"\ [#tenancy]_ -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------------------------------------------+ - | Name | Description | - +======+=================================================================================+ - | ID | The integral, unique identifier of the :term:`Delivery Service` being inspected | - +------+---------------------------------------------------------------------------------+ - -:pattern: The actual regular expression - - .. warning:: Be sure that ``\``\ s are escaped, or the expression may not work as intended! - -:setNumber: The order in which this regular expression should be checked -:type: The integral, unique identifier of a routing regular expression type - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/deliveryservices/1/regexes HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 55 - Content-Type: application/json - - { - "pattern": ".*\\.foo-bar\\..*", - "type": 31, - "setNumber": 1 - } - -Response Structure ------------------- -:id: The integral, unique identifier of this regular expression -:pattern: The actual regular expression - ``\``\ s are escaped -:setNumber: The order in which the regular expression is evaluated against requests -:type: The integral, unique identifier of the type of this regular expression -:typeName: The type of regular expression - determines that against which it will be evaluated - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: kS5dRzAhFKE7vfzHK7XVIwpMOjztksk9MU+qtj5YU/1oxVHmqNbJ12FeOOIJsZJCXbYlnBS04sCI95Sz5wed1Q== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 28 Nov 2018 17:00:42 GMT - Content-Length: 188 - - { "alerts": [ - { - "text": "Delivery service regex creation was successful.", - "level": "success" - } - ], - "response": { - "id": 2, - "type": 31, - "typeName": "HOST_REGEXP", - "setNumber": 1, - "pattern": ".*\\.foo-bar\\..*" - }} - - -.. [#tenancy] Users will only be able to view and create regular expressions for the :term:`Delivery Services` their :term:`Tenant` is allowed to see. diff --git a/docs/source/api/v2/deliveryservices_id_regexes_rid.rst b/docs/source/api/v2/deliveryservices_id_regexes_rid.rst deleted file mode 100644 index 0ceee86501..0000000000 --- a/docs/source/api/v2/deliveryservices_id_regexes_rid.rst +++ /dev/null @@ -1,158 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-id-regexes-rid: - -******************************************* -``deliveryservices/{{ID}}/regexes/{{rID}}`` -******************************************* - -``PUT`` -======= -Updates a routing regular expression. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations"\ [#tenancy]_ -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-----------------------------------------------------------------------------------+ - | Name | Description | - +======+===================================================================================+ - | ID | The integral, unique identifier of the :term:`Delivery Service` being inspected | - +------+-----------------------------------------------------------------------------------+ - | rID | The integral, unique identifier of the routing regular expression being inspected | - +------+-----------------------------------------------------------------------------------+ - -:pattern: The actual regular expression - - .. warning:: Be sure that ``\``\ s are escaped, or the expression may not work as intended! - -:setNumber: The order in which this regular expression should be checked -:type: The integral, unique identifier of a routing regular expression type - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/deliveryservices/1/regexes/2 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 55 - Content-Type: application/json - - { - "pattern": ".*\\.foo-bar\\..*", - "type": 33, - "setNumber": 1 - } - -Response Structure ------------------- -:id: The integral, unique identifier of this regular expression -:pattern: The actual regular expression - ``\``\ s are escaped -:setNumber: The order in which the regular expression is evaluated against requests -:type: The integral, unique identifier of the type of this regular expression -:typeName: The type of regular expression - determines that against which it will be evaluated - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: kS5dRzAhFKE7vfzHK7XVIwpMOjztksk9MU+qtj5YU/1oxVHmqNbJ12FeOOIJsZJCXbYlnBS04sCI95Sz5wed1Q== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 29 Nov 2018 17:54:58 GMT - Content-Length: 188 - - { "alerts": [ - { - "text": "Delivery service regex creation was successful.", - "level": "success" - } - ], - "response": { - "id": 2, - "type": 33, - "typeName": "PATH_REGEXP", - "setNumber": 1, - "pattern": ".*\\.foo-bar\\..*" - }} - - - -``DELETE`` -========== -Deletes a routing regular expression. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations"\ [#tenancy]_ -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-----------------------------------------------------------------------------------+ - | Name | Description | - +======+===================================================================================+ - | ID | The integral, unique identifier of the :term:`Delivery Service` being inspected | - +------+-----------------------------------------------------------------------------------+ - | rID | The integral, unique identifier of the routing regular expression being inspected | - +------+-----------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/deliveryservices/1/regexes/2 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 8oEa78x7f/o39LIS98W6G+UqE6cX/Iw4v3mMHvbAs1iWHALuDYRz3VOtA6jzfGQKpB04Om8qaVG+zWRrBVoCmQ== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 29 Nov 2018 18:44:00 GMT - Content-Length: 76 - - { "alerts": [ - { - "text": "deliveryservice_regex was deleted.", - "level": "success" - } - ]} - -.. [#tenancy] Users will only be able to view, delete and update regular expressions for the :term:`Delivery Services` their :term:`Tenant` is allowed to see. diff --git a/docs/source/api/v2/deliveryservices_id_routing.rst b/docs/source/api/v2/deliveryservices_id_routing.rst deleted file mode 100644 index 023c548a88..0000000000 --- a/docs/source/api/v2/deliveryservices_id_routing.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-id-routing: - -*********************************** -``deliveryservices/{{ID}}/routing`` -*********************************** - -``GET`` -======= -Retrieves the aggregated routing percentages for a given :term:`Delivery Service`. This is accomplished by polling stats from all online Traffic Routers via the :ref:`tr-api-crs-stats` route. - -:Auth. Required: Yes -:Roles Required: None\ [#tenancy]_ -:Response Type: Object - -.. note:: Only HTTP or DNS :term:`Delivery Services` can be requested. - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+------------------------------------------------------------------------------+ - | Name | Description | - +======+==============================================================================+ - | ID | The integral, unique identifier for the :term:`Delivery Service` of interest | - +------+------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/deliveryservices/1/routing HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:cz: The percent of requests to online Traffic Routers for this :term:`Delivery Service` that were satisfied by a :term:`Coverage Zone File` -:deepCz: The percent of requests to online Traffic Routers for this :term:`Delivery Service` that were satisfied by a :term:`Deep Coverage Zone File` -:dsr: The percent of requests to online Traffic Routers for this :term:`Delivery Service` that were satisfied by sending the client to an overflow :term:`Delivery Service` -:err: The percent of requests to online Traffic Routers for this :term:`Delivery Service` that resulted in an error -:fed: The percent of requests to online Traffic Routers for this :term:`Delivery Service` that were satisfied by sending the client to a federated CDN -:geo: The percent of requests to online Traffic Routers for this :term:`Delivery Service` that were satisfied using 3rd party geographic IP mapping -:miss: The percent of requests to online Traffic Routers for this :term:`Delivery Service` that could not be satisfied -:regionalAlternate: The percent of requests to online Traffic Routers for this :term:`Delivery Service` that were satisfied by sending the client to the alternate, Regional Geo-blocking URL -:regionalDenied: The percent of requests to online Traffic Routers for this :term:`Delivery Service` that were denied due to geographic location policy -:staticRoute: The percent of requests to online Traffic Routers for this :term:`Delivery Service` that were satisfied with :ref:`ds-static-dns-entries` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Fri, 30 Nov 2018 15:08:07 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: UgPziRC/5u4+CfkZ9xm0EkEzjjJVu6cwBrFd/n3xH/ZmlkaXkQaa1y4+B7DyE46vxFLYE0ODOcQchyn7JkoQOg== - Content-Length: 132 - - { "response": { - "cz": 79, - "deepCz": 0.50, - "dsr": 0, - "err": 0, - "fed": 0.25, - "geo": 20, - "miss": 0.25, - "regionalAlternate": 0, - "regionalDenied": 0, - "staticRoute": 0 - }} - -.. [#tenancy] Users will only be able to view routing details for the :term:`Delivery Services` their :term:`Tenant` is allowed to see. diff --git a/docs/source/api/v2/deliveryservices_id_safe.rst b/docs/source/api/v2/deliveryservices_id_safe.rst deleted file mode 100644 index b0144bc548..0000000000 --- a/docs/source/api/v2/deliveryservices_id_safe.rst +++ /dev/null @@ -1,241 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-id-safe: - -******************************** -``deliveryservices/{{ID}}/safe`` -******************************** - -``PUT`` -======= -Allows a user to edit metadata fields of a :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: None\ [#tenancy]_ -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+--------------------------------------------------------------------------------+ - | Name | Description | - +======+================================================================================+ - | ID | The integral, unique identifier of the :term:`Delivery Service` being modified | - +------+--------------------------------------------------------------------------------+ - -:displayName: A string that is the :ref:`ds-display-name` -:infoUrl: An optional\ [#optional]_ string containing the :ref:`ds-info-url` -:longDesc: An optional\ [#optional]_ string containing the :ref:`ds-longdesc` of this :term:`Delivery Service` -:longDesc1: An optional\ [#optional]_ string containing the 2nd long description of this :term:`Delivery Service` - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/deliveryservices/1/safe HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - Content-Length: 132 - - { - "displayName": "test", - "infoUrl": "this is not even a real URL", - "longDesc": "longDesc1 is implicitly set to null in this example - } - -Response Structure ------------------- -:active: A boolean that defines :ref:`ds-active`. -:anonymousBlockingEnabled: A boolean that defines :ref:`ds-anonymous-blocking` -:cacheurl: A :ref:`ds-cacheurl` - - .. deprecated:: ATCv3.0 - This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later - -:ccrDnsTtl: The :ref:`ds-dns-ttl` - named "ccrDnsTtl" for legacy reasons -:cdnId: The integral, unique identifier of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs -:cdnName: Name of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs -:checkPath: A :ref:`ds-check-path` -:consistentHashRegex: A :ref:`ds-consistent-hashing-regex` -:consistentHashQueryParams: An array of :ref:`ds-consistent-hashing-qparams` -:deepCachingType: The :ref:`ds-deep-caching` setting for this :term:`Delivery Service` -:displayName: The :ref:`ds-display-name` -:dnsBypassCname: A :ref:`ds-dns-bypass-cname` -:dnsBypassIp: A :ref:`ds-dns-bypass-ip` -:dnsBypassIp6: A :ref:`ds-dns-bypass-ipv6` -:dnsBypassTtl: The :ref:`ds-dns-bypass-ttl` -:dscp: A :ref:`ds-dscp` to be used within the :term:`Delivery Service` -:ecsEnabled: A boolean that defines the :ref:`ds-ecs` setting on this :term:`Delivery Service` -:edgeHeaderRewrite: A set of :ref:`ds-edge-header-rw-rules` -:exampleURLs: An array of :ref:`ds-example-urls` -:fqPacingRate: The :ref:`ds-fqpr` -:geoLimit: An integer that defines the :ref:`ds-geo-limit` -:geoLimitCountries: A string containing a comma-separated list defining the :ref:`ds-geo-limit-countries` -:geoLimitRedirectUrl: A :ref:`ds-geo-limit-redirect-url` -:geoProvider: The :ref:`ds-geo-provider` -:globalMaxMbps: The :ref:`ds-global-max-mbps` -:globalMaxTps: The :ref:`ds-global-max-tps` -:httpBypassFqdn: A :ref:`ds-http-bypass-fqdn` -:id: An integral, unique identifier for this :term:`Delivery Service` -:infoUrl: An :ref:`ds-info-url` -:initialDispersion: The :ref:`ds-initial-dispersion` -:ipv6RoutingEnabled: A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service` -:lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in :ref:`non-rfc-datetime` -:logsEnabled: A boolean that defines the :ref:`ds-logs-enabled` setting on this :term:`Delivery Service` -:longDesc: The :ref:`ds-longdesc` of this :term:`Delivery Service` -:longDesc1: The 2nd long description of this :term:`Delivery Service` -:longDesc2: the 3rd long description of this :term:`Delivery Service` -:matchList: The :term:`Delivery Service`'s :ref:`ds-matchlist` - - :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped) - :setNumber: An integer that provides explicit ordering of :ref:`ds-matchlist` items - this is used as a priority ranking by Traffic Router, and is not guaranteed to correspond to the ordering of items in the array. - :type: The type of match performed using ``pattern``. - -:maxDnsAnswers: The :ref:`ds-max-dns-answers` allowed for this :term:`Delivery Service` -:maxOriginConnections: The :ref:`ds-max-origin-connections` -:midHeaderRewrite: A set of :ref:`ds-mid-header-rw-rules` -:missLat: The :ref:`ds-geo-miss-default-latitude` used by this :term:`Delivery Service` -:missLong: The :ref:`ds-geo-miss-default-longitude` used by this :term:`Delivery Service` -:multiSiteOrigin: A boolean that defines the use of :ref:`ds-multi-site-origin` by this :term:`Delivery Service` -:orgServerFqdn: The :ref:`ds-origin-url` -:originShield: A :ref:`ds-origin-shield` string -:profileDescription: The :ref:`profile-description` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated -:profileId: The :ref:`profile-id` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated -:profileName: The :ref:`profile-name` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated -:protocol: An integral, unique identifier that corresponds to the :ref:`ds-protocol` used by this :term:`Delivery Service` -:qstringIgnore: An integral, unique identifier that corresponds to the :ref:`ds-qstring-handling` setting on this :term:`Delivery Service` -:rangeRequestHandling: An integral, unique identifier that corresponds to the :ref:`ds-range-request-handling` setting on this :term:`Delivery Service` -:regexRemap: A :ref:`ds-regex-remap` -:regionalGeoBlocking: A boolean defining the :ref:`ds-regionalgeo` setting on this :term:`Delivery Service` -:remapText: :ref:`ds-raw-remap` -:signed: ``true`` if and only if ``signingAlgorithm`` is not ``null``, ``false`` otherwise -:signingAlgorithm: Either a :ref:`ds-signing-algorithm` or ``null`` to indicate URL/URI signing is not implemented on this :term:`Delivery Service` -:rangeSliceBlockSize: An integer that defines the byte block size for the ATS Slice Plugin. It can only and must be set if ``rangeRequestHandling`` is set to 3. -:sslKeyVersion: This integer indicates the :ref:`ds-ssl-key-version` -:tenantId: The integral, unique identifier of the :ref:`ds-tenant` who owns this :term:`Delivery Service` -:trRequestHeaders: If defined, this defines the :ref:`ds-tr-req-headers` used by Traffic Router for this :term:`Delivery Service` -:trResponseHeaders: If defined, this defines the :ref:`ds-tr-resp-headers` used by Traffic Router for this :term:`Delivery Service` -:type: The :ref:`ds-types` of this :term:`Delivery Service` -:typeId: The integral, unique identifier of the :ref:`ds-types` of this :term:`Delivery Service` -:xmlId: This :term:`Delivery Service`'s :ref:`ds-xmlid` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 10 Feb 2020 16:33:03 GMT; Max-Age=3600; HttpOnly - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Feb 2020 15:33:03 GMT - Content-Length: 853 - - { "alerts": [ - { - "text": "Delivery Service safe update successful.", - "level": "success" - } - ], - "response": [ - { - "active": true, - "anonymousBlockingEnabled": false, - "cacheurl": null, - "ccrDnsTtl": null, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "checkPath": null, - "displayName": "test", - "dnsBypassCname": null, - "dnsBypassIp": null, - "dnsBypassIp6": null, - "dnsBypassTtl": null, - "dscp": 0, - "edgeHeaderRewrite": null, - "geoLimit": 0, - "geoLimitCountries": null, - "geoLimitRedirectURL": null, - "geoProvider": 0, - "globalMaxMbps": null, - "globalMaxTps": null, - "httpBypassFqdn": null, - "id": 1, - "infoUrl": "this is not even a real URL", - "initialDispersion": 1, - "ipv6RoutingEnabled": true, - "lastUpdated": "2020-02-10 15:33:03+00", - "logsEnabled": true, - "longDesc": "longDesc1 is implicitly set to null in this example", - "longDesc1": null, - "longDesc2": null, - "matchList": [ - { - "type": "HOST_REGEXP", - "setNumber": 0, - "pattern": ".*\\.demo1\\..*" - } - ], - "maxDnsAnswers": null, - "midHeaderRewrite": null, - "missLat": 42, - "missLong": -88, - "multiSiteOrigin": false, - "originShield": null, - "orgServerFqdn": "http://origin.infra.ciab.test", - "profileDescription": null, - "profileId": null, - "profileName": null, - "protocol": 2, - "qstringIgnore": 0, - "rangeRequestHandling": 0, - "regexRemap": null, - "regionalGeoBlocking": false, - "remapText": null, - "routingName": "video", - "signed": false, - "sslKeyVersion": 1, - "tenantId": 1, - "type": "HTTP", - "typeId": 1, - "xmlId": "demo1", - "exampleURLs": [ - "http://video.demo1.mycdn.ciab.test", - "https://video.demo1.mycdn.ciab.test" - ], - "deepCachingType": "NEVER", - "fqPacingRate": null, - "signingAlgorithm": null, - "tenant": "root", - "trResponseHeaders": null, - "trRequestHeaders": null, - "consistentHashRegex": null, - "consistentHashQueryParams": [ - "abc", - "pdq", - "xxx", - "zyx" - ], - "maxOriginConnections": 0, - "ecsEnabled": false, - "rangeSliceBlockSize": null - } - ]} - -.. [#tenancy] Only those :term:`Delivery Services` assigned to :term:`Tenants` that are the requesting user's :term:`Tenant` or children thereof may be modified with this endpoint. -.. [#optional] If these fields are not present in the request body they are *implicitly set to* ``null``. diff --git a/docs/source/api/v2/deliveryservices_id_servers.rst b/docs/source/api/v2/deliveryservices_id_servers.rst deleted file mode 100644 index 2f151abea7..0000000000 --- a/docs/source/api/v2/deliveryservices_id_servers.rst +++ /dev/null @@ -1,154 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-id-servers: - -*********************************** -``deliveryservices/{{ID}}/servers`` -*********************************** -.. caution:: It's often much easier to use :ref:`to-api-deliveryservices-xmlid-servers` instead - -``GET`` -======= -Retrieves properties of Edge-Tier servers assigned to a :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------------------------------------------------------+ - | Name | Description | - +======+=============================================================================================+ - | ID | The integral, unique identifier of the Delivery service for which servers will be displayed | - +------+---------------------------------------------------------------------------------------------+ - -Response Structure ------------------- -: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 :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 -:id: An integral, unique identifier for the server -:iloIpAddress: The IPv4 address of the lights-out-management port\ [#ilowikipedia]_ -:iloIpGateway: The IPv4 gateway address of the lights-out-management port\ [#ilowikipedia]_ -:iloIpNetmask: The IPv4 subnet mask of the lights-out-management port\ [#ilowikipedia]_ -:iloPassword: The password of the of the lights-out-management user - displays as ``******`` unless the requesting user has the 'admin' role)\ [#ilowikipedia]_ -:iloUsername: The user name for lights-out-management\ [#ilowikipedia]_ -:interfaceMtu: The :abbr:`MTU (Maximum Transmission Unit)` to configure for ``interfaceName`` - - .. seealso:: `The Wikipedia article on Maximum Transmission Unit `_ - -:interfaceName: The network interface name used by the server -:ip6Address: The IPv6 address and subnet mask of the server - applicable for the interface ``interfaceName`` -:ip6Gateway: The IPv6 gateway address of the server - applicable for the interface ``interfaceName`` -:ipAddress: The IPv4 address of the server- applicable for the interface ``interfaceName`` -:ipGateway: The IPv4 gateway of the server- applicable for the interface ``interfaceName`` -:ipNetmask: The IPv4 subnet mask of the server- applicable for the interface ``interfaceName`` -:lastUpdated: The time and date at which this server was last updated, in :ref:`non-rfc-datetime` -:mgmtIpAddress: The IPv4 address of the server's management port -: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 :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 -:rack: A string indicating "rack" location -:routerHostName: The human-readable name of the router -:routerPortName: The human-readable name of the router port -:status: The Status of the server - - .. seealso:: :ref:`health-proto` - -:statusId: An integral, unique identifier for the status of the server - - .. 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 -:updPending: ``true`` if the server has updates pending, ``false`` otherwise - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: MaIvaO8OSjysr4bCkuXFEMf3o6mOqga1aM4IHN/tcP2aa1iXEmA5IrHB7DaqNX/2vGHLXvN+01FEAR/lRNqr1w== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 14 Nov 2018 21:28:23 GMT - Content-Length: 891 - - { "response": [ - { - "cachegroup": "CDN_in_a_Box_Edge", - "cachegroupId": 7, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "domainName": "infra.ciab.test", - "guid": null, - "hostName": "edge", - "httpsPort": 443, - "id": 10, - "iloIpAddress": "", - "iloIpGateway": "", - "iloIpNetmask": "", - "iloPassword": "", - "iloUsername": "", - "interfaceMtu": 1500, - "interfaceName": "eth0", - "ip6Address": "fc01:9400:1000:8::100", - "ip6Gateway": "fc01:9400:1000:8::1", - "ipAddress": "172.16.239.100", - "ipGateway": "172.16.239.1", - "ipNetmask": "255.255.255.0", - "lastUpdated": "2018-11-14 21:08:44+00", - "mgmtIpAddress": "", - "mgmtIpGateway": "", - "mgmtIpNetmask": "", - "offlineReason": "", - "physLocation": "Apachecon North America 2018", - "physLocationId": 1, - "profile": "ATS_EDGE_TIER_CACHE", - "profileDesc": "Edge Cache - Apache Traffic Server", - "profileId": 9, - "rack": "", - "routerHostName": "", - "routerPortName": "", - "status": "REPORTED", - "statusId": 3, - "tcpPort": 80, - "type": "EDGE", - "typeId": 11, - "updPending": false - } - ]} - - -.. [#ilowikipedia] See `the Wikipedia article on Out-of-Band Management `_ for more information. diff --git a/docs/source/api/v2/deliveryservices_id_servers_eligible.rst b/docs/source/api/v2/deliveryservices_id_servers_eligible.rst deleted file mode 100644 index bd0528e42d..0000000000 --- a/docs/source/api/v2/deliveryservices_id_servers_eligible.rst +++ /dev/null @@ -1,146 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-id-servers-eligible: - -******************************************** -``deliveryservices/{{ID}}/servers/eligible`` -******************************************** - -.. caution:: This endpoint may not work as advertised, and its use is therefore discouraged! - -``GET`` -======= -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: - -- 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: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------------------------------------------------------+ - | Name | Description | - +======+=============================================================================================+ - | ID | The integral, unique identifier of the Delivery service for which servers will be displayed | - +------+---------------------------------------------------------------------------------------------+ - -Response Structure ------------------- -: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 :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 -:id: An integral, unique identifier for the server -:iloIpAddress: The IPv4 address of the lights-out-management port\ [#ilowikipedia]_ -:iloIpGateway: The IPv4 gateway address of the lights-out-management port\ [#ilowikipedia]_ -:iloIpNetmask: The IPv4 subnet mask of the lights-out-management port\ [#ilowikipedia]_ -:iloPassword: The password of the of the lights-out-management user - displays as ``******`` unless the requesting user has the 'admin' role)\ [#ilowikipedia]_ -:iloUsername: The user name for lights-out-management\ [#ilowikipedia]_ -:interfaceMtu: The :abbr:`MTU (Maximum Transmission Unit)` to configure for ``interfaceName`` - - .. seealso:: `The Wikipedia article on Maximum Transmission Unit `_ - -:interfaceName: The network interface name used by the server -:ip6Address: The IPv6 address and subnet mask of the server - applicable for the interface ``interfaceName`` -:ip6Gateway: The IPv6 gateway address of the server - applicable for the interface ``interfaceName`` -:ipAddress: The IPv4 address of the server- applicable for the interface ``interfaceName`` -:ipGateway: The IPv4 gateway of the server- applicable for the interface ``interfaceName`` -:ipNetmask: The IPv4 subnet mask of the server- applicable for the interface ``interfaceName`` -:lastUpdated: The time and date at which this server was last updated, in :ref:`non-rfc-datetime` -:mgmtIpAddress: The IPv4 address of the server's management port -: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 :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 -:rack: A string indicating "rack" location -:routerHostName: The human-readable name of the router -:routerPortName: The human-readable name of the router port -:status: The Status of the server - - .. seealso:: :ref:`health-proto` - -:statusId: An integral, unique identifier for the status of the server - - .. 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 :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 - :caption: Response Example - - { "response": [ - { - "cachegroup": "CDN_in_a_Box_Edge", - "cachegroupId": 7, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "domainName": "infra.ciab.test", - "guid": null, - "hostName": "edge", - "httpsPort": 443, - "id": 10, - "iloIpAddress": "", - "iloIpGateway": "", - "iloIpNetmask": "", - "iloPassword": "", - "iloUsername": "", - "interfaceMtu": 1500, - "interfaceName": "eth0", - "ip6Address": "fc01:9400:1000:8::100", - "ip6Gateway": "fc01:9400:1000:8::1", - "ipAddress": "172.16.239.100", - "ipGateway": "172.16.239.1", - "ipNetmask": "255.255.255.0", - "lastUpdated": "2018-10-30 16:01:12+00", - "mgmtIpAddress": "", - "mgmtIpGateway": "", - "mgmtIpNetmask": "", - "offlineReason": "", - "physLocation": "Apachecon North America 2018", - "physLocationId": 1, - "profile": "ATS_EDGE_TIER_CACHE", - "profileDesc": "Edge Cache - Apache Traffic Server", - "profileId": 9, - "rack": "", - "routerHostName": "", - "routerPortName": "", - "status": "REPORTED", - "statusId": 3, - "tcpPort": 80, - "type": "EDGE", - "typeId": 11, - "updPending": false - } - ]} - -.. [#ilowikipedia] See `the Wikipedia article on Out-of-Band Management `_ for more information. diff --git a/docs/source/api/v2/deliveryservices_id_urlkeys.rst b/docs/source/api/v2/deliveryservices_id_urlkeys.rst deleted file mode 100644 index 3939e9cad8..0000000000 --- a/docs/source/api/v2/deliveryservices_id_urlkeys.rst +++ /dev/null @@ -1,93 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-id-urlkeys: - -*********************************** -``deliveryservices/{{ID}}/urlkeys`` -*********************************** - -``GET`` -======= -.. seealso:: :ref:`to-api-deliveryservices-xmlid-xmlid-urlkeys` - -Retrieves URL signing keys for a :term:`Delivery Service`. - -.. caution:: This method will return the :term:`Delivery Service`'s **PRIVATE** URL signing keys! Be wary of using this endpoint and **NEVER** share the output with anyone who would be unable to see it on their own. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+----------------------------------------------------------------------------------------+ - | Name | Description | - +======+========================================================================================+ - | id | Filter for the :term:`Delivery Service` identified by this integral, unique identifier | - +------+----------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/deliveryservices/1/urlkeys HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - -Response Structure ------------------- -:key: The private URL signing key for this :term:`Delivery Service` as a base-64-encoded string, where ```` is the "generation" of the key e.g. the first key will always be named ``"key0"``. Up to 16 concurrent generations are retained at any time (```` is always on the interval [0,15]) - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Sun, 23 Feb 2020 16:34:56 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: cTc5OPE3hM+CiyQPCy36zD2tsQcfkvIqQ7/D82WGMWHm+ACW3YbcKhgPnSQU6+Tuj4jya52Kx9+nw5+OonFvPQ== - X-Server-Name: traffic_ops_golang/ - Date: Sun, 23 Feb 2020 15:34:56 GMT - Content-Length: 533 - - { - "response": { - "key0": "...", - "key1": "...", - "key2": "...", - "key3": "...", - "key4": "...", - "key5": "...", - "key6": "...", - "key7": "...", - "key8": "...", - "key9": "..." - "key10": "...", - "key11": "...", - "key12": "...", - "key13": "...", - "key14": "...", - "key15": "...", - } - } diff --git a/docs/source/api/v2/deliveryservices_regexes.rst b/docs/source/api/v2/deliveryservices_regexes.rst deleted file mode 100644 index 3f752b015a..0000000000 --- a/docs/source/api/v2/deliveryservices_regexes.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - - -.. _to-api-v2-deliveryservices_regexes: - -**************************** -``deliveryservices_regexes`` -**************************** - -``GET`` -======= -Retrieves routing regular expressions for all :term:`Delivery Services`. - -:Auth. Required: Yes -:Roles Required: None\ [1]_ -:Response Type: Array - -Request Structure ------------------ -No parameters available - -Response Structure ------------------- -:dsName: The name of the :term:`Delivery Service` represented by this object -:regexes: An array of objects that represent various routing regular expressions used by ``dsName`` - - :pattern: The actual regular expression - ``\``\ s are escaped - :setNumber: The order in which the regular expression is evaluated against requests - :type: The type of regular expression - determines that against which it will be evaluated - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: +2MI+Q/NJqTizlMR/MhPAL+yu6/z/Yqvo5fDO8F593RMOmK6dX/Al4wARbEG+HQaJNgSCRPsiLVATusrmnnCMA== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 27 Nov 2018 19:22:59 GMT - Content-Length: 110 - - { "response": [ - { - "regexes": [ - { - "type": "HOST_REGEXP", - "setNumber": 0, - "pattern": ".*\\.demo1\\..*" - } - ], - "dsName": "demo1" - } - ]} - -.. [1] If tenancy is used, then users (regardless of role) will only be able to see the routing regular expressions used by :term:`Delivery Services` their tenant has permissions to see. diff --git a/docs/source/api/v2/deliveryservices_request.rst b/docs/source/api/v2/deliveryservices_request.rst deleted file mode 100644 index c9a372d2ca..0000000000 --- a/docs/source/api/v2/deliveryservices_request.rst +++ /dev/null @@ -1,139 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-request: - -**************************** -``deliveryservices/request`` -**************************** - -.. note:: This route does NOT do the same thing as :ref:`POST deliveryservice_requests`. - -.. deprecated:: ATCv6 - This endpoint does not appear in Traffic Ops API version 4.0 - released with Apache Traffic Control version 6.0 - or later. - -``POST`` -======== -Submits an emailed requesting that a :term:`Delivery Service` be created. - -:Auth. Required: Yes -:Roles Required: "admin", "Federation", "operations", "Portal", or "Steering" -:Response Type: ``undefined`` - -Request Structure ------------------ -:details: An object describing the actual parameters for the Delivery Service request - - :customer: Name of the customer associated with the :term:`Delivery Service` - must only contain alphanumeric characters and the characters :kbd:`@`, :kbd:`!`, :kbd:`#`, :kbd:`$`, :kbd:`%`, :kbd:`^`, :kbd:`&`, :kbd:`*`, :kbd:`(`, :kbd:`)`, :kbd:`[`, :kbd:`]`, :kbd:`.`, :kbd:`\ `, and :kbd:`-` - - .. versionchanged:: ATCv6 - Prior to ATC version 6, this field had no restrictions. - - :deepCachingType: An optional string describing when to do Deep Caching for this :term:`Delivery Service` - one of: - - NEVER - Never use deep caching (default) - ALWAYS - Always use deep caching - - :deliveryProtocol: The protocol used to retrieve content from the CDN - one of: - - * http - * https - * http/https - - :hasNegativeCachingCustomization: ``true`` if any customization is required for negative caching, ``false`` otherwise - :hasOriginACLWhitelist: ``true`` if access to the origin is restricted using an Access Control List (ACL or "whitelist") of IP addresses - :hasOriginDynamicRemap: If ``true``, this :term:`Delivery Service` can dynamically map to multiple origin URLs - :hasSignedURLs: If ``true``, this :term:`Delivery Service`'s URLs are signed - :headerRewriteEdge: An optional string containing a header re-write rule to be used at the Edge tier - :headerRewriteMid: An optional string containing a header re-write rule to be used at the Mid tier - :headerRewriteRedirectRouter: An optional string containing a header re-write rule to be used by the Traffic Router - :maxLibrarySizeEstimate: A special string that describes the estimated size of the sum total of content available through this :term:`Delivery Service` - :negativeCachingCustomizationNote: A note remarking on the use, customization, or complications associated with negative caching for this :term:`Delivery Service` - :notes: An optional string containing additional instructions or notes regarding the Request - :originHeaders: An optional, comma-separated string of header values that must be passed to requests to the :term:`Delivery Service`'s origin - :originTestFile: A URL path to a test file available on the :term:`Delivery Service`'s origin server - :originURL: The URL of the :term:`Delivery Service`'s origin server - :otherOriginSecurity: An optional string describing any and all other origin security measures that need to be considered for access to the :term:`Delivery Service`'s origin - :overflowService: An optional string containing the IP address or URL of an overflow point (used if rate limits are met or exceeded - :peakBPSEstimate: A special string describing the estimated peak data transfer rate of the :term:`Delivery Service` in Bytes Per Second (BPS) - :peakTPSEstimate: A special string describing the estimated peak transaction rate of the :term:`Delivery Service` in Transactions Per Second (TPS) - :queryStringHandling: A special string describing how the :term:`Delivery Service` should treat URLs containing query parameters - :rangeRequestHandling: A special string describing how the :term:`Delivery Service` should handle range requests - :rateLimitingGBPS: An optional field which, if defined, should contain the maximum allowed data transfer rate for the :term:`Delivery Service` in GigaBytes Per Second (GBPS) - :rateLimitingTPS: An optional field which, if defined, should contain the maximum allowed transaction rate for the :term:`Delivery Service` in Transactions Per Second (TPS) - :routingName: An optional field which, if defined, should contain the routing name for the :term:`Delivery Service`, e.g. ``SomeRoutingName.DeliveryService_xml_id.CDNName.com`` - :routingType: The :term:`Delivery Service`'s routing type, should be one of: - - HTTP - The Traffic Router re-directs clients to :term:`cache servers` using the HTTP ``302 REDIRECT`` response code - DNS - The Traffic Router responds to requests for name resolution of the :term:`Delivery Service`'s routing name with IP addresses of :term:`cache servers` - STEERING - This :term:`Delivery Service` routes clients to other :term:`Delivery Services` - which will in turn (generally) route them to clients - ANY_MAP - Some kind of undocumented black magic is used to get clients to... content, probably? - - :serviceAliases: An optional array of aliases for this :term:`Delivery Service` - :serviceDesc: A description of the :term:`Delivery Service` - -:emailTo: The email to which the Delivery Service request will be sent - -.. code-block:: json - :caption: Request Example - - { "emailTo": "foo@bar.com", - "details": { - "customer": "XYZ Corporation", - "contentType": "static", - "deepCachingType": "NEVER", - "deliveryProtocol": "http", - "routingType": "http", - "routingName": "demo1", - "serviceDesc": "service description goes here", - "peakBPSEstimate": "less-than-5-Gbps", - "peakTPSEstimate": "less-than-1000-TPS", - "maxLibrarySizeEstimate": "less-than-200-GB", - "originURL": "http://myorigin.com", - "hasOriginDynamicRemap": false, - "originTestFile": "http://origin.infra.ciab.test", - "hasOriginACLWhitelist": false, - "originHeaders": "", - "otherOriginSecurity": "", - "queryStringHandling": "ignore-in-cache-key-and-pass-up", - "rangeRequestHandling": "range-requests-not-used", - "hasSignedURLs": false, - "hasNegativeCachingCustomization": false, - "negativeCachingCustomizationNote": "", - "serviceAliases": [], - "rateLimitingGBPS": 50, - "rateLimitingTPS": 5000, - "overflowService": null, - "headerRewriteEdge": "", - "headerRewriteMid": "", - "headerRewriteRedirectRouter": "", - "notes": "" - }} - -Response Structure ------------------- -.. code-block:: json - :caption: Response Example - - { "alerts": [{ - "level": "success", - "text": "Delivery Service request sent to foo@bar.com." - }]} diff --git a/docs/source/api/v2/deliveryservices_required_capabilities.rst b/docs/source/api/v2/deliveryservices_required_capabilities.rst deleted file mode 100644 index da51996a01..0000000000 --- a/docs/source/api/v2/deliveryservices_required_capabilities.rst +++ /dev/null @@ -1,224 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-required-capabilities: - -****************************************** -``deliveryservices_required_capabilities`` -****************************************** - -``GET`` -======= -Gets all associations of :term:`Server Capability` to :term:`Delivery Services`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +--------------------+----------+---------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +====================+==========+===============================================================================================================+ - | deliveryServiceID | no | Filter :term:`Server Capability` associations by :term:`Delivery Service` integral, unique identifier | - +--------------------+----------+---------------------------------------------------------------------------------------------------------------+ - | xmlID | no | Filter :term:`Server Capability` associations by :term:`Delivery Service` :ref:`ds-xmlid` | - +--------------------+----------+---------------------------------------------------------------------------------------------------------------+ - | requiredCapability | no | Filter :term:`Server Capability` associations by :term:`Server Capability` name | - +--------------------+----------+---------------------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/deliveryservices_required_capabilities HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:deliveryServiceID: The associated :term:`Delivery Service`'s integral, unique identifier -:xmlID: The associated :term:`Delivery Service`'s :ref:`ds-xmlid` -:lastUpdated: The date and time at which this association between the :term:`Delivery Service` and the :term:`Server Capability` was last updated, in :ref:`non-rfc-datetime` -:requiredCapability: The :term:`Server Capability`'s name - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: UFO3/jcBFmFZM7CsrsIwTfPc5v8gUiXqJm6BNp1boPb4EQBnWNXZh/DbBwhMAOJoeqDImoDlrLnrVjQGO4AooA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 07 Oct 2019 22:15:11 GMT - Content-Length: 396 - - { - "response": [ - { - "deliveryServiceID": 1, - "lastUpdated": "2019-10-07 22:05:31+00", - "requiredCapability": "ram", - "xmlId": "example_ds-1" - }, - { - "deliveryServiceID": 2, - "lastUpdated": "2019-10-07 22:05:31+00", - "requiredCapability": "disk", - "xmlId": "example_ds-2" - } - ] - } - -``POST`` -======== -Associates a :term:`Server Capability` with a :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -.. note:: A :term:`Server Capability` can only be made required on a :term:`Delivery Service` if its associated Servers already have that :term:`Server Capability` assigned. - -Request Structure ------------------ -:deliveryServiceID: The integral, unique identifier of the :term:`Delivery Service` to be associated -:requiredCapability: The name of the :term:`Server Capability` to be associated - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/deliveryservices_required_capabilities HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 56 - Content-Type: application/json - - { - "deliveryServiceID": 1, - "requiredCapability": "disk" - } - -Response Structure ------------------- -:deliveryServiceID: The newly associated :term:`Delivery Service`'s integral, unique identifier -:lastUpdated: The date and time at which this association between the :term:`Delivery Service` and the :term:`Server Capability` was last updated, in :ref:`non-rfc-datetime` -:requiredCapability: The newly associated :term:`Server Capability`'s name - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: eQrl48zWids0kDpfCYmmtYMpegjnFxfOVvlBYxxLSfp7P7p6oWX4uiC+/Cfh2X9i3G+MQ36eH95gukJqOBOGbQ== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 07 Oct 2019 22:15:11 GMT - Content-Length: 287 - - { - "alerts": [ - { - "level": "success", - "text": "deliveryservice.RequiredCapability was created." - } - ], - "response": { - "deliveryServiceID": 1, - "lastUpdated": "2019-10-07 22:15:11+00", - "requiredCapability": "disk" - } - } - -``DELETE`` -========== -Dissociate a :term:`Server Capability` from a :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -:deliveryServiceID: The integral, unique identifier of the :term:`Delivery Service` from which a :term:`Server Capability` will be dissociated -:requiredCapability: The name of the :term:`Server Capability` to dissociate - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/deliveryservices_required_capabilities HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 56 - Content-Type: application/json - - { - "deliveryServiceID": 1, - "requiredCapability": "disk" - } - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: eQrl48zWids0kDpfCYmmtYMpegjnFxfOVvlBYxxLSfp7P7p6oWX4uiC+/Cfh2X9i3G+MQ36eH95gukJqOBOGbQ== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 07 Oct 2019 22:15:11 GMT - Content-Length: 127 - - { - "alerts": [ - { - "level": "success", - "text": "deliveryservice.RequiredCapability was deleted." - } - ] - } diff --git a/docs/source/api/v2/deliveryservices_sslkeys_add.rst b/docs/source/api/v2/deliveryservices_sslkeys_add.rst deleted file mode 100644 index b368b790df..0000000000 --- a/docs/source/api/v2/deliveryservices_sslkeys_add.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-sslkeys-add: - -******************************** -``deliveryservices/sslkeys/add`` -******************************** - -.. seealso:: In most cases it is preferable to allow Traffic Ops to generate the keys via :ref:`to-api-deliveryservices-sslkeys-generate`, rather than uploading them manually using this endpoint. - -``POST`` -======== -Allows user to upload an SSL certificate, csr, and private key for a :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object (string) - -Request Structure ------------------ -:cdn: The name of the CDN to which the :term:`Delivery Service` belongs -:certificate: An object that contains the actual components of the SSL key - - :crt: The certificate for the :term:`Delivery Service` identified by ``key`` - :csr: The csr file for the :term:`Delivery Service` identified by ``key`` - :key: The private key for the :term:`Delivery Service` identified by ``key`` - -:key: The :ref:`ds-xmlid` of the :term:`Delivery Service` to which these keys will be assigned -:version: An integer that defines the "version" of the key - which may be thought of as the sequential generation; that is, the higher the number the more recent the key - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/deliveryservices/sslkeys/add HTTP/1.1 - Host: trafficops.infra.ciab.test - Content-Type: application/json - - { - "key": "ds-01", - "version": "1", - "certificate": { - "key": "some_key", - "csr": "some_csr", - "crt": "some_crt" - } - } - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "response": "Successfully added ssl keys for ds-01" - } diff --git a/docs/source/api/v2/deliveryservices_sslkeys_generate.rst b/docs/source/api/v2/deliveryservices_sslkeys_generate.rst deleted file mode 100644 index 1a35b5c0d3..0000000000 --- a/docs/source/api/v2/deliveryservices_sslkeys_generate.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-sslkeys-generate: - -************************************* -``deliveryservices/sslkeys/generate`` -************************************* - -``POST`` -======== -Generates an SSL certificate, csr, and private key for a :term:`Delivery Service` - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object (string) - -Request Structure ------------------ -:city: An optional field which, if present, will represent the resident city of the generated SSL certificate -:country: An optional field which, if present, will represent the resident country of the generated SSL certificate -:hostname: The desired hostname of the :term:`Delivery Service` - - .. note:: In most cases, this must be the same as the :term:`Delivery Service` URL' - -:key: The :ref:`ds-xmlid` of the :term:`Delivery Service` for which keys will be generated -:organization: An optional field which, if present, will represent the organization for which the SSL certificate was generated -:state: An optional field which, if present, will represent the resident state or province of the generated SSL certificate -:businessUnit: An optional field which, if present, will represent the business unit for which the SSL certificate was generated -:version: An integer that defines the "version" of the key - which may be thought of as the sequential generation; that is, the higher the number the more recent the key - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/deliveryservices/sslkeys/generate HTTP/1.1 - Content-Type: application/json - - { - "key": "ds-01", - "businessUnit": "CDN Engineering", - "version": "3", - "hostname": "tr.ds-01.ott.kabletown.com", - "country": "US", - "organization": "Kabletown", - "city": "Denver", - "state": "Colorado" - } - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Content-Type: application/json - - { "response": "Successfully created ssl keys for ds-01" } diff --git a/docs/source/api/v2/deliveryservices_sslkeys_generate_letsencrypt.rst b/docs/source/api/v2/deliveryservices_sslkeys_generate_letsencrypt.rst deleted file mode 100644 index 54c528815f..0000000000 --- a/docs/source/api/v2/deliveryservices_sslkeys_generate_letsencrypt.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-sslkeys-generate-letsencrypt: - -************************************************* -``deliveryservices/sslkeys/generate/letsencrypt`` -************************************************* - -``POST`` -======== -Generates an SSL certificate and private key using Let's Encrypt for a :term:`Delivery Service` - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object (string) - -Request Structure ------------------ -:key: The :ref:`ds-xmlid` of the :term:`Delivery Service` for which keys will be generated [#needOne]_ -:deliveryservice: The :ref:`ds-xmlid` of the :term:`Delivery Service` for which keys will be generated [#needOne]_ -:version: An integer that defines the "version" of the key - which may be thought of as the sequential generation; that is, the higher the number the more recent the key -:hostname: The desired hostname of the :term:`Delivery Service` - - .. note:: In most cases, this must be the same as the :ref:`ds-example-urls`. - -:cdn: The name of the CDN of the :term:`Delivery Service` for which the certs will be generated - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/deliveryservices/sslkeys/generate/letsencrypt HTTP/1.1 - Content-Type: application/json - - { - "key": "ds-01", - "deliveryservice": "ds-01", - "version": "3", - "hostname": "tr.ds-01.ott.kabletown.com", - "cdn":"test-cdn" - } - - -Response Structure ------------------- -.. code-block:: json - :caption: Response Example - - { "alerts": [{ - "level": "success", - "text": "Beginning async ACME call for demo1 using Lets Encrypt. This may take a few minutes. Status updates can be found here: /api/4.0/async_status/1" - }]} - -.. [#needOne] Either the ``key`` or the ``deliveryservice`` field must be provided. If both are provided, then they must match. diff --git a/docs/source/api/v2/deliveryservices_xmlid_servers.rst b/docs/source/api/v2/deliveryservices_xmlid_servers.rst deleted file mode 100644 index 76a22ccae3..0000000000 --- a/docs/source/api/v2/deliveryservices_xmlid_servers.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-xmlid-servers: - -*************************************** -``deliveryservices/{{xml_id}}/servers`` -*************************************** - -``POST`` -======== -Assigns :term:`cache servers` to a :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations"\ [#tenancy]_ -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +--------+----------------------------------------------------------------------------------------+ - | Name | Description | - +========+========================================================================================+ - | xml_id | The 'xml_id' of the :term:`Delivery Service` whose server assignments are being edited | - +--------+----------------------------------------------------------------------------------------+ - -:serverNames: An array of hostname of :term:`cache servers` to assign to this :term:`Delivery Service` - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/deliveryservices/test/servers HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 24 - Content-Type: application/json - - { "serverNames": [ "edge" ] } - -Response Structure ------------------- -:xml_id: The :ref:`ds-xmlid` of the :term:`Delivery Service` to which the servers in ``serverNames`` have been assigned -:serverNames: An array of hostnames of :term:`cache servers` assigned to :term:`Delivery Service` identified by ``xml_id`` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: zTpLrWiLM4xRsm8mlBQFB5KzT478AjloSyXHgtyWhebCv1YIwWltmkjr0HFgc3GMGZODt+fyzkOYy5Zl/yBtJw== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 20 Nov 2018 15:21:50 GMT - Content-Length: 52 - - { "response": { - "serverNames": [ - "edge" - ], - "xmlId": "test" - }} - -.. [#tenancy] Users can only assign servers to :term:`Delivery Services` that are visible to their :term:`Tenant`. diff --git a/docs/source/api/v2/deliveryservices_xmlid_urisignkeys.rst b/docs/source/api/v2/deliveryservices_xmlid_urisignkeys.rst deleted file mode 100644 index 2e50212381..0000000000 --- a/docs/source/api/v2/deliveryservices_xmlid_urisignkeys.rst +++ /dev/null @@ -1,194 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-xmlid-urisignkeys: - -******************************************* -``deliveryservices/{{xml_id}}/urisignkeys`` -******************************************* - -``DELETE`` -========== -Deletes URISigning objects for a :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: admin\ [#tenancy]_ -:Response Type: ``undefined`` - -Request Structure ------------------ - -.. table:: Request Path Parameters - - +-----------+----------+----------------------------------------+ - | Name | Required | Description | - +===========+==========+========================================+ - | xml_id | yes | xml_id of the desired delivery service | - +-----------+----------+----------------------------------------+ - -Response Structure ------------------- -TBD - -``GET`` -======= -Retrieves one or more URISigning objects for a delivery service. - -:Auth. Required: Yes -:Roles Required: admin\ [#tenancy]_ -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Route Parameters - - +-----------+----------+----------------------------------------+ - | Name | Required | Description | - +===========+==========+========================================+ - | xml_id | yes | xml_id of the desired delivery service | - +-----------+----------+----------------------------------------+ - -Response Structure ------------------- - -:Issuer: a string describing the issuer of the URI signing object. Multiple URISigning objects may be returned in a response, see example -:renewal_kid: a string naming the jwt key used for renewals -:keys: json array of jwt symmetric keys -:alg: this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, :rfc:`7518` -:kid: this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in :rfc:`7516` -:kty: this parameter repeats for each jwt key in the array and specifies the key type as defined in :rfc:`7516` -:k: this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see :rfc:`7516` - -.. code-block:: json - :caption: Response Example - - { "Kabletown URI Authority": { - "renewal_kid": "Second Key", - "keys": [ - { - "alg": "HS256", - "kid": "First Key", - "kty": "oct", - "k": "Kh_RkUMj-fzbD37qBnDf_3e_RvQ3RP9PaSmVEpE24AM" - }, - { - "alg": "HS256", - "kid": "Second Key", - "kty": "oct", - "k": "fZBpDBNbk2GqhwoB_DGBAsBxqQZVix04rIoLJ7p_RlE" - } - ] - }} - - -``POST`` -======== -Assigns URISigning objects to a delivery service. - -:Auth. Required: Yes -:Roles Required: admin\ [#tenancy]_ -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +-----------+----------+----------------------------------------+ - | Name | Required | Description | - +===========+==========+========================================+ - | xml_id | yes | xml_id of the desired delivery service | - +-----------+----------+----------------------------------------+ - -Request Structure ------------------ -:Issuer: a string describing the issuer of the URI signing object. Multiple URISigning objects may be returned in a response, see example -:renewal_kid: a string naming the jwt key used for renewals -:keys: json array of jwt symmetric keys -:alg: this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, :rfc:`7518` -:kid: this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in :rfc:`7516` -:kty: this parameter repeats for each jwt key in the array and specifies the key type as defined in :rfc:`7516` -:k: this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see :rfc:`7516` - -.. code-block:: json - :caption: Request Example - - { "Kabletown URI Authority": { - "renewal_kid": "Second Key", - "keys": [ - { - "alg": "HS256", - "kid": "First Key", - "kty": "oct", - "k": "Kh_RkUMj-fzbD37qBnDf_3e_RvQ3RP9PaSmVEpE24AM" - }, - { - "alg": "HS256", - "kid": "Second Key", - "kty": "oct", - "k": "fZBpDBNbk2GqhwoB_DGBAsBxqQZVix04rIoLJ7p_RlE" - } - ] - }} - -``PUT`` -======= -updates URISigning objects on a delivery service. - -:Auth. Required: Yes -:Roles Required: admin\ [#tenancy]_ -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +-----------+----------+----------------------------------------+ - | Name | Required | Description | - +===========+==========+========================================+ - | xml_id | yes | xml_id of the desired delivery service | - +-----------+----------+----------------------------------------+ - -Request Structure ------------------ -:Issuer: a string describing the issuer of the URI signing object. Multiple URISigning objects may be returned in a response, see example -:renewal_kid: a string naming the jwt key used for renewals -:keys: json array of jwt symmetric keys -:alg: this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, :rfc:`7518` -:kid: this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in :rfc:`7516` -:kty: this parameter repeats for each jwt key in the array and specifies the key type as defined in :rfc:`7516` -:k: this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see :rfc:`7516` - -.. code-block:: json - :caption: Request Example - - { "Kabletown URI Authority": { - "renewal_kid": "Second Key", - "keys": [ - { - "alg": "HS256", - "kid": "First Key", - "kty": "oct", - "k": "Kh_RkUMj-fzbD37qBnDf_3e_RvQ3RP9PaSmVEpE24AM" - }, - { - "alg": "HS256", - "kid": "Second Key", - "kty": "oct", - "k": "fZBpDBNbk2GqhwoB_DGBAsBxqQZVix04rIoLJ7p_RlE" - } - ] - }} - -.. [#tenancy] URI Signing Keys can only be created, viewed, deleted, or modified on :term:`Delivery Services` that either match the requesting user's :term:`Tenant` or are descendants thereof. diff --git a/docs/source/api/v2/deliveryservices_xmlid_xmlid_sslkeys.rst b/docs/source/api/v2/deliveryservices_xmlid_xmlid_sslkeys.rst deleted file mode 100644 index 765710c5f6..0000000000 --- a/docs/source/api/v2/deliveryservices_xmlid_xmlid_sslkeys.rst +++ /dev/null @@ -1,144 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-xmlid-xmlid-sslkeys: - -******************************************** -``deliveryservices/xmlId/{{XMLID}}/sslkeys`` -******************************************** - -``GET`` -======= -Retrieves SSL keys for a :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +-------+------------------------------------------------------+ - | Name | Description | - +=======+======================================================+ - | XMLID | The 'xml_id' of the desired :term:`Delivery Service` | - +-------+------------------------------------------------------+ - - -.. table:: Request Query Parameters - - +---------+----------+-----------------------------------------------------------------------------------------+ - | Name | Required | Description | - +=========+==========+=========================================================================================+ - | version | no | The version number of the SSL keys to retrieve | - +---------+----------+-----------------------------------------------------------------------------------------+ - | decode | no | If ``true``, the returned keys will be decoded - if ``false``, they will not be decoded | - +---------+----------+-----------------------------------------------------------------------------------------+ - -.. caution:: There's almost certainly no good reason to request the private key! Even when "base 64-encoded" do not let **ANYONE** see this who would be unable to request it themselves! - -Response Structure ------------------- -:businessUnit: An optional field which, if present, contains the business unit entered by the user when generating the SSL certificate\ [1]_ -:certificate: An object containing the actual generated key, certificate, and signature of the SSL keys - - :crt: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) certificate for the :term:`Delivery Service` identified by ``deliveryservice`` - :csr: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) csr file for the :term:`Delivery Service` identified by ``deliveryservice`` - :key: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) private key for the :term:`Delivery Service` identified by ``deliveryservice`` - - .. caution:: There's almost certainly no good reason to request the private key! Even when "base 64-encoded" do not let **ANYONE** see this who would be unable to request it themselves! - -:cdn: The CDN of the :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\ [1]_ -:country: An optional field which, if present, contains the country entered by the user when generating the SSL certificate\ [1]_ -:deliveryservice: The 'xml_id' of the :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 a FQDN 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\ [1]_ -:state: An optional field which, if present, contains the state entered by the user when generating certificate\ [1]_ -:version: An integer that defines the "version" of the key - which may be thought of as the sequential generation; that is, the higher the number the more recent the key -:expiration: The expiration date of the certificate for the :term:`Delivery Service` in :rfc:`3339` format - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Content-Type: application/json - - { "response": { - "certificate": { - "crt": "crt", - "key": "key", - "csr": "csr" - }, - "deliveryservice": "my-ds", - "cdn": "qa", - "businessUnit": "CDN_Eng", - "city": "Denver", - "organization": "KableTown", - "hostname": "foober.com", - "country": "US", - "state": "Colorado", - "version": "1", - "expiration": "2020-08-18T13:53:06Z" - }} - -``DELETE`` -========== -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object (string) - -Request Structure ------------------ -.. table:: Request Path Parameters - - +-------+----------+-------------------------------------------------------------+ - | Name | Required | Description | - +=======+==========+=============================================================+ - | xmlId | yes | The :ref:`ds-xmlid` of the desired :term:`Delivery Service` | - +-------+----------+-------------------------------------------------------------+ - -.. table:: Request Query Parameters - - +---------+----------+------------------------------------------------------------+ - | Name | Required | Description | - +=========+==========+============================================================+ - | version | no | The version number of the SSL keys that shall be retrieved | - +---------+----------+------------------------------------------------------------+ - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Wed, 18 Mar 2020 17:36:10 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: Pj+zCoOXg19nGNxcSkjib2iDjG062Y3RcEEV+OYnwbGIsLcpa0BKZleY/qJOKT5DkSoX2qQkckUxUqdDxjVorQ== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 18 Mar 2020 16:36:10 GMT - Content-Length: 79 - - { - "response": "Successfully deleted ssl keys for demo1" - } - -.. [1] These optional fields will be present in the response if and only if they were specified during key generation; they are optional during key generation and thus cannot be guaranteed to exist or not exist. diff --git a/docs/source/api/v2/deliveryservices_xmlid_xmlid_urlkeys.rst b/docs/source/api/v2/deliveryservices_xmlid_xmlid_urlkeys.rst deleted file mode 100644 index 2c6b905c5d..0000000000 --- a/docs/source/api/v2/deliveryservices_xmlid_xmlid_urlkeys.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-xmlid-xmlid-urlkeys: - -******************************************** -``deliveryservices/xmlId/{{xmlid}}/urlkeys`` -******************************************** - -``GET`` -======= -.. seealso:: :ref:`to-api-v2-deliveryservices-id-urlkeys` - -Retrieves URL signing keys for a :term:`Delivery Service`. - -.. caution:: This method will return the :term:`Delivery Service`'s **PRIVATE** URL signing keys! Be wary of using this endpoint and **NEVER** share the output with anyone who would be unable to see it on their own. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +-------+------------------------------------------------------+ - | Name | Description | - +=======+======================================================+ - | xmlid | The 'xml_id' of the desired :term:`Delivery Service` | - +-------+------------------------------------------------------+ - -Response Structure ------------------- -:key: The private URL signing key for this :term:`Delivery Service` as a base-64-encoded string, where ```` is the "generation" of the key e.g. the first key will always be named ``"key0"``. Up to 16 concurrent generations are retained at any time (```` is always on the interval [0,15]) - -.. code-block:: json - :caption: Response Example - - { "response": { - "key9":"ZvVQNYpPVQWQV8tjQnUl6osm4y7xK4zD", - "key6":"JhGdpw5X9o8TqHfgezCm0bqb9SQPASWL", - "key8":"ySXdp1T8IeDEE1OCMftzZb9EIw_20wwq", - "key0":"D4AYzJ1AE2nYisA9MxMtY03TPDCHji9C", - "key3":"W90YHlGc_kYlYw5_I0LrkpV9JOzSIneI", - "key12":"ZbtMb3mrKqfS8hnx9_xWBIP_OPWlUpzc", - "key2":"0qgEoDO7sUsugIQemZbwmMt0tNCwB1sf", - "key4":"aFJ2Gb7atmxVB8uv7T9S6OaDml3ycpGf", - "key1":"wnWNR1mCz1O4C7EFPtcqHd0xUMQyNFhA", - "key11":"k6HMzlBH1x6htKkypRFfWQhAndQqe50e", - "key10":"zYONfdD7fGYKj4kLvIj4U0918csuZO0d", - "key15":"3360cGaIip_layZMc_0hI2teJbazxTQh", - "key5":"SIwv3GOhWN7EE9wSwPFj18qE4M07sFxN", - "key13":"SqQKBR6LqEOzp8AewZUCVtBcW_8YFc1g", - "key14":"DtXsu8nsw04YhT0kNoKBhu2G3P9WRpQJ", - "key7":"cmKoIIxXGAxUMdCsWvnGLoIMGmNiuT5I" - }} diff --git a/docs/source/api/v2/deliveryservices_xmlid_xmlid_urlkeys_copyfromxmlid_copyfromxmlid.rst b/docs/source/api/v2/deliveryservices_xmlid_xmlid_urlkeys_copyfromxmlid_copyfromxmlid.rst deleted file mode 100644 index 000e81e66e..0000000000 --- a/docs/source/api/v2/deliveryservices_xmlid_xmlid_urlkeys_copyfromxmlid_copyfromxmlid.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-xmlid-xml_id-urlkeys-copyFrom_xml_id: - -******************************************************************************* -``deliveryservices/xmlId/{{xml_id}}/urlkeys/copyFromXmlId/{{copyFrom_xml_id}}`` -******************************************************************************* - -``POST`` -======== -Allows a user to copy URL signing keys from a specified :term:`Delivery Service` to another :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object (string) - -Request Structure ------------------ -.. table:: Request Path Parameters - - +-----------------+--------------------------------------------------------------------------------------+ - | 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 ------------------- -.. code-block:: json - :caption: Response Example - - { - "response": "Successfully copied and stored keys" - } diff --git a/docs/source/api/v2/deliveryservices_xmlid_xmlid_urlkeys_generate.rst b/docs/source/api/v2/deliveryservices_xmlid_xmlid_urlkeys_generate.rst deleted file mode 100644 index 79ed9bbcb5..0000000000 --- a/docs/source/api/v2/deliveryservices_xmlid_xmlid_urlkeys_generate.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryservices-xmlid-xmlid-urlkeys-generate: - -****************************************************** -``deliveryservices/xmlId/{{xml_id}}/urlkeys/generate`` -****************************************************** - -``POST`` -======== -Generates URL signing keys for a :term:`Delivery Service` - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object (string) - -Request Structure ------------------ -.. table:: Request Path Parameters - - +--------+-------------------------------------------------------------+ - | Name | Description | - +========+=============================================================+ - | xml_id | The :ref:`ds-xmlid` of the desired :term:`Delivery Service` | - +--------+-------------------------------------------------------------+ - -Response Structure ------------------- -.. code-block:: json - :caption: Response Example - - { - "response": "Successfully generated and stored keys" - } diff --git a/docs/source/api/v2/deliveryserviceserver.rst b/docs/source/api/v2/deliveryserviceserver.rst deleted file mode 100644 index 9e9d0187e9..0000000000 --- a/docs/source/api/v2/deliveryserviceserver.rst +++ /dev/null @@ -1,163 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryserviceserver: - -************************* -``deliveryserviceserver`` -************************* - -``GET`` -======= -Retrieve information about the assignment of servers to :term:`Delivery Services` - -:Auth. Required: Yes -:Roles Required: None\ [1]_ -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------+----------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Default | Description | - +===========+==========+===================+==============================================================================================================================================================================+ - | cdn | no | None | Limit the results to delivery service servers for the given CDN name | - +-----------+----------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | page | no | 0 | The page number for use in pagination - ``0`` means "no pagination" | - +-----------+----------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | limit | no | 20 | Limits the results to a maximum of this number - if pagination is used, this defines the number of results per page | - +-----------+----------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | orderby | no | "deliveryService" | Choose the ordering of the results - the value must either be the name of one of the fields of the objects in the ``response`` array or be empty to skip ordering altogether | - +-----------+----------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/deliveryserviceserver?page=1&limit=2&orderby=lastUpdated HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - - -Response Structure ------------------- -Unlike most API endpoints, this will return a JSON response body containing both a "response" object as well as other, top-level fields (besides the optional "alerts" field). For this reason, this section contains a "response" key, which normally is implicit. - -.. seealso:: :ref:`to-api-response-structure` - -:limit: The maximum size of the ``response`` array, also indicative of the number of results per page using the pagination requested by the query parameters (if any) - this should be the same as the ``limit`` query parameter (if given) -:orderby: A string that names the field by which the elements of the ``response`` array are ordered - should be the same as the ``orderby`` request query parameter (if given) -:response: An array of objects, each of which represents a server's :term:`Delivery Service` assignment - - :deliveryService: The integral, unique identifier of the :term:`Delivery Service` to which the server identified by ``server`` is assigned - :lastUpdated: The date and time at which the server's assignment to a :term:`Delivery Service` was last updated - :server: The integral, unique identifier of a server which is assigned to the :term:`Delivery Service` identified by ``deliveryService`` - -:size: The page number - if pagination was requested in the query parameters, else ``0`` to indicate no pagination - of the results represented by the ``response`` array. This is named "size" for legacy reasons - - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: J7sK8PohQWyTpTrMjjrWdlJwPj+Zyep/xutM25uVosL6cHgi30nXa6VMyOC5Y3vd9r5KLES8rTgR+qUQcZcJ/A== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 01 Nov 2018 14:27:45 GMT - Content-Length: 129 - - { "orderby": "lastUpdated", - "response": [ - { - "server": 8, - "deliveryService": 1, - "lastUpdated": "2018-11-01 14:10:38+00" - } - ], - "size": 1, - "limit": 2 - } - -.. [1] While no roles are required, this endpoint *does* respect tenancy permissions (pending `GitHub Issue #2978 `_\ ). - -``POST`` -======== -Assign a set of one or more servers to a :term:`Delivery Service` - -:Auth. Required: Yes -:Roles Required: "admin" or "operations"\ [2]_ -:Response Type: Object - -Request Structure ------------------ -:dsId: The integral, unique identifier of the :term:`Delivery Service` to which the servers identified in the ``servers`` array will be assigned -:replace: If ``true``, any existing assignments for a server identified in the ``servers`` array will be overwritten by this request -:servers: An array of integral, unique identifiers for servers which are to be assigned to the :term:`Delivery Service` identified by ``deliveryService`` - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/deliveryserviceserver HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 46 - Content-Type: application/x-www-form-urlencoded - - dsId=1&replace=true&servers=12 - -Response Structure ------------------- -:dsId: The integral, unique identifier of the :term:`Delivery Service` to which the servers identified by the elements of the ``servers`` array have been assigned -:replace: If ``true``, any existing assignments for a server identified in the ``servers`` array have been overwritten by this request -:servers: An array of integral, unique identifiers for servers which have been assigned to the :term:`Delivery Service` identified by ``deliveryService`` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: D+HhGhoxzaxvka9vZIStoaOZUpX23nz7zZnMbpFHNRO3MawyEaSb3GVUHQyCv6sDgwhpZZjRggDmctGCw88flg== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 01 Nov 2018 14:12:49 GMT - Content-Length: 123 - - { "alerts": [ - { - "text": "server assignements complete", - "level": "success" - } - ], - "response": { - "dsId": 1, - "replace": false, - "servers": [ 12 ] - }} - - -.. [2] Users with the "admin" or "operations" roles will be able to modify ALL server-to-Delivery-Service assignments, whereas all other users can only assign servers to the :term:`Delivery Services` their Tenant has permissions to edit. diff --git a/docs/source/api/v2/deliveryserviceserver_dsid_serverid.rst b/docs/source/api/v2/deliveryserviceserver_dsid_serverid.rst deleted file mode 100644 index e7ba4479d0..0000000000 --- a/docs/source/api/v2/deliveryserviceserver_dsid_serverid.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-deliveryserviceserver-dsid-serverid: - -*********************************************** -``deliveryserviceserver/{{DSID}}/{{serverID}}`` -*********************************************** - -``DELETE`` -========== -Removes a :term:`cache server` from a :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations"\ [1]_ -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +----------+----------+---------------------------------------------------------------+ - | Name | Required | Description | - +==========+==========+===============================================================+ - | dsId | yes | An integral, unique identifier for a :term:`Delivery Service` | - +----------+----------+---------------------------------------------------------------+ - | serverID | yes | An integral, unique identifier for a server | - +----------+----------+---------------------------------------------------------------+ - -.. note:: The server identified by ``serverID`` must be a :term:`cache server`, or the assignment will fail. - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: rGD2sOMHYF0sga1zuTytyLHCUkkc3ZwQRKvZ/HuPzObOP4WztKTOVXB4uhs3iJqBg9zRB2TucMxONHN+3/yShQ== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 01 Nov 2018 14:24:34 GMT - Content-Length: 80 - - { "alerts": [ - { - "text": "Server unlinked from delivery service.", - "level": "success" - } - ]} - -.. [1] Users with the "admin" or "operations" roles will be able to delete *any*:term:`Delivery Service`, whereas other users will only be able to delete :term:`Delivery Services` that their tenant has permissions to delete. diff --git a/docs/source/api/v2/divisions.rst b/docs/source/api/v2/divisions.rst deleted file mode 100644 index 65259aed50..0000000000 --- a/docs/source/api/v2/divisions.rst +++ /dev/null @@ -1,146 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-divisions: - -************* -``divisions`` -************* - -``GET`` -======= -Returns a JSON representation of all configured :term:`Divisions`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------+---------------------------------------------------------------------------------------------------------------+ - | Name | Description | - +===========+===============================================================================================================+ - | id | Filter for :term:`Divisions` having this integral, unique identifier | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | name | Filter for :term:`Divisions` with this name | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | orderby | Choose the ordering of the results - must be the name of one of the fields of the objects in the ``response`` | - | | array | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | sortOrder | Changes the order of sorting. Either ascending (default or "asc") or descending ("desc") | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | limit | Choose the maximum number of results to return | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | offset | The number of results to skip before beginning to return results. Must use in conjunction with limit | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | page | 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``. | - +-----------+---------------------------------------------------------------------------------------------------------------+ - -Response Structure ------------------- -:id: An integral, unique identifier for this Division -:lastUpdated: The date and time at which this Division was last modified, in :ref:`non-rfc-datetime` -:name: The Division name - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: SLKi9RHa67sGoSz62IDcQsk7KZjTXKfonqMoCUFPXGcNUdhBssvUjc1G7KkWK8X1Ny16geMx2BN8Hm/3dQ75GA== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 29 Nov 2018 19:44:03 GMT - Content-Length: 139 - - { "response": [ - { - "id": 1, - "lastUpdated": "2018-11-29 18:38:28+00", - "name": "Quebec" - }, - { - "id": 2, - "lastUpdated": "2018-11-29 18:38:28+00", - "name": "USA" - } - ]} - - -``POST`` -======== -Creates a new Division. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -:name: The name of the new Division - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/divisions HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 16 - Content-Type: application/json - - {"name": "test"} - -Response Structure ------------------- -:id: An integral, unique identifier for this Division -:lastUpdated: The date and time at which this Division was last modified, in :ref:`non-rfc-datetime` -:name: The Division name - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: +pJm4c3O+JTaSXNt+LP+u240Ba/SsvSSDOQ4rDc6hcyZ0FIL+iY/WWrMHhpLulRGKGY88bM4YPCMaxGn3FZ9yQ== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 29 Nov 2018 19:52:06 GMT - Content-Length: 136 - - { "alerts": [ - { - "text": "division was created.", - "level": "success" - } - ], - "response": { - "id": 3, - "lastUpdated": "2018-11-29 19:52:06+00", - "name": "test" - }} diff --git a/docs/source/api/v2/divisions_id.rst b/docs/source/api/v2/divisions_id.rst deleted file mode 100644 index 715b34a7be..0000000000 --- a/docs/source/api/v2/divisions_id.rst +++ /dev/null @@ -1,87 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-divisions-id: - -******************** -``divisions/{{ID}}`` -******************** - -``PUT`` -======= -Updates a specific Division - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" - - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-----------------------------------------------------------+ - | Name | Description | - +======+===========================================================+ - | ID | The integral, unique identifier of the requested Division | - +------+-----------------------------------------------------------+ - - -:name: The new name of the Division - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/divisions/3 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 17 - Content-Type: application/json - - {"name": "quest"} - -Response Structure ------------------- -:id: An integral, unique identifier for this Division -:lastUpdated: The date and time at which this Division was last modified, in :ref:`non-rfc-datetime` -:name: The Division name - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: yBd8MzBR/Qbc/xts44WEIFRTrqeMKZwUe2ufpm6JH6frh1UjFmYRs3/B7E5FTruFWRTuvEIlx5EpDmp3f9LjzA== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 29 Nov 2018 20:10:36 GMT - Content-Length: 137 - - { "alerts": [ - { - "text": "division was updated.", - "level": "success" - } - ], - "response": { - "id": 3, - "lastUpdated": "2018-11-29 20:10:36+00", - "name": "quest" - }} diff --git a/docs/source/api/v2/federation_resolvers.rst b/docs/source/api/v2/federation_resolvers.rst deleted file mode 100644 index 46bd6e77aa..0000000000 --- a/docs/source/api/v2/federation_resolvers.rst +++ /dev/null @@ -1,230 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-federation_resolvers: - -************************ -``federation_resolvers`` -************************ - -``GET`` -======= -Retrieves :term:`Federation` Resolvers. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------------+----------+-----------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +============+==========+=====================================================================================================+ - | id | no | Return only the Federation Resolver identified by this integral, unique identifier | - +------------+----------+-----------------------------------------------------------------------------------------------------+ - | ipAddress | no | Return only the Federation Resolver(s) that has/have this IP Address | - +------------+----------+-----------------------------------------------------------------------------------------------------+ - | type | no | Return only the Federation Resolvers of this :term:`Type` | - +------------+----------+-----------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/federation_resolvers?type=RESOLVE6 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.63.0 - Accept: */* - Cookie: mojolicious=... - - -Response Structure ------------------- -:id: The integral, unique identifier of the resolver -:ipAddress: The IP address or :abbr:`CIDR (Classless Inter-Domain Routing)`-notation subnet of the resolver - may be IPv4 or IPv6 -:lastUpdated: The date and time at which this resolver was last updated, in :ref:`non-rfc-datetime` -:type: The :term:`Type` of the resolver - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 4TLkULAOAuap47H+hpwyf2lHjDbHbSNQHLMj7BCTHtps2CQxCuq7mwctbwqmPdmAjLOUXAIRsHmvSuAp4K64jw== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 06 Nov 2019 00:03:56 GMT - Content-Length: 101 - - { "response": [ - { - "id": 1, - "ipAddress": "::1/1", - "lastUpdated": "2019-11-06 00:00:40+00", - "type": "RESOLVE6" - } - ]} - - -``POST`` -======== -Creates a new federation resolver. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: Object - -Request Structure ------------------ -:ipAddress: The IP address of the resolver - may be IPv4 or IPv6 -:typeId: The integral, unique identifier of the :term:`Type` of resolver being created - - .. caution:: This field should only ever be an identifier for one of the :term:`Types` "RESOLVE4" or "RESOLVE6", but there is **no protection for this built into Traffic Ops** and therefore **any valid** :term:`Type` **identifier will be silently accepted by Traffic Ops** and so care should be taken to ensure that these :term:`Types` are properly identified. If any :term:`Type` besides "RESOLVE4" or "RESOLVE6" is identified, the resulting resolver *will* **not** *work*. - - .. seealso:: :ref:`to-api-types` is the endpoint that can be used to determine the identifier for various :term:`Types` - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/federation_resolvers HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.63.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 36 - Content-Type: application/json - - { - "ipAddress": "::1/1", - "typeId": 37 - } - -Response Structure ------------------- -:id: The integral, unique identifier of the resolver -:ipAddress: The IP address or :abbr:`CIDR (Classless Inter-Domain Routing)`-notation subnet of the resolver - may be IPv4 or IPv6 -:type: The :term:`Type` of the resolver -:typeId: The integral, unique identifier of the :term:`Type` of the resolver - - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: e9D8JNrQb64xpuDwoBwbISSWUkDGCL2l37NuDXsXsPYof2EqmeHondD8NzxDSwWNJ8d9B9DXpZDbRUtgdXR8BQ== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 06 Nov 2019 00:00:40 GMT - Content-Length: 153 - - { "alerts": [ - { - "text": "Federation Resolver created [ IP = ::1/1 ] with id: 1", - "level": "success" - } - ], - "response": { - "id": 1, - "ipAddress": "::1/1", - "type": "RESOLVE6", - "typeId": 37 - }} - -``DELETE`` -========== -Deletes a federation resolver. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------+----------------------------------------------------------------------------------+ - | Name | Required | Description | - +======+==========+=======================================================================+ - | id | yes | Integral, unique identifier for the federation resolver to be deleted | - +------+----------+-----------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/federation_resolvers?id=4 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 ------------------- -:id: The integral, unique identifier of the resolver -:ipAddress: The IP address or :abbr:`CIDR (Classless Inter-Domain Routing)`-notation subnet of the resolver - may be IPv4 or IPv6 -:type: The :term:`Type` of the resolver - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; HttpOnly - Whole-Content-Sha512: 2v4LYQdRVhaFJVd86Iv1BWVYzNPSlzpQ222bUB7Zz+Ss8A48FNyHZjPlq5a+a4g9KAQCTUIytWnIQk+L1fF6FQ== - X-Server-Name: traffic_ops_golang/ - Date: Fri, 08 Nov 2019 23:19:01 GMT - Content-Length: 161 - - { "alerts": [ - { - "text": "Federation resolver deleted [ IP = 1.2.6.4/22 ] with id: 4", - "level": "success" - } - ], - "response": { - "id": 4, - "ipAddress": "1.2.6.4/22", - "type": "RESOLVE6" - }} diff --git a/docs/source/api/v2/federations.rst b/docs/source/api/v2/federations.rst deleted file mode 100644 index 77065aca2a..0000000000 --- a/docs/source/api/v2/federations.rst +++ /dev/null @@ -1,259 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-federations: - -*************** -``federations`` -*************** - -``GET`` -======= -Retrieves a list of :term:`Federation` mappings (i.e. :term:`Federation` Resolvers) for the current user. - -:Auth. Required: Yes -:Roles Required: "admin", "Federation", "operations", "Portal", or "Steering" -:Response Type: Array - -Request Structure ------------------ -No parameters available. - -Response Structure ------------------- -:deliveryService: The ``xml_id`` that uniquely identifies the :term:`Delivery Service` that uses the federation mappings in ``mappings`` -:mappings: An array of objects that represent the mapping of a :term:`Federation`'s :abbr:`CNAME (Canonical Name)` to one or more Resolvers - - :cname: The actual CNAME used by the :term:`Federation` - :resolve4: An array of IPv4 addresses (or subnets in :abbr:`CIDR (Classless Inter-Domain Routing)` notation) capable of resolving the :term:`Federation`'s CNAME - :resolve6: An array of IPv6 addresses (or subnets in :abbr:`CIDR (Classless Inter-Domain Routing)` notation) capable of resolving the :term:`Federation`'s CNAME - :ttl: The :abbr:`TTL (Time To Live)` of the CNAME in hours - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: d6Llm5qNc2sfgVH9IimW7hA4wvtBUq6EzUmpJf805kB0k6v2WysNgFEWK4hBXNdAYkr8hYuKPrwDy3tCx0OZ8Q== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 03 Dec 2018 17:19:13 GMT - Content-Length: 136 - - { "response": [ - { - "mappings": [ - { - "ttl": 300, - "cname": "blah.blah.", - "resolve4": [ - "0.0.0.0/32" - ], - "resolve6": [ - "::/128" - ] - } - ], - "deliveryService": "demo1" - } - ]} - - -``POST`` -======== -Allows a user to create :term:`Federation` Resolvers for :term:`Delivery Services`, providing the :term:`Delivery Service` is within a CDN that has some associated :term:`Federation`. - -.. warning:: Confusingly, this method of this endpoint does **not** create a new :term:`Federation`; to do that, the :ref:`to-api-cdns-name-federations` endpoint must be used. Furthermore, the :term:`Federation` must properly be assigned to a :term:`Delivery Service` using the :ref:`to-api-federations-id-deliveryservices` and assigned to the user creating Resolvers using :ref:`to-api-federations-id-users`. - -.. seealso:: The :ref:`to-api-federations-id-federation_resolvers` endpoint duplicates this functionality. - -:Auth. Required: Yes -:Roles Required: "admin", "Federation", "operations", "Portal", or "Steering" -:Response Type: Object (string) - -Request Structure ------------------ - -The request payload is an array of objects that describe Delivery Service :term:`Federation` Resolver mappings. Each object in the array must be in the following format. - -:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` which will use the :term:`Federation` Resolvers specified in ``mappings`` -:mappings: An object containing two arrays of IP addresses (or subnets in :abbr:`CIDR (Classless Inter-Domain Routing)` notation) to use as :term:`Federation` Resolvers - - :resolve4: An array of IPv4 addresses (or subnets in :abbr:`CIDR (Classless Inter-Domain Routing)` notation) that can resolve the :term:`Delivery Service`'s :term:`Federation` - :resolve6: An array of IPv6 addresses (or subnets in :abbr:`CIDR (Classless Inter-Domain Routing)` notation) that can resolve the :term:`Delivery Service`'s :term:`Federation` - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/federations HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 118 - Content-Type: application/json - - - [{ - "deliveryService":"demo1", - "mappings":{ - "resolve4":["127.0.0.1", "0.0.0.0/32"], - "resolve6":["::1", "5efa::ff00/128"] - } - }] - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: B7TSUOYZPRPyi3mVy+CuxiXR5k/d0s07w4i6kYzpWS+YL79juEfkuSqfedaYG/kMA8O9XbjkWRjcBAdxOVrdTQ== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 23 Oct 2019 22:28:02 GMT - Content-Length: 152 - - { "alerts": [ - { - "text": "admin successfully created federation resolvers.", - "level": "success" - } - ], - "response": "admin successfully created federation resolvers." - } - - -``DELETE`` -========== -Deletes **all** :term:`Federation` Resolvers associated with the logged-in user's :term:`Federations`. - -:Auth. Required: Yes -:Roles Required: "admin", "Federation", "operations", "Portal", or "Steering" -:Response Type: Object (string) - -Request Structure ------------------ -No parameters available - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/federations HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: fd7P45mIiHuYqZZW6+8K+YjY1Pe504Aaw4J4Zp9AhrqLX72ERytTqWtAp1msutzNSRUdUSC72+odNPtpv3O8uw== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 23 Oct 2019 23:34:53 GMT - Content-Length: 184 - - { "alerts": [ - { - "text": "admin successfully deleted all federation resolvers: [ 8.8.8.8 ]", - "level": "success" - } - ], - "response": "admin successfully deleted all federation resolvers: [ 8.8.8.8 ]" - } - -``PUT`` -======= -Replaces **all** :term:`Federations` associated with a user's :term:`Delivery Service`\ (s) with those defined inside the request payload. - -:Auth. Required: Yes -:Roles Required: "admin", "Federation", "operations", "Portal", or "Steering" -:Response Type: Object (string) - -Request Structure ------------------ -The request payload is an array of objects that describe Delivery Service :term:`Federation` Resolver mappings. Each object in the array must be in the following format. - -:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` which will use the :term:`Federation` Resolvers specified in ``mappings`` -:mappings: An object containing two arrays of IP addresses (or subnets in :abbr:`CIDR (Classless Inter-Domain Routing)` notation) to use as :term:`Federation` Resolvers - - :resolve4: An array of IPv4 addresses (or subnets in :abbr:`CIDR (Classless Inter-Domain Routing)` notation) that can resolve the :term:`Delivery Service`'s :term:`Federation` - :resolve6: An array of IPv6 addresses (or subnets in :abbr:`CIDR (Classless Inter-Domain Routing)` notation) that can resolve the :term:`Delivery Service`'s :term:`Federation` - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/federations HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 95 - Content-Type: application/json - - [{ "mappings": { - "resolve4": ["8.8.8.8"], - "resolve6": [] - }, - "deliveryService":"demo1" - }] - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: dQ5AvQULhc254zQwgUpBl1/CHbLr/clKtkbs0Ju9f1BM4xIfbbO3puFNN9zaEaZ1iz0lBvHFp/PgfUqisD3QHA== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 23 Oct 2019 23:22:03 GMT - Content-Length: 258 - Content-Type: application/json - - { "alerts": [ - { - "text": "admin successfully deleted all federation resolvers: [ 8.8.8.8 ]", - "level": "success" - }, - { - "text": "admin successfully created federation resolvers.", - "level": "success" - } - ], - "response": "admin successfully created federation resolvers." - } diff --git a/docs/source/api/v2/federations_all.rst b/docs/source/api/v2/federations_all.rst deleted file mode 100644 index 0e4aab51c9..0000000000 --- a/docs/source/api/v2/federations_all.rst +++ /dev/null @@ -1,93 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-federations-all: - -******************* -``federations/all`` -******************* - -``GET`` -======= -Retrieves a list of :term:`Federation` mappings (also called :term:`Federation` Resolvers) for the current user. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: Array - -Request Structure ------------------ -No parameters available. - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/federations/all HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - -Response Structure ------------------- -:deliveryService: The :ref:`ds-xmlid` of the delivery service. -:mappings: An array of objects that represent the mapping of a :term:`Federation`'s :abbr:`CNAME (Canonical Name)` to one or more Resolvers - - :cname: The actual CNAME used by the :term:`Federation` - :ttl: The :abbr:`TTL (Time To Live)` of the CNAME in hours - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Sun, 23 Feb 2020 21:38:06 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: UQBlGVPJytYMkv0V42EAIoJUnXjBTCXnOGpOberxte6TtnX63LTAKFfD2LejBVYXkKtnCdkBbs+SzhA0H1zdog== - X-Server-Name: traffic_ops_golang/ - Date: Sun, 23 Feb 2020 20:38:06 GMT - Content-Length: 138 - - { - "response": [ - { - "mappings": [ - { - "ttl": 60, - "cname": "img1.mcdn.ciab.test." - }, - { - "ttl": 60, - "cname": "img2.mycdn.ciab.test." - } - ], - "deliveryService": "demo1" - }, - { - "mappings": [ - { - "ttl": 60, - "cname": "static.mycdn.ciab.test." - } - ], - "deliveryService": "demo2" - } - ] - } diff --git a/docs/source/api/v2/federations_id_deliveryservices.rst b/docs/source/api/v2/federations_id_deliveryservices.rst deleted file mode 100644 index 8157bffee3..0000000000 --- a/docs/source/api/v2/federations_id_deliveryservices.rst +++ /dev/null @@ -1,173 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-federations-id-deliveryservices: - -*************************************** -``federations/{{ID}}/deliveryservices`` -*************************************** - -``GET`` -======= -Retrieves :term:`Delivery Services` assigned to a :term:`Federation`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+--------------------------------------------------------------------+ - | Name | Description | - +======+====================================================================+ - | ID | The integral, unique identifier for the federation to be inspected | - +------+--------------------------------------------------------------------+ - -.. table:: Request Query Parameters - - +-----------+----------+--------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+======================================================================================================================================+ - | 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 | - +-----------+----------+--------------------------------------------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/federations/1/deliveryservices HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:cdn: The CDN to which this :term:`Delivery Service` Belongs -:id: The integral, unique identifier for the :term:`Delivery Service` -:type: The routing type used by this :term:`Delivery Service` -:xmlId: The 'xml_id' which uniquely identifies this :term:`Delivery Service` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - access-control-allow-credentials: true - access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept - access-control-allow-methods: POST,GET,OPTIONS,PUT,DELETE - access-control-allow-origin: * - cache-control: no-cache, no-store, max-age=0, must-revalidate - content-type: application/json - date: Wed, 05 Dec 2018 00:44:13 GMT - X-Server-Name: traffic_ops_golang/ - set-cookie: mojolicious=...; expires=Wed, 05 Dec 2018 04:44:13 GMT; path=/; HttpOnly - vary: Accept-Encoding - whole-content-sha512: 7Y9Q/qHeXfbjJduvucRCR85wf4VRfyYhlK59sNRkzIJuwnsMhFcEfYfNqrvELwfexOum/VEX2f/1oa+I/edGfw== - content-length: 74 - - { "response": [ - { - "xmlId": "demo1", - "cdn": "CDN-in-a-Box", - "type": "HTTP", - "id": 1 - } - ]} - -``POST`` -======== -Assigns one or more :term:`Delivery Services` to a federation. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+--------------------------------------------------------------------+ - | Name | Description | - +======+====================================================================+ - | ID | The integral, unique identifier for the federation to be inspected | - +------+--------------------------------------------------------------------+ - -:dsIds: An array of integral, unique identifiers for :term:`Delivery Services` which will be assigned to this federation -:replace: An optional boolean (default: ``false``) which, if ``true``, will cause any conflicting assignments already in place to be overridden by this request - - .. note:: If ``replace`` is not given (and/or not ``true``), then any conflicts with existing assignments will cause the entire operation to fail. - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/federations/1/deliveryservices HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 32 - Content-Type: application/json - - { - "dsIds": [1], - "replace": true - } - -Response Structure ------------------- -:dsIds: An array of integral, unique identifiers for :term:`Delivery Services` which are now assigned to this federation -:replace: An optional boolean (default: ``false``) which, if ``true``, means any conflicting assignments already in place were overridden by this request - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - access-control-allow-credentials: true - access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - access-control-allow-methods: POST,GET,OPTIONS,PUT,DELETE - access-control-allow-origin: * - content-type: application/json - set-cookie: mojolicious=...; Path=/; HttpOnly - whole-content-sha512: rVd0nx8G3bRI8ub1zw6FTdmwQ7jer4zoqzOZf5tC1ckrR0HEIOH1Azdcmvv0FVE5I0omcHVnrYbzab7tUtmnog== - x-server-name: traffic_ops_golang/ - content-length: 137 - date: Wed, 05 Dec 2018 00:34:06 GMT - - { "alerts": [ - { - "text": "1 delivery service(s) were assigned to the federation 1", - "level": "success" - } - ], - "response": { - "dsIds": [ - 1 - ], - "replace": true - }} - diff --git a/docs/source/api/v2/federations_id_deliveryservices_id.rst b/docs/source/api/v2/federations_id_deliveryservices_id.rst deleted file mode 100644 index 291f8c3b02..0000000000 --- a/docs/source/api/v2/federations_id_deliveryservices_id.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-federations-id-deliveryservices-id: - -************************************************ -``federations/{{ID}}/deliveryservices/{{dsID}}`` -************************************************ - -``DELETE`` -========== -Removes a :term:`Delivery Service` from a federation. A :term:`Delivery Service` cannot be removed from a federation if it is the only :term:`Delivery Service` assigned to said federation - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+----------------------------------------------------------------------------------------------------------------------------------+ - | Name | Description | - +======+==================================================================================================================================+ - | ID | The integral, unique identifier of the federation from which the :term:`Delivery Service` identified by ``dsID`` will be removed | - +------+----------------------------------------------------------------------------------------------------------------------------------+ - | dsID | The integral, unique identifier of the :term:`Delivery Service` which will be removed from the federation identified by ``ID`` | - +------+----------------------------------------------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/federations/1/deliveryservices/1 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - access-control-allow-credentials: true - access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept - access-control-allow-methods: POST,GET,OPTIONS,PUT,DELETE - access-control-allow-origin: * - cache-control: no-cache, no-store, max-age=0, must-revalidate - content-type: application/json - date: Wed, 05 Dec 2018 01:06:51 GMT - X-Server-Name: traffic_ops_golang/ - set-cookie: mojolicious=...; expires=Wed, 05 Dec 2018 05:06:51 GMT; path=/; HttpOnly - vary: Accept-Encoding - whole-content-sha512: NqAZuZYlF1UWOaazbj/j4gWX7ye0kGGakRRFEkK6ShxqXvCxE0dCTyu75qiLPN2wSgr3FGQnp2Sq345sE7In9g== - content-length: 98 - - { "alerts": [ - { - "level": "success", - "text": "federation deliveryservice was deleted." - } - ]} diff --git a/docs/source/api/v2/federations_id_federation_resolvers.rst b/docs/source/api/v2/federations_id_federation_resolvers.rst deleted file mode 100644 index 71774500d3..0000000000 --- a/docs/source/api/v2/federations_id_federation_resolvers.rst +++ /dev/null @@ -1,157 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-federations-id-federation_resolvers: - -******************************************* -``federations/{{ID}}/federation_resolvers`` -******************************************* - -``GET`` -======= -Retrieves federation resolvers assigned to a federation. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+------------------------------------------------------------------------------------------+ - | Name | Description | - +======+==========================================================================================+ - | ID | The integral, unique identifier for the federation for which resolvers will be retrieved | - +------+------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/federations/1/federation_resolvers HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:id: The integral, unique identifier of this federation resolver -:ipAddress: The IP address of the federation resolver - may be IPv4 or IPv6 -:type: The type of resolver - one of: - - RESOLVE4 - This resolver is for IPv4 addresses (and ``ipAddress`` is IPv4) - RESOLVE6 - This resolver is for IPv6 addresses (and ``ipAddress`` is IPv6) - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - access-control-allow-credentials: true - access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept - access-control-allow-methods: POST,GET,OPTIONS,PUT,DELETE - access-control-allow-origin: * - cache-control: no-cache, no-store, max-age=0, must-revalidate - content-type: application/json - date: Wed, 05 Dec 2018 00:49:50 GMT - X-Server-Name: traffic_ops_golang/ - set-cookie: mojolicious=...; expires=Wed, 05 Dec 2018 04:49:50 GMT; path=/; HttpOnly - vary: Accept-Encoding - whole-content-sha512: csC18kE3YjiILHP1wmJg7V4h/XWY8HUMKyPuZWnde2g7HJ4gTY51HfjCSqhyKvIJQ8Rl7uEqshF3Ey6xIMOX4A== - content-length: 63 - - { "response": [ - { - "ipAddress": "0.0.0.0", - "type": "RESOLVE4", - "id": 1 - } - ]} - -``POST`` -======== -Assigns one or more resolvers to a federation. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+------------------------------------------------------------------------------------------+ - | Name | Description | - +======+==========================================================================================+ - | ID | The integral, unique identifier for the federation for which resolvers will be retrieved | - +------+------------------------------------------------------------------------------------------+ - -:fedResolverIds: An array of integral, unique identifiers for federation resolvers -:replace: An optional boolean (default: ``false``) which, if ``true``, will cause any conflicting assignments already in place to be overridden by this request - - .. note:: If ``replace`` is not given (and/or not ``true``), then any conflicts with existing assignments will cause the entire operation to fail. - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/federations/1/federation_resolvers HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 41 - Content-Type: application/json - - { - "fedResolverIds": [1], - "replace": true - } - -Response Structure ------------------- -:fedResolverIds: An array of integral, unique identifiers for federation resolvers -:replace: An optionally-present boolean (default: ``false``) which, if ``true``, any conflicting assignments already in place were overridden by this request - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - access-control-allow-credentials: true - access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept - access-control-allow-methods: POST,GET,OPTIONS,PUT,DELETE - access-control-allow-origin: * - cache-control: no-cache, no-store, max-age=0, must-revalidate - content-type: application/json - date: Wed, 05 Dec 2018 00:47:47 GMT - X-Server-Name: traffic_ops_golang/ - set-cookie: mojolicious=...; expires=Wed, 05 Dec 2018 04:47:47 GMT; path=/; HttpOnly - vary: Accept-Encoding - whole-content-sha512: +JDcRByS3HO6pMg3Gzkvn0w7/v5oRul9e+RxyFIOKJKNHOkZILyQBS+PJpxDeCgwI19+0poW5dyHPPR9SwbNCA== - content-length: 148 - - { "alerts": [ - { - "level": "success", - "text": "1 resolver(s) were assigned to the test.quest. federation" - } - ], - "response": { - "replace": true, - "fedResolverIds": [ - 1 - ] - }} diff --git a/docs/source/api/v2/federations_id_users.rst b/docs/source/api/v2/federations_id_users.rst deleted file mode 100644 index d9ad61da29..0000000000 --- a/docs/source/api/v2/federations_id_users.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-federations-id-users: - -**************************** -``federations/{{ID}}/users`` -**************************** - -``GET`` -======= -Retrieves users assigned to a federation. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-------------------------------------------------------------------------------------+ - | Name | Description | - +======+=====================================================================================+ - | ID | The integral, unique identifier of the federation for which users will be retrieved | - +------+-------------------------------------------------------------------------------------+ - -.. table:: Request Query Parameters - - +-----------+----------+--------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+======================================================================================================================================+ - | userID | no | Show only the user that has this integral, unique identifier | - +-----------+----------+--------------------------------------------------------------------------------------------------------------------------------------+ - | role | no | Show only the users that have this role | - +-----------+----------+--------------------------------------------------------------------------------------------------------------------------------------+ - | 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``. | - +-----------+----------+--------------------------------------------------------------------------------------------------------------------------------------+ - -Response Structure ------------------- -:company: The company to which the user belongs -:email: The user's email address -:fullName: The user's full name -:id: An integral, unique identifier for the user -:role: The user's highest role -:username: The user's short "username" - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - access-control-allow-credentials: true - access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept - access-control-allow-methods: POST,GET,OPTIONS,PUT,DELETE - access-control-allow-origin: * - cache-control: no-cache, no-store, max-age=0, must-revalidate - content-type: application/json - date: Wed, 05 Dec 2018 00:31:34 GMT - X-Server-Name: traffic_ops_golang/ - set-cookie: mojolicious=...; expires=Wed, 05 Dec 2018 04:31:34 GMT; path=/; HttpOnly - vary: Accept-Encoding - whole-content-sha512: eQQoF2xlbK2I2oTja7zrt/FlkLzCgwpU2zb2+rmIjHbHJ3MnmsSczSamIAAyTzs5gDaqcuUX1G35ZB8d7Bj82g== - content-length: 101 - - { "response": [ - { - "fullName": null, - "email": null, - "id": 2, - "role": "admin", - "company": null, - "username": "admin" - } - ]} - - -``POST`` -======== -Assigns one or more users to a federation. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: Object - -Request Structure ------------------ -:userIds: An array of integral, unique identifiers for users which will be assigned to this federation -:replace: An optional boolean (default: ``false``) which, if ``true``, will cause any conflicting assignments already in place to be overridden by this request - - .. note:: If ``replace`` is not given (and/or not ``true``), then any conflicts with existing assignments will cause the entire operation to fail. - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/federations/1/users HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 34 - Content-Type: application/json - - { - "userIds": [2], - "replace": true - } - -Response Structure ------------------- -:userIds: An array of integral, unique identifiers for users which have been assigned to this federation -:replace: An optional boolean (default: ``false``) which, if ``true``, caused any conflicting assignments already in place to be overridden by this request - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - access-control-allow-credentials: true - access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept - access-control-allow-methods: POST,GET,OPTIONS,PUT,DELETE - access-control-allow-origin: * - cache-control: no-cache, no-store, max-age=0, must-revalidate - content-type: application/json - date: Wed, 05 Dec 2018 00:29:19 GMT - X-Server-Name: traffic_ops_golang/ - set-cookie: mojolicious=...; expires=Wed, 05 Dec 2018 04:29:19 GMT; path=/; HttpOnly - vary: Accept-Encoding - whole-content-sha512: MvPmgOAs58aSOGvh+iEilflgOexbaexg+qE2IPrQZX0H4iSX4JvEys9adbGE9a9yaLj9uUMxg77N6ZyDhVqsbQ== - content-length: 137 - - { "alerts": [ - { - "level": "success", - "text": "1 user(s) were assigned to the test.quest. federation" - } - ], - "response": { - "userIds": [ - 2 - ], - "replace": true - }} diff --git a/docs/source/api/v2/federations_id_users_id.rst b/docs/source/api/v2/federations_id_users_id.rst deleted file mode 100644 index 6d32e8d13d..0000000000 --- a/docs/source/api/v2/federations_id_users_id.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-federations-id-users-id: - -*************************************** -``federations/{{ID}}/users/{{userID}}`` -*************************************** - -``DELETE`` -========== -Removes a user from a federation. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +--------+----------------------------------------------------------------------------------------------------------------+ - | Name | Description | - +========+================================================================================================================+ - | ID | An integral, unique identifier for the federation from which the user identified by ``userID`` will be removed | - +--------+----------------------------------------------------------------------------------------------------------------+ - | userID | An integral, unique identifier for the user who will be removed from the federation identified by ``ID`` | - +--------+----------------------------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Structure - - DELETE /api/2.0/federations/1/users/2 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - access-control-allow-credentials: true - access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept - access-control-allow-methods: POST,GET,OPTIONS,PUT,DELETE - access-control-allow-origin: * - cache-control: no-cache, no-store, max-age=0, must-revalidate - content-type: application/json - date: Wed, 05 Dec 2018 01:14:04 GMT - X-Server-Name: traffic_ops_golang/ - set-cookie: mojolicious=...; expires=Wed, 05 Dec 2018 05:14:04 GMT; path=/; HttpOnly - vary: Accept-Encoding - whole-content-sha512: xdF6l7jdd2t8au6lh4pFtDqYxTfehzke2aDBuytL7I74hK9KCT7ssLuYbfvD8ejdqqF3+jiBiFk7neQ8c4vVUQ== - content-length: 93 - - { "alerts": [ - { - "level": "success", - "text": "Removed user [ admin ] from federation [ foo.bar. ]" - } - ]} diff --git a/docs/source/api/v2/isos.rst b/docs/source/api/v2/isos.rst deleted file mode 100644 index 0a046c6dd1..0000000000 --- a/docs/source/api/v2/isos.rst +++ /dev/null @@ -1,109 +0,0 @@ -.. -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-isos: - -******** -``isos`` -******** - -``POST`` -======== -Generates an ISO from the requested ISO source. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: undefined - ISO image as a streaming download - -Request Structure ------------------ -:dhcp: A string that specifies whether the generated system image will use DHCP IP address leasing; one of: - - yes - DHCP will be used, and other network configuration keys need not be present in the request (and are ignored if they are) - no - DHCP will not be used, and the desired network configuration **must** be specified manually in the request body - -:disk: An optional string that names the block device (under ``/dev/``) used for the boot media, e.g. "sda" -: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, an :abbr:`LACP (Link Aggregation Control Protocol)` binding configuration will be created and included in the system image - - .. seealso:: `The Link Aggregation Wikipedia page `_\ . - -:ip6Address: An optional string containing the IPv6 address of the generated system image -:ip6Gateway: An optional string specifying the IPv6 address of the generated system image's network gateway - this will be ignored if ``ipGateway`` is specified -:ipAddress: An optional\ [1]_ string containing the IP address of the generated system image -:ipGateway: An optional\ [1]_ string specifying the IP address of the generated system image's network gateway -:ipNetmask: An optional\ [1]_ string specifying the subnet mask of the generated system image -:osversionDir: The name of the directory containing the ISO source - - .. seealso:: :ref:`to-api-osversions` - -:rootPass: The password used by the generated system image's ``root`` user - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/isos HTTP/1.1 - Host: some.trafficops.host - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 334 - Content-Type: application/json - - { - "osversionDir": "centos72", - "hostName": "test", - "domainName": "quest", - "rootPass": "twelve", - "dhcp": "no", - "interfaceMtu": 1500, - "ipAddress": "1.3.3.7", - "ipNetmask": "255.255.255.255", - "ipGateway": "8.0.0.8", - "ip6Address": "1::3:3:7", - "ip6Gateway": "8::8", - "interfaceName": "eth0", - "disk": "hda" - } - -.. [1] This optional key is required if and only if ``dhcp`` is "no". - -Response Structure ------------------- -ISO image as a streaming download. - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Connection: keep-alive - Content-Disposition: attachment; filename="test-centos72_centos72-netinstall.iso" - Content-Encoding: gzip - Content-Type: application/download - Date: Wed, 05 Feb 2020 21:59:15 GMT - Set-Cookie: mojolicious=...; Path=/; Expires=Wed, 05 Feb 2020 22:59:11 GMT; Max-Age=3600; HttpOnly - Transfer-Encoding: chunked - Whole-Content-sha512: sLSVQGrLCQ4hGQhv2reragQHWNi2aKMcz2c/HMAH45tLcZ1LenPyOzWRcRfHUNbV4PEEKOoiTfwE2HlA+WtRIQ== - X-Server-Name: traffic_ops_golang/ - diff --git a/docs/source/api/v2/jobs.rst b/docs/source/api/v2/jobs.rst deleted file mode 100644 index 487996bb3b..0000000000 --- a/docs/source/api/v2/jobs.rst +++ /dev/null @@ -1,391 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-jobs: - -******** -``jobs`` -******** - -``GET`` -======= -Retrieve :term:`Content Invalidation Jobs`. - -:Auth. Required: Yes -:Roles Required: None\ [#tenancy]_ -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +======================+==========+==================================================================================================================================================================+ - | assetUrl | no | Return only :term:`Content Invalidation Jobs` that operate on URLs by matching this regular expression | - +----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | cdn | no | Return only :term:`Content Invalidation Jobs` for delivery services with this CDN name | - +----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | createdBy | no | Return only :term:`Content Invalidation Jobs` that were created by the user with this username | - +----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | deliveryService | no | Return only :term:`Content Invalidation Jobs` that operate on the :term:`Delivery Service` with this :ref:`ds-xmlid` | - +----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | dsId | no | Return only :term:`Content Invalidation Jobs` pending on the :term:`Delivery Service` identified by this integral, unique identifier | - +----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | id | no | Return only the single :term:`Content Invalidation Job` identified by this integral, unique identifer | - +----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | keyword | no | Return only :term:`Content Invalidation Jobs` that have this "keyword" - only "PURGE" should exist | - +----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | maxRevalDurationDays | no | Return only :term:`Content Invalidation Jobs` with a startTime that is within the window defined by the ``maxRevalDurationDays`` :term:`Parameter` in | - | | | :ref:`the-global-profile` | - +----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | userId | no | Return only :term:`Content Invalidation Jobs` created by the user identified by this integral, unique identifier | - +----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/jobs?id=3&dsId=1&userId=2 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: python-requests/2.20.1 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - -Response Structure ------------------- -:assetUrl: A regular expression - matching URLs will be operated upon according to ``keyword`` -:createdBy: The username of the user who initiated the :term:`job` -:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which this :term:`job` operates -:id: An integral, unique identifier for this :term:`job` -:keyword: A keyword that represents the operation being performed by the :term:`job`: - - PURGE - This :term:`job` will prevent caching of URLs matching the ``assetUrl`` until it is removed (or its Time to Live expires) - -:parameters: A string containing key/value pairs representing parameters associated with the :term:`job` - currently only uses Time to Live e.g. ``"TTL:48h"`` -:startTime: The date and time at which the :term:`job` began, in a non-standard format - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-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: gH41oEi2zrd3y8yo+wfohn4/oHU098RpyPnqBzU7HlLUDkMOPKjAZnamcYqfdy7yDCFDUcgqkvbFAvnljxyb8w== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 18 Jun 2019 19:47:30 GMT - Content-Length: 186 - - { "response": [{ - "assetUrl": "http://origin.infra.ciab.test/.*", - "createdBy": "admin", - "deliveryService": "demo1", - "id": 3, - "keyword": "PURGE", - "parameters": "TTL:2h", - "startTime": "2019-06-18 21:28:31+00" - }]} - - -``POST`` -======== -Creates a new :term:`Content Invalidation Job`. - -.. caution:: Creating a :term:`Content Invalidation Job` immediately triggers a CDN-wide revalidation update. In the case that the global :term:`Parameter` ``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger a CDN-wide "Queue Updates". This means that :term:`Content Invalidation Jobs` become active **immediately** at their ``startTime`` - unlike most other configuration changes they do not wait for a :term:`Snapshot` or a "Queue Updates". Furthermore, if the global :term:`Parameter` ``use_reval_pending`` *is* ``"0"``, this will cause all pending configuration changes to propagate to all :term:`cache servers` in the CDN. Take care when using this endpoint. - -:Auth. Required: Yes -:Roles Required: "operations" or "admin"\ [#tenancy]_ -:Response Type: Object - -Request Structure ------------------ -:deliveryService: This should either be the integral, unique identifier of a :term:`Delivery Service`, or a string containing an :ref:`ds-xmlid` -:startTime: This can be a string in the legacy ``YYYY-MM-DD HH:MM:SS`` format, or a string in :rfc:`3339` format, or a string representing a date in the same non-standard format as the ``last_updated`` fields common in other API responses, or finally it can be a number indicating the number of milliseconds since the Unix Epoch (January 1, 1970 UTC). This date must be in the future. -:regex: A regular expression that will be used to match the path part of URIs for content stored on :term:`cache servers` that service traffic for the :term:`Delivery Service` identified by ``deliveryService``. -:ttl: Either the number of hours for which the :term:`Content Invalidation Job` should remain active, or a "duration" string, which is a sequence of numbers followed by units. The accepted units are: - - - ``h`` gives a duration in hours - - ``m`` gives a duration in minutes - - ``s`` gives a duration in seconds - - ``ms`` gives a duration in milliseconds - - ``us`` (or ``µs``) gives a duration in microseconds - - ``ns`` gives a duration in nanoseconds - - These durations can be combined e.g. ``2h45m`` specifies a TTL of two hours and forty-five minutes - however note that durations are always rounded up to the nearest hour so that e.g. ``121m`` becomes three hours. TTLs cannot ever be negative, obviously. - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/jobs HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: python-requests/2.20.1 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - Content-Length: 80 - Content-Type: application/json - - { - "deliveryService": "demo1", - "startTime": 1560893311219, - "regex": "/.*", - "ttl": "121m" - } - -Response Structure ------------------- -:assetUrl: A regular expression - matching URLs will be operated upon according to ``keyword`` -:createdBy: The username of the user who initiated the :term:`job` -:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which this :term:`job` operates -:id: An integral, unique identifier for this :term:`job` -:keyword: A keyword that represents the operation being performed by the :term:`job`: - - PURGE - This :term:`job` will prevent caching of URLs matching the ``assetUrl`` until it is removed (or its Time to Live expires) - -:parameters: A string containing key/value pairs representing parameters associated with the :term:`job` - currently only uses Time to Live e.g. ``"TTL:48h"`` -:startTime: The date and time at which the :term:`job` began, in a non-standard format - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Location: https://trafficops.infra.ciab.test/api/2.0/jobs?id=3 - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: nB2xg2IqO56rLT8dI4+KZgxOsTe5ShctG1U8epRsY9NyyMIpx8TZYt5MrO2QikuYh+NnyoR6V0VICCnGCKZpKw== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 18 Jun 2019 19:37:06 GMT - Content-Length: 238 - - { - "alerts": [ - { - "text": "Invalidation Job creation was successful", - "level": "success" - } - ], - "response": { - "assetUrl": "http://origin.infra.ciab.test/.*", - "createdBy": "admin", - "deliveryService": "demo1", - "id": 3, - "keyword": "PURGE", - "parameters": "TTL:2h", - "startTime": "2019-06-18 21:28:31+00" - } - } - - -``PUT`` -======= -Replaces an existing :term:`Content Invalidation Job` with a new one provided in the request. This method of editing a :term:`Content Invalidation Job` does not prevent the requesting user from changing fields that normally only have one value. Use with care. - -.. caution:: Modifying a :term:`Content Invalidation Job` immediately triggers a CDN-wide revalidation update. In the case that the global :term:`Parameter` ``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger a CDN-wide "Queue Updates". This means that :term:`Content Invalidation Jobs` become active **immediately** at their ``startTime`` - unlike most other configuration changes they do not wait for a :term:`Snapshot` or a "Queue Updates". Furthermore, if the global :term:`Parameter` ``use_reval_pending`` *is* ``"0"``, this will cause all pending configuration changes to propagate to all :term:`cache servers` in the CDN. Take care when using this endpoint. - -:Auth. Required: Yes -:Roles Required: "operations" or "admin"\ [#tenancy]_ -:Response Type: Object - -Request Structure ------------------ -.. table:: Query Parameters - - +------+----------+----------------------------------------------------------------------------------------+ - | Name | Required | Description | - +======+==========+========================================================================================+ - | id | yes | The integral, unique identifier of the :term:`Content Invalidation Job` being modified | - +------+----------+----------------------------------------------------------------------------------------+ - -:assetUrl: A regular expression - matching URLs will be operated upon according to ``keyword`` - - .. note:: Unlike in the payloads of POST_ requests to this endpoint, this must be a **full** URL regular expression, as it is **not** combined with the :ref:`ds-origin-url` of the :term:`Delivery Service` identified by ``deliveryService``. - -:createdBy: The username of the user who initiated the :term:`job`\ [#readonly]_ -:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which this :term:`job` operates\ [#readonly]_ - unlike POST_ request payloads, this cannot be an integral, unique identifier -:id: An integral, unique identifier for this :term:`job`\ [#readonly]_ -:keyword: A keyword that represents the operation being performed by the :term:`job`. It can have any (string) value, but the only value with any meaning to Traffic Control is: - - PURGE - This :term:`job` will prevent caching of URLs matching the ``assetUrl`` until it is removed (or its Time to Live expires) - -:parameters: A string containing space-separated key/value pairs - delimited by colons (:kbd:`:`\ s) representing parameters associated with the :term:`job`. In practice, any string can be passed as a :term:`job`'s ``parameters``, but the only value with meaning is a single key/value pair indicated a :abbr:`TTL (Time To Live)` in hours in the format :file:`TTL:{hours}h`, and any other type of value may cause components of Traffic Control to work improperly or not at all. -:startTime: This can be a string in the legacy ``YYYY-MM-DD HH:MM:SS`` format, or a string in :rfc:`3339` format, or a string representing a date in the same non-standard format as the ``last_updated`` fields common in other API responses, or finally it can be a number indicating the number of milliseconds since the Unix Epoch (January 1, 1970 UTC). This **must** be in the future, but only by no more than two days. - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/jobs?id=3 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: python-requests/2.20.1 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - Content-Length: 188 - Content-Type: application/json - - { - "assetUrl": "http://origin.infra.ciab.test/.*", - "createdBy": "admin", - "deliveryService": "demo1", - "id": 3, - "keyword": "PURGE", - "parameters": "TTL:360h", - "startTime": "2019-06-20 18:33:40+00" - } - -Response Structure ------------------- -:assetUrl: A regular expression - matching URLs will be operated upon according to ``keyword`` -:createdBy: The username of the user who initiated the :term:`job` -:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which this :term:`job` operates -:id: An integral, unique identifier for this :term:`job` -:keyword: A keyword that represents the operation being performed by the :term:`job`: - - PURGE - This :term:`job` will prevent caching of URLs matching the ``assetUrl`` until it is removed (or its Time to Live expires) - -:parameters: A string containing key/value pairs representing parameters associated with the :term:`job` - currently only uses Time to Live e.g. ``"TTL:48h"`` -:startTime: The date and time at which the :term:`job` began, in a non-standard format - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-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: +P1PTav4ZBoiQcCqQnUqf+J0dCfQgVj8mzzKtUCA69mWYulya9Bjf6BUd8Aro2apmpgPBkCEA5sITJV1tMYA0Q== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 19 Jun 2019 13:38:59 GMT - Content-Length: 234 - - { "alerts": [{ - "text": "job updated", - "level": "success" - }], - "response": { - "assetUrl": "http://origin.infra.ciab.test/.*", - "createdBy": "admin", - "deliveryService": "demo1", - "id": 3, - "keyword": "PURGE", - "parameters": "TTL:360h", - "startTime": "2019-06-20 18:33:40+00" - }} - - -``DELETE`` -========== -Deletes a :term:`Content Invalidation Job`. - -.. tip:: :term:`Content Invalidation Jobs` that have passed their :abbr:`TTL (Time To Live)` are not automatically deleted - for record-keeping purposes - so use this to clean up old :term:`jobs` that are no longer useful. - -.. caution:: Deleting a :term:`Content Invalidation Job` immediately triggers a CDN-wide revalidation update. In the case that the global :term:`Parameter` ``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger a CDN-wide "Queue Updates". This means that :term:`Content Invalidation Jobs` become active **immediately** at their ``startTime`` - unlike most other configuration changes they do not wait for a :term:`Snapshot` or a "Queue Updates". Furthermore, if the global :term:`Parameter` ``use_reval_pending`` *is* ``"0"``, this will cause all pending configuration changes to propagate to all :term:`cache servers` in the CDN. Take care when using this endpoint. - -:Auth. Required: Yes -:Roles Required: "operations" or "admin"\ [#tenancy]_ -:Response Type: Object - -Request Structure ------------------ -.. table:: Query Parameters - - +------+----------+----------------------------------------------------------------------------------------+ - | Name | Required | Description | - +======+==========+========================================================================================+ - | id | yes | The integral, unique identifier of the :term:`Content Invalidation Job` being modified | - +------+----------+----------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/jobs?id=3 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: python-requests/2.20.1 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - Content-Length: 0 - -Response Structure ------------------- -:assetUrl: A regular expression - matching URLs will be operated upon according to ``keyword`` -:createdBy: The username of the user who initiated the :term:`job` -:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which this :term:`job` operates -:id: An integral, unique identifier for this :term:`job` -:keyword: A keyword that represents the operation being performed by the :term:`job`: - - PURGE - This :term:`job` will prevent caching of URLs matching the ``assetUrl`` until it is removed (or its Time to Live expires) - -:parameters: A string containing key/value pairs representing parameters associated with the :term:`job` - currently only uses Time to Live e.g. ``"TTL:48h"`` -:startTime: The date and time at which the :term:`job` began, in a non-standard format - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-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: FqfziXJYYwHb84Fac9+p4NEY3EsklYxe94wg/VOmlXk4R6l4SaPSh015CChPt/yT72MsWSETnIuRD9KtoK4I+w== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 18 Jun 2019 22:55:15 GMT - Content-Length: 234 - - { "alerts": [ - { - "text": "job was deleted", - "level": "success" - } - ], - "response": { - "assetUrl": "http://origin.infra.ciab.test/.*", - "createdBy": "admin", - "deliveryService": "demo1", - "id": 3, - "keyword": "PURGE", - "parameters": "TTL:36h", - "startTime": "2019-06-20 18:33:40+00" - }} - - -.. [#tenancy] When viewing :term:`Content Invalidation Jobs`, only those jobs that operate on a :term:`Delivery Service` visible to the requesting user's :term:`Tenant` will be returned. Likewise, creating a new :term:`Content Invalidation Jobs` requires that the target :term:`Delivery Service` is modifiable by the requesting user's :term:`Tenant`. However, when modifying or deleting an existing :term:`Content Invalidation Jobs`, the operation can be completed if and only if the requesting user's :term:`Tenant` is the same as the :term:`job`'s :term:`Delivery Service`'s :term:`Tenant` or a descendant thereof, **and** if the requesting user's :term:`Tenant` is the same as the :term:`Tenant` of the *user who initially created the :term:`job`* or a descendant thereof. -.. [#readonly] This field must exist, but it must *not* be different than the same field of the existing :term:`job` (i.e. as seen in a GET_ response) diff --git a/docs/source/api/v2/letsencrypt_autorenew.rst b/docs/source/api/v2/letsencrypt_autorenew.rst deleted file mode 100644 index 4cdbce4c6d..0000000000 --- a/docs/source/api/v2/letsencrypt_autorenew.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-letsencrypt-autorenew: - -************************* -``letsencrypt/autorenew`` -************************* - -``POST`` -======== -Generates an SSL certificate and private key using Let's Encrypt for a :term:`Delivery Service` - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -No parameters available - - -Response Structure ------------------- - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Content-Type: application/json - - { "alerts": [ - { - "text": "This endpoint is deprecated, please use letsencrypt/autorenew instead", - "level": "warning" - }, - { - "text": "Beginning async call to renew certificates. This may take a few minutes.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/letsencrypt_dnsrecords.rst b/docs/source/api/v2/letsencrypt_dnsrecords.rst deleted file mode 100644 index e1f26a8716..0000000000 --- a/docs/source/api/v2/letsencrypt_dnsrecords.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-letsencrypt-dnsrecord: - -************************** -``letsencrypt/dnsrecords`` -************************** - -``GET`` -======== -Gets DNS challenge records for Let's Encrypt DNS challenge for a specified :abbr:`FQDN (Fully Qualified Domain Name)`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------+----------+--------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +======+==========+==================================================================================================+ - | fqdn | no | Return only DNS challenge records for the specified :abbr:`FQDN (Fully Qualified Domain Name)` | - +------+----------+--------------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/letsencrypt/dnsrecord?fqdn=_acme-challenge.demo1.example.com. HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - - -Response Structure ------------------- -:fqdn: The :abbr:`FQDN (Fully Qualified Domain Name)` for the TXT record location to complete the DNS challenge -:record: The record provided by Let's Encrypt to complete the DNS challenge - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Content-Type: application/json - - { "response": [ - { - "fqdn":"_acme-challenge.demo1.example.com.", - "record":"testRecord" - } - ]} diff --git a/docs/source/api/v2/logs.rst b/docs/source/api/v2/logs.rst deleted file mode 100644 index 33da62857e..0000000000 --- a/docs/source/api/v2/logs.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. -.. _to-api-v2-logs: - -******** -``logs`` -******** - -.. note:: This endpoint's responses will contain a cookie (``last_seen_log``) that is used by :ref:`to-api-logs-newcount` to determine the time of last access. Be sure your client uses cookies properly if you intend to use :ref:`to-api-logs-newcount` in concert with this endpoint! - -``GET`` -======= -Fetches a list of changes that have been made to the Traffic Control system - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------+----------+-------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+=====================================================================================================================================+ - | days | no | An integer number of days of change logs to return, by default there is no limit applied | - +-----------+----------+-------------------------------------------------------------------------------------------------------------------------------------+ - | limit | no | The number of records to which to limit the response, if there is no limit query params, it limits to 1000 | - +-----------+----------+-------------------------------------------------------------------------------------------------------------------------------------+ - | 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``. | - +-----------+----------+-------------------------------------------------------------------------------------------------------------------------------------+ - | username | no | A name to which to limit the response too | - +-----------+----------+-------------------------------------------------------------------------------------------------------------------------------------+ - -.. versionadded:: ATCv6 - The ``username``, ``page``, ``offset`` query parameters were added to this in endpoint across across all API versions in :abbr:`ATC (Apache Traffic Control)` version 6.0.0. - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/logs?days=1&limit=2&username=admin HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:id: Integral, unique identifier for the Log entry -:lastUpdated: Date and time at which the change was made, in :ref:`non-rfc-datetime` -:level: Log categories for each entry, e.g. 'UICHANGE', 'OPER', 'APICHANGE' -:message: Log detail about what occurred -:ticketNum: Optional field to cross reference with any bug tracking systems -:user: Name of the user who made the change - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Thu, 15 Nov 2018 15:11:38 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: last_seen_log="2018-11-15% 15:11:38"; path=/; Max-Age=604800 - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: 40dV+azaZ3b6F30y6YHVbV3H2a3ekZrdoxICupwaxQnj62pwYfb7YCM7Qhe3OAItmB77Tbg9INy27ymaz3hr9A== - Content-Length: 357 - - { "response": [ - { - "ticketNum": null, - "level": "APICHANGE", - "lastUpdated": "2018-11-14 21:40:06.493975+00", - "user": "admin", - "id": 444, - "message": "User [ test ] unlinked from deliveryservice [ 1 | demo1 ]." - }, - { - "ticketNum": null, - "level": "APICHANGE", - "lastUpdated": "2018-11-14 21:37:30.707571+00", - "user": "admin", - "id": 443, - "message": "1 delivery services were assigned to test" - } - }], - "summary": { - "count": 2 - } - } - -Summary Fields -"""""""""""""" -The ``summary`` object returned by this method of this endpoint uses only the ``count`` :ref:`standard property `. diff --git a/docs/source/api/v2/logs_newcount.rst b/docs/source/api/v2/logs_newcount.rst deleted file mode 100644 index a358843022..0000000000 --- a/docs/source/api/v2/logs_newcount.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - - -.. _to-api-v2-logs-newcount: - -***************** -``logs/newcount`` -***************** - -``GET`` -======= -Gets the number of new changes made to the Traffic Control system - "new" being defined as the last time the client requested either :ref:`to-api-logs` - -.. note:: This endpoint's functionality is implemented by the :ref:`to-api-logs` endpoint's response setting cookies for the client to use when requesting _this_ endpoint. Take care that your client respects cookies! - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -No parameters available - -Response Structure ------------------- -:newLogcount: The integer number of new changes - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Thu, 15 Nov 2018 15:17:35 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: Ugdqe8GXKSOExphwbDX/Gli+2vBpubttbpfYMbJaCP7adox3MzmVRi2RxTDL5kwPewrcL1CO88zGITskhOsc9g== - Content-Length: 30 - - { "response": { - "newLogcount": 4 - }} diff --git a/docs/source/api/v2/origins.rst b/docs/source/api/v2/origins.rst deleted file mode 100644 index 2aa998e229..0000000000 --- a/docs/source/api/v2/origins.rst +++ /dev/null @@ -1,421 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-origins: - -*********** -``origins`` -*********** - -``GET`` -======= -Gets all requested :term:`Origins`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------------+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +=================+==========+===================================================================================================================================================================+ - | 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 | - +-----------------+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | deliveryservice | no | Return only :term:`Origins` that belong to the :term:`Delivery Service` identified by this integral, unique identifier | - +-----------------+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | id | no | Return only the :term:`Origin` that has this integral, unique identifier | - +-----------------+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | name | no | Return only :term:`Origins` by this name | - +-----------------+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | profileId | no | Return only :term:`Origins` which use the :term:`Profile` that has this :ref:`profile-id` | - +-----------------+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | primary | no | If ``true``, return only :term:`Origins` which are the the primary :term:`Origin` of the :term:`Delivery Service` to which they belong - if ``false`` return only | - | | | :term:`Origins` which are *not* the primary :term:`Origin` of the :term:`Delivery Service` to which they belong | - +-----------------+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | tenant | no | Return only :term:`Origins` belonging to the tenant 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``. | - +-----------------+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -.. note:: Several fields of origin definitions which are filterable by Query Parameters are allowed to be ``null``. ``null`` values in these fields will be filtered *out* appropriately by such Query Parameters, but do note that ``null`` is not a valid value accepted by any of these Query Parameters, and attempting to pass it will result in an error. - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/origins?name=demo1 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -: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: 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` -:ip6Address: The IPv6 address of the :term:`Origin` -:ipAddress: The IPv4 address of the :term:`Origin` -:isPrimary: A boolean value which, when ``true`` specifies this :term:`Origin` as the 'primary' :term:`Origin` served by ``deliveryService`` -:lastUpdated: The date and time at which this :term:`Origin` was last modified -:name: The name of the :term:`Origin` -:port: The TCP port on which the :term:`Origin` listens -:profile: The :ref:`profile-name` of the :term:`Profile` used by this :term:`Origin` -:profileId: The :ref:`profile-id` of the :term:`Profile` used by this :term:`Origin` -:protocol: The protocol used by this origin - will be one of 'http' or 'https' -:tenant: The name of the :term:`Tenant` that owns this :term:`Origin` -:tenantId: An integral, unique identifier for the :term:`Tenant` that owns this :term:`Origin` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: sm8DpvdvrfdSVLtmXTdfjsZbTlbc+pI40Gy0aj00XIURTPfFXuv/4LgHb6A3r92iymbRHvFrH6qdB2g97U2sBg== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 11 Dec 2018 15:43:41 GMT - Content-Length: 376 - - { "response": [ - { - "cachegroup": null, - "cachegroupId": null, - "coordinate": null, - "coordinateId": null, - "deliveryService": "demo1", - "deliveryServiceId": 1, - "fqdn": "origin.infra.ciab.test", - "id": 1, - "ip6Address": null, - "ipAddress": null, - "isPrimary": true, - "lastUpdated": "2018-12-10 19:11:32+00", - "name": "demo1", - "port": null, - "profile": null, - "profileId": null, - "protocol": "http", - "tenant": "root", - "tenantId": 1 - } - ]} - -``POST`` -======== -Creates a new origin definition. - -.. warning:: At the time of this writing it is possible to create and/or modify origin definitions assigned to STEERING and CLIENT_STEERING :term:`Delivery Services` - despite that an origin has no meaning in those contexts. In these cases, the API responses may give incorrect output - see `GitHub Issue #3107 `_ for details and updates. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -: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` -:ipAddress: An optional string containing the IPv4 address of the :term:`Origin` -:isPrimary: An optional boolean which, if ``true`` will set this :term:`Origin` as the 'primary' :term:`Origin` served by the :term:`Delivery Service` identified by ``deliveryServiceID`` - - .. note:: Though not specifying this field in this request will leave it as ``null`` in the output, Traffic Ops will silently coerce that to its default value: ``false``. - -:name: A human-friendly name of the :term:`Origin` -:port: An optional port number on which the :term:`Origin` listens for incoming TCP connections -:profileId: An optional :ref:`profile-id` ofa :term:`Profile` that shall be used by this :term:`Origin` -:protocol: The protocol used by the origin - must be one of 'http' or 'https' -:tenantId: An optional\ [1]_, integral, unique identifier for the :term:`Tenant` which shall own the new :term:`Origin` - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/origins HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 114 - Content-Type: application/json - - { - "deliveryServiceId": 2, - "fqdn": "example.com", - "name": "example", - "port": 80, - "protocol": "http", - "tenantId": 1 - } - -.. [1] The ``tenantId`` field is required if and only if tenancy is enabled within Traffic Ops. - -Response Structure ------------------- -: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 -: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` -:ip6Address: The IPv6 address of the :term:`Origin` -:ipAddress: The IPv4 address of the :term:`Origin` -:isPrimary: A boolean value which, when ``true`` specifies this :term:`Origin` as the 'primary' :term:`Origin` served by ``deliveryService`` -:lastUpdated: The date and time at which this :term:`Origin` was last modified -:name: The name of the :term:`Origin` -:port: The TCP port on which the :term:`Origin` listens -:profile: The :ref:`profile-name` of the :term:`Profile` used by this :term:`Origin` -:profileId: The :ref:`profile-id` the :term:`Profile` used by this :term:`Origin` -:protocol: The protocol used by this origin - will be one of 'http' or 'https' -:tenant: The name of the :term:`Tenant` that owns this :term:`Origin` -:tenantId: An integral, unique identifier for the :term:`Tenant` that owns this :term:`Origin` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: z4gp0MaqYu+gSRORhKT2eObVBuVDVx1rdteRaN5kRL9uJ3hNzUCi4dSKIt0rgNgOEDt6x/iTYrmVhr/TSHYtmA== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 11 Dec 2018 15:14:27 GMT - Content-Length: 418 - - { "alerts": [ - { - "text": "origin was created.", - "level": "success" - } - ], - "response": { - "cachegroup": null, - "cachegroupId": null, - "coordinate": null, - "coordinateId": null, - "deliveryService": null, - "deliveryServiceId": 2, - "fqdn": "example.com", - "id": 2, - "ip6Address": null, - "ipAddress": null, - "isPrimary": null, - "lastUpdated": "2018-12-11 15:14:27+00", - "name": "example", - "port": 80, - "profile": null, - "profileId": null, - "protocol": "http", - "tenant": null, - "tenantId": 1 - }} - -``PUT`` -======= -Updates an :term:`Origin` definition. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------+----------+-------------------------------------------------------------------------------+ - | Name | Required | Description | - +======+==========+===============================================================================+ - | id | yes | The integral, unique identifier of the :term:`Origin` definition being edited | - +------+----------+-------------------------------------------------------------------------------+ - -: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` -:ipAddress: An optional string containing the IPv4 address of the :term:`Origin` -:isPrimary: An optional boolean which, if ``true`` will set this :term:`Origin` as the 'primary' origin served by the :term:`Delivery Service` identified by ``deliveryServiceID`` -:name: A human-friendly name of the :term:`Origin` -:port: An optional port number on which the :term:`Origin` listens for incoming TCP connections -:profileId: An optional :ref:`profile-id` of the :term:`Profile` that shall be used by this :term:`Origin` -:protocol: The protocol used by the :term:`Origin` - must be one of 'http' or 'https' -:tenantId: An optional\ [1]_, integral, unique identifier for the :term:`Tenant` which shall own the new :term:`Origin` - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/origins?id=2 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 135 - Content-Type: application/json - - { - "deliveryServiceId": 2, - "fqdn": "example.com", - "isprimary": true, - "name": "example", - "port": 443, - "protocol": "https", - "tenantId": 1 - } - - -Response Structure ------------------- -: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 -: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` -:ip6Address: The IPv6 address of the :term:`Origin` -:ipAddress: The IPv4 address of the :term:`Origin` -:isPrimary: A boolean value which, when ``true`` specifies this :term:`Origin` as the 'primary' :term:`Origin` served by ``deliveryService`` -:lastUpdated: The date and time at which this :term:`Origin` was last modified -:name: The name of the :term:`Origin` -:port: The TCP port on which the :term:`Origin` listens -:profile: The :ref:`profile-name` of the :term:`Profile` used by this :term:`Origin` -:profileId: The :ref:`profile-id` the :term:`Profile` used by this :term:`Origin` -:protocol: The protocol used by this origin - will be one of 'http' or 'https' -:tenant: The name of the :term:`Tenant` that owns this :term:`Origin` -:tenantId: An integral, unique identifier for the :term:`Tenant` that owns this :term:`Origin` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: Zx7jOa7UAQxRtDenYodvGQSoooPj4m0yY0AIeUpbdelmYMiNdPYtW82BCmMesFXkmP74nV4HbTUyDHVMuJxZ7g== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 11 Dec 2018 15:40:53 GMT - Content-Length: 420 - - { "alerts": [ - { - "text": "origin was updated.", - "level": "success" - } - ], - "response": { - "cachegroup": null, - "cachegroupId": null, - "coordinate": null, - "coordinateId": null, - "deliveryService": null, - "deliveryServiceId": 2, - "fqdn": "example.com", - "id": 2, - "ip6Address": null, - "ipAddress": null, - "isPrimary": true, - "lastUpdated": "2018-12-11 15:40:53+00", - "name": "example", - "port": 443, - "profile": null, - "profileId": null, - "protocol": "https", - "tenant": null, - "tenantId": 1 - }} - -``DELETE`` -========== -Deletes an :term:`Origin` definition. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------+----------+--------------------------------------------------------------------------------+ - | Name | Required | Description | - +======+==========+================================================================================+ - | id | yes | The integral, unique identifier of the :term:`Origin` definition being deleted | - +------+----------+--------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/origins?id=2 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: fLaY4/nh0yR38xq5weBKYg02+aQV6Z1ZroOq9UqUCHLMMrH1NMyhOHx+EphPq7JxkjmGY04WCt6VvDyjGWcgfQ== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 11 Dec 2018 17:04:14 GMT - Content-Length: 61 - - { "alerts": [ - { - "text": "origin was deleted.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/osversions.rst b/docs/source/api/v2/osversions.rst deleted file mode 100644 index 93060b137f..0000000000 --- a/docs/source/api/v2/osversions.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-osversions: - -************** -``osversions`` -************** -.. seealso:: :ref:`tp-tools-generate-iso` - -``GET`` -======= -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 -:Response Type: Object - -Request Structure ------------------ -No parameters available. - -Response Structure ------------------- -This endpoint has no constant keys in its ``response``. Instead, each key in the ``response`` object is the name of an OS, and the value is a string that names the directory where the ISO source can be found. These directories sit under ``/var/www/files/`` on the Traffic Ops host machine by default, or at the location defined by the ``kickstart.files.location`` :term:`Parameter` of the Traffic Ops server's :term:`Profile`, if it is defined. - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: RxbRY2DZ+lYOdTzzUETEZ3wtLBiD2BwXMVuaZjhe4a4cwgcZKRBWxZ6Qy5YYujFe1+UBiTG4sML/Amn27F4AVg== - X-Server-Name: traffic_ops_golang/ - Date: Fri, 30 Nov 2018 19:14:36 GMT - Content-Length: 38 - - { "response": { - "CentOS 7.2": "centos72" - }} - - -Configuration File ------------------- -The data returned from the endpoint comes directly from a configuration file. By default, the file is located at ``/var/www/files/osversions.json``. -The **directory** of the file can be changed by creating a specific :term:`Parameter` named ``kickstart.files.location`` in configuration file ``mkisofs``. - -The format of the file is a JSON object as described in `Response Structure`_. - -.. code-block:: json - :caption: Example osversions.json file - - { - "CentOS 7.2": "centos72" - } - - -The legacy Perl Traffic Ops used a Perl configuration file located by default at ``/var/www/files/osversions.cfg``. A Perl script is provided -to convert the legacy configuration file to the new JSON format. The script is located within the Traffic Control repository at ``traffic_ops/app/bin/osversions-convert.pl``. - -.. code-block:: shell - :caption: Example usage of conversion script - - ./osversions-convert.pl < /var/www/files/osversions.cfg > /var/www/files/osversions.json diff --git a/docs/source/api/v2/parameterprofile.rst b/docs/source/api/v2/parameterprofile.rst deleted file mode 100644 index c16130259a..0000000000 --- a/docs/source/api/v2/parameterprofile.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-parameterprofile: - -******************** -``parameterprofile`` -******************** - -``POST`` -======== -Create one or more :term:`Parameter`/:term:`Profile` assignments. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -:paramId: The :ref:`parameter-id` of the :term:`Parameter` to be assigned to the :term:`Profiles` identified within the ``profileIds`` array -:profileIds: An array of :term:`Profile` :ref:`IDs ` to which the :term:`Parameter` identified by ``paramId`` shall be assigned -:replace: An optional boolean (default: false) which, if ``true``, will cause any conflicting :term:`Profile`/:term:`Parameter` assignments to be overridden. - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/parameterprofile HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 38 - Content-Type: application/json - - { - "paramId": 4, - "profileIds": [18] - } - -Response Structure ------------------- -:paramId: The :ref:`parameter-id` of the :term:`Parameter` which has been assigned to the :term:`Profiles` identified within the ``profileIds`` array -:profileIds: An array of :term:`Profile` :ref:`IDs ` to which the :term:`Parameter` identified by ``paramId`` has been assigned -:replace: An optional boolean (default: false) which, if ``true``, caused any conflicting :term:`Profile`/:term:`Parameter` assignments to be overridden. - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: N2ahnhEnfZ0UqnjylN6Vu3HaOZk340YuiuyiqkhTbk0pENp+kwBPYu4Z/sqBAloCfXSQaWlJzaeXw4uOD5heWw== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 15:18:23 GMT - Content-Length: 147 - - { "alerts": [ - { - "text": "2 parameters were assigned to the 18 profile", - "level": "success" - } - ], - "response": { - "profileId": 18, - "paramIds": [ - 2, - 3 - ], - "replace": false - }} diff --git a/docs/source/api/v2/parameters.rst b/docs/source/api/v2/parameters.rst deleted file mode 100644 index f316b4787f..0000000000 --- a/docs/source/api/v2/parameters.rst +++ /dev/null @@ -1,209 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-parameters: - -************** -``parameters`` -************** - -``GET`` -======= -Gets all :term:`Parameters` configured in Traffic Ops - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-------------+----------+---------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +=============+==========+===============================================================================================================+ - | configFile | no | Filter :term:`Parameters` by :ref:`parameter-config-file` | - +-------------+----------+---------------------------------------------------------------------------------------------------------------+ - | id | no | Filters :term:`Parameters` by :ref:`parameter-id` | - +-------------+----------+---------------------------------------------------------------------------------------------------------------+ - | name | no | Filter :term:`Parameters` by :ref:`parameter-name` | - +-------------+----------+---------------------------------------------------------------------------------------------------------------+ - | value | no | Filter :term:`Parameters` by :ref:`parameter-value` | - +-------------+----------+---------------------------------------------------------------------------------------------------------------+ - | 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``. | - +-------------+----------+---------------------------------------------------------------------------------------------------------------+ - -.. versionadded:: ATCv6 - The ``value`` query parameter was added to all API versions in ATC version 6.0. - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/parameters?configFile=records.config&name=location HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:configFile: The :term:`Parameter`'s :ref:`parameter-config-file` -:id: The :term:`Parameter`'s :ref:`parameter-id` -:lastUpdated: The date and time at which this :term:`Parameter` was last updated, in :ref:`non-rfc-datetime` -:name: :ref:`parameter-name` of the :term:`Parameter` -:profiles: An array of :term:`Profile` :ref:`Names ` that use this :term:`Parameter` -:secure: A boolean value that describes whether or not the :term:`Parameter` is :ref:`parameter-secure` -:value: The :term:`Parameter`'s :ref:`parameter-value` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: UFO3/jcBFmFZM7CsrsIwTfPc5v8gUiXqJm6BNp1boPb4EQBnWNXZh/DbBwhMAOJoeqDImoDlrLnrVjQGO4AooA== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 05 Dec 2018 18:23:39 GMT - Content-Length: 212 - - { "response": [ - { - "configFile": "records.config", - "id": 29, - "lastUpdated": "2018-12-05 17:51:02+00", - "name": "location", - "profiles": [ - "ATS_EDGE_TIER_CACHE", - "ATS_MID_TIER_CACHE" - ], - "secure": false, - "value": "/etc/trafficserver/" - } - ]} - -``POST`` -======== -Creates one or more new :term:`Parameters`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Array - -Request Structure ------------------ -The request body may be in one of two formats, a single :term:`Parameter` object or an array of :term:`Parameter` objects. Each :term:`Parameter` object shall have the following keys: - -:configFile: The :term:`Parameter`'s :ref:`parameter-config-file` -:name: :ref:`parameter-name` of the :term:`Parameter` -:secure: A boolean value that describes whether or not the :term:`Parameter` is :ref:`parameter-secure` -:value: The :term:`Parameter`'s :ref:`parameter-value` - -.. code-block:: http - :caption: Request Example - Single Object Format - - POST /api/2.0/parameters HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 84 - Content-Type: application/json - - { - "name": "test", - "value": "quest", - "configFile": "records.config", - "secure": false - } - -.. code-block:: http - :caption: Request Example - Array Format - - POST /api/2.0/parameters HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 180 - Content-Type: application/json - - [{ - "name": "test", - "value": "quest", - "configFile": "records.config", - "secure": false - }, - { - "name": "foo", - "value": "bar", - "configFile": "records.config", - "secure": false - }] - -Response Structure ------------------- -:configFile: The :term:`Parameter`'s :ref:`parameter-config-file` -:id: The :term:`Parameter`'s :ref:`parameter-id` -:lastUpdated: The date and time at which this :term:`Parameter` was last updated, in :ref:`non-rfc-datetime` -:name: :ref:`parameter-name` of the :term:`Parameter` -:profiles: An array of :term:`Profile` :ref:`Names ` that use this :term:`Parameter` -:secure: A boolean value that describes whether or not the :term:`Parameter` is :ref:`parameter-secure` -:value: The :term:`Parameter`'s :ref:`parameter-value` - -.. code-block:: http - :caption: Response Example - Single Object Format - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: eQrl48zWids0kDpfCYmmtYMpegjnFxfOVvlBYxxLSfp7P7p6oWX4uiC+/Cfh2X9i3G+MQ36eH95gukJqOBOGbQ== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 05 Dec 2018 19:18:21 GMT - Content-Length: 212 - - { "alerts": [ - { - "text": "param was created.", - "level": "success" - } - ], - "response": { - "configFile": "records.config", - "id": 124, - "lastUpdated": "2018-12-05 19:18:21+00", - "name": "test", - "profiles": null, - "secure": false, - "value": "quest" - }} diff --git a/docs/source/api/v2/parameters_id.rst b/docs/source/api/v2/parameters_id.rst deleted file mode 100644 index 43e5859908..0000000000 --- a/docs/source/api/v2/parameters_id.rst +++ /dev/null @@ -1,153 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-parameters-id: - -********************* -``parameters/{{ID}}`` -********************* - -``PUT`` -======= -Replaces a :term:`Parameter`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+------------------------------------------------------------------------+ - | Name | Description | - +======+========================================================================+ - | ID | The :ref:`parameter-id` of the :term:`Parameter` which will be deleted | - +------+------------------------------------------------------------------------+ - -:configFile: The :term:`Parameter`'s :ref:`parameter-config-file` -:name: :ref:`parameter-name` of the :term:`Parameter` -:secure: A boolean value that describes whether or not the :term:`Parameter` is :ref:`parameter-secure` -:value: The :term:`Parameter`'s :ref:`parameter-value` - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/parameters/124 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 81 - Content-Type: application/json - - { - "name": "foo", - "value": "bar", - "configFile": "records.config", - "secure": false - } - -Response Structure ------------------- -:configFile: The :term:`Parameter`'s :ref:`parameter-config-file` -:id: The :term:`Parameter`'s :ref:`parameter-id` -:lastUpdated: The date and time at which this :term:`Parameter` was last updated, in :ref:`non-rfc-datetime` -:name: :ref:`parameter-name` of the :term:`Parameter` -:profiles: An array of :term:`Profile` :ref:`Names ` that use this :term:`Parameter` -:secure: A boolean value that describes whether or not the :term:`Parameter` is :ref:`parameter-secure` -:value: The :term:`Parameter`'s :ref:`parameter-value` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: DMxS2gKceFVKRtezON/vsnrC+zI8onASSHaGv5i3wwvUvyt9KEe72gxQd6ZgVcSq3K8ZpkH6g3UI/WtEfdp5vA== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 05 Dec 2018 20:21:07 GMT - Content-Length: 209 - - { "alerts": [ - { - "text": "param was updated.", - "level": "success" - } - ], - "response": { - "configFile": "records.config", - "id": 125, - "lastUpdated": "2018-12-05 20:21:07+00", - "name": "foo", - "profiles": null, - "secure": false, - "value": "bar" - }} - -``DELETE`` -========== -Deletes the specified :term:`Parameter`. If, however, the :term:`Parameter` is associated with one or more :term:`Profiles`, deletion will fail. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response TYpe: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+------------------------------------------------------------------------+ - | Name | Description | - +======+========================================================================+ - | ID | The :ref:`parameter-id` of the :term:`Parameter` which will be deleted | - +------+------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/parameters/124 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: hJjQq2Seg7sqWt+jKgp6gwRxUtoVU34PFoc9wEaweXdaIBTn/BscoUuyw2/n+V8GZPqpeQcihZE50/0oQhdtHw== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 05 Dec 2018 19:20:30 GMT - Content-Length: 60 - - { "alerts": [ - { - "text": "param was deleted.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/phys_locations.rst b/docs/source/api/v2/phys_locations.rst deleted file mode 100644 index b4bbca991e..0000000000 --- a/docs/source/api/v2/phys_locations.rst +++ /dev/null @@ -1,220 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-phys_locations: - -****************** -``phys_locations`` -****************** - -``GET`` -======= -Retrieves :term:`Physical Locations` - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------+---------------------------------------------------------------------------------------------------------------+ - | Name | Description | - +===========+===============================================================================================================+ - | id | Filter by integral, unique identifier | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | region | Filter by integral, unique identifier of containing :term:`Region` | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | name | Filter by name | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | orderby | Choose the ordering of the results - must be the name of one of the fields of the objects in the ``response`` | - | | array | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | sortOrder | Changes the order of sorting. Either ascending (default or "asc") or descending ("desc") | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | limit | Choose the maximum number of results to return | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | offset | The number of results to skip before beginning to return results. Must use in conjunction with limit | - +-----------+---------------------------------------------------------------------------------------------------------------+ - | page | 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 - - GET /api/2.0/phys_locations?name=CDN_in_a_Box HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:address: The physical location's street address -:city: The name of the city in which the physical location lies -:comments: Any and all human-readable comments -:email: The email address of the physical location's ``poc`` -:id: An integral, unique identifier for the physical location -:lastUpdated: The date and time at which the physical location was last updated, in :ref:`non-rfc-datetime` -:name: The name of the physical location -:phone: A phone number where the the physical location's ``poc`` might be reached -:poc: The name of a "point of contact" for the physical location -:region: The name of the region within which the physical location lies -:regionId: An integral, unique identifier for the region within which the physical location lies -:shortName: An abbreviation of the ``name`` -:state: An abbreviation of the name of the state or province within which this physical location lies -:zip: The zip code of the physical location - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 0g4b3W1AwXytCnBo8TReQQij2v9oHAl7MG9KuwMig5V4sFcMM5qP8dgPsFTunFr00DPI20c7BpUbZsvJtsYTEQ== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 05 Dec 2018 22:19:52 GMT - Content-Length: 275 - - { "response": [ - { - "address": "1600 Pennsylvania Avenue NW", - "city": "Washington", - "comments": "", - "email": "", - "id": 2, - "lastUpdated": "2018-12-05 17:50:58+00", - "name": "CDN_in_a_Box", - "phone": "", - "poc": "", - "regionId": 1, - "region": "Washington, D.C", - "shortName": "ciab", - "state": "DC", - "zip": "20500" - } - ]} - -``POST`` -======== -Creates a new physical location - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -:address: The physical location's street address -:city: The name of the city in which the physical location lies -:comments: An optional string for containing any and all human-readable comments -:email: An optional string containing email address of the physical location's ``poc`` -:name: An optional name of the physical location -:phone: An optional string containing the phone number where the the physical location's ``poc`` might be reached -:poc: The name of a "point of contact" for the physical location -:region: An optional string naming the region that contains this physical location\ [1]_ -:regionId: An integral, unique identifier for the region within which the physical location lies\ [1]_ -:shortName: An abbreviation of the ``name`` -:state: An abbreviation of the name of the state or province within which this physical location lies -:zip: The zip code of the physical location - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/phys_locations HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 326 - Content-Type: application/json - - { - "address": "Buckingham Palace", - "city": "London", - "comments": "Buckingham Palace", - "email": "steve.kingstone@royal.gsx.gov.uk", - "name": "Great_Britain", - "phone": "0-843-816-6276", - "poc": "Her Majesty The Queen Elizabeth Alexandra Mary Windsor II", - "regionId": 3, - "shortName": "uk", - "state": "Westminster", - "zip": "SW1A 1AA" - } - -.. [1] The only "region" key that actually matters in the request body is ``regionId``; ``region`` is not validated and has no effect - particularly not the effect of re-naming the region - beyond changing the name in the API response to this request. Subsequent requests will reveal the true name of the region. Note that if ``region`` is not present in the request body it will be ``null`` in the response, but again further requests will show the true region name. - -Response Structure ------------------- -:address: The physical location's street address -:city: The name of the city in which the physical location lies -:comments: Any and all human-readable comments -:email: The email address of the physical location's ``poc`` -:id: An integral, unique identifier for the physical location -:lastUpdated: The date and time at which the physical location was last updated, in :ref:`non-rfc-datetime` -:name: The name of the physical location -:phone: A phone number where the the physical location's ``poc`` might be reached -:poc: The name of a "point of contact" for the physical location -:region: The name of the region within which the physical location lies -:regionId: An integral, unique identifier for the region within which the physical location lies -:shortName: An abbreviation of the ``name`` -:state: An abbreviation of the name of the state or province within which this physical location lies -:zip: The zip code of the physical location - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: GZ/BC+AgGpOQNfd9oiZy19jtsD8MPOdeyi7PVdz+9YSiLYP44gmn5K+Xi1yS0l59yjHf7O+C1loVQPSlIeP9fg== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 06 Dec 2018 00:14:47 GMT - Content-Length: 443 - - { "alerts": [ - { - "text": "physLocation was created.", - "level": "success" - } - ], - "response": { - "address": "Buckingham Palace", - "city": "London", - "comments": "Buckingham Palace", - "email": "steve.kingstone@royal.gsx.gov.uk", - "id": 3, - "lastUpdated": "2018-12-06 00:14:47+00", - "name": "Great_Britain", - "phone": "0-843-816-6276", - "poc": "Her Majesty The Queen Elizabeth Alexandra Mary Windsor II", - "regionId": 3, - "region": null, - "shortName": "uk", - "state": "Westminster", - "zip": "SW1A 1AA" - }} diff --git a/docs/source/api/v2/phys_locations_id.rst b/docs/source/api/v2/phys_locations_id.rst deleted file mode 100644 index c3a77912e0..0000000000 --- a/docs/source/api/v2/phys_locations_id.rst +++ /dev/null @@ -1,184 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-phys_locations-id: - -************************* -``phys_locations/{{ID}}`` -************************* - -``PUT`` -======= -Updates a :term:`Physical Location` - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+----------------------------------------------------------------------------------+ - | 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 -:comments: An optional string for containing any and all human-readable comments -:email: An optional string containing email address of the physical location's ``poc`` -:name: An optional name of the physical location -:phone: An optional string containing the phone number where the the physical location's ``poc`` might be reached -:poc: The name of a "point of contact" for the physical location -:region: An optional string naming the region that contains this physical location\ [1]_ -:regionId: An integral, unique identifier for the region within which the physical location lies\ [1]_ -:shortName: An abbreviation of the ``name`` -:state: An abbreviation of the name of the state or province within which this physical location lies -:zip: The zip code of the physical location - -.. code-block:: http - :caption: Request Structure - - PUT /api/2.0/phys_locations/2 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 268 - Content-Type: application/json - - { - "address": "1600 Pennsylvania Avenue NW", - "city": "Washington", - "comments": "The White House", - "email": "the@white.house", - "name": "CDN_in_a_Box", - "phone": "1-202-456-1414", - "poc": "Donald J. Trump", - "regionId": 2, - "shortName": "ciab", - "state": "DC", - "zip": "20500" - } - -.. [1] The only "region" key that actually matters in the request body is ``regionId``; ``region`` is not validated and has no effect - particularly not the effect of re-naming the region - beyond changing the name in the API response to this request. Subsequent requests will reveal the true name of the region. Note that if ``region`` is not present in the request body it will be ``null`` in the response, but again further requests will show the true region name. - -Response Structure ------------------- -:address: The physical location's street address -:city: The name of the city in which the physical location lies -:comments: Any and all human-readable comments -:email: The email address of the physical location's ``poc`` -:id: An integral, unique identifier for the physical location -:lastUpdated: The date and time at which the physical location was last updated, in :ref:`non-rfc-datetime` -:name: The name of the physical location -:phone: A phone number where the the physical location's ``poc`` might be reached -:poc: The name of a "point of contact" for the physical location -:region: The name of the region within which the physical location lies -:regionId: An integral, unique identifier for the region within which the physical location lies -:shortName: An abbreviation of the ``name`` -:state: An abbreviation of the name of the state or province within which this physical location lies -:zip: The zip code of the physical location - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: qnMe6OqxjSU8H1njlh00HWNR20YnVlOCufqCTdMBcdC1322jk2ICFQsQQ3XuOOR0WSb7h7OHCfXqDC1/jA1xjA== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 05 Dec 2018 23:39:17 GMT - Content-Length: 385 - - { "alerts": [ - { - "text": "physLocation was updated.", - "level": "success" - } - ], - "response": { - "address": "1600 Pennsylvania Avenue NW", - "city": "Washington", - "comments": "The White House", - "email": "the@white.house", - "id": 2, - "lastUpdated": "2018-12-05 23:39:17+00", - "name": "CDN_in_a_Box", - "phone": "1-202-456-1414", - "poc": "Donald J. Trump", - "regionId": 2, - "region": null, - "shortName": "ciab", - "state": "DC", - "zip": "20500" - }} - -``DELETE`` -========== -Deletes a :term:`Physical Location` - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+--------------------------------------------------------------------------------+ - | Name | Description | - +======+================================================================================+ - | ID | The integral, unique identifier of the :term:`Physical Location` being deleted | - +------+--------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/phys_locations/3 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: KeW/tEmICwpCGC8F0YMTqHdeR9J6W6Z3w/U+HOSbeCGyaEheCIhIsWlngT3dyfH1tiu8UyzaPB6QrJyXdybBkw== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 06 Dec 2018 00:28:48 GMT - Content-Length: 67 - - { "alerts": [ - { - "text": "physLocation was deleted.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/ping.rst b/docs/source/api/v2/ping.rst deleted file mode 100644 index f8ab6fe894..0000000000 --- a/docs/source/api/v2/ping.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-ping: - -******** -``ping`` -******** -Checks whether Traffic Ops is online. - -``GET`` -======= -:Auth. Required: No -:Response Type: ``undefined`` - -Request Structure ------------------ -No parameters available. - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/ping HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - -Response Structure ------------------- -:ping: Returns an object containing only the ``"ping"`` property, which always has the value ``"pong"``. - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Whole-Content-Sha512: 0HqcLcYHCB4AFYGFzcAsP2h+PCMlYxk/TqMajcy3fWCzY730Tv32k5trUaJLeSBbRx2FUi7z/sTAuzikdg0E4g== - X-Server-Name: traffic_ops_golang/ - Date: Sun, 23 Feb 2020 20:52:01 GMT - Content-Length: 40 - Content-Type: application/x-gzip - - { - "ping": "pong" - } diff --git a/docs/source/api/v2/plugins.rst b/docs/source/api/v2/plugins.rst deleted file mode 100644 index 3f4b0611ee..0000000000 --- a/docs/source/api/v2/plugins.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-plugins: - -*********** -``plugins`` -*********** -.. seealso:: :ref:`to_go_plugins` - -``GET`` -======= -Retrieves the list of configured enabled Traffic Ops plugins. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. code-block:: http - :caption: Request Example - - GET /api/2.0/plugins HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:description: A short description of the plugin. -:name: The name of the plugin. -:version: A (hopefully) semantic version number describing the version of the plugin. - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Tue, 11 Dec 2018 20:51:48 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: n73jg9XR4V5Cwqq56Rf3wuIi99k3mM5u2NAjcZ/gQBu8jvAFymDlnZqKeJ+wTll1vjIsHpXCOVXV7+5UGakLgA== - Transfer-Encoding: chunked - - { "response": [ - { - "name": "helloworld", - "version": "1.0.0", - "description": "configuration plugin to run at startup" - } - ]} diff --git a/docs/source/api/v2/profileparameter.rst b/docs/source/api/v2/profileparameter.rst deleted file mode 100644 index 449d2e0321..0000000000 --- a/docs/source/api/v2/profileparameter.rst +++ /dev/null @@ -1,87 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-profileparameter: - -******************** -``profileparameter`` -******************** -.. seealso:: :ref:`to-api-profileparameters`. - -``POST`` -======== -Create one or more :term:`Profile`/:term:`Parameter` assignments. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -:profileId: The :ref:`profile-id` of the :term:`Profile` to which the :term:`Parameters` identified within the ``parameterIds`` array will be assigned -:paramIds: An array of :term:`Parameter` :ref:`IDs ` which shall be assigned to the :term:`Profile` identified by ``profileId`` -:replace: An optional boolean (default: false) which, if ``true``, will cause any conflicting :term:`Profile`/:term:`Parameter` assignments to be overridden. - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/profileparameter HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 38 - Content-Type: application/json - - { - "profileId": 18, - "paramIds": [2, 3] - } - -Response Structure ------------------- -:profileId: The :ref:`profile-id` of the :term:`Profile` to which the :term:`Parameters` identified within the ``parameterIds`` array are assigned -:paramIds: An array of :term:`Parameter` :ref:`IDs ` which have been assigned to the :term:`Profile` identified by ``profileId`` -:replace: An optional boolean (default: false) which, if ``true``, indicates that any conflicting :term:`Profile`/:term:`Parameter` assignments have been overridden. - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: N2ahnhEnfZ0UqnjylN6Vu3HaOZk340YuiuyiqkhTbk0pENp+kwBPYu4Z/sqBAloCfXSQaWlJzaeXw4uOD5heWw== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 15:18:23 GMT - Content-Length: 147 - - { "alerts": [ - { - "text": "2 parameters were assigned to the 18 profile", - "level": "success" - } - ], - "response": { - "profileId": 18, - "paramIds": [ - 2, - 3 - ], - "replace": false - }} diff --git a/docs/source/api/v2/profileparameters.rst b/docs/source/api/v2/profileparameters.rst deleted file mode 100644 index 1071d4a430..0000000000 --- a/docs/source/api/v2/profileparameters.rst +++ /dev/null @@ -1,186 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-profileparameters: - -********************* -``profileparameters`` -********************* - -``GET`` -======= - -Retrieves all :term:`Parameter`/:term:`Profile` assignments. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+===============================================================================================================+ - | 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``. | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - -Response Structure ------------------- -:lastUpdated: The date and time at which this :term:`Profile`/:term:`Parameter` association was last modified, in :ref:`non-rfc-datetime` -:parameter: The :ref:`parameter-id` of a :term:`Parameter` assigned to ``profile`` -:profile: The :ref:`profile-name` of the :term:`Profile` to which the :term:`Parameter` identified by ``parameter`` is assigned - -.. code-block:: http - :caption: Response Structure - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: +bnMkRgdx4bJoGGlr3mZl539obj3aQAP8e65FAXgywdRAUfXZCFM6VNDn7wScXBmvF2SFXo9F+MhuSwrtB9mPg== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 15:09:13 GMT - Transfer-Encoding: chunked - - { "response": [ - { - "lastUpdated": "2018-12-05 17:50:49+00", - "profile": "GLOBAL", - "parameter": 4 - }, - { - "lastUpdated": "2018-12-05 17:50:49+00", - "profile": "GLOBAL", - "parameter": 5 - } - ]} - -.. note:: The response example for this endpoint has been truncated to only the first two elements of the resulting array, as the output was hundreds of lines long. - -``POST`` -======== -Associate a :term:`Parameter` to a :term:`Profile`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -This endpoint accepts two formats for the request payload: - -Single Object Format - For assigning a single :term:`Parameter` to a single :term:`Profile` -Array Format - For making multiple assignments of :term:`Parameters` to :term:`Profiles` simultaneously - -Single Object Format -"""""""""""""""""""" -:parameterId: The :ref:`parameter-id` of a :term:`Parameter` to assign to some :term:`Profile` -:profileId: The :ref:`profile-id` of the :term:`Profile` to which the :term:`Parameter` identified by ``parameterId`` will be assigned - -.. code-block:: http - :caption: Request Example - Single Object Format - - POST /api/2.0/profileparameters HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 36 - Content-Type: application/json - - { - "profileId": 18, - "parameterId": 1 - } - -Array Format -"""""""""""" -:parameterId: The :ref:`parameter-id` of a :term:`Parameter` to assign to some :term:`Profile` -:profileId: The :ref:`profile-id` of the :term:`Profile` to which the :term:`Parameter` identified by ``parameterId`` will be assigned - -.. code-block:: http - :caption: Request Example - Array Format - - POST /api/2.0/profileparameters HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 88 - Content-Type: application/json - - [{ - "profileId": 18, - "parameterId": 2 - }, - { - "profileId": 18, - "parameterId": 3 - }] - -Response Structure ------------------- -:lastUpdated: The date and time at which the :term:`Profile`/:term:`Parameter` assignment was last modified, in :ref:`non-rfc-datetime` -:parameter: :ref:`parameter-name` of the :term:`Parameter` which is assigned to ``profile`` -:parameterId: The :ref:`parameter-id` of the assigned :term:`Parameter` -:profile: :ref:`profile-name` of the :term:`Profile` to which the :term:`Parameter` is assigned -:profileId: The :ref:`profile-id` of the :term:`Profile` to which the :term:`Parameter` identified by ``parameterId`` is assigned - -.. code-block:: http - :caption: Response Example - Single Object Format - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: eDmIwlzX44fZdxLRPHMNa8aoGAK5fQv9Y70A2eeQHfEkliU4evwcsQ4WeHcH0l3/wPTGlpyC0gwLo8LQQpUxWQ== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 13:50:11 GMT - Content-Length: 166 - - { "alerts": [ - { - "text": "profileParameter was created.", - "level": "success" - } - ], - "response": { - "lastUpdated": null, - "profile": null, - "profileId": 18, - "parameter": null, - "parameterId": 1 - }} diff --git a/docs/source/api/v2/profileparameters_profileID_parameterID.rst b/docs/source/api/v2/profileparameters_profileID_parameterID.rst deleted file mode 100644 index 163b1aa1af..0000000000 --- a/docs/source/api/v2/profileparameters_profileID_parameterID.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-profileparameters-profileID-parameterID: - -*************************************************** -``profileparameters/{{profileID}}/{{parameterID}}`` -*************************************************** - -``DELETE`` -========== -Deletes a :term:`Profile`/:term:`Parameter` association. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +-------------+------------------------------------------------------------------------------------------------------------------------------+ - | Name | Description | - +=============+==============================================================================================================================+ - | profileID | The :ref:`profile-id` of the :term:`Profile` from which a :term:`Parameter` shall be removed | - +-------------+------------------------------------------------------------------------------------------------------------------------------+ - | parameterID | The :ref:`parameter-id` of the :term:`Parameter` which shall be removed from the :term:`Profile` identified by ``profileID`` | - +-------------+------------------------------------------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/profileparameters/18/129 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: JQuBqHyT9MnNwO9NSIDVQhkRtXdeAJc95W1pF2dwQeoBFmf0Y8knXm3/O/rbJDEoUC7DhUQN1aoYIsqqmz4qQQ== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 15:00:15 GMT - Content-Length: 71 - - { "alerts": [ - { - "text": "profileParameter was deleted.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/profiles.rst b/docs/source/api/v2/profiles.rst deleted file mode 100644 index b06b8bc7f5..0000000000 --- a/docs/source/api/v2/profiles.rst +++ /dev/null @@ -1,168 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-profiles: - -************ -``profiles`` -************ - -``GET`` -======= -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-------+----------+--------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +=======+==========+========================================================================================================+ - | cdn | no | Used to filter :term:`Profiles` by the integral, unique identifier of the CDN to which they belong | - +-------+----------+--------------------------------------------------------------------------------------------------------+ - | id | no | Filters :term:`Profiles` by :ref:`profile-id` | - +-------+----------+--------------------------------------------------------------------------------------------------------+ - | name | no | Filters :term:`Profiles` by :ref:`profile-name` | - +-------+----------+--------------------------------------------------------------------------------------------------------+ - | param | no | Used to filter :term:`Profiles` by the :ref:`parameter-id` of a :term:`Parameter` associated with them | - +-------+----------+--------------------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/profiles?name=ATS_EDGE_TIER_CACHE HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:cdn: The integral, unique identifier of the :ref:`profile-cdn` to which this :term:`Profile` belongs -:cdnName: The name of the :ref:`profile-cdn` to which this :term:`Profile` belongs -:description: The :term:`Profile`'s :ref:`profile-description` -:id: The :term:`Profile`'s :ref:`profile-id` -:lastUpdated: The date and time at which this :term:`Profile` was last updated, in :ref:`non-rfc-datetime` -:name: The :term:`Profile`'s :ref:`profile-name` -:routingDisabled: The :term:`Profile`'s :ref:`profile-routing-disabled` setting -:type: The :term:`Profile`'s :ref:`profile-type` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: QEpKM/DwHBRvue9K7XKrpwKFKhW6yCMQ2vSQgxE7dWFGJaqC4KOUO92bsJU/5fjI9qlB+1uMT2kz6mFb1Wzp/w== - X-Server-Name: traffic_ops_golang/ - Date: Fri, 07 Dec 2018 20:40:31 GMT - Content-Length: 220 - - { "response": [ - { - "id": 9, - "lastUpdated": "2018-12-05 17:51:00+00", - "name": "ATS_EDGE_TIER_CACHE", - "description": "Edge Cache - Apache Traffic Server", - "cdnName": "CDN-in-a-Box", - "cdn": 2, - "routingDisabled": false, - "type": "ATS_PROFILE" - } - ]} - -``POST`` -======== -Creates a new :term:`Profile`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -:cdn: The integral, unique identifier of the :ref:`profile-cdn` to which this :term:`Profile` shall belong -:description: The :term:`Profile`'s :ref:`profile-description` -:name: The :term:`Profile`'s :ref:`profile-name` -:routingDisabled: The :term:`Profile`'s :ref:`profile-routing-disabled` setting -:type: The :term:`Profile`'s :ref:`profile-type` - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/profiles HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 125 - Content-Type: application/json - - { - "name": "test", - "description": "A test profile for API examples", - "cdn": 2, - "type": "UNK_PROFILE", - "routingDisabled": true - } - -Response Structure ------------------- -:cdn: The integral, unique identifier of the :ref:`profile-cdn` to which this :term:`Profile` belongs -:cdnName: The name of the :ref:`profile-cdn` to which this :term:`Profile` belongs -:description: The :term:`Profile`'s :ref:`profile-description` -:id: The :term:`Profile`'s :ref:`profile-id` -:lastUpdated: The date and time at which this :term:`Profile` was last updated, in :ref:`non-rfc-datetime` -:name: The :term:`Profile`'s :ref:`profile-name` -:routingDisabled: The :term:`Profile`'s :ref:`profile-routing-disabled` setting -:type: The :term:`Profile`'s :ref:`profile-type` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: UGV3PCnYBY0J3siICR0f9VVRNdUK1+9zsDDP6T9yt6t+AoHckHe6bvzOli9to/fGhC2zz5l9Nc1ro4taJUDD8g== - X-Server-Name: traffic_ops_golang/ - Date: Fri, 07 Dec 2018 21:24:49 GMT - Content-Length: 251 - - { "alerts": [ - { - "text": "profile was created.", - "level": "success" - } - ], - "response": { - "id": 16, - "lastUpdated": "2018-12-07 21:24:49+00", - "name": "test", - "description": "A test profile for API examples", - "cdnName": null, - "cdn": 2, - "routingDisabled": true, - "type": "UNK_PROFILE" - }} diff --git a/docs/source/api/v2/profiles_id.rst b/docs/source/api/v2/profiles_id.rst deleted file mode 100644 index b62e2d7b72..0000000000 --- a/docs/source/api/v2/profiles_id.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-profiles-id: - -******************* -``profiles/{{ID}}`` -******************* - -``PUT`` -======= -Replaces the specified :term:`Profile` with the one in the request payload - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-------------------------------------------------------------+ - | Name | Description | - +======+=============================================================+ - | ID | The :ref:`profile-id` of the :term:`Profile` being modified | - +------+-------------------------------------------------------------+ - -:cdn: The integral, unique identifier of the :ref:`profile-cdn` to which this :term:`Profile` will belong -:description: The :term:`Profile`'s new :ref:`profile-description` -:name: The :term:`Profile`'s new :ref:`profile-name` -:routingDisabled: The :term:`Profile`'s new :ref:`profile-routing-disabled` setting -:type: The :term:`Profile`'s new :ref:`profile-type` - - .. warning:: Changing this will likely break something, be **VERY** careful when modifying this value - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/profiles/16 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 125 - Content-Type: application/json - - { - "name": "test", - "description": "A test profile for API examples", - "cdn": 2, - "type": "UNK_PROFILE", - "routingDisabled": true - } - -Response Structure ------------------- -:cdn: The integral, unique identifier of the :ref:`profile-cdn` to which this :term:`Profile` belongs -:cdnName: The name of the :ref:`profile-cdn` to which this :term:`Profile` belongs -:description: The :term:`Profile`'s :ref:`profile-description` -:id: The :term:`Profile`'s :ref:`profile-id` -:lastUpdated: The date and time at which this :term:`Profile` was last updated, in :ref:`non-rfc-datetime` -:name: The :term:`Profile`'s :ref:`profile-name` -:routingDisabled: The :term:`Profile`'s :ref:`profile-routing-disabled` setting -:type: The :term:`Profile`'s :ref:`profile-type` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: Pnf+G9G3/+edt4b8PVsyGZHsNzaFEgphaGSminjRlRmMpWtuLAA20WZDUo3nX0QO81c2GCuFuEh9uMF2Vjeppg== - X-Server-Name: traffic_ops_golang/ - Date: Fri, 07 Dec 2018 21:45:06 GMT - Content-Length: 251 - - { "alerts": [ - { - "text": "profile was updated.", - "level": "success" - } - ], - "response": { - "id": 16, - "lastUpdated": "2018-12-07 21:45:06+00", - "name": "test", - "description": "A test profile for API examples", - "cdnName": null, - "cdn": 2, - "routingDisabled": true, - "type": "UNK_PROFILE" - }} - - -``DELETE`` -========== -Allows user to delete a :term:`Profile`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+------------------------------------------------------------+ - | Name | Description | - +======+============================================================+ - | ID | The :ref:`profile-id` of the :term:`Profile` being deleted | - +------+------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/profiles/16 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: HNmJkZaNW9yil08/3TnqZ5FllH6Rp+jgp3KI46FZdojLYcu+8jEhDLl1okoirdrHyU4R1c3hjCI0urN7PVvWDA== - X-Server-Name: traffic_ops_golang/ - Date: Fri, 07 Dec 2018 21:55:33 GMT - Content-Length: 62 - - { "alerts": [ - { - "text": "profile was deleted.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/profiles_id_export.rst b/docs/source/api/v2/profiles_id_export.rst deleted file mode 100644 index 309a06609e..0000000000 --- a/docs/source/api/v2/profiles_id_export.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-profiles-id-export: - -************************** -``profiles/{{ID}}/export`` -************************** - -``GET`` -======= - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +-----------+--------------------------------------------------------------+ - | Parameter | Description | - +===========+==============================================================+ - | id | The :ref:`profile-id` of the :term:`Profile` to be exported | - +-----------+--------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/profiles/3/export HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:profile: The exported :term:`Profile` - - :cdn: The name of the :ref:`profile-cdn` to which this :term:`Profile` belongs - :description: The :term:`Profile`'s :ref:`profile-description` - :name: The :term:`Profile`'s :ref:`profile-name` - :type: The :term:`Profile`'s :ref:`profile-type` - -:parameters: An array of :term:`Parameters` in use by this :term:`Profile` - - :config_file: The :term:`Parameter`'s :ref:`parameter-config-file` - :name: :ref:`parameter-name` of the :term:`Parameter` - :value: The :term:`Parameter`'s :ref:`parameter-value` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Disposition: attachment; filename="GLOBAL.json" - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: mzP7DVxFAGhICxqagwDyBDRea7oBZPMAx7NCDeOBVCRqlcCFFe7XL3JP58b80aaVOW/2ZGfg/jpYF70cdDfzQA== - X-Server-Name: traffic_ops_golang/ - Date: Fri, 13 Sep 2019 20:14:42 GMT - Transfer-Encoding: gzip - - - { "profile": { - "name": "GLOBAL", - "description": "Global Traffic Ops profile", - "cdn": "ALL", - "type": "UNK_PROFILE" - }, - "parameters": [ - { - "config_file": "global", - "name": "tm.instance_name", - "value": "Traffic Ops CDN" - }, - { - "config_file": "global", - "name": "tm.toolname", - "value": "Traffic Ops" - } - ]} diff --git a/docs/source/api/v2/profiles_id_parameters.rst b/docs/source/api/v2/profiles_id_parameters.rst deleted file mode 100644 index 1b3e665b28..0000000000 --- a/docs/source/api/v2/profiles_id_parameters.rst +++ /dev/null @@ -1,242 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-profiles-id-parameters: - -****************************** -``profiles/{{ID}}/parameters`` -****************************** - -``GET`` -======= - -Retrieves all :term:`Parameters` assigned to the :term:`Profile`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+------------------------------------------------------------------------------------------+ - | Name | Description | - +======+==========================================================================================+ - | ID | The :ref:`profile-id` of the :term:`Profile` for which :term:`Parameters` will be listed | - +------+------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/parameters/profile/GLOBAL HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:configFile: The :term:`Parameter`'s :ref:`parameter-config-file` -:id: The :term:`Parameter`'s :ref:`parameter-id` -:lastUpdated: The date and time at which this :term:`Parameter` was last updated, in :ref:`non-rfc-datetime` -:name: :ref:`parameter-name` of the :term:`Parameter` -:profiles: An array of :term:`Profile` :ref:`Names ` that use this :term:`Parameter` -:secure: A boolean value that describes whether or not the :term:`Parameter` is :ref:`parameter-secure` -:value: The :term:`Parameter`'s :ref:`parameter-value` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: NudgZXUNyKNpmSFf856KEjyy+Pin/bFhG9NoRBDAxYbRKt2T5fF5Ze7sUNZfFI5n/ZZsgbx6Tsgtfd7oM6j+eg== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 05 Dec 2018 21:08:56 GMT - Content-Length: 542 - - { "response": [ - { - "configFile": "global", - "id": 4, - "lastUpdated": "2018-12-05 17:50:49+00", - "name": "tm.instance_name", - "secure": false, - "value": "Traffic Ops CDN" - }, - { - "configFile": "global", - "id": 5, - "lastUpdated": "2018-12-05 17:50:49+00", - "name": "tm.toolname", - "secure": false, - "value": "Traffic Ops" - }, - { - "configFile": "global", - "id": 6, - "lastUpdated": "2018-12-05 17:50:51+00", - "name": "use_tenancy", - "secure": false, - "value": "1" - }, - { - "configFile": "regex_revalidate.config", - "id": 7, - "lastUpdated": "2018-12-05 17:50:49+00", - "name": "maxRevalDurationDays", - "secure": false, - "value": "90" - } - ]} - -``POST`` -======== - -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. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-------------------------------------------------------------------------------------------+ - | Name | Description | - +======+===========================================================================================+ - | ID | The :ref:`profile-id` of the :term:`Profile` to which :term:`Parameters` will be assigned | - +------+-------------------------------------------------------------------------------------------+ - -This endpoint accepts two formats for the request payload: - -Single Object Format - For assigning a single :term:`Parameter` to a single :term:`Profile` -Parameter Array Format - For making multiple assignments of :term:`Parameters` to :term:`Profiles` simultaneously - -.. warning:: Most API endpoints dealing with :term:`Parameters` treat :ref:`parameter-secure` as a boolean value, whereas this endpoint takes the legacy approach of treating it as an integer. Be careful when passing data back and forth, as boolean values will **not** be accepted by this endpoint! - -Single Parameter Format -""""""""""""""""""""""" -:configFile: The :term:`Parameter`'s :ref:`parameter-config-file` -:name: :ref:`parameter-name` of the :term:`Parameter` -:secure: A boolean value that describes whether or not the :term:`Parameter` is :ref:`parameter-secure` -:value: The :term:`Parameter`'s :ref:`parameter-value` - -.. code-block:: http - :caption: Response Example - Single Parameter Format - - POST /api/2.0/profiles/18/parameters HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 99 - Content-Type: application/json - - { - "name": "test", - "configFile": "quest", - "value": "A test parameter for API examples", - "secure": 0 - } - - -Parameter Array Format -"""""""""""""""""""""" -:configFile: The :term:`Parameter`'s :ref:`parameter-config-file` -:name: :ref:`parameter-name` of the :term:`Parameter` -:secure: A boolean value that describes whether or not the :term:`Parameter` is :ref:`parameter-secure` -:value: The :term:`Parameter`'s :ref:`parameter-value` - -.. code-block:: http - :caption: Request Example - Parameter Array Format - - POST /api/2.0/profiles/18/parameters HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 212 - Content-Type: application/json - - [{ - "name": "test", - "configFile": "quest", - "value": "A test parameter for API examples", - "secure": 0 - }, - { - "name": "foo", - "configFile": "bar", - "value": "Another test parameter for API examples", - "secure": 0 - }] - -Response Structure ------------------- -:parameters: An array of objects representing the :term:`Parameters` which have been assigned - - :configFile: The :term:`Parameter`'s :ref:`parameter-config-file` - :name: :ref:`parameter-name` of the :term:`Parameter` - :secure: A boolean value that describes whether or not the :term:`Parameter` is :ref:`parameter-secure` - :value: The :term:`Parameter`'s :ref:`parameter-value` - -:profileId: The :ref:`profile-id` of the :term:`Profile` to which the :term:`Parameter`\ (s) have been assigned -:profileName: :ref:`profile-name` of the :term:`Profile` to which the :term:`Parameter`\ (s) have been assigned - -.. code-block:: http - :caption: Response Example - Single Parameter Format - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: R2QUyCaNvKvVv/PNVNmEd/ma5h/iP1fMJlqhv+x2jE/zNpHJ1KVXt6s3btB8nnHv6IDF/gt5kIzQ0mbW5U8bpg== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 14:45:28 GMT - Content-Length: 253 - - { "alerts": [ - { - "text": "Assign parameters successfully to profile test", - "level": "success" - } - ], - "response": { - "parameters": [ - { - "configFile": "quest", - "name": "test", - "secure": 0, - "value": "A test parameter for API examples", - "id": 126 - } - ], - "profileId": 18, - "profileName": "test" - }} - -.. note:: The format of the request does not affect the format of the response. ``parameters`` will be an array either way. diff --git a/docs/source/api/v2/profiles_import.rst b/docs/source/api/v2/profiles_import.rst deleted file mode 100644 index c606be556b..0000000000 --- a/docs/source/api/v2/profiles_import.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-profiles-import: - -******************* -``profiles/import`` -******************* - -``POST`` -======== - -Imports a :term:`Profile` that was exported via :ref:`to-api-profiles-id-export` - -.. note:: On import of the :term:`Profile` :term:`Parameters` if a :term:`Parameter` already exists with the same :ref:`parameter-name`, :ref:`parameter-config-file` and :ref:`parameter-value` it will link that to the :term:`Profile` instead of creating it. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ - -:profile: The exported :term:`Profile` - - :cdn: The name of the :ref:`profile-cdn` to which this :term:`Profile` belongs - :description: The :term:`Profile`'s :ref:`profile-description` - :name: The :term:`Profile`'s :ref:`profile-name` - :type: The :term:`Profile`'s :ref:`profile-type` - -:parameters: An array of :term:`Parameters` in use by this :term:`Profile` - - :config_file: The :term:`Parameter`'s :ref:`parameter-config-file` - :name: :ref:`parameter-name` of the :term:`Parameter` - :value: The :term:`Parameter`'s :ref:`parameter-value` - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/profiles/import HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - Content-Type: application/json - - { "profile": { - "name": "GLOBAL", - "description": "Global Traffic Ops profile", - "cdn": "ALL", - "type": "UNK_PROFILE" - }, - "parameters": [ - { - "config_file": "global", - "name": "tm.instance_name", - "value": "Traffic Ops CDN" - }, - { - "config_file": "global", - "name": "tm.toolname", - "value": "Traffic Ops" - } - ]} - -Response Structure ------------------- -:cdn: The name of the :ref:`profile-cdn` to which this :term:`Profile` belongs -:description: The :term:`Profile`'s :ref:`profile-description` -:name: The :term:`Profile`'s :ref:`profile-name` -:type: The :term:`Profile`'s :ref:`profile-type` -:id: The :term:`Profile`'s :ref:`profile-id` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: mzP7DVxFAGhICxqagwDyBDRea7oBZPMAx7NCDeOBVCRqlcCFFe7XL3JP58b80aaVOW/2ZGfg/jpYF70cdDfzQA== - X-Server-Name: traffic_ops_golang/ - Date: Fri, 13 Sep 2019 20:14:42 GMT - Transfer-Encoding: gzip - - - { "alerts": [ - { - "level": "success", - "text": "Profile imported [ Global ] with 2 new and 0 existing parameters" - } - ], - "response": { - "cdn": "ALL", - "name": "Global", - "id": 18, - "type": "UNK_PROFILE", - "description": "Global Traffic Ops profile" - }} diff --git a/docs/source/api/v2/profiles_name_name_copy_copy.rst b/docs/source/api/v2/profiles_name_name_copy_copy.rst deleted file mode 100644 index 50ac76e343..0000000000 --- a/docs/source/api/v2/profiles_name_name_copy_copy.rst +++ /dev/null @@ -1,88 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-profiles-name-name-copy-copy: - -**************************************** -``profiles/name/{{name}}/copy/{{copy}}`` -**************************************** - -``POST`` -======== -Copy :term:`Profile` to a new :term:`Profile`. The new :term:`Profile`'s :ref:`profile-name` must not already exist. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-----------------------------------------------------------------------------+ - | Name | Description | - +======+=============================================================================+ - | name | The :ref:`profile-name` of the new :term:`Profile` | - +------+-----------------------------------------------------------------------------+ - | copy | The :ref:`profile-name` of :term:`Profile` from which the copy will be made | - +------+-----------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/profiles/name/GLOBAL_copy/copy/GLOBAL HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:description: The new :term:`Profile`'s :ref:`profile-description` -:id: The :ref:`profile-id` of the new :term:`Profile` -:idCopyFrom: The :ref:`profile-id` of the :term:`Profile` from which the copy was made -:name: The :ref:`profile-name` of the new :term:`Profile` -:profileCopyFrom: The :ref:`profile-name` of the :term:`Profile` from which the copy was made - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Fri, 07 Dec 2018 22:03:54 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: r6V9viEZui1WCns0AUGEx1MtxjjXiU8SZVOtSQjeq7ZJDLl5s8fMmjJdR/HRWduHn7Ax6GzYhoKwnIjMyc7ZWg== - Content-Length: 252 - - { "alerts": [ - { - "level": "success", - "text": "Created new profile [ GLOBAL_copy ] from existing profile [ GLOBAL ]" - } - ], - "response": { - "idCopyFrom": 1, - "name": "GLOBAL_copy", - "profileCopyFrom": "GLOBAL", - "id": 17, - "description": "Global Traffic Ops profile, DO NOT DELETE" - }} diff --git a/docs/source/api/v2/profiles_name_name_parameters.rst b/docs/source/api/v2/profiles_name_name_parameters.rst deleted file mode 100644 index 161eb6bfd8..0000000000 --- a/docs/source/api/v2/profiles_name_name_parameters.rst +++ /dev/null @@ -1,246 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-profiles-name-name-parameters: - -************************************* -``profiles/name/{{name}}/parameters`` -************************************* - -``GET`` -======= -Retrieves all :term:`Parameters` associated with a given :term:`Profile` - -:Auth. Required: Yes -:Roles Required: None -:Response Type: None - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+--------------------------------------------------------------------------------------------+ - | Name | Description | - +======+============================================================================================+ - | name | The :ref:`profile-name` of the :term:`Profile` for which :term:`Parameters` will be listed | - +------+--------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/profiles/name/GLOBAL/parameters HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:configFile: The :term:`Parameter`'s :ref:`parameter-config-file` -:id: The :term:`Parameter`'s :ref:`parameter-id` -:lastUpdated: The date and time at which this :term:`Parameter` was last updated, in :ref:`non-rfc-datetime` -:name: :ref:`parameter-name` of the :term:`Parameter` -:profiles: An array of :term:`Profile` :ref:`Names ` that use this :term:`Parameter` -:secure: A boolean value that describes whether or not the :term:`Parameter` is :ref:`parameter-secure` -:value: The :term:`Parameter`'s :ref:`parameter-value` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: NudgZXUNyKNpmSFf856KEjyy+Pin/bFhG9NoRBDAxYbRKt2T5fF5Ze7sUNZfFI5n/ZZsgbx6Tsgtfd7oM6j+eg== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 05 Dec 2018 21:52:08 GMT - Content-Length: 542 - - { "response": [ - { - "configFile": "global", - "id": 4, - "lastUpdated": "2018-12-05 17:50:49+00", - "name": "tm.instance_name", - "secure": false, - "value": "Traffic Ops CDN" - }, - { - "configFile": "global", - "id": 5, - "lastUpdated": "2018-12-05 17:50:49+00", - "name": "tm.toolname", - "secure": false, - "value": "Traffic Ops" - }, - { - "configFile": "global", - "id": 6, - "lastUpdated": "2018-12-05 17:50:51+00", - "name": "use_tenancy", - "secure": false, - "value": "1" - }, - { - "configFile": "regex_revalidate.config", - "id": 7, - "lastUpdated": "2018-12-05 17:50:49+00", - "name": "maxRevalDurationDays", - "secure": false, - "value": "90" - } - ]} - -``POST`` -======== -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. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------------------------------------------------------+ - | Name | Description | - +======+=============================================================================================+ - | name | The :ref:`profile-name` of the :term:`Profile` to which :term:`Parameters` will be assigned | - +------+---------------------------------------------------------------------------------------------+ - -This endpoint accepts two formats for the request payload: - -Single Parameter Format - Specify a single parameter to assign to the specified profile -Parameter Array Format - Specify multiple parameters to assign to the specified profile - -.. warning:: Most API endpoints dealing with parameters treat ``secure`` as a boolean value, whereas this endpoint takes the legacy approach of treating it as an integer. Be careful when passing data back and forth, as boolean values will **not** be accepted by this endpoint! - -Single Parameter Format -""""""""""""""""""""""" -:configFile: The :term:`Parameter`'s :ref:`parameter-config-file` -:name: :ref:`parameter-name` of the :term:`Parameter` -:secure: A boolean value that describes whether or not the :term:`Parameter` is :ref:`parameter-secure` -:value: The :term:`Parameter`'s :ref:`parameter-value` - -.. code-block:: http - :caption: Request Example - Single Parameter Format - - POST /api/2.0/profiles/name/test/parameters HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 99 - Content-Type: application/json - - { - "name": "test", - "configFile": "quest", - "value": "A test parameter for API examples", - "secure": 0 - } - -Parameter Array Format -"""""""""""""""""""""" -:configFile: The :term:`Parameter`'s :ref:`parameter-config-file` -:name: :ref:`parameter-name` of the :term:`Parameter` -:secure: A boolean value that describes whether or not the :term:`Parameter` is :ref:`parameter-secure` -:value: The :term:`Parameter`'s :ref:`parameter-value` - -.. code-block:: http - :caption: Request Example - Parameter Array Format - - POST /api/2.0/profiles/name/test/parameters HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 212 - Content-Type: application/json - - [{ - "name": "test", - "configFile": "quest", - "value": "A test parameter for API examples", - "secure": 0 - }, - { - "name": "foo", - "configFile": "bar", - "value": "Another test parameter for API examples", - "secure": 0 - }] - -Response Structure ------------------- -:parameters: An array of objects representing the :term:`Parameters` which have been assigned - - :configFile: The :term:`Parameter`'s :ref:`parameter-config-file` - :name: :ref:`parameter-name` of the :term:`Parameter` - :secure: A boolean value that describes whether or not the :term:`Parameter` is :ref:`parameter-secure` - :value: The :term:`Parameter`'s :ref:`parameter-value` - -:profileId: The :ref:`profile-id` of the :term:`Profile` to which the :term:`Parameter`\ (s) have been assigned -:profileName: :ref:`profile-name` of the :term:`Profile` to which the :term:`Parameter`\ (s) have been assigned - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: HQWqOkoYHjvcxheWPrHOb0oZnUC+qLG1LO4OjtsLLnZYVUIu/qgJrzvziPnKq3FEHUWaZrnDCZM/iZD8AXOKBw== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 14:20:22 GMT - Content-Length: 357 - - { "alerts": [ - { - "text": "Assign parameters successfully to profile test", - "level": "success" - } - ], - "response": { - "parameters": [ - { - "configFile": "quest", - "name": "test", - "secure": 0, - "value": "A test parameter for API examples", - "id": 126 - }, - { - "configFile": "bar", - "name": "foo", - "secure": 0, - "value": "Another test parameter for API examples", - "id": 129 - } - ], - "profileId": 18, - "profileName": "test" - }} - -.. note:: The format of the request does not affect the format of the response. ``parameters`` will be an array either way. diff --git a/docs/source/api/v2/regions.rst b/docs/source/api/v2/regions.rst deleted file mode 100644 index 4c0793b4f5..0000000000 --- a/docs/source/api/v2/regions.rst +++ /dev/null @@ -1,224 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-regions: - -*********** -``regions`` -*********** - -``GET`` -======= -Retrieves information about :term:`Regions` - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+===============================================================================================================+ - | division | no | Filter :term:`Regions` by the integral, unique identifier of the :term:`Division` which contains them | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | id | no | Filter :term:`Regions` by integral, unique identifier | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | name | no | Filter :term:`Regions` by name | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/regions?division=1 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure -------------------- -:divisionName: The name of the division which contains this region -:divisionId: The integral, unique identifier of the division which contains this region -:id: An integral, unique identifier for this region -:lastUpdated: The date and time at which this region was last updated, in :ref:`non-rfc-datetime` -:name: The region name - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: nSYbR+fRXaxhYl7dWgf0Udo2AsiXEnwvED1CPbk7ZNWK03I3TOhtmCQx9ABnJJ6xKYnlt6EKMeopVTK0nKU+SQ== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 06 Dec 2018 01:58:38 GMT - Content-Length: 117 - - { "response": [ - { - "divisionName": "Quebec", - "division": 1, - "id": 2, - "lastUpdated": "2018-12-05 17:50:58+00", - "name": "Montreal" - } - ]} - -``POST`` -======== -Creates a new region - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -:division: The integral, unique identifier of the division which shall contain the new region\ [1]_ -:divisionName: The name of the division which shall contain the new region\ [1]_ -:name: The name of the region - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/regions HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 65 - Content-Type: application/json - - { - "name": "Manchester", - "division": "4", - "divisionName": "England" - } - -.. [1] The only "division" key that actually matters in the request body is ``division``; ``divisionName`` is not validated and has no effect - particularly not the effect of re-naming the division - beyond changing the name in the API response to this request. Subsequent requests will reveal the true name of the division. Note that if ``divisionName`` is not present in the request body it will be ``null`` in the response, but again further requests will show the true division name (provided it has been assigned to a division). - -Response Structure ------------------- -:divisionName: The name of the division which contains this region -:divisionId: The integral, unique identifier of the division which contains this region -:id: An integral, unique identifier for this region -:lastUpdated: The date and time at which this region was last updated, in :ref:`non-rfc-datetime` -:name: The region name - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: ezxk+iP7o7KE7zpWmGc0j8nz5k+1wAzY0HiNiA2xswTQrt+N+6CgQqUV2r9G1HAsPNr0HF2PhYs/Xr7DrYOw0A== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 06 Dec 2018 02:14:45 GMT - Content-Length: 178 - - { "alerts": [ - { - "text": "region was created.", - "level": "success" - } - ], - "response": { - "divisionName": "England", - "division": 3, - "id": 5, - "lastUpdated": "2018-12-06 02:14:45+00", - "name": "Manchester" - }} - -``DELETE`` -========== -Deletes a region. If no query parameter is specified, a ``400 Bad Request`` response is returned. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ - -.. table:: Request Query Parameters - - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+===============================================================================================================+ - | id | no | Delete :term:`Region` by integral, unique identifier | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | name | no | Delete :term:`Region` by name | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/regions?name=Manchester HTTP/1.1 - User-Agent: curl/7.29.0 - Host: trafficops.infra.ciab.test - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Fri, 07 Feb 2020 13:56:24 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: yNqXKcoiohEbJrEkH8LD1zifh87dIusuvUqgQnYueyKqCXkfd5bQvQ0OhQ2AAdSZa/oe2SAqMjojGsUlxHtIQw== - X-Server-Name: traffic_ops_golang/ - Date: Fri, 07 Feb 2020 12:56:24 GMT - Content-Length: 62 - - { - "alerts": [ - { - "text": "region was deleted.", - "level": "success" - } - ] - } diff --git a/docs/source/api/v2/regions_id.rst b/docs/source/api/v2/regions_id.rst deleted file mode 100644 index d1a6d1531e..0000000000 --- a/docs/source/api/v2/regions_id.rst +++ /dev/null @@ -1,99 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-regions-id: - -****************** -``regions/{{ID}}`` -****************** - -``PUT`` -======= -Updates a :term:`Region`. - -:Auth. Required: Yes -:Role(s) Required: "admin" or "operator" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------------------+ - | Name | Description | - +======+=========================================================+ - | ID | The integral, unique identifier of the region to update | - +------+---------------------------------------------------------+ - -:division: The new integral, unique identifier of the division which shall contain the region\ [1]_ -:divisionName: The new name of the division which shall contain the region\ [1]_ -:name: The new name of the region - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/regions/5 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 60 - Content-Type: application/json - - { - "name": "Leeds", - "division": 3, - "divisionName": "England" - } - -.. [1] The only "division" key that actually matters in the request body is ``division``; ``divisionName`` is not validated and has no effect - particularly not the effect of re-naming the division - beyond changing the name in the API response to this request. Subsequent requests will reveal the true name of the division. Note that if ``divisionName`` is not present in the request body it will be ``null`` in the response, but again further requests will show the true division name (provided it has been assigned to a division). - - -Response Structure ------------------- -:divisionName: The name of the division which contains this region -:divisionId: The integral, unique identifier of the division which contains this region -:id: An integral, unique identifier for this region -:lastUpdated: The date and time at which this region was last updated, in :ref:`non-rfc-datetime` -:name: The region name - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 7SVj4q7dtSTNQEJlBApEwlad28WBVFnpdHaatoIpNfeLltfcpcdVTcOKB4JXQv7rlSD2p/TxBQC6EXpxwYTnKQ== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 06 Dec 2018 02:23:40 GMT - Content-Length: 173 - - { "alerts": [ - { - "text": "region was updated.", - "level": "success" - } - ], - "response": { - "divisionName": "England", - "division": 3, - "id": 5, - "lastUpdated": "2018-12-06 02:23:40+00", - "name": "Leeds" - }} diff --git a/docs/source/api/v2/roles.rst b/docs/source/api/v2/roles.rst deleted file mode 100644 index 4b432fe9d9..0000000000 --- a/docs/source/api/v2/roles.rst +++ /dev/null @@ -1,310 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-roles: - -********* -``roles`` -********* - -``GET`` -======= -Retrieves all user :term:`Roles`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+===============================================================================================================+ - | id | no | Return only the :term:`Role` identified by this integral, unique identifier | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | name | no | Return only the :term:`Role` with this name | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | privLevel | no | Return only those :term:`Roles` that have this privilege level | - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/roles?name=admin HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:capabilities: An array of the names of the Capabilities given to this :term:`Role` -:description: A description of the :term:`Role` -:id: The integral, unique identifier for this :term:`Role` -:name: The name of the :term:`Role` -:privLevel: An integer that allows for comparison between :term:`Roles` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: TEDXlQqWMSnJbL10JtFdbw0nqciNpjc4bd6m7iAB8aymakWeF+ghs1k5LayjdzHcjeDE8UNF/HXSxOFvoLFEuA== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 04 Sep 2019 17:15:36 GMT - Content-Length: 120 - - { "response": [ - { - "id": 4, - "name": "admin", - "description": "super-user", - "privLevel": 30, - "capabilities": [ - "all-write", - "all-read" - ] - } - ]} - -``POST`` -======== -Creates a new :term:`Role`. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: Object - -Request Structure ------------------ -:capabilities: An optional array of capability names that will be granted to the new :term:`Role` -:description: A helpful description of the :term:`Role`'s purpose. -:name: The name of the new :term:`Role` -:privLevel: The privilege level of the new :term:`Role`\ [#privlevel]_ - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/roles HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 56 - Content-Type: application/json - - { - "name": "test", - "description": "quest", - "privLevel": 30 - } - - -Response Structure ------------------- -:capabilities: An array of the names of the Capabilities given to this :term:`Role` - - .. tip:: This can be ``null`` *or* empty, depending on whether it was present in the request body, or merely empty. Obviously, it can also be a populated array. - -:description: A description of the :term:`Role` -:id: The integral, unique identifier for this :term:`Role` -:name: The name of the :term:`Role` -:privLevel: An integer that allows for comparison between :term:`Roles` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: gzfc7m/in5vVsVP+Y9h6JJfDhgpXKn9VAzoiPENhKbQfP8Q6jug08Rt2AK/3Nz1cx5zZ8P9IjVxDdIg7mlC8bw== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 04 Sep 2019 17:44:42 GMT - Content-Length: 150 - - { "alerts": [{ - "text": "role was created.", - "level": "success" - }], - "response": { - "id": 5, - "name": "test", - "description": "quest", - "privLevel": 30, - "capabilities": null - }} - -``PUT`` -======= -Replaces an existing :term:`Role` with one provided by the request. - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------+----------+--------------------------------------------------------------------+ - | Name | Required | Description | - +======+==========+====================================================================+ - | id | yes | The integral, unique identifier of the :term:`Role` to be replaced | - +------+----------+--------------------------------------------------------------------+ - -:capabilities: An optional array of capability names that will be granted to the new :term:`Role` - - .. warning:: When not present, the affected :term:`Role`'s Capabilities will be unchanged - *not* removed, unlike when the array is empty. - -:description: A helpful description of the :term:`Role`'s purpose. -:name: The new name of the :term:`Role` -:privLevel: The new privilege level of the new :term:`Role`\ [#privlevel]_ - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/roles?id=5 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 56 - Content-Type: application/json - - { - "name":"test", - "privLevel": 29, - "description": "quest" - } - -Response Structure ------------------- -:capabilities: An array of the names of the Capabilities given to this :term:`Role` - - .. tip:: This can be ``null`` *or* empty, depending on whether it was present in the request body, or merely empty. Obviously, it can also be a populated array. - - .. warning:: If no ``capabilities`` array was given in the request, this will *always* be ``null``, even if the :term:`Role` has Capabilities that would have gone unchanged. - -:description: A description of the :term:`Role` -:id: The integral, unique identifier for this :term:`Role` -:name: The name of the :term:`Role` -:privLevel: An integer that allows for comparison between :term:`Roles` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: mlHQenE1Q3gjrIK2lC2hfueQOaTCpdYEfboN0A9vYPUIwTiaF5ZaAMPQBdfGyiAhgHRxowITs3bR7s1L++oFTQ== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 05 Sep 2019 12:56:46 GMT - Content-Length: 150 - - { - "alerts": [ - { - "text": "role was updated.", - "level": "success" - } - ], - "response": { - "id": 5, - "name": "test", - "description": "quest", - "privLevel": 29, - "capabilities": null - } - } - - -``DELETE`` -========== -Deletes a :term:`Role` - -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------+----------+--------------------------------------------------------------------+ - | Name | Required | Description | - +======+==========+====================================================================+ - | id | yes | The integral, unique identifier of the :term:`Role` to be replaced | - +------+----------+--------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/roles?id=5 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 10jeFZihtbvAus/XyHAW8rhgS9JBD+X/ezCp1iExYkEcHxN4gjr1L6x8zDFXORueBSlFldgtbWKT7QsmwCHUWA== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 05 Sep 2019 13:02:06 GMT - Content-Length: 59 - - { "alerts": [{ - "text": "role was deleted.", - "level": "success" - }]} - -.. [#privlevel] ``privLevel`` cannot exceed the privilege level of the requesting user. Which, of course, must be the privilege level of "admin". Basically, this means that there can never exist a :term:`Role` with a higher privilege level than "admin". diff --git a/docs/source/api/v2/server_capabilities.rst b/docs/source/api/v2/server_capabilities.rst deleted file mode 100644 index 86a27f5054..0000000000 --- a/docs/source/api/v2/server_capabilities.rst +++ /dev/null @@ -1,190 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-server_capabilities: - -*********************** -``server_capabilities`` -*********************** - -``GET`` -======= -Retrieves :term:`Server Capabilities`. - -:Auth. Required: Yes -:Roles Required: "read-only" -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------+----------+-----------------------------------------------------+ - | Name | Required | Description | - +======+==========+=====================================================+ - | name | no | Return the :term:`Server Capability` with this name | - +------+----------+-----------------------------------------------------+ - -.. code-block:: http - :caption: Request Structure - - GET /api/2.0/server_capabilities?name=RAM HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:name: The name of this :term:`Server Capability` -:lastUpdated: The date and time at which this :term:`Server Capability` was last updated, in ISO-like format - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: EH8jo8OrCu79Tz9xpgT3YRyKJ/p2NcTmbS3huwtqRByHz9H6qZLQjA59RIPaVSq3ZxsU6QhTaox5nBkQ9LPSAA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 07 Oct 2019 21:36:13 GMT - Content-Length: 68 - - { - "response": [ - { - "name": "RAM", - "lastUpdated": "2019-10-07 20:38:24+00" - } - ] - } - -``POST`` -======== -Create a new :term:`Server Capability`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -:name: The name of the :term:`Server Capability` - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/server_capabilities HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 15 - Content-Type: application/json - - { - "name": "RAM" - } - -Response Structure ------------------- -:name: The name of this :term:`Server Capability` -:lastUpdated: The date and time at which this :term:`Server Capability` was last updated, in ISO-like format - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: ysdopC//JQI79BRUa61s6M2HzHxYHpo5RdcuauOoqCYxiVOoUhNZfOVydVkv8zDN2qA374XKnym4kWj3VzQIXg== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 07 Oct 2019 22:10:00 GMT - Content-Length: 137 - - { - "alerts": [ - { - "text": "server capability was created.", - "level": "success" - } - ], - "response": { - "name": "RAM", - "lastUpdated": "2019-10-07 22:10:00+00" - } - } - -``DELETE`` -========== -Deletes a specific :term:`Server Capability`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------+----------+---------------------------------------------------------+ - | Name | Required | Description | - +======+==========+=========================================================+ - | name | yes | The name of the :term:`Server Capability` to be deleted | - +------+----------+---------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/server_capabilities?name=RAM HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 8zCAATbCzcqiqigGVBy7WF1duDuXu1Wg2DBe9yfqTw/c+yhE2eUk73hFTA/Oqt0kocaN7+1GkbFdPkQPvbnRaA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 07 Oct 2019 20:44:40 GMT - Content-Length: 72 - - { - "alerts": [ - { - "text": "server capability was deleted.", - "level": "success" - } - ] - } diff --git a/docs/source/api/v2/server_server_capabilities.rst b/docs/source/api/v2/server_server_capabilities.rst deleted file mode 100644 index f322b36920..0000000000 --- a/docs/source/api/v2/server_server_capabilities.rst +++ /dev/null @@ -1,225 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-server-server-capabilities: - -****************************** -``server_server_capabilities`` -****************************** - -``GET`` -======= -Gets all associations of :term:`Server Capabilities` to :term:`cache servers`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +==================+==========+==============================================================================================================================+ - | serverId | no | Filter :term:`Server Capability` associations by the integral, unique identifier of the server to which they are assigned | - +------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ - | serverHostName | no | Filter :term:`Server Capability` associations by the host name of the server to which they are assigned | - +------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ - | serverCapability | no | Filter :term:`Server Capability` associations by :term:`Server Capability` name | - +------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/server_server_capabilities HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:serverHostName: The server's host name -:serverId: The server's integral, unique identifier -:lastUpdated: The date and time at which this association between the server and the :term:`Server Capability` was last updated, in :ref:`non-rfc-datetime` -:serverCapability: The :term:`Server Capability`'s name - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: UFO3/jcBFmFZM7CsrsIwTfPc5v8gUiXqJm6BNp1boPb4EQBnWNXZh/DbBwhMAOJoeqDImoDlrLnrVjQGO4AooA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 07 Oct 2019 22:15:11 GMT - Content-Length: 150 - - { - "response": [ - { - "lastUpdated": "2019-10-07 22:05:31+00", - "serverHostName": "atlanta-org-1", - "serverId": 260, - "serverCapability": "ram" - }, - { - "lastUpdated": "2019-10-07 22:05:31+00", - "serverHostName": "atlanta-org-2", - "serverId": 261, - "serverCapability": "disk" - } - ] - } - -``POST`` -======== -Associates a :term:`Server Capability` to a server. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -:serverId: The integral, unique identifier of a server to be associated with a :term:`Server Capability` -:serverCapability: The :term:`Server Capability`'s name to associate - -.. note:: The server referenced must be either an :term:`Edge-tier` or :term:`Mid-tier cache server`. - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/server_server_capabilities HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 84 - Content-Type: application/json - - { - "serverId": 1, - "serverCapability": "disk" - } - -Response Structure ------------------- -:serverId: The integral, unique identifier of the newly associated server -:lastUpdated: The date and time at which this association between the server and the :term:`Server Capability` was last updated, in :ref:`non-rfc-datetime` -:serverCapability: The :term:`Server Capability`'s name - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: eQrl48zWids0kDpfCYmmtYMpegjnFxfOVvlBYxxLSfp7P7p6oWX4uiC+/Cfh2X9i3G+MQ36eH95gukJqOBOGbQ== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 07 Oct 2019 22:15:11 GMT - Content-Length: 157 - - { - "alerts": [ - { - "text": "server server_capability was created.", - "level": "success" - } - ], - "response": { - "lastUpdated": "2019-10-07 22:15:11+00", - "serverId": 1, - "serverCapability": "disk" - } - } - -``DELETE`` -========== -Disassociate a server from a :term:`Server Capability`. - - .. note:: If the ``serverCapability`` is a :term:`Server Capability` required by a :term:`Delivery Service` that to which the server is assigned the DELETE will be blocked until either the server is unassigned from the :term:`Delivery Service` or the :term:`Server Capability` is no longer required by the :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------------------+----------+-----------------------------------------------------------------+ - | Name | Required | Description | - +==================+==========+=================================================================+ - | serverId | yes | The integral, unique identifier of the server to disassociate | - +------------------+----------+-----------------------------------------------------------------+ - | serverCapability | yes | term:`Server Capability` name to disassociate from given server | - +------------------+----------+-----------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/server_server_capabilities?serverId=1&serverCapability=disk HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: UFO3/jcBFmFZM7CsrsIwTfPc5v8gUiXqJm6BNp1boPb4EQBnWNXZh/DbBwhMAOJoeqDImoDlrLnrVjQGO4AooA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 07 Oct 2019 22:15:11 GMT - Content-Length: 96 - - { - "alerts": [ - { - "text": "server server_capability was deleted.", - "level": "success" - } - ] - } diff --git a/docs/source/api/v2/servercheck.rst b/docs/source/api/v2/servercheck.rst deleted file mode 100644 index b7863a0030..0000000000 --- a/docs/source/api/v2/servercheck.rst +++ /dev/null @@ -1,134 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-servercheck: - -*************** -``servercheck`` -*************** - -.. seealso:: :ref:`to-check-ext` - -``GET`` -======= -Fetches identifying and meta information as well as "check" values regarding all servers that have a :term:`Type` with a name beginning with "EDGE" or "MID" (ostensibly this is equivalent to all :term:`cache servers`). - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -No parameters available. - -Response Structure ------------------- -:adminState: The name of the server's :term:`Status` - called "adminState" for legacy reasons -:cacheGroup: The name of the :term:`Cache Group` to which the server belongs -:checks: An optionally present map of the names of "checks" to their values. Only numeric and boolean checks are represented, and boolean checks are represented as integers with ``0`` meaning "false" and ``1`` meaning "true". Will not appear if the server in question has no valued "checks". -:hostName: The (short) hostname of the server -:id: The server's integral, unique identifier -:profile: The name of the :term:`Profile` used by the server -:revalPending: A boolean that indicates whether or not the server has pending revalidations -:type: The name of the server's :term:`Type` -:updPending: A boolean that indicates whether or not the server has pending updates - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Thu, 23 Jan 2020 20:00:19 GMT; Max-Age=3600; HttpOnly - X-Server-Name: traffic_ops_golang/ - Date: Thu, 23 Jan 2020 19:00:19 GMT - Content-Length: 352 - - { "response": [ - { - "adminState": "REPORTED", - "cacheGroup": "CDN_in_a_Box_Edge", - "id": 12, - "hostName": "edge", - "revalPending": false, - "profile": "ATS_EDGE_TIER_CACHE", - "type": "EDGE", - "updPending": false - }, - { - "adminState": "REPORTED", - "cacheGroup": "CDN_in_a_Box_Mid", - "id": 11, - "hostName": "mid", - "revalPending": false, - "profile": "ATS_MID_TIER_CACHE", - "type": "MID", - "updPending": false - } - ]} - -``POST`` -======== -Post a server check result to the "serverchecks" table. Updates the resulting value from running a given check extension on a server. - -:Auth. Required: Yes -:Roles Required: None\ [1]_ -:Response Type: Object - -Request Structure ------------------ -The request only requires to have either ``host_name`` or ``id`` defined. - -:host_name: The hostname of the server to which this "servercheck" refers. -:id: The id of the server to which this "servercheck" refers. -:servercheck_short_name: The short name of the "servercheck". -:value: The value of the "servercheck" - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/servercheck HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 113 - Content-Type: application/json - - { - "id": 1, - "host_name": "edge", - "servercheck_short_name": "test", - "value": 1 - } - -Response Structure ------------------- -.. code-block:: json - :caption: Response Example - - { "alerts": [ - { - "level": "success", - "text": "Server Check was successfully updated." - } - ]} - -.. [1] No roles are required to use this endpoint, however access is controlled by username. Only the reserved user ``extension`` is permitted the use of this endpoint. - diff --git a/docs/source/api/v2/servercheck_extensions.rst b/docs/source/api/v2/servercheck_extensions.rst deleted file mode 100644 index a89c6078bd..0000000000 --- a/docs/source/api/v2/servercheck_extensions.rst +++ /dev/null @@ -1,213 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-servercheck_extensions: - -************************** -``servercheck/extensions`` -************************** -.. seealso:: :ref:`admin-to-ext-script` - -``GET`` -======= -Retrieves the list of Traffic Ops extensions. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +==================+==========+==============================================================================================================================+ - | id | no | Filter TO Extensions by the integral, unique identifier of an Extension | - +------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ - | name | no | Filter TO Extensions by the name of an Extension | - +------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ - | script_file | no | Filter TO Extensions by the base filename of the script that runs for the Extension | - +------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ - | isactive | no | Boolean used to return either only active (1) or inactive(0) TO Extensions | - +------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ - | type | no | Filter TO Extensions by the type of Extension | - +------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/servercheck/extensions HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:additional_config_json: A string containing a JSON-encoded object with extra configuration options... inside a JSON object... -:description: A short description of the extension - - .. note:: This is, unfortunately, ``null`` for all default extensions - -:id: An integral, unique identifier for this extension definition -:info_url: A URL where info about this extension may be found -:isactive: An integer describing the boolean notion of whether or not the extension is active; one of: - - 0 - disabled - 1 - enabled - -:name: The name of the extension -:script_file: The base filename of the script that runs for the extension -:servercheck_shortname: The name of the column in the table at 'Monitor' -> 'Cache Checks' in Traffic Portal, where "Check Extension" output is displayed -:type: The Check :term:`Type` of the extension. This will always be a CHECK_EXTENSION type with the naming convention of ``CHECK_EXTENSION_*``. -:version: A (hopefully) semantic version number describing the version of the plugin - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Tue, 11 Dec 2018 20:51:48 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: n73jg9XR4V5Cwqq56Rf3wuIi99k3mM5u2NAjcZ/gQBu8jvAFymDlnZqKeJ+wTll1vjIsHpXCOVXV7+5UGakLgA== - Transfer-Encoding: chunked - - { "response": [ - { - "script_file": "ToPingCheck.pl", - "version": "1.0.0", - "name": "ILO_PING", - "description": null, - "info_url": "-", - "additional_config_json": "{ check_name: \"ILO\", \"base_url\": \"https://localhost\", \"select\": \"ilo_ip_address\", \"cron\": \"9 * * * *\" }", - "isactive": 1, - "type": "CHECK_EXTENSION_BOOL", - "id": 1, - "servercheck_short_name": "ILO" - }, - { - "script_file": "ToPingCheck.pl", - "version": "1.0.0", - "name": "10G_PING", - "description": null, - "info_url": "-", - "additional_config_json": "{ check_name: \"10G\", \"base_url\": \"https://localhost\", \"select\": \"ip_address\", \"cron\": \"18 * * * *\" }", - "isactive": 1, - "type": "CHECK_EXTENSION_BOOL", - "id": 2, - "servercheck_short_name": "10G" - } - ]} - -``POST`` -======== -Creates a new Traffic Ops check extension. - -:Auth. Required: Yes -:Roles Required: None\ [1]_ -:Response Type: ``undefined`` - -Request Structure ------------------ -:additional_config_json: An optional string containing a JSON-encoded object with extra configuration options... inside a JSON object... -:description: A short description of the extension -:info_url: A URL where info about this extension may be found -:isactive: An integer describing the boolean notion of whether or not the extension is active; one of: - - 0 - disabled - 1 - enabled - -:name: The name of the extension -:script_file: The base filename of the script that runs for the extension - - .. seealso:: :ref:`admin-to-ext-script` for details on where the script should be located on the Traffic Ops server - -:servercheck_shortname: The name of the column in the table at 'Monitor' -> 'Cache Checks' in Traffic Portal, where "Check Extension" output is displayed -:type: The :term:`Type` of extension. Must be CHECK_EXTENSION type with the naming convention of ``CHECK_EXTENSION_*``. -:version: A (hopefully) semantic version number describing the version of the plugin - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/servercheck/extensions HTTP/1.1 - Host: cache1.example.com:6443 - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 208 - Content-Type: application/json - - { - "name": "test", - "version": "0.0.1-1", - "info_url": "", - "script_file": "", - "isactive": 0, - "description": "A test extension for API examples", - "servercheck_short_name": "test", - "type": "CHECK_EXTENSION_NUM" - } - - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Wed, 12 Dec 2018 16:37:44 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: 7M67PYnli6WzGQFS3g8Gh1SOyq6VENZMqm/kUffOTLLFfuWSEuSLA65R5R+VyJiNjdqOG5Bp78mk+JYcqhtVGw== - Content-Length: 89 - - { "supplemental": - { - "id": 5 - }, - "alerts": [{ - "level": "success", - "text": "Check Extension Loaded." - }]} - -.. [1] No roles are required to use this endpoint, however access is controlled by username. Only the reserved user ``extension`` is permitted the use of this endpoint. diff --git a/docs/source/api/v2/servercheck_extensions_id.rst b/docs/source/api/v2/servercheck_extensions_id.rst deleted file mode 100644 index 0ddeac7883..0000000000 --- a/docs/source/api/v2/servercheck_extensions_id.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-servercheck_extensions-id: - -********************************* -``servercheck/extensions/{{ID}}`` -********************************* - -``DELETE`` -========== -Deletes a Traffic Ops server check extension definition. This does **not** delete the actual extension file. - -:Auth. Required: Yes -:Roles Required: None\ [1]_ -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------------------------------------+ - | Name | Description | - +======+===========================================================================+ - | ID | The integral, unique identifier of the extension definition to be deleted | - +------+---------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/servercheck/extensions/16 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Wed, 12 Dec 2018 16:33:52 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: EB0Nu85azbGzaehDTAODP3NPqWbByIza1XQhgwtsW2WTXyK/dxQtncp0YiJXyO0tH9H+n+6BBfojBOb5h0dFPA== - Content-Length: 60 - - { "alerts": [ - { - "level": "success", - "text": "Extension deleted." - } - ]} - -.. [1] No roles are required to use this endpoint, however access is controlled by username. Only the reserved user ``extension`` is permitted the use of this endpoint. diff --git a/docs/source/api/v2/servers.rst b/docs/source/api/v2/servers.rst deleted file mode 100644 index 647f289c42..0000000000 --- a/docs/source/api/v2/servers.rst +++ /dev/null @@ -1,424 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-servers: - -*********** -``servers`` -*********** - -``GET`` -======= -Retrieves properties of all servers across all CDNs. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------------+----------+-------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +============+==========+===================================================================================================================+ - | 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 | - +------------+----------+-------------------------------------------------------------------------------------------------------------------+ - | hostName | no | Return only those servers that have this (short) hostname | - +------------+----------+-------------------------------------------------------------------------------------------------------------------+ - | id | no | Return only the server with this integral, unique identifier | - +------------+----------+-------------------------------------------------------------------------------------------------------------------+ - | profileId | no | Return only those servers that are using the :term:`Profile` that has this :ref:`profile-id` | - +------------+----------+-------------------------------------------------------------------------------------------------------------------+ - | status | no | Return only those servers with this status - see :ref:`health-proto` | - +------------+----------+-------------------------------------------------------------------------------------------------------------------+ - | type | no | Return only servers of this :term:`Type` | - +------------+----------+-------------------------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/servers?hostName=mid HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -: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 :abbr:`FQDN (Fully Qualified Domain Name)` -:guid: An identifier used to uniquely identify the server - - .. 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 :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`` -:ip6IsService: A boolean value which if ``true`` indicates that the IPv6 address will be used for routing content. -:ip6Gateway: The IPv6 address of the gateway used by ``interfaceName`` -:ipAddress: The IPv4 address of ``interfaceName`` -:ipIsService: A boolean value which if ``true`` indicates that the IPv4 address will be used for routing content. -:ipGateway: The IPv4 address of the gateway used by ``interfaceName`` -:ipNetmask: The IPv4 subnet mask used by ``interfaceName`` -:lastUpdated: The date and time at which this server description was last modified -:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management' -: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 -: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 -:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation -:rack: A string indicating "server rack" location -:routerHostName: The human-readable name of the router responsible for reaching this server -:routerPortName: The human-readable name of the port used by the router responsible for reaching this server -:status: The :term:`Status` of the server - - .. seealso:: :ref:`health-proto` - -:statusId: The integral, unique identifier of the status of this server - - .. seealso:: :ref:`health-proto` - -:tcpPort: The port on which this server listens for incoming TCP connections - - .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections. - -:type: The name of the :term:`Type` of this server -:typeId: The integral, unique identifier of the 'type' of this server -:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Control Cache Config (:term:`t3c`, formerly ORT) -:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards. -:xmppPasswd: The password used in XMPP communications with the server - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: WyapQctUIhjzEALka5QbBiZRZ58Mlc6MJSwjBeGyJS2UzbL3W6lN/4kvAZtPrP4qMWQBWz6JjbF7Y5lNRASUmQ== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 16:13:31 GMT - Content-Length: 939 - - { "response": [ - { - "cachegroup": "CDN_in_a_Box_Mid", - "cachegroupId": 6, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "domainName": "infra.ciab.test", - "guid": null, - "hostName": "mid", - "httpsPort": 443, - "id": 10, - "iloIpAddress": "", - "iloIpGateway": "", - "iloIpNetmask": "", - "iloPassword": "", - "iloUsername": "", - "interfaceMtu": 1500, - "interfaceName": "eth0", - "ip6Address": "fc01:9400:1000:8::120", - "ip6Gateway": "fc01:9400:1000:8::1", - "ipAddress": "172.16.239.120", - "ipGateway": "172.16.239.1", - "ipNetmask": "255.255.255.0", - "lastUpdated": "2018-12-05 18:45:05+00", - "mgmtIpAddress": "", - "mgmtIpGateway": "", - "mgmtIpNetmask": "", - "offlineReason": "", - "physLocation": "Apachecon North America 2018", - "physLocationId": 1, - "profile": "ATS_MID_TIER_CACHE", - "profileDesc": "Mid Cache - Apache Traffic Server", - "profileId": 10, - "rack": "", - "revalPending": false, - "routerHostName": "", - "routerPortName": "", - "status": "REPORTED", - "statusId": 3, - "tcpPort": 80, - "type": "MID", - "typeId": 12, - "updPending": false, - "xmppId": "mid", - "xmppPasswd": "", - "ipIsService": true, - "ip6IsService": true - } - ]} - -``POST`` -======== -Allows a user to create a new server. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -: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 :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 :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. - -:interfaceName: The name of the primary network interface used by the server -:ip6Address: An optional IPv6 address and subnet mask of ``interfaceName`` -:ip6IsService: An optional boolean value which if ``true`` indicates that the IPv6 address will be used for routing content. Defaults to ``true``. -:ip6Gateway: An optional IPv6 address of the gateway used by ``interfaceName`` -:ipAddress: The IPv4 address of ``interfaceName`` -:ipIsService: An optional boolean value which if ``true`` indicates that the IPv4 address will be used for routing content. Defaults to ``true``. -:ipGateway: The IPv4 address of the gateway used by ``interfaceName`` -:ipNetmask: The IPv4 subnet mask used by ``interfaceName`` -:mgmtIpAddress: An optional IPv4 address of some network interface on the server used for 'management' -:mgmtIpGateway: An optional IPv4 address of a gateway used by some network interface on the server used for 'management' -:mgmtIpNetmask: An optional IPv4 subnet mask used by some network interface on the server used for 'management' -:physLocationId: An integral, unique identifier for the physical location where the server resides -:profileId: The :ref:`profile-id` the :term:`Profile` that shall be used by this server -:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation -:rack: An optional string indicating "server rack" location -:routerHostName: An optional string containing the human-readable name of the router responsible for reaching this server -:routerPortName: An optional string containing the human-readable name of the port used by the router responsible for reaching this server -:statusId: The integral, unique identifier of the status of this server - - .. seealso:: :ref:`health-proto` - -:tcpPort: An optional port number on which this server listens for incoming TCP connections - - .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections. - -:typeId: The integral, unique identifier of the 'type' of this server -:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Control Cache Config (T3C, formerly ORT) -:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards. -:xmppPasswd: An optional password used in XMPP communications with the server - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/servers HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 599 - Content-Type: application/json - - { - "cachegroupId": 6, - "cdnId": 2, - "domainName": "infra.ciab.test", - "hostName": "test", - "httpsPort": 443, - "iloIpAddress": "", - "iloIpGateway": "", - "iloIpNetmask": "", - "iloPassword": "", - "iloUsername": "", - "interfaceMtu": 1500, - "interfaceName": "eth0", - "ip6Address": "::1", - "ip6Gateway": "::2", - "ipAddress": "0.0.0.1", - "ipGateway": "0.0.0.2", - "ipNetmask": "255.255.255.0", - "mgmtIpAddress": "", - "mgmtIpGateway": "", - "mgmtIpNetmask": "", - "offlineReason": "", - "physLocationId": 1, - "profileId": 10, - "routerHostName": "", - "routerPortName": "", - "statusId": 3, - "tcpPort": 80, - "typeId": 12, - "updPending": false, - "ipIsService": true, - "ip6IsService": true - } - -Response Structure ------------------- -: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 :abbr:`FQDN (Fully Qualified Domain Name)` -:guid: An identifier used to uniquely identify the server - - .. 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 :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`` -:ip6IsService: A boolean value which if ``true`` indicates that the IPv6 address will be used for routing content. -:ip6Gateway: The IPv6 address of the gateway used by ``interfaceName`` -:ipAddress: The IPv4 address of ``interfaceName`` -:ipIsService: A boolean value which if ``true`` indicates that the IPv4 address will be used for routing content. -:ipGateway: The IPv4 address of the gateway used by ``interfaceName`` -:ipNetmask: The IPv4 subnet mask used by ``interfaceName`` -:lastUpdated: The date and time at which this server description was last modified -:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management' -: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 :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 -:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation -:rack: A string indicating "server rack" location -:routerHostName: The human-readable name of the router responsible for reaching this server -:routerPortName: The human-readable name of the port used by the router responsible for reaching this server -:status: The status of the server - - .. seealso:: :ref:`health-proto` - -:statusId: The integral, unique identifier of the status of this server - - .. seealso:: :ref:`health-proto` - -:tcpPort: The port on which this server listens for incoming TCP connections - - .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections. - -:type: The name of the 'type' of this server -:typeId: The integral, unique identifier of the 'type' of this server -:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Control Cache Config (T3C, formerly ORT) -:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards. -:xmppPasswd: The password used in XMPP communications with the server - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: mcGmmu5ONDg3jmvlkItcw6jxiT1ecmePYujZfmKiZrn5ThKjsSadeJIynaeOK0XVUjHuYHdtdynSqxr2rdzEyA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 17:44:04 GMT - Content-Length: 850 - - { "alerts": [ - { - "text": "server was created.", - "level": "success" - } - ], - "response": { - "cachegroup": null, - "cachegroupId": 6, - "cdnId": 2, - "cdnName": null, - "domainName": "infra.ciab.test", - "guid": null, - "hostName": "test", - "httpsPort": 443, - "id": 13, - "iloIpAddress": "", - "iloIpGateway": "", - "iloIpNetmask": "", - "iloPassword": "", - "iloUsername": "", - "interfaceMtu": 1500, - "interfaceName": "eth0", - "ip6Address": "::1", - "ip6Gateway": "::2", - "ipAddress": "0.0.0.1", - "ipGateway": "0.0.0.2", - "ipNetmask": "255.255.255.0", - "lastUpdated": "2018-12-10 17:44:04+00", - "mgmtIpAddress": "", - "mgmtIpGateway": "", - "mgmtIpNetmask": "", - "offlineReason": "", - "physLocation": null, - "physLocationId": 1, - "profile": null, - "profileDesc": null, - "profileId": 10, - "rack": null, - "revalPending": null, - "routerHostName": "", - "routerPortName": "", - "status": null, - "statusId": 3, - "tcpPort": 80, - "type": "", - "typeId": 12, - "updPending": false, - "xmppId": "test", - "xmppPasswd": null, - "ipIsService": true, - "ip6IsService": true - }} - -.. [1] For more information see the `Wikipedia page on Lights-Out management `_\ . diff --git a/docs/source/api/v2/servers_details.rst b/docs/source/api/v2/servers_details.rst deleted file mode 100644 index 0d99b726b6..0000000000 --- a/docs/source/api/v2/servers_details.rst +++ /dev/null @@ -1,171 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-servers-details: - -******************* -``servers/details`` -******************* -Retrieves details of :ref:`tp-configure-servers`. - - -``GET`` -======= -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -.. note:: On top of the response including the response key that is of type array it will also include the keys ``limit``, ``orderby``, and ``size``. - -Request Structure ------------------ -.. table:: Request Query Parameters - - +----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +================+========================================+================================================================================================================================================================+ - | hostName | Required if no physLocationID provided | Return only the servers with this (short) hostname. Capitalization of "hostName" is important. | - +----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | physLocationID | Required if no hostName provided | Return only servers with this integral, unique identifier for the physical location where the server resides. Capitalization of "physLocationID" is important. | - +----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/servers/details?hostName=edge HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - -Response Structure ------------------- -:limit: The maximum size of the ``response`` array, also indicative of the number of results per page using the pagination requested by the query parameters (if any) - this should be the same as the ``limit`` query parameter (if given) -:orderby: A string that names the field by which the elements of the ``response`` array are ordered - should be the same as the ``orderby`` request query parameter (if given) -:response: An array of objects, each of which represents the details of a given :ref:`Server `. - - :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 :abbr:`FQDN (Fully Qualified Domain Name)` - :guid: An identifier used to uniquely identify the server - - .. 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 :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`` - :ipAddress: The IPv4 address of ``interfaceName`` - :ipGateway: The IPv4 address of the gateway used by ``interfaceName`` - :ipNetmask: The IPv4 subnet mask used by ``interfaceName`` - :mgmtIpAddress: The IPv4 address of the server's management port - :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 - :physLocation: The name of the 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 - :rack: A string indicating "server rack" location - :routerHostName: The human-readable name of the router responsible for reaching this server - :routerPortName: The human-readable name of the port used by the router responsible for reaching this server - :status: The status of the server - - .. seealso:: :ref:`health-proto` - - :tcpPort: The port on which this server listens for incoming TCP connections - - .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections. - - :type: The name of the 'type' of this server - :xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards. - :xmppPasswd: The password used in XMPP communications with the server - -:size: The page number - if pagination was requested in the query parameters, else ``0`` to indicate no pagination - of the results represented by the ``response`` array. This is named "size" for legacy reasons - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 01:27:36 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: HW2F3CEpohNAvNlEDhUfXmtwpEka4dwUWFVUSSjW98aXiv10vI6ysRIcC2P9huabCz5fdHqY3tp0LR4ekwEHqw== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 24 Feb 2020 00:27:36 GMT - Content-Length: 493 - - { - "limit": 1000, - "orderby": "hostName", - "response": [ - { - "cachegroup": "CDN_in_a_Box_Edge", - "cdnName": "CDN-in-a-Box", - "deliveryservices": [ - 1 - ], - "domainName": "infra.ciab.test", - "guid": null, - "hardwareInfo": null, - "hostName": "edge", - "httpsPort": 443, - "id": 5, - "iloIpAddress": "", - "iloIpGateway": "", - "iloIpNetmask": "", - "iloPassword": "", - "iloUsername": "", - "interfaceMtu": 1500, - "interfaceName": "eth0", - "ip6Address": "fc01:9400:1000:8::3", - "ip6Gateway": "fc01:9400:1000:8::1", - "ipAddress": "172.16.239.3", - "ipGateway": "172.16.239.1", - "ipNetmask": "255.255.255.0", - "mgmtIpAddress": "", - "mgmtIpGateway": "", - "mgmtIpNetmask": "", - "offlineReason": "", - "physLocation": "Apachecon North America 2018", - "profile": "ATS_EDGE_TIER_CACHE", - "profileDesc": "Edge Cache - Apache Traffic Server", - "rack": "", - "routerHostName": "", - "routerPortName": "", - "status": "REPORTED", - "tcpPort": 80, - "type": "EDGE", - "xmppId": "edge", - "xmppPasswd": "" - } - ], - "size": 1 - } - -.. [1] For more information see the `Wikipedia page on Lights-Out management `_\ . diff --git a/docs/source/api/v2/servers_hostname_update.rst b/docs/source/api/v2/servers_hostname_update.rst deleted file mode 100644 index 9980dc0613..0000000000 --- a/docs/source/api/v2/servers_hostname_update.rst +++ /dev/null @@ -1,87 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-servers-hostname-update: - -************************************* -``servers/{{HostName-Or-ID}}/update`` -************************************* - -``POST`` -======== -:term:`Queue` or dequeue updates and revalidation updates for a specific server. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: undefined - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------------------+---------------------------------------------------------------------------------------------------------+ - | Name | Description | - +==================+=========================================================================================================+ - | HostName-OR-ID | The hostName or integral, unique identifier of the server on which updates are being queued or dequeued | - +------------------+---------------------------------------------------------------------------------------------------------+ - -.. table:: Request Query Parameters - - +---------------+----------+--------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===============+==========+======================================================================================+ - | updated | no | The value to set for the queue update flag on this server. May be 'true' or 'false'. | - +---------------+----------+--------------------------------------------------------------------------------------+ - | reval_updated | no | The value to set for the queue update flag on this server. May be 'true' or 'false'. | - +---------------+----------+--------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/servers/my-edge/update?updated=true&reval_updated=false HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Mon, 10 Dec 2018 18:20:04 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: 9Mmo9hIFZyF5gAvfdJD//VH9eNgiHVLinXt88H0GlJSHhwND8gMxaFyC+f9XZfiNAoGd1MKi1934ZJGmaIR6qQ== - Content-Length: 49 - - { - "alerts" : - [ - { - "text" : "successfully set server 'my-edge' updated=true reval_updated=false", - "level" : "success" - } - ] - } diff --git a/docs/source/api/v2/servers_hostname_update_status.rst b/docs/source/api/v2/servers_hostname_update_status.rst deleted file mode 100644 index ea08b17e53..0000000000 --- a/docs/source/api/v2/servers_hostname_update_status.rst +++ /dev/null @@ -1,95 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-servers-hostname-update_status: - -************************************** -``servers/{{hostname}}/update_status`` -************************************** - -.. note:: This endpoint only truly has meaning for :term:`cache servers`, though it will return a valid response for any server configured in Traffic Ops. - -``GET`` -======= -Retrieves information regarding pending updates and :term:`Content Invalidation Jobs` for a given server - -:Auth. Required: Yes -:Roles Required: None -:Response Type: ``undefined`` - this endpoint will return a top-level array containing the response, as opposed to within a ``response`` object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +----------+----------------------------------------------------+ - | Name | Description | - +==========+====================================================+ - | hostname | The (short) hostname of the server being inspected | - +----------+----------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/servers/edge/update_status HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -Each object in the returned array\ [1]_ will contain the following fields: - -:host_id: The integral, unique identifier for the server for which the other fields in this object represent the pending updates and revalidation status -:host_name: The (short) hostname of the server for which the other fields in this object represent the pending updates and revalidation status -:parent_pending: A boolean telling whether or not the :term:`parents` of this server have pending updates -:parent_reval_pending: A boolean telling whether or not the :term:`parents` of this server have pending :term:`Content Invalidation Jobs` -:reval_pending: ``true`` if the server has pending :term:`Content Invalidation Jobs`, ``false`` otherwise -:status: The name of the status of this server - - .. seealso:: :ref:`health-proto` gives more information on how these statuses are used, and the ``GET`` method of the :ref:`to-api-statuses` endpoint can be used to retrieve information about all server statuses configured in Traffic Ops. - -:upd_pending: ``true`` if the server has pending updates, ``false`` otherwise -:use_reval_pending: A boolean which tells :term:`ORT` whether or not this version of Traffic Ops should use pending :term:`Content Invalidation Jobs` - - .. note:: This field was introduced to give :term:`ORT` the ability to work with Traffic Control versions 1.x and 2.x seamlessly - as of Traffic Control v3.0 there is no reason for this field to ever be ``false``. - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: R6BjNVrcecHGn3eGDqQ1yDiBnEDGQe7QtOMIsRwlpck9SZR8chRQznrkTF3YdROAZ1l8BxR3fXTIvKHIzK2/dA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 04 Feb 2019 16:24:01 GMT - Content-Length: 174 - - [{ - "host_name": "edge", - "upd_pending": false, - "reval_pending": false, - "use_reval_pending": true, - "host_id": 10, - "status": "REPORTED", - "parent_pending": false, - "parent_reval_pending": false - }] - -.. [1] Despite that the returned object is an array, exactly one server's information is requested and thus returned. That is to say, the array should always have a length of exactly one. diff --git a/docs/source/api/v2/servers_id.rst b/docs/source/api/v2/servers_id.rst deleted file mode 100644 index fa96b0d9c3..0000000000 --- a/docs/source/api/v2/servers_id.rst +++ /dev/null @@ -1,309 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-servers-id: - -****************** -``servers/{{ID}}`` -****************** - -``PUT`` -======= -Allow user to edit a server. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------+ - | Name | Description | - +======+=============================================+ - | ID | The integral, unique identifier of a server | - +------+---------------------------------------------+ - -: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 :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 :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. - -:interfaceName: The name of the primary network interface used by the server -:ip6Address: An optional IPv6 address and subnet mask of ``interfaceName`` -:ip6IsService: An optional boolean value which if ``true`` indicates that the IPv6 address will be used for routing content. Defaults to ``true``. -:ip6Gateway: An optional IPv6 address of the gateway used by ``interfaceName`` -:ipAddress: The IPv4 address of ``interfaceName`` -:ipIsService: An optional boolean value which if ``true`` indicates that the IPv4 address will be used for routing content. Defaults to ``true``. -:ipGateway: The IPv4 address of the gateway used by ``interfaceName`` -:ipNetmask: The IPv4 subnet mask used by ``interfaceName`` -:mgmtIpAddress: An optional IPv4 address of some network interface on the server used for 'management' -:mgmtIpGateway: An optional IPv4 address of a gateway used by some network interface on the server used for 'management' -:mgmtIpNetmask: An optional IPv4 subnet mask used by some network interface on the server used for 'management' -:physLocationId: An integral, unique identifier for the physical location where the server resides -:profileId: The :ref:`profile-id` the :term:`Profile` that shall be used by this server -:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation -:rack: An optional string indicating "server rack" location -:routerHostName: An optional string containing the human-readable name of the router responsible for reaching this server -:routerPortName: An optional string containing the human-readable name of the port used by the router responsible for reaching this server -:statusId: The integral, unique identifier of the status of this server - - .. seealso:: :ref:`health-proto` - -:tcpPort: An optional port number on which this server listens for incoming TCP connections - - .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections. - -:typeId: The integral, unique identifier of the 'type' of this server -:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Control Cache Config (T3C, formerly ORT) -:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards. -:xmppPasswd: An optional password used in XMPP communications with the server - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/servers/13 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 599 - Content-Type: application/json - - { - "cachegroupId": 6, - "cdnId": 2, - "domainName": "infra.ciab.test", - "hostName": "quest", - "httpsPort": 443, - "iloIpAddress": "", - "iloIpGateway": "", - "iloIpNetmask": "", - "iloPassword": "", - "iloUsername": "", - "interfaceMtu": 1500, - "interfaceName": "eth0", - "ip6Address": "::1", - "ip6Gateway": "::2", - "ipAddress": "0.0.0.1", - "ipGateway": "0.0.0.2", - "ipNetmask": "255.255.255.0", - "mgmtIpAddress": "", - "mgmtIpGateway": "", - "mgmtIpNetmask": "", - "offlineReason": "", - "physLocationId": 1, - "profileId": 10, - "routerHostName": "", - "routerPortName": "", - "statusId": 3, - "tcpPort": 80, - "typeId": 12, - "updPending": true, - "ipIsService": true, - "ip6IsService": true - } - -Response Structure ------------------- -: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 :abbr:`FQDN (Fully Qualified Domain Name)` -:guid: An identifier used to uniquely identify the server - - .. 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`` -:interfaceName: The name of the primary network interface used by the server -:ip6Address: The IPv6 address and subnet mask of ``interfaceName`` -:ip6IsService: A boolean value which if ``true`` indicates that the IPv6 address will be used for routing content. -:ip6Gateway: The IPv6 address of the gateway used by ``interfaceName`` -:ipAddress: The IPv4 address of ``interfaceName`` -:ipIsService: A boolean value which if ``true`` indicates that the IPv4 address will be used for routing content. -:ipGateway: The IPv4 address of the gateway used by ``interfaceName`` -:ipNetmask: The IPv4 subnet mask used by ``interfaceName`` -:lastUpdated: The date and time at which this server description was last modified -:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management' -: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 -: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 -:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation -:rack: A string indicating "server rack" location -:routerHostName: The human-readable name of the router responsible for reaching this server -:routerPortName: The human-readable name of the port used by the router responsible for reaching this server -:status: The status of the server - - .. seealso:: :ref:`health-proto` - -:statusId: The integral, unique identifier of the status of this server - - .. seealso:: :ref:`health-proto` - -:tcpPort: The port on which this server listens for incoming TCP connections - - .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections. - -:type: The name of the 'type' of this server -:typeId: The integral, unique identifier of the 'type' of this server -:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Control Cache Config (T3C, formerly ORT) -:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards. -:xmppPasswd: The password used in XMPP communications with the server - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 9lGAMCCC9I/bOpuBSyf3ACffjHeRuXCTuxrA/oU78uYzW5FeFTq5PHSSnsnqKG5E0vWg0Rko0CwguGeNc9IT0w== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 17:58:57 GMT - Content-Length: 848 - - { "alerts": [ - { - "text": "server was updated.", - "level": "success" - } - ], - "response": { - "cachegroup": null, - "cachegroupId": 6, - "cdnId": 2, - "cdnName": null, - "domainName": "infra.ciab.test", - "guid": null, - "hostName": "quest", - "httpsPort": 443, - "id": 13, - "iloIpAddress": "", - "iloIpGateway": "", - "iloIpNetmask": "", - "iloPassword": "", - "iloUsername": "", - "interfaceMtu": 1500, - "interfaceName": "eth0", - "ip6Address": "::1", - "ip6Gateway": "::2", - "ipAddress": "0.0.0.1", - "ipGateway": "0.0.0.2", - "ipNetmask": "255.255.255.0", - "lastUpdated": "2018-12-10 17:58:57+00", - "mgmtIpAddress": "", - "mgmtIpGateway": "", - "mgmtIpNetmask": "", - "offlineReason": "", - "physLocation": null, - "physLocationId": 1, - "profile": null, - "profileDesc": null, - "profileId": 10, - "rack": null, - "revalPending": null, - "routerHostName": "", - "routerPortName": "", - "status": null, - "statusId": 3, - "tcpPort": 80, - "type": "", - "typeId": 12, - "updPending": true, - "xmppId": null, - "xmppPasswd": null, - "ipIsService": true, - "ip6IsService": true - }} - -``DELETE`` -========== -Allow user to delete server through api. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------+ - | Name | Description | - +======+=============================================+ - | ID | The integral, unique identifier of a server | - +------+---------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/servers/13 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: JZdjKJYWN9w9NF6VE/rVkGUqecycKB2ABkkI4LNDmgpJLwu53bRHAA+4uWrow0zuba/4MSEhHKshutziypSxPg== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 18:23:21 GMT - Content-Length: 61 - - { "alerts": [ - { - "text": "server was deleted.", - "level": "success" - } - ]} - -.. [1] For more information see the `Wikipedia page on Lights-Out management `_\ . diff --git a/docs/source/api/v2/servers_id_deliveryservices.rst b/docs/source/api/v2/servers_id_deliveryservices.rst deleted file mode 100644 index 6e8a5b3bd5..0000000000 --- a/docs/source/api/v2/servers_id_deliveryservices.rst +++ /dev/null @@ -1,324 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-servers-id-deliveryservices: - -*********************************** -``servers/{{ID}}/deliveryservices`` -*********************************** - -``GET`` -======= -Retrieves all :term:`Delivery Services` assigned to a specific server. - -:Auth. Required: Yes -:Roles Required: None\ [#tenancy]_ -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+------------------------------------------------------------------------------------------------------------+ - | Name | Description | - +======+============================================================================================================+ - | ID | The integral, unique identifier of the server for which assigned :term:`Delivery Services` shall be listed | - +------+------------------------------------------------------------------------------------------------------------+ - -.. table:: Request Query Parameters - - +-----------+----------+---------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+===============================================================================================================+ - | 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 - - GET /api/2.0/servers/9/deliveryservices HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:active: A boolean that defines :ref:`ds-active`. -:anonymousBlockingEnabled: A boolean that defines :ref:`ds-anonymous-blocking` -:cacheurl: A :ref:`ds-cacheurl` - - .. deprecated:: ATCv3.0 - This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later - -:ccrDnsTtl: The :ref:`ds-dns-ttl` - named "ccrDnsTtl" for legacy reasons -:cdnId: The integral, unique identifier of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs -:cdnName: Name of the :ref:`ds-cdn` to which the :term:`Delivery Service` belongs -:checkPath: A :ref:`ds-check-path` -:consistentHashRegex: A :ref:`ds-consistent-hashing-regex` -:consistentHashQueryParams: An array of :ref:`ds-consistent-hashing-qparams` -:deepCachingType: The :ref:`ds-deep-caching` setting for this :term:`Delivery Service` -:displayName: The :ref:`ds-display-name` -:dnsBypassCname: A :ref:`ds-dns-bypass-cname` -:dnsBypassIp: A :ref:`ds-dns-bypass-ip` -:dnsBypassIp6: A :ref:`ds-dns-bypass-ipv6` -:dnsBypassTtl: The :ref:`ds-dns-bypass-ttl` -:dscp: A :ref:`ds-dscp` to be used within the :term:`Delivery Service` -:ecsEnabled: A boolean that defines the :ref:`ds-ecs` setting on this :term:`Delivery Service` -:edgeHeaderRewrite: A set of :ref:`ds-edge-header-rw-rules` -:exampleURLs: An array of :ref:`ds-example-urls` -:fqPacingRate: The :ref:`ds-fqpr` -:geoLimit: An integer that defines the :ref:`ds-geo-limit` -:geoLimitCountries: A string containing a comma-separated list defining the :ref:`ds-geo-limit-countries` -:geoLimitRedirectUrl: A :ref:`ds-geo-limit-redirect-url` -:geoProvider: The :ref:`ds-geo-provider` -:globalMaxMbps: The :ref:`ds-global-max-mbps` -:globalMaxTps: The :ref:`ds-global-max-tps` -:httpBypassFqdn: A :ref:`ds-http-bypass-fqdn` -:id: An integral, unique identifier for this :term:`Delivery Service` -:infoUrl: An :ref:`ds-info-url` -:initialDispersion: The :ref:`ds-initial-dispersion` -:ipv6RoutingEnabled: A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service` -:lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in :ref:`non-rfc-datetime` -:logsEnabled: A boolean that defines the :ref:`ds-logs-enabled` setting on this :term:`Delivery Service` -:longDesc: The :ref:`ds-longdesc` of this :term:`Delivery Service` -:longDesc1: The 2nd long description of this :term:`Delivery Service` -:longDesc2: the 3rd long description of this :term:`Delivery Service` -:matchList: The :term:`Delivery Service`'s :ref:`ds-matchlist` - - :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped) - :setNumber: An integer that provides explicit ordering of :ref:`ds-matchlist` items - this is used as a priority ranking by Traffic Router, and is not guaranteed to correspond to the ordering of items in the array. - :type: The type of match performed using ``pattern``. - -:maxDnsAnswers: The :ref:`ds-max-dns-answers` allowed for this :term:`Delivery Service` -:maxOriginConnections: The :ref:`ds-max-origin-connections` -:midHeaderRewrite: A set of :ref:`ds-mid-header-rw-rules` -:missLat: The :ref:`ds-geo-miss-default-latitude` used by this :term:`Delivery Service` -:missLong: The :ref:`ds-geo-miss-default-longitude` used by this :term:`Delivery Service` -:multiSiteOrigin: A boolean that defines the use of :ref:`ds-multi-site-origin` by this :term:`Delivery Service` -:orgServerFqdn: The :ref:`ds-origin-url` -:originShield: A :ref:`ds-origin-shield` string -:profileDescription: The :ref:`profile-description` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated -:profileId: The :ref:`profile-id` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated -:profileName: The :ref:`profile-name` of the :ref:`ds-profile` with which this :term:`Delivery Service` is associated -:protocol: An integral, unique identifier that corresponds to the :ref:`ds-protocol` used by this :term:`Delivery Service` -:qstringIgnore: An integral, unique identifier that corresponds to the :ref:`ds-qstring-handling` setting on this :term:`Delivery Service` -:rangeRequestHandling: An integral, unique identifier that corresponds to the :ref:`ds-range-request-handling` setting on this :term:`Delivery Service` -:regexRemap: A :ref:`ds-regex-remap` -:regionalGeoBlocking: A boolean defining the :ref:`ds-regionalgeo` setting on this :term:`Delivery Service` -:remapText: :ref:`ds-raw-remap` -:signed: ``true`` if and only if ``signingAlgorithm`` is not ``null``, ``false`` otherwise -:signingAlgorithm: Either a :ref:`ds-signing-algorithm` or ``null`` to indicate URL/URI signing is not implemented on this :term:`Delivery Service` -:rangeSliceBlockSize: An integer that defines the byte block size for the ATS Slice Plugin. It can only and must be set if ``rangeRequestHandling`` is set to 3. -:sslKeyVersion: This integer indicates the :ref:`ds-ssl-key-version` -:tenantId: The integral, unique identifier of the :ref:`ds-tenant` who owns this :term:`Delivery Service` -:trRequestHeaders: If defined, this defines the :ref:`ds-tr-req-headers` used by Traffic Router for this :term:`Delivery Service` -:trResponseHeaders: If defined, this defines the :ref:`ds-tr-resp-headers` used by Traffic Router for this :term:`Delivery Service` -:type: The :ref:`ds-types` of this :term:`Delivery Service` -:typeId: The integral, unique identifier of the :ref:`ds-types` of this :term:`Delivery Service` -:xmlId: This :term:`Delivery Service`'s :ref:`ds-xmlid` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: CFmtW41aoDezCYxtAXnS54dfFOD6jdxDJ2/LMpbBqnndy5kac7JQhdFAWF109sl95XVSUV85JHFzXZTw/mJabQ== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Jun 2019 17:01:30 GMT - Content-Length: 1500 - - { "response": [ { - "active": true, - "anonymousBlockingEnabled": false, - "cacheurl": null, - "ccrDnsTtl": null, - "cdnId": 2, - "cdnName": "CDN-in-a-Box", - "checkPath": null, - "displayName": "Demo 1", - "dnsBypassCname": null, - "dnsBypassIp": null, - "dnsBypassIp6": null, - "dnsBypassTtl": null, - "dscp": 0, - "edgeHeaderRewrite": null, - "geoLimit": 0, - "geoLimitCountries": null, - "geoLimitRedirectURL": null, - "geoProvider": 0, - "globalMaxMbps": null, - "globalMaxTps": null, - "httpBypassFqdn": null, - "id": 1, - "infoUrl": null, - "initialDispersion": 1, - "ipv6RoutingEnabled": true, - "lastUpdated": "2019-06-10 15:14:29+00", - "logsEnabled": true, - "longDesc": "Apachecon North America 2018", - "longDesc1": null, - "longDesc2": null, - "matchList": [ - { - "type": "HOST_REGEXP", - "setNumber": 0, - "pattern": ".*\\.demo1\\..*" - } - ], - "maxDnsAnswers": null, - "midHeaderRewrite": null, - "missLat": 42, - "missLong": -88, - "multiSiteOrigin": false, - "originShield": null, - "orgServerFqdn": "http://origin.infra.ciab.test", - "profileDescription": null, - "profileId": null, - "profileName": null, - "protocol": 2, - "qstringIgnore": 0, - "rangeRequestHandling": 0, - "regexRemap": null, - "regionalGeoBlocking": false, - "remapText": null, - "routingName": "video", - "signed": false, - "sslKeyVersion": 1, - "tenantId": 1, - "type": "HTTP", - "typeId": 1, - "xmlId": "demo1", - "exampleURLs": [ - "http://video.demo1.mycdn.ciab.test", - "https://video.demo1.mycdn.ciab.test" - ], - "deepCachingType": "NEVER", - "fqPacingRate": null, - "signingAlgorithm": null, - "tenant": "root", - "trResponseHeaders": null, - "trRequestHeaders": null, - "consistentHashRegex": null, - "consistentHashQueryParams": [ - "abc", - "pdq", - "xxx", - "zyx" - ], - "maxOriginConnections": 0, - "ecsEnabled": false, - "rangeSliceBlockSize": null - }]} - - -.. [#tenancy] Only the :term:`Delivery Services` visible to the requesting user's :term:`Tenant` will appear, regardless of their :term:`Role` or the :term:`Delivery Services`' actual 'server assignment' status. - -``POST`` -======== -Assign an arbitrary number of :term:`Delivery Services` to a single server. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+----------+---------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +------+----------+---------------------------------------------------------------------------------------------+ - | ID | Yes | The integral, unique identifier of the server that you want to assign delivery services to. | - +------+----------+---------------------------------------------------------------------------------------------+ - -.. table:: Request Query Parameters - - +---------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +---------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | replace | Yes | Whether the list of :term:`Delivery Services` you provide should replace the existing list or be merged with the existing list. Must be a 1, or true, or 0, or false. | - +---------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -The request body is an array of IDs of :term:`Delivery Services` that you want to assign to the server. The array can be empty, but it must be provided. - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/servers/6/deliveryservices?replace=1 HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - Content-Length: 3 - - [ - 1 - ] - -Response Structure ------------------- -:dsIds: An array of integral, unique identifiers for :term:`Delivery Services` which the request added to server. If ``:replace:`` is ``false``, :term:`Delivery Services` that are already assigned will remain, though they are not listed by ``:dsIds:``. -:replace: The ``:replace:`` value you provided in the body of the request, or ``null`` if none was provided. -:serverId: The server's integral, unique identifier - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 25 Feb 2020 09:08:32 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: iV+JzAZSsmlxRZsNtIRg3oA9470hAwrMpq5xhcYVi0Y831Trx2YRlsyhYpOPqHg5+QPoXHGF0nx8uso0fuNarw== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 25 Feb 2020 08:08:32 GMT - Content-Length: 129 - - { - "alerts": [ - { - "text": "successfully assigned dses to server", - "level": "success" - } - ], - "response": { - "serverId": 6, - "dsIds": [ - 1 - ], - "replace": true - } - } diff --git a/docs/source/api/v2/servers_id_queue_update.rst b/docs/source/api/v2/servers_id_queue_update.rst deleted file mode 100644 index 8788a674f9..0000000000 --- a/docs/source/api/v2/servers_id_queue_update.rst +++ /dev/null @@ -1,96 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-servers-id-queue_update: - -******************************* -``servers/{{ID}}/queue_update`` -******************************* -.. caution:: In the vast majority of cases, it is advisable that the ``PUT`` method of the :ref:`to-api-servers-id` endpoint be used instead. - -``POST`` -======== -:term:`Queue` or dequeue updates for a specific server. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------------------------------------------------------+ - | Name | Description | - +======+=============================================================================================+ - | ID | The integral, unique identifier of the server on which updates are being queued or dequeued | - +------+---------------------------------------------------------------------------------------------+ - -:action: A string describing what action to take regarding server updates; one of: - - queue - :term:`Queue Updates` for the server, propagating configuration changes to the actual server - dequeue - Cancels any pending updates on the server - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/servers/13/queue_update HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 22 - Content-Type: application/json - - { - "action": "dequeue" - } - -Response Structure ------------------- -:action: The action processed, one of: - - queue - :term:`Queue Updates` was performed on the server, propagating configuration changes to the actual server - dequeue - Canceled any pending updates on the server - -:serverId: The integral, unique identifier of the server on which ``action`` was taken - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Mon, 10 Dec 2018 18:20:04 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: 9Mmo9hIFZyF5gAvfdJD//VH9eNgiHVLinXt88H0GlJSHhwND8gMxaFyC+f9XZfiNAoGd1MKi1934ZJGmaIR6qQ== - Content-Length: 49 - - { - "response": { - "serverId": "13", - "action": "dequeue" - } - } diff --git a/docs/source/api/v2/servers_id_status.rst b/docs/source/api/v2/servers_id_status.rst deleted file mode 100644 index f5c625dd5d..0000000000 --- a/docs/source/api/v2/servers_id_status.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-servers-id-status: - -************************* -``servers/{{ID}}/status`` -************************* - -``PUT`` -======= -Updates server status and queues updates on all child caches if server type is EDGE or MID. Also, captures offline reason if status is set to ADMIN_DOWN or OFFLINE and prepends offline reason with the user that initiated the status change. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-----------------------------------------------------------------------------+ - | Name | Description | - +======+=============================================================================+ - | ID | The integral, unique identifier of the server whose status is being changed | - +------+-----------------------------------------------------------------------------+ - -:offlineReason: A string containing the reason for the status change -:status: The name or integral, unique identifier of the server's new status - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/servers/13/status HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 56 - Content-Type: application/json - - { - "status": "ADMIN_DOWN", - "offlineReason": "Bad drives" - } - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Mon, 10 Dec 2018 18:08:44 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: LS1jCo5eMVKxmeYDol0I2LgLYazocSggR5hynNoLcPmMov9u2s3ulksPdQtG1N3aS+VM9tdMsCrahFPraLJVwg== - Content-Length: 158 - - { "alerts": [ - { - "level": "success", - "text": "Updated status [ ADMIN_DOWN ] for quest.infra.ciab.test [ admin: Bad drives ] and queued updates on all child caches" - } - ]} diff --git a/docs/source/api/v2/snapshot.rst b/docs/source/api/v2/snapshot.rst deleted file mode 100644 index c634671817..0000000000 --- a/docs/source/api/v2/snapshot.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-snapshot: - -************ -``snapshot`` -************ - -``PUT`` -======= -Performs a CDN :term:`Snapshot`. Effectively, this propagates the new *configuration* of the CDN to its *operating state*, which replaces the output of the :ref:`to-api-cdns-name-snapshot` endpoint with the output of the :ref:`to-api-cdns-name-snapshot-new` endpoint. -This also changes the output of the :ref:`to-api-v2-cdns-name-configs-monitoring` endpoint since that endpoint returns the latest monitoring information from the *operating state*. - -.. Note:: By default, snapshotting the CDN also deletes all HTTPS certificates for every :term:`Delivery Service` which has been deleted since the last :term:`Snapshot`. In order to disable this behavior, set ``disable_auto_cert_deletion`` in :ref:`cdn.conf` to ``true``. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-------+-----------------------------------------------------------------+ - | Name | Description | - +=======+=================================================================+ - | cdn | The name of the CDN for which a :term:`Snapshot` shall be taken | - +-------+-----------------------------------------------------------------+ - | cdnID | The id of the CDN for which a :term:`Snapshot` shall be taken | - +-------+-----------------------------------------------------------------+ - -.. Note:: At least one query parameter must be given. - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/snapshot?cdn=CDN-in-a-Box HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-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: gmaWI0tKgNFPYO0zMrLCGDosBJkPbeIvW4BH9tEh96VjBqyWqzjgPySoMa3ViM1BQXA6VAUOGmc76VyhBsaTzA== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 18 Mar 2020 15:51:48 GMT - Content-Length: 47 - - { - "response": "SUCCESS" - } diff --git a/docs/source/api/v2/staticdnsentries.rst b/docs/source/api/v2/staticdnsentries.rst deleted file mode 100644 index 6dc7c0640f..0000000000 --- a/docs/source/api/v2/staticdnsentries.rst +++ /dev/null @@ -1,370 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-staticdnsentries: - -******************** -``staticdnsentries`` -******************** - -``GET`` -======= -Retrieve all static DNS entries configured within Traffic Control - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===================+==========+============================================================================================================================================+ - | 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 the :term:`Cache Group` that has this :ref:`cache-group-name` | - +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+ - | 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 :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 | - +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+ - | host | no | Return only static DNS entries that resolve this :abbr:`FQDN (Fully Qualified Domain Name)` | - +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+ - | id | no | Return only the static DNS entry with this integral, unique identifier | - +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+ - | ttl | no | Return only static DNS entries with this :abbr:`TTL (Time To Live)` | - +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+ - | type | no | Return only static DNS entries of this type | - +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+ - | typeId | no | Return only static DNS entries of the type identified by this integral, unique identifier | - +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/staticdnsentries?address=foo.bar HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:address: If ``typeId`` identifies a ``CNAME`` type record, this is the Canonical Name (CNAME) of the server with a trailing period, 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, 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`` -:id: An integral, unique identifier for this static DNS entry -: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 :term:`Type` of this static DNS entry - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: Px1zTH3ihg+hfmdADGcap0Juuud39fGsx5Y3CzqaFNmRwFu1ZLMzOsy0EN2pb7vpOtpI6/zeIUYAC3dbsBwOmA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 20:04:33 GMT - Content-Length: 226 - - { "response": [ - { - "address": "foo.bar.", - "cachegroup": null, - "cachegroupId": null, - "deliveryservice": "demo1", - "deliveryserviceId": 1, - "host": "test", - "id": 2, - "lastUpdated": "2018-12-10 19:59:56+00", - "ttl": 300, - "type": "CNAME_RECORD", - "typeId": 41 - } - ]} - -``POST`` -======== -Creates a new, static DNS entry. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -:address: If ``typeId`` identifies a ``CNAME`` type record, this is the Canonical Name (CNAME) of the server with a trailing period, 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 :abbr:`FQDN (Fully Qualified Domain Name)` which shall resolve to ``address`` -: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 - - POST /api/2.0/staticdnsentries HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 92 - Content-Type: application/json - - { - "address": "test.quest.", - "deliveryserviceId": 1, - "host": "test", - "ttl": 300, - "typeId": 41 - } - -Response Structure ------------------- -:address: If ``typeId`` identifies a ``CNAME`` type record, this is the Canonical Name (CNAME) of the server with a trailing period, 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, 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`` -:id: An integral, unique identifier for 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 - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 8dcJyjw2NJZx0L9Oz16P7g/7j5A1jlpyiY6Y+rRVQ2wGcwYI3yiGPrz6ur0qKzgqEBBsh8aPF44WTHAR9jUJdg== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 19:54:19 GMT - Content-Length: 282 - - { "alerts": [ - { - "text": "staticDNSEntry was created.", - "level": "success" - } - ], - "response": { - "address": "test.quest.", - "cachegroup": null, - "cachegroupId": null, - "deliveryservice": null, - "deliveryserviceId": 1, - "host": "test", - "id": 2, - "lastUpdated": "2018-12-10 19:54:19+00", - "ttl": 300, - "type": "CNAME_RECORD", - "typeId": 41 - }} - -``PUT`` -======= -Updates a static DNS entry. - -:Auth. Required: Yes -:Role(s) Required: "admin" or "operator" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------+-------------------------------------------------------------------+ - | Name | Description | - +======+===================================================================+ - | id | The integral, unique identifier of the static DNS entry to modify | - +------+-------------------------------------------------------------------+ - -:address: If ``typeId`` identifies a ``CNAME`` type record, this is the Canonical Name (CNAME) of the server with a trailing period, 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 :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 - - PUT /api/2.0/staticdnsentries?id=2 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 89 - Content-Type: application/json - - { - "address": "foo.bar.", - "deliveryserviceId": 1, - "host": "test", - "ttl": 300, - "typeId": 41 - } - -Response Structure ------------------- -:address: If ``typeId`` identifies a ``CNAME`` type record, this is the Canonical Name (CNAME) of the server with a trailing period, 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, 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 :abbr:`FQDN (Fully Qualified Domain Name)` which shall resolve to ``address`` -:id: An integral, unique identifier for 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 - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: +FaYmpnlIIzVSBq0nosw29NZcV9xFhlVgWuUqXUyiDihVUSzX4jrdAloRDgzDvKsYQB8LSkPdGHwt1zjgSzUtA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 19:59:56 GMT - Content-Length: 279 - - { "alerts": [ - { - "text": "staticDNSEntry was updated.", - "level": "success" - } - ], - "response": { - "address": "foo.bar.", - "cachegroup": null, - "cachegroupId": null, - "deliveryservice": null, - "deliveryserviceId": 1, - "host": "test", - "id": 2, - "lastUpdated": "2018-12-10 19:59:56+00", - "ttl": 300, - "type": null, - "typeId": 41 - }} - - -``DELETE`` -========== -Delete staticdnsentries. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------+-------------------------------------------------------------------+ - | Name | Description | - +======+===================================================================+ - | id | The integral, unique identifier of the static DNS entry to delete | - +------+-------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/staticdnsentries?id=2 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: g6uqHPU44LuTtqU2ahtazrVCpcpNWVc9kWJQOYRuiVLDnsm39KOB/xt3XM6j0/X3WYiIawnNspkxRC85LJHwFA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 20:05:52 GMT - Content-Length: 69 - - { "alerts": [ - { - "text": "staticDNSEntry was deleted.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/stats_summary.rst b/docs/source/api/v2/stats_summary.rst deleted file mode 100644 index b763165360..0000000000 --- a/docs/source/api/v2/stats_summary.rst +++ /dev/null @@ -1,249 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-stats-summary: - -***************** -``stats_summary`` -***************** - -``GET`` -======= -Either retrieve a list of summary stats or the timestamp of the latest recorded stats summary. - -What is returned is driven by the query parameter ``lastSummaryDate``. - -If the parameter is set it will return an object with the latest timestamp, else an array of summary stats will be returned. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array or Object - -Request Structure ------------------ - -Summary Stats -""""""""""""" - -.. table:: Request Query Parameters - - +---------------------+----------+-------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +=====================+==========+=======================================================================================================+ - | deliveryServiceName | no | Return only summary stats that were reported for :term:`Delivery Service` with the given display name | - +---------------------+----------+-------------------------------------------------------------------------------------------------------+ - | cdnName | no | Return only summary stats that were reported for CDN with the given name | - +---------------------+----------+-------------------------------------------------------------------------------------------------------+ - | statName | no | Return only summary stats that were reported for given stat name | - +---------------------+----------+-------------------------------------------------------------------------------------------------------+ - | orderby | no | Choose the ordering of the results - can only be one of deliveryServiceName, statName or cdnName | - +---------------------+----------+-------------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/stats_summary HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Last Updated Summary Stat -"""""""""""""""""""""""""" - -.. table:: Request Query Parameters - - +-----------------+----------+---------------------------------------------------+ - | Name | Required | Description | - +=================+==========+===================================================+ - | statName | no | Get lastest updated date for the given stat | - +-----------------+----------+---------------------------------------------------+ - | lastSummaryDate | yes | Tells route to get only lastest updated timestamp | - +-----------------+----------+---------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/stats_summary?lastSummaryDate=true HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- - -Summary Stats -""""""""""""" - -:cdnName: The CDN name for which the summary stat was taken for - - .. note:: If the ``cdn`` is equal to ``all`` it represents summary_stats across all delivery services across all CDNs - -:deliveryServiceName: The :term:`Delivery Service` display name for which the summary stat was taken for - - .. note:: If the ``deliveryServiceName`` is equal to ``all`` it represents summary_stats across all delivery services within the given CDN - -:statName: Stat name summary stat represents -:statValue: Summary stat value -:summaryTime: Timestamp of summary, in :ref:`non-rfc-datetime` -:statDate: Date stat was taken, in ``YYYY-MM-DD`` format - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: dHNip9kpTGGS1w39/fWcFehNktgmXZus8XaufnmDpv0PyG/3fK/KfoCO3ZOj9V74/CCffps7doEygWeL/xRtKA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 20:56:59 GMT - Content-Length: 150 - - { "response": [ - { - "cdnName": "CDN-in-a-Box", - "deliveryServiceName": "all", - "statName": "daily_maxgbps", - "statValue": 5, - "summaryTime": "2019-11-19 00:04:06+00", - "statDate": "2019-11-19" - }, - { - "cdnName": "CDN-in-a-Box", - "deliveryServiceName": "all", - "statName": "daily_maxgbps", - "statValue": 3, - "summaryTime": "2019-11-18 00:04:06+00", - "statDate": "2019-11-18" - }, - { - "cdnName": "CDN-in-a-Box", - "deliveryServiceName": "all", - "statName": "daily_bytesserved", - "statValue": 1000, - "summaryTime": "2019-11-19 00:04:06+00", - "statDate": "2019-11-19" - } - ]} - -Last Updated Summary Stat -""""""""""""""""""""""""" - -:summaryTime: Timestamp of the last updated summary, in :ref:`non-rfc-datetime` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: dHNip9kpTGGS1w39/fWcFehNktgmXZus8XaufnmDpv0PyG/3fK/KfoCO3ZOj9V74/CCffps7doEygWeL/xRtKA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 20:56:59 GMT - Content-Length: 150 - - { "response": { - "summaryTime": "2019-11-19 00:04:06+00" - }} - -``POST`` -======== - -Post a stats summary for a given stat. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -:cdnName: The CDN name for which the summary stat was taken for - - .. note:: If the ``cdn`` is equal to ``all`` it represents summary_stats across all delivery services across all CDNs - -:deliveryServiceName: The :term:`Delivery Service` display name for which the summary stat was taken for - - .. note:: If the ``deliveryServiceName`` is equal to ``all`` it represents summary_stats across all delivery services within the given CDN - -:statName: Stat name summary stat represents -:statValue: Summary stat value -:summaryTime: Timestamp of summary, in :ref:`non-rfc-datetime` -:statDate: Date stat was taken, in ``YYYY-MM-DD`` format - -.. note:: ``statName``, ``statValue`` and ``summaryTime`` are required. If ``cdnName`` and ``deliveryServiceName`` are not given they will default to ``all``. - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/stats_summary HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 113 - Content-Type: application/json - - { - "cdnName": "CDN-in-a-Box", - "deliveryServiceName": "all", - "statName": "daily_maxgbps", - "statValue": 10, - "summaryTime": "2019-12-05 00:03:57+00", - "statDate": "2019-12-05" - } - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: ezxk+iP7o7KE7zpWmGc0j8nz5k+1wAzY0HiNiA2xswTQrt+N+6CgQqUV2r9G1HAsPNr0HF2PhYs/Xr7DrYOw0A== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 06 Dec 2018 02:14:45 GMT - Content-Length: 97 - - { "alerts": [ - { - "text": "Stats Summary was successfully created", - "level": "success" - }] - } diff --git a/docs/source/api/v2/statuses.rst b/docs/source/api/v2/statuses.rst deleted file mode 100644 index d880bcd11a..0000000000 --- a/docs/source/api/v2/statuses.rst +++ /dev/null @@ -1,96 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-statuses: - -************ -``statuses`` -************ - -``GET`` -======= -Retrieves a list of all server :term:`Statuses`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-------------+----------+------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +=============+==========+======================================================================================================+ - | description | no | Return only :term:`Statuses` with this *exact* description | - +-------------+----------+------------------------------------------------------------------------------------------------------+ - | id | no | Return only the :term:`Status` with this integral, unique identifier | - +-------------+----------+------------------------------------------------------------------------------------------------------+ - | name | no | Return only :term:`Statuses` with this name | - +-------------+----------+------------------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/statuses?name=REPORTED HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -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 :ref:`non-rfc-datetime` -:name: The name of the status - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: dHNip9kpTGGS1w39/fWcFehNktgmXZus8XaufnmDpv0PyG/3fK/KfoCO3ZOj9V74/CCffps7doEygWeL/xRtKA== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 20:56:59 GMT - Content-Length: 150 - - { "response": [ - { - "description": "Server is online and reported in the health protocol.", - "id": 3, - "lastUpdated": "2018-12-10 19:11:17+00", - "name": "REPORTED" - } - ]} diff --git a/docs/source/api/v2/steering.rst b/docs/source/api/v2/steering.rst deleted file mode 100644 index 5071a55b65..0000000000 --- a/docs/source/api/v2/steering.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-steering: - -************ -``steering`` -************ - -``GET`` -======= -Gets a list of all :ref:`Steering Targets ` in the Traffic Ops database. - -:Auth. Required: Yes -:Roles Required: "Portal", "Steering", "Federation", "operations" or "admin" -:Response Type: Array - -Request Structure ------------------ -No parameters available. - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/steering HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - -Response Structure ------------------- -:deliveryService: A string that is the :ref:`ds-xmlid` of the steering :term:`Delivery Service` -:clientSteering: Whether this is a :ref:`client steering ` Delivery Service. -:targets: The delivery services that the :ref`Steering Delivery Service ` targets. - - :order: If this is a :ref:`STEERING_ORDER ` target, this is the value of the order. Otherwise, ``0``. - :weight: If this is a :ref:`STEERING_WEIGHT ` target, this is the value of the weight. Otherwise, ``0``. - :deliveryService: A string that is the :ref:`ds-xmlid` of the steering :term:`Delivery Service` - -:filters: Filters of type :ref:`STEERING_REGEXP ` that exist on either of the targets. - - :deliveryService: A string that is the :ref:`ds-xmlid` of the steering :term:`Delivery Service` - :pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped) - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 18:56:57 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: hcJa4xVLDx7bxBmoSjYo5YUwdSBWQr9GlqRYrc6ZU7LeenjiV3go22YlIHt/GtjLcHQjJ5DulKRhdsvFMq7Fng== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 24 Feb 2020 17:56:57 GMT - Content-Length: 167 - - { - "response": [ - { - "deliveryService": "steering1", - "clientSteering": true, - "targets": [ - { - "order": 0, - "weight": 1, - "deliveryService": "demo1" - }, - { - "order": 0, - "weight": 2, - "deliveryService": "demo2" - } - ], - "filters": [ - { - "deliveryService": "demo1", - "pattern": ".*\\.demo1\\..*" - }, - { - "deliveryService": "demo2", - "pattern": ".*\\.demo2*\\..*" - } - ] - } - ] - } diff --git a/docs/source/api/v2/steering_id_targets.rst b/docs/source/api/v2/steering_id_targets.rst deleted file mode 100644 index 1d67d2a434..0000000000 --- a/docs/source/api/v2/steering_id_targets.rst +++ /dev/null @@ -1,184 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-steering-id-targets: - -*************************** -``steering/{{ID}}/targets`` -*************************** - -``GET`` -======= -Get all targets for a steering :term:`Delivery Service`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+----------------------------------------------------------------------------------------------------------+ - | Name | Description | - +======+==========================================================================================================+ - | ID | The integral, unique identifier of a steering :term:`Delivery Service` for which targets shall be listed | - +------+----------------------------------------------------------------------------------------------------------+ - -.. table:: Request Query Parameters - - +-----------+-------------------------------------------------------------------------------------------------------------------------+ - | Name | Description | - +===========+=========================================================================================================================+ - | target | Return only the target mappings that target the :term:`Delivery Service` identified by this integral, unique identifier | - +-----------+-------------------------------------------------------------------------------------------------------------------------+ - | orderby | Choose the ordering of the results - must be the name of one of the fields of the objects in the ``response`` array | - +-----------+-------------------------------------------------------------------------------------------------------------------------+ - | sortOrder | Changes the order of sorting. Either ascending (default or "asc") or descending ("desc") | - +-----------+-------------------------------------------------------------------------------------------------------------------------+ - | limit | Choose the maximum number of results to return | - +-----------+-------------------------------------------------------------------------------------------------------------------------+ - | offset | The number of results to skip before beginning to return results. Must use in conjunction with limit | - +-----------+-------------------------------------------------------------------------------------------------------------------------+ - | page | 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 Structure - - GET /api/2.0/steering/2/targets?target=1 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -: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: 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 - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: utlJK4oYS2l6Ff7NzAqRuQeMEtazYn3rM3Nlux2XgTLxvSyslHy0mJrwDExSU05gVMdrgYCLZrZEvPHlENT1nA== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 11 Dec 2018 14:09:23 GMT - Content-Length: 130 - - { "response": [ - { - "deliveryService": "test", - "deliveryServiceId": 2, - "target": "demo1", - "targetId": 1, - "type": "HTTP", - "typeId": 1, - "value": 100 - } - ]} - -``POST`` -======== -Create a steering target. - -:Auth. Required: Yes -:Roles Required: Portal, Steering, Federation, "operations" or "admin" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------------------------------------------------------------------+ - | Name | Description | - +======+=========================================================================================================+ - | ID | The integral, unique identifier of a steering :term:`Delivery Service` to which a target shall be added | - +------+---------------------------------------------------------------------------------------------------------+ - -:targetId: The integral, unique identifier of a :term:`Delivery Service` which shall be a new steering target for the :term:`Delivery Service` identified by the ``ID`` path parameter -:typeId: The integral, unique identifier of the routing type of the new target :term:`Delivery Service` -:value: The 'weight' which shall be attributed to the new target :term:`Delivery Service` - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/steering/2/targets HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 43 - Content-Type: application/json - - { - "targetId": 1, - "value": 100, - "typeId": 1 - } - -Response Structure ------------------- -: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: 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 - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: +dTvfzrnOhdwAOMmY28r0+gFV5z+3aABI2FfAMziTYcU+pZrDanrJzMXpKWIL5Q/oCUBZpJDRt9hRCFkT4oGYw== - X-Server-Name: traffic_ops_golang/ - Date: Mon, 10 Dec 2018 21:22:17 GMT - Content-Length: 196 - - { "alerts": [ - { - "text": "steeringtarget was created.", - "level": "success" - } - ], - "response": { - "deliveryService": "test", - "deliveryServiceId": 2, - "target": "demo1", - "targetId": 1, - "type": "HTTP", - "typeId": 1, - "value": 100 - }} diff --git a/docs/source/api/v2/steering_id_targets_targetID.rst b/docs/source/api/v2/steering_id_targets_targetID.rst deleted file mode 100644 index 86c6d31f8a..0000000000 --- a/docs/source/api/v2/steering_id_targets_targetID.rst +++ /dev/null @@ -1,153 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-steering-id-targets-targetID: - -**************************************** -``steering/{{ID}}/targets/{{targetID}}`` -**************************************** - -``PUT`` -======= -Updates a steering target. - -:Auth. Required: Yes -:Roles Required: Portal, Steering, Federation, "operations" or "admin" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +----------+--------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Description | - +==========+======================================================================================================================================+ - | ID | The integral, unique identifier of a steering :term:`Delivery Service` | - +----------+--------------------------------------------------------------------------------------------------------------------------------------+ - | 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 :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 - :caption: Request Example - - PUT /api/2.0/steering/2/targets/1 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 26 - Content-Type: application/json - - { - "value": 1, - "typeId": 1 - } - -Response Structure ------------------- -: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: 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 - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: AfXsIRzdtU3HZYkr93qBMVTZRJ5oTF2u5sKYnd+DSqxZ+RQxY6vXtCupnnXCf9dxMt5QXRW1EFOW/FBG6lFrTg== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 11 Dec 2018 14:34:22 GMT - Content-Length: 194 - - { "alerts": [ - { - "text": "steeringtarget was updated.", - "level": "success" - } - ], - "response": { - "deliveryService": "test", - "deliveryServiceId": 2, - "target": "demo1", - "targetId": 1, - "type": "HTTP", - "typeId": 1, - "value": 1 - }} - -``DELETE`` -========== -Removes a specific target mapping from a specific :term:`Delivery Service` - -:Auth. Required: Yes -:Roles Required: Portal, Steering, Federation, "operations" or "admin" -:Response Type: ``undefined`` - -Request Structure ------------------ -.. table:: Request Path Parameters - - +----------+----------------------------------------------------------------------------------------------------------------------------------------------------+ - | Name | Description | - +==========+====================================================================================================================================================+ - | ID | The integral, unique identifier of a steering :term:`Delivery Service` - a target of which shall be deleted | - +----------+----------------------------------------------------------------------------------------------------------------------------------------------------+ - | targetID | The integral, unique identifier of a :term:`Delivery Service` which is a target to be removed of the :term:`Delivery Service` identified by ``ID`` | - +----------+----------------------------------------------------------------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/steering/2/targets/1 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: N6h8Kl7uQveqpTc3fmKXFDY2yYe5smApNcaTow4ab0DHGFdJfqQh89I4nvvaXvmVNhxVAqX3UE/6blbO8/9Xqg== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 11 Dec 2018 14:42:54 GMT - Content-Length: 69 - - { "alerts": [ - { - "text": "steeringtarget was deleted.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/system_info.rst b/docs/source/api/v2/system_info.rst deleted file mode 100644 index 3d75253402..0000000000 --- a/docs/source/api/v2/system_info.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-system-info: - -*************** -``system/info`` -*************** - -``GET`` -======= -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -No parameters available. - -Response Structure ------------------- -:parameters: An object containing information about the Traffic Ops server - - .. note:: These are all the :term:`Parameters` in :ref:`the-global-profile`, so the keys below are merely those present by default required for Traffic Control to operate - - :default_geo_miss_latitude: The default latitude used when geographic lookup of an IP address fails - :default_geo_miss_longitude: The default longitude used when geographic lookup of an IP address fails - :tm.instance_name: The name of the Traffic Ops instance; typically used when multiple instances are active - :tm.toolname: The name of the Traffic Ops tool (usually "Traffic Ops") - used in several API endpoints and written in comment headers on most Apache Traffic Server (ATS) configuration files generated by Traffic Ops - :tm.url: The URL for this Traffic Ops instance ) - used in several API endpoints and written in comment headers on most Apache Traffic Server (ATS) configuration files generated by Traffic Ops - :use_reval_pending: A string containing an integer which represents a boolean value (hold your applause); one of: - - "0" - Do not use pending revalidations - this effectively prohibits the use of "Content Invalidation Jobs" - "1" - Use pending revalidations - this effectively enables the use of "Content Invalidation Jobs" - - :use_tenancy: A string containing an integer which represents a boolean value; one of: - - "0" - Do not use tenancy - this effectively disables all ``*tenant*`` endpoints and removes tenancy restrictions on origins and :term:`Delivery Services` - "1" - Use tenancy - this effectively enables all ``*tenant*`` endpoints and enforces tenancy restrictions on origins and :term:`Delivery Services` - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: ObxOXk1jrC1/JtrqElUICceyx9iJKJxZydEIHvAU7khTTQwt0QGvSO4ELDkdrbu3ctFo3pf3NAMaMM9tAkNokg== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 11 Dec 2018 19:06:01 GMT - Content-Length: 285 - - { "response": { - "parameters": { - "default_geo_miss_latitude": "0", - "default_geo_miss_longitude": "-1", - "tm.instance_name": "CDN-In-A-Box", - "tm.logourl": "/images/tc_logo.png", - "tm.toolname": "Traffic Ops", - "tm.url": "https://trafficops.infra.ciab.test:443/", - "use_reval_pending": "0", - "use_tenancy": "1" - } - }} diff --git a/docs/source/api/v2/tenants.rst b/docs/source/api/v2/tenants.rst deleted file mode 100644 index 92517f170b..0000000000 --- a/docs/source/api/v2/tenants.rst +++ /dev/null @@ -1,167 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-tenants: - -*********** -``tenants`` -*********** - -``GET`` -======= -Get all requested :term:`Tenants`. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------+------------------------------------------------------------------------------------+ - | Name | Description | - +===========+====================================================================================+ - | active | If ``true``, return only active :term:`Tenants`; if ``false`` return only inactive | - | | :term:`Tenants` | - +-----------+------------------------------------------------------------------------------------+ - | id | Return only :term:`Tenants` with this integral, unique identifier | - +-----------+------------------------------------------------------------------------------------+ - | name | Return only :term:`Tenants` with this name | - +-----------+------------------------------------------------------------------------------------+ - | orderby | Choose the ordering of the results - must be the name of one of the fields of the | - | | objects in the ``response`` array | - +-----------+------------------------------------------------------------------------------------+ - | sortOrder | Changes the order of sorting. Either ascending (default or "asc") or descending | - | | ("desc") | - +-----------+------------------------------------------------------------------------------------+ - | limit | Choose the maximum number of results to return | - +-----------+------------------------------------------------------------------------------------+ - | offset | The number of results to skip before beginning to return results. Must use in | - | | conjunction with limit | - +-----------+------------------------------------------------------------------------------------+ - | page | 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 - - GET /api/2.0/tenants?name=root HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -: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 - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: Yzr6TfhxgpZ3pbbrr4TRG4wC3PlnHDDzgs2igtz/1ppLSy2MzugqaGW4y5yzwzl5T3+7q6HWej7GQZt1XIVeZQ== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 11 Dec 2018 19:57:58 GMT - Content-Length: 106 - - { "response": [ - { - "id": 1, - "name": "root", - "active": true, - "lastUpdated": "2018-12-10 19:11:17+00", - "parentId": null - } - ]} - -``POST`` -======== -Create a new tenant. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -:active: An optional boolean - default: ``false`` - which indicates whether or not the tenant shall be immediately active -:name: The name of the tenant -:parentId: The integral, unique identifier of the parent of this tenant - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/tenants HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 48 - Content-Type: application/json - - { - "active": true, - "name": "test", - "parentId": 1 - } - -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 - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: ysdopC//JQI79BRUa61s6M2HzHxYHpo5RdcuauOoqCYxiVOoUhNZfOVydVkv8zDN2qA374XKnym4kWj3VzQIXg== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 11 Dec 2018 19:37:16 GMT - Content-Length: 162 - - { "alerts": [ - { - "text": "tenant was created.", - "level": "success" - } - ], - "response": { - "id": 9, - "name": "test", - "active": true, - "lastUpdated": "2018-12-11 19:37:16+00", - "parentId": 1 - }} diff --git a/docs/source/api/v2/tenants_id.rst b/docs/source/api/v2/tenants_id.rst deleted file mode 100644 index 2b651d13c2..0000000000 --- a/docs/source/api/v2/tenants_id.rst +++ /dev/null @@ -1,147 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-tenants-id: - -****************** -``tenants/{{ID}}`` -****************** - -``PUT`` -======= -Updates a specific tenant. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+---------------------------------------------------------------+ - | Name | Description | - +======+===============================================================+ - | ID | The integral, unique identifier for the tenant being modified | - +------+---------------------------------------------------------------+ - -:active: An optional boolean - default: ``false`` - which indicates whether or not the tenant shall be immediately active -:name: The name of the tenant -:parentId: The integral, unique identifier of the parent of this tenant - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/tenants/9 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 59 - Content-Type: application/json - - { - "active": true, - "name": "quest", - "parentId": 3 - } - -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 - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 5soYQFrG2x5ZJ1e5UZIOLUv/928qyd2Bfgw21Wv85rqjLpyeT3djkfRVD1/xpKConulNrZs2czJKrrwZA7X61w== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 11 Dec 2018 20:30:54 GMT - Content-Length: 163 - - { "alerts": [ - { - "text": "tenant was updated.", - "level": "success" - } - ], - "response": { - "id": 9, - "name": "quest", - "active": true, - "lastUpdated": "2018-12-11 20:30:54+00", - "parentId": 3 - }} - -``DELETE`` -========== -Deletes a specific tenant. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+--------------------------------------------------------------+ - | Name | Description | - +======+==============================================================+ - | ID | The integral, unique identifier for the tenant being deleted | - +------+--------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - DELETE /api/2.0/tenants/9 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: KU0XIbFoD0Cy06kzH2Gl59pBqie/TEFJgh33mssGNwXJZlRkTLaSTHT8Df4X+pOs7UauZH10akGvaA0UTiN/vg== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 11 Dec 2018 20:40:31 GMT - Content-Length: 61 - - { "alerts": [ - { - "text": "tenant was deleted.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/types.rst b/docs/source/api/v2/types.rst deleted file mode 100644 index 14377c41ed..0000000000 --- a/docs/source/api/v2/types.rst +++ /dev/null @@ -1,158 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-types: - -********* -``types`` -********* - -``GET`` -======= -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 -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +============+==========+================================================================================================================================+ - | id | no | Return only the type that is identified by this integral, unique identifier | - +------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ - | name | no | Return only types with this name | - +------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ - | useInTable | no | Return only types that are used to identify the type of the object stored in the Traffic Ops database table that has this name | - +------------+----------+--------------------------------------------------------------------------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Structure - - GET /api/2.0/types?name=TC_LOC HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:description: A short description of this type -:id: An integral, unique identifier for this type -:lastUpdated: The date and time at which this type was last updated, in :ref:`non-rfc-datetime` -:name: The name of this type -:useInTable: The name of the Traffic Ops database table that contains objects which are grouped, identified, or described by this type - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: EH8jo8OrCu79Tz9xpgT3YRyKJ/p2NcTmbS3huwtqRByHz9H6qZLQjA59RIPaVSq3ZxsU6QhTaox5nBkQ9LPSAA== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 12 Dec 2018 22:59:22 GMT - Content-Length: 168 - - { "response": [ - { - "id": 48, - "lastUpdated": "2018-12-12 16:26:41+00", - "name": "TC_LOC", - "description": "Location for Traffic Control Component Servers", - "useInTable": "cachegroup" - } - ]} - -``POST`` -======== -Creates a type - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ - -:description: A short description of this type -:name: The name of this type -:useInTable: The name of the Traffic Ops database table that contains objects which are grouped, identified, or described by this type. - - .. note:: The only useInTable value that is allowed to be created dynamically is 'server' - -.. code-block:: http - :caption: Request Structure - - POST /api/2.0/type HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 67 - Content-Type: application/json - - { - "name": "Example01", - "description": "Example", - "useInTable": "server" - } - -Response Structure ------------------- - -:description: A short description of this type -:id: An integral, unique identifier for this type -:lastUpdated: The date and time at which this type was last updated, in :ref:`non-rfc-datetime` -:name: The name of this type -:useInTable: The name of the Traffic Ops database table that contains objects which are grouped, identified, or described by this type - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: EH8jo8OrCu79Tz9xpgT3YRyKJ/p2NcTmbS3huwtqRByHz9H6qZLQjA59RIPaVSq3ZxsU6QhTaox5nBkQ9LPSAA== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 26 Feb 2020 18:58:41 GMT - Content-Length: 171 - - { - "alerts": [ - { - "text": "type was created.", - "level": "success" - }], - "response": [ - { - "id": 3004, - "lastUpdated": "2020-02-26 18:58:41+00", - "name": "Example01", - "description": "Example" - "useInTable": "server" - }] - } diff --git a/docs/source/api/v2/types_id.rst b/docs/source/api/v2/types_id.rst deleted file mode 100644 index 4c9fdbc3e7..0000000000 --- a/docs/source/api/v2/types_id.rst +++ /dev/null @@ -1,156 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-types-id: - -**************** -``types/{{ID}}`` -**************** - -``PUT`` -======= -Updates a type - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-----------------------------------------------------------+ - | Name | Description | - +======+===========================================================+ - | ID | The integral, unique identifier of the type being updated | - +------+-----------------------------------------------------------+ - -:description: A short description of this type -:name: The name of this type -:useInTable: The name of the Traffic Ops database table that contains objects which are grouped, identified, or described by this type. - -.. note:: Only types with useInTable set to 'server' are allowed to be updated. - -.. code-block:: http - :caption: Request Structure - - PUT /api/2.0/type/3004 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 68 - Content-Type: application/json - - { - "name": "Example01", - "description": "Example2", - "useInTable": "server" - } - -Response Structure ------------------- -:description: A short description of this type -:id: An integral, unique identifier for this type -:lastUpdated: The date and time at which this type was last updated, in :ref:`non-rfc-datetime` -:name: The name of this type -:useInTable: The name of the Traffic Ops database table that contains objects which are grouped, identified, or described by this type - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: EH8jo8OrCu79Tz9xpgT3YRyKJ/p2NcTmbS3huwtqRByHz9H6qZLQjA59RIPaVSq3ZxsU6QhTaox5nBkQ9LPSAA== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 26 Feb 2020 18:58:41 GMT - Content-Length: 172 - - { - "alerts": [ - { - "text": "type was updated.", - "level": "success" - }], - "response": [ - { - "id": 3004, - "lastUpdated": "2020-02-26 18:58:41+00", - "name": "Example02", - "description": "Example" - "useInTable": "server" - }] - } - -``DELETE`` -========== -Deletes a type - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-----------------------------------------------------------+ - | Name | Description | - +======+===========================================================+ - | ID | The integral, unique identifier of the type being deleted | - +------+-----------------------------------------------------------+ - -.. note:: Only types with useInTable set to "server" are allowed to be deleted. - -.. code-block:: http - :caption: Request Structure - - DELETE /api/2.0/type/3004 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 0 - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: EH8jo8OrCu79Tz9xpgT3YRyKJ/p2NcTmbS3huwtqRByHz9H6qZLQjA59RIPaVSq3ZxsU6QhTaox5nBkQ9LPSAA== - X-Server-Name: traffic_ops_golang/ - Date: Wed, 26 Feb 2020 18:58:41 GMT - Content-Length: 84 - - { - "alerts": [ - { - "text": "type was deleted.", - "level": "success" - }], - } diff --git a/docs/source/api/v2/user_current.rst b/docs/source/api/v2/user_current.rst deleted file mode 100644 index 50185f3ef5..0000000000 --- a/docs/source/api/v2/user_current.rst +++ /dev/null @@ -1,241 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-user-current: - -**************** -``user/current`` -**************** - -``GET`` -======= -.. caution:: As a username is needed to log in, any administrator or application must necessarily know the current username at any given time. Thus it's generally better to use the ``username`` query parameter of a ``GET`` request to :ref:`to-api-users` instead. - -Retrieves the details of the authenticated user. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -No parameters available. - -Response Structure ------------------- -:addressLine1: The user's address - including street name and number -:addressLine2: An additional address field for e.g. apartment number -:city: The name of the city wherein the user resides -:company: The name of the company for which the user works -:country: The name of the country wherein the user resides -:email: The user's email address -:fullName: The user's full name, e.g. "John Quincy Adams" -:gid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user -:id: An integral, unique identifier for this user -:lastUpdated: The date and time at which the user was last modified, in :ref:`non-rfc-datetime` -:newUser: A meta field with no apparent purpose that is usually ``null`` unless explicitly set during creation or modification of a user via some API endpoint -:phoneNumber: The user's phone number -:postalCode: The postal code of the area in which the user resides -:publicSshKey: The user's public key used for the SSH protocol -:registrationSent: If the user was created using the :ref:`to-api-users-register` endpoint, this will be the date and time at which the registration email was sent - otherwise it will be ``null`` -:role: The integral, unique identifier of the highest-privilege :term:`Role` assigned to this user -:rolename: The name of the highest-privilege :term:`Role` assigned to this user -:stateOrProvince: The name of the state or province where this user resides -:tenant: The name of the :term:`Tenant` to which this user belongs -:tenantId: The integral, unique identifier of the :term:`Tenant` to which this user belongs -:uid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user -:username: The user's username - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: HQwu9FxFyinXSVFK5+wpEhSxU60KbqXuokFbMZ3OoerOoM5ZpWpglsHz7mRch8VAw0dzwsJzpPJivj07RiKaJg== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 13 Dec 2018 15:14:45 GMT - Content-Length: 382 - - { "response": { - "username": "admin", - "localUser": true, - "addressLine1": null, - "addressLine2": null, - "city": null, - "company": null, - "country": null, - "email": null, - "fullName": "admin", - "gid": null, - "id": 2, - "newUser": false, - "phoneNumber": null, - "postalCode": null, - "publicSshKey": null, - "role": 1, - "rolename": "admin", - "stateOrProvince": null, - "tenant": "root", - "tenantId": 1, - "uid": null, - "lastUpdated": "2018-12-12 16:26:32+00" - }} - -``PUT`` -======= -.. warning:: Assuming the current user's integral, unique identifier is known, it's generally better to use the ``PUT`` method of the :ref:`to-api-users` instead. - -.. warning:: Users that login via LDAP pass-back cannot be modified - -Updates the date for the authenticated user. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Object - -Request Structure ------------------ -:user: The entire request must be inside a top-level "user" key for legacy reasons - - :addressLine1: The user's address - including street name and number - :addressLine2: An additional address field for e.g. apartment number - :city: The name of the city wherein the user resides - :company: The name of the company for which the user works - :confirmLocalPasswd: An optional 'confirm' field in a new user's password specification. This has no known effect and in fact *doesn't even need to match* ``localPasswd`` - :country: The name of the country wherein the user resides - :email: The user's email address - cannot be an empty string\ [#notnull]_. The given email is validated (circuitously) by `GitHub user asaskevich's regular expression `_ . Note that it can't actually distinguish a valid, deliverable, email address but merely ensure the email is in a commonly-found format. - :fullName: The user's full name, e.g. "John Quincy Adams" - :gid: A legacy field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user - please don't use this - :id: The user's integral, unique, identifier - this cannot be changed\ [#notnull]_ - :localPasswd: Optionally, the user's password. This should never be given if it will not be changed. An empty string or ``null`` can be used to explicitly specify no change. - :phoneNumber: The user's phone number - :postalCode: The user's postal code - :publicSshKey: The user's public encryption key used for the SSH protocol - :role: The integral, unique identifier of the highest permission :term:`Role` which will be permitted to the user - this cannot be altered from the user's current :term:`Role`\ [#notnull]_ - :stateOrProvince: The state or province in which the user resides - :tenantId: The integral, unique identifier of the :term:`Tenant` to which the new user shall belong\ [#tenancy]_\ [#notnull]_ - :uid: A legacy field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user - please don't use this - :username: The user's new username\ [#notnull]_ - -.. code-block:: http - :caption: Request Example - - PUT /api/2.0/user/current HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 465 - Content-Type: application/json - - { "user": { - "addressLine1": null, - "addressLine2": null, - "city": null, - "company": null, - "country": null, - "email": "admin@infra.trafficops.ciab.test", - "fullName": "admin", - "gid": null, - "id": 2, - "phoneNumber": null, - "postalCode": null, - "publicSshKey": null, - "role": 1, - "stateOrProvince": null, - "tenantId": 1, - "uid": null, - "username": "admin" - }} - -Response Structure ------------------- -:addressLine1: The user's address - including street name and number -:addressLine2: An additional address field for e.g. apartment number -:city: The name of the city wherein the user resides -:company: The name of the company for which the user works -:country: The name of the country wherein the user resides -:email: The user's email address validated (circuitously) by `GitHub user asaskevich's regular expression `_ . Note that it can't actually distinguish a valid, deliverable, email address but merely ensure the email is in a commonly-found format. -:fullName: The user's full name, e.g. "John Quincy Adams" -:gid: A legacy field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user -:id: An integral, unique identifier for this user -:lastUpdated: The date and time at which the user was last modified, in :ref:`non-rfc-datetime` -:newUser: A meta field with no apparent purpose -:phoneNumber: The user's phone number -:postalCode: The postal code of the area in which the user resides -:publicSshKey: The user's public key used for the SSH protocol -:registrationSent: If the user was created using the :ref:`to-api-users-register` endpoint, this will be the date and time at which the registration email was sent - otherwise it will be ``null`` -:role: The integral, unique identifier of the highest-privilege :term:`Role` assigned to this user -:rolename: The name of the highest-privilege :term:`Role` assigned to this user -:stateOrProvince: The name of the state or province where this user resides -:tenant: The name of the :term:`Tenant` to which this user belongs -:tenantId: The integral, unique identifier of the :term:`Tenant` to which this user belongs -:uid: A legacy field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user -:username: The user's username - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Date: Thu, 13 Dec 2018 21:05:49 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: sHFqZQ4Cv7IIWaIejoAvM2Fr/HSupcX3D16KU/etjw+4jcK9EME3Bq5ohLC+eQ52BDCKW2Ra+AC3TfFtworJww== - Content-Length: 478 - - { "alerts": [ - { - "text": "User profile was successfully updated", - "level": "success" - } - ], - "response": { - "addressLine1": null, - "addressLine2": null, - "city": null, - "company": null, - "country": null, - "email": "admin@infra.trafficops.ciab.test", - "fullName": null, - "gid": null, - "id": 2, - "lastUpdated": "2019-10-08 20:14:25+00", - "newUser": false, - "phoneNumber": null, - "postalCode": null, - "publicSshKey": null, - "registrationSent": null, - "role": 1, - "roleName": "admin", - "stateOrProvince": null, - "tenant": "root", - "tenantId": 1, - "uid": null, - "username": "admin" - }} - -.. [#notnull] This field cannot be ``null``. -.. [#tenancy] This endpoint respects tenancy; a user cannot assign itself to a :term:`Tenant` that is not the same :term:`Tenant` to which it was previously assigned or a descendant thereof. diff --git a/docs/source/api/v2/user_login.rst b/docs/source/api/v2/user_login.rst deleted file mode 100644 index 2140feb159..0000000000 --- a/docs/source/api/v2/user_login.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-user-login: - -************** -``user/login`` -************** - -``POST`` -======== -Authentication of a user using username and password. Traffic Ops will send back a session cookie. - -:Auth. Required: No -:Roles Required: None -:Response Type: ``undefined`` - -Request Structure ------------------ -:p: Password -:u: Username - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/user/login HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 26 - Content-Type: application/json - - { - "u": "admin", - "p": "twelve" - } - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: UdO6T3tMNctnVusDXzRjVwwYOnD7jmnBzPEB9PvOt2bHajTv3SKTPiIZjDzvhU6EX4p+JoG4fA5wlhgxpsejIw== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 13 Dec 2018 15:21:33 GMT - Content-Length: 65 - - { "alerts": [ - { - "text": "Successfully logged in.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/user_login_oauth.rst b/docs/source/api/v2/user_login_oauth.rst deleted file mode 100644 index 99d8d885f3..0000000000 --- a/docs/source/api/v2/user_login_oauth.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-user-login-oauth: - -******************** -``user/login/oauth`` -******************** - -``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. - -:Auth. Required: No -:Roles Required: None -:Response Type: ``undefined`` - -Request Structure ------------------ -:authCodeTokenUrl: URL for code-to-token conversion -:code: Code -:clientId: Client Id -:redirectUri: Redirect URI - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/user/login/oauth HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 26 - Content-Type: application/json - - { - "authCodeTokenUrl": "https://url-to-convert-code-to-token.example.com", - "code": "AbCd123", - "clientId": "oauthClientId", - "redirectUri": "https://traffic-portal.example.com/sso" - } - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: UdO6T3tMNctnVusDXzRjVwwYOnD7jmnBzPEB9PvOt2bHajTv3SKTPiIZjDzvhU6EX4p+JoG4fA5wlhgxpsejIw== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 13 Dec 2018 15:21:33 GMT - Content-Length: 65 - - { "alerts": [ - { - "text": "Successfully logged in.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/user_login_token.rst b/docs/source/api/v2/user_login_token.rst deleted file mode 100644 index 9da4156e02..0000000000 --- a/docs/source/api/v2/user_login_token.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-user-login-token: - -******************** -``user/login/token`` -******************** - -``POST`` -======== -Authentication of a user using a token. Normally, the token is obtained via a call to either :ref:`to-api-user-reset_password` or :ref:`to-api-users-register`. - -:Auth. Required: No -:Roles Required: None -:Response Type: ``undefined`` - -Request Structure ------------------ -:t: A :abbr:`UUID (Universal Unique Identifier)` generated for the user. - - .. impl-detail:: Though not strictly necessary for authentication provided direct database access, the tokens generated for use with this endpoint are compliant with :RFC:`4122`. - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/user/login/token HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 44 - Content-Type: application/json - - { - "t": "18EE200C-FF24-11E8-BF01-870C776752A3" - } - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: FuS3TkVosxHtpxRGMJ2on+WnFdYTNSPjxz/Gh1iT4UCJ2/P0twUbAGQ3tTx9EfGiAzg9CNQiVUFGnYjJZ6NCpg== - X-Server-Name: traffic_ops_golang/ - Date: Fri, 20 Sep 2019 15:02:43 GMT - Content-Length: 66 - - { "alerts": [ - { - "text": "Successfully logged in.", - "level": "success" - } - ]} diff --git a/docs/source/api/v2/user_logout.rst b/docs/source/api/v2/user_logout.rst deleted file mode 100644 index f14290db9a..0000000000 --- a/docs/source/api/v2/user_logout.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-user-logout: - -*************** -``user/logout`` -*************** - -``POST`` -======== -User logout. Invalidates the session cookie of the currently logged-in user. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: ``undefined`` - -Request Structure ------------------ -No parameters available - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Thu, 13 Dec 2018 21:25:36 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: 6KEdr1ZC512zkOl03KwvQE0L7qrJ/+ek6ztymkYy9p8gdPUyYyzGEAJ/Ldb8GY0UBFYmgqeZ3yWHvTcEsOQMiw== - Content-Length: 61 - - { "alerts": [ - { - "level": "success", - "text": "You are logged out." - } - ]} diff --git a/docs/source/api/v2/user_reset_password.rst b/docs/source/api/v2/user_reset_password.rst deleted file mode 100644 index 13bd97acec..0000000000 --- a/docs/source/api/v2/user_reset_password.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-user-reset_password: - -*********************** -``user/reset_password`` -*********************** - -``POST`` -======== -Sends an email to reset a user's password. - -:Auth. Required: No -:Roles Required: None -:Response Type: ``undefined`` - -Request Structure ------------------ -:email: The email address of the user to initiate password reset - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/user/reset_password HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 35 - Content-Type: application/json - - { - "email": "test@example.com" - } - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Thu, 13 Dec 2018 22:11:53 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: lKWwVYbgKklk7bljnQJZwWV5bljIk+GkooD6SAc3CSexVKvfbL9dgL5iBc/BNNRk2pIU5I/1GgldcDLrXsF1ZA== - Content-Length: 109 - - { "alerts": [ - { - "level": "success", - "text": "Successfully sent password reset to email 'test@example.com'" - } - ]} diff --git a/docs/source/api/v2/users.rst b/docs/source/api/v2/users.rst deleted file mode 100644 index 72b30499bf..0000000000 --- a/docs/source/api/v2/users.rst +++ /dev/null @@ -1,265 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-users: - -********* -``users`` -********* - -``GET`` -======= -Retrieves all requested users. - -:Auth. Required: Yes -:Roles Required: None\ [1]_ -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Query Parameters - - +-----------+----------+------------------------------------------------------------------------------------------+ - | Name | Required | Description | - +===========+==========+==========================================================================================+ - | id | no | Return only the user identified by this integral, unique identifier | - +-----------+----------+------------------------------------------------------------------------------------------+ - | tenant | no | Return only users belonging to the :term:`Tenant` identified by tenant name | - +-----------+----------+------------------------------------------------------------------------------------------+ - | role | no | Return only users belonging to the :term:`Role` identified by role name | - +-----------+----------+------------------------------------------------------------------------------------------+ - | username | no | Return only the user with this username | - +-----------+----------+------------------------------------------------------------------------------------------+ - | 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 - - GET /api/2.0/users?username=admin HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:addressLine1: The user's address - including street name and number -:addressLine2: An additional address field for e.g. apartment number -:city: The name of the city wherein the user resides -:company: The name of the company for which the user works -:country: The name of the country wherein the user resides -:email: The user's email address -:fullName: The user's full name, e.g. "John Quincy Adams" -:gid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user - now it is always ``null`` -:id: An integral, unique identifier for this user -:lastUpdated: The date and time at which the user was last modified, in :ref:`non-rfc-datetime` -:newUser: A meta field with no apparent purpose that is usually ``null`` unless explicitly set during creation or modification of a user via some API endpoint -:phoneNumber: The user's phone number -:postalCode: The postal code of the area in which the user resides -:publicSshKey: The user's public key used for the SSH protocol -:registrationSent: If the user was created using the :ref:`to-api-users-register` endpoint, this will be the date and time at which the registration email was sent - otherwise it will be ``null`` -:role: The integral, unique identifier of the highest-privilege role assigned to this user -:rolename: The name of the highest-privilege role assigned to this user -:stateOrProvince: The name of the state or province where this user resides -:tenant: The name of the tenant to which this user belongs -:tenantId: The integral, unique identifier of the tenant to which this user belongs -:uid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user - now it is always ``null`` -:username: The user's username - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: YBJLN8NbOxOvECe1RGtcwCzIPDhyhLpW56nTJHQM5WI2WUDe2mAKREpaEE72nzrfBliq1GABwJlsxq2OdhcFkw== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 13 Dec 2018 01:03:53 GMT - Content-Length: 391 - - { "response": [ - { - "username": "admin", - "registrationSent": null, - "addressLine1": null, - "addressLine2": null, - "city": null, - "company": null, - "country": null, - "email": null, - "fullName": null, - "gid": null, - "id": 2, - "newUser": false, - "phoneNumber": null, - "postalCode": null, - "publicSshKey": null, - "role": 1, - "rolename": "admin", - "stateOrProvince": null, - "tenant": "root", - "tenantId": 1, - "uid": null, - "lastUpdated": "2018-12-12 16:26:32+00" - } - ]} - -.. [1] While no roles are required, this endpoint does respect tenancy. A user will only be able to see, create, delete or modify other users belonging to the same tenant, or its descendants. - -``POST`` -======== -Creates a new user. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations"\ [1]_ -:Response Type: Object - -Request Structure ------------------ -:addressLine1: An optional field which should contain the user's address - including street name and number -:addressLine2: An optional field which should contain an additional address field for e.g. apartment number -:city: An optional field which should contain the name of the city wherein the user resides -:company: An optional field which should contain the name of the company for which the user works -:confirmLocalPasswd: The 'confirm' field in a new user's password specification - must match ``localPasswd`` -:country: An optional field which should contain the name of the country wherein the user resides -:email: The user's email address The given email is validated (circuitously) by `GitHub user asaskevich's regular expression `_ . Note that it can't actually distinguish a valid, deliverable, email address but merely ensure the email is in a commonly-found format. -:fullName: The user's full name, e.g. "John Quincy Adams" -:localPasswd: The user's password -:newUser: An optional meta field with no apparent purpose - don't use this -:phoneNumber: An optional field which should contain the user's phone number -:postalCode: An optional field which should contain the user's postal code -:publicSshKey: An optional field which should contain the user's public encryption key used for the SSH protocol -:role: The number that corresponds to the highest permission role which will be permitted to the user -:stateOrProvince: An optional field which should contain the name of the state or province in which the user resides -:tenantId: The integral, unique identifier of the tenant to which the new user shall belong - - .. note:: This field is optional if and only if tenancy is not enabled in Traffic Control - -:username: The new user's username - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/users HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 304 - Content-Type: application/json - - { - "username": "mike", - "addressLine1": "22 Mike Wazowski You've Got Your Life Back Lane", - "city": "Monstropolis", - "compary": "Monsters Inc.", - "email": "mwazowski@minc.biz", - "fullName": "Mike Wazowski", - "localPasswd": "BFFsully", - "confirmLocalPasswd": "BFFsully", - "newUser": true, - "role": 1, - "tenantId": 1 - } - -Response Structure ------------------- -:addressLine1: The user's address - including street name and number -:addressLine2: An additional address field for e.g. apartment number -:city: The name of the city wherein the user resides -:company: The name of the company for which the user works -:country: The name of the country wherein the user resides -:email: The user's email address -:fullName: The user's full name, e.g. "John Quincy Adams" -:gid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user - now it is always ``null`` -:id: An integral, unique identifier for this user -:lastUpdated: The date and time at which the user was last modified, in :ref:`non-rfc-datetime` -:newUser: A meta field with no apparent purpose that is usually ``null`` unless explicitly set during creation or modification of a user via some API endpoint -:phoneNumber: The user's phone number -:postalCode: The postal code of the area in which the user resides -:publicSshKey: The user's public key used for the SSH protocol -:registrationSent: If the user was created using the :ref:`to-api-users-register` endpoint, this will be the date and time at which the registration email was sent - otherwise it will be ``null`` -:role: The integral, unique identifier of the highest-privilege role assigned to this user -:rolename: The name of the highest-privilege role assigned to this user -:stateOrProvince: The name of the state or province where this user resides -:tenant: The name of the tenant to which this user belongs -:tenantId: The integral, unique identifier of the tenant to which this user belongs -:uid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user - now it is always ``null`` -:username: The user's username - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Thu, 13 Dec 2018 02:28:27 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: vDqbaMvgeeoIds1czqvIWlyDG8WLnCCJdF14Ub05nsE+oJOakkyeZ8odf4d0Zjtqpk01hoVo14H2tjuWPdqwgw== - Content-Length: 520 - - { "alerts": [ - { - "level": "success", - "text": "User creation was successful." - } - ], - "response": { - "registrationSent": null, - "email": "mwazowski@minc.biz", - "tenantId": 1, - "city": "Monstropolis", - "tenant": "root", - "id": 8, - "company": null, - "rolename": "admin", - "phoneNumber": null, - "country": null, - "fullName": "Mike Wazowski", - "publicSshKey": null, - "uid": null, - "stateOrProvince": null, - "lastUpdated": null, - "username": "mike", - "newUser": false, - "addressLine2": null, - "role": 1, - "addressLine1": "22 Mike Wazowski You've Got Your Life Back Lane", - "postalCode": null, - "gid": null - }} diff --git a/docs/source/api/v2/users_id.rst b/docs/source/api/v2/users_id.rst deleted file mode 100644 index 1c76baaaf0..0000000000 --- a/docs/source/api/v2/users_id.rst +++ /dev/null @@ -1,253 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-users-id: - -**************** -``users/{{ID}}`` -**************** - -``GET`` -======= -Retrieves a specific user. - -:Auth. Required: Yes -:Roles Required: None -:Response Type: Array - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+-------------------------------------------------------------+ - | Name | Description | - +======+=============================================================+ - | ID | The integral, unique identifier of the user to be retrieved | - +------+-------------------------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/users/2 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - -Response Structure ------------------- -:addressLine1: The user's address - including street name and number -:addressLine2: An additional address field for e.g. apartment number -:city: The name of the city wherein the user resides -:company: The name of the company for which the user works -:country: The name of the country wherein the user resides -:email: The user's email address -:fullName: The user's full name, e.g. "John Quincy Adams" -:gid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user - now it is always ``null`` -:id: An integral, unique identifier for this user -:lastUpdated: The date and time at which the user was last modified, in :ref:`non-rfc-datetime` -:newUser: A meta field with no apparent purpose that is usually ``null`` unless explicitly set during creation or modification of a user via some API endpoint -:phoneNumber: The user's phone number -:postalCode: The postal code of the area in which the user resides -:publicSshKey: The user's public key used for the SSH protocol -:registrationSent: If the user was created using the :ref:`to-api-users-register` endpoint, this will be the date and time at which the registration email was sent - otherwise it will be ``null`` -:role: The integral, unique identifier of the highest-privilege role assigned to this user -:rolename: The name of the highest-privilege role assigned to this user -:stateOrProvince: The name of the state or province where this user resides -:tenant: The name of the tenant to which this user belongs -:tenantId: The integral, unique identifier of the tenant to which this user belongs -:uid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user - now it is always ``null`` -:username: The user's username - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: 9vqUmt8fWEuDb+9LQJ4sGbbF4Z0a7uNyBNSWhyzAi3fBUZ5mGhd4Jx5IuSlEqiLZnYeViJJL8mpRortkHCgp5Q== - X-Server-Name: traffic_ops_golang/ - Date: Thu, 13 Dec 2018 17:46:00 GMT - Content-Length: 588 - - { "response": [ - { - "username": "admin", - "registrationSent": null, - "addressLine1": "not a real address", - "addressLine2": "not a real address either", - "city": "not a real city", - "company": "not a real company", - "country": "not a real country", - "email": "not@real.email", - "fullName": "Not a real Full Name", - "gid": null, - "id": 2, - "newUser": false, - "phoneNumber": "not a real phone number", - "postalCode": "not a real postal code", - "publicSshKey": "not a real ssh key", - "role": 1, - "rolename": "admin", - "stateOrProvince": "not a real state or province", - "tenant": "root", - "tenantId": 1, - "uid": null, - "lastUpdated": "2018-12-13 17:24:23+00" - } - ]} - -``PUT`` -======= - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +------+------------------------------------------------------------+ - | Name | Description | - +======+============================================================+ - | ID | The integral, unique identifier of the user to be modified | - +------+------------------------------------------------------------+ - -:addressLine1: An optional field which should contain the user's address - including street name and number -:addressLine2: An optional field which should contain an additional address field for e.g. apartment number -:city: An optional field which should contain the name of the city wherein the user resides -:company: An optional field which should contain the name of the company for which the user works -:confirmLocalPasswd: The 'confirm' field in a new user's password specification - must match ``localPasswd`` -:country: An optional field which should contain the name of the country wherein the user resides -:email: The user's email address The given email is validated (circuitously) by `GitHub user asaskevich's regular expression `_ . Note that it can't actually distinguish a valid, deliverable, email address but merely ensure the email is in a commonly-found format. -:fullName: The user's full name, e.g. "John Quincy Adams" -:localPasswd: The user's password -:newUser: An optional meta field with no apparent purpose - don't use this -:phoneNumber: An optional field which should contain the user's phone number -:postalCode: An optional field which should contain the user's postal code -:publicSshKey: An optional field which should contain the user's public encryption key used for the SSH protocol -:role: The number that corresponds to the highest permission role which will be permitted to the user -:stateOrProvince: An optional field which should contain the name of the state or province in which the user resides -:tenantId: The integral, unique identifier of the tenant to which the new user shall belong - - .. note:: This field is optional if and only if tenancy is not enabled in Traffic Control - -:username: The new user's username - -.. code-block:: http - :caption: Request Structure - - PUT /api/2.0/users/2 HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 458 - Content-Type: application/json - - { - "addressLine1": "not a real address", - "addressLine2": "not a real address either", - "city": "not a real city", - "company": "not a real company", - "country": "not a real country", - "email": "not@real.email", - "fullName": "Not a real fullName", - "phoneNumber": "not a real phone number", - "postalCode": "not a real postal code", - "publicSshKey": "not a real ssh key", - "stateOrProvince": "not a real state or province", - "tenantId": 1, - "role": 1, - "username": "admin" - } - -Response Structure ------------------- -:addressLine1: The user's address - including street name and number -:addressLine2: An additional address field for e.g. apartment number -:city: The name of the city wherein the user resides -:company: The name of the company for which the user works -:country: The name of the country wherein the user resides -:email: The user's email address -:fullName: The user's full name, e.g. "John Quincy Adams" -:gid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user - now it is always ``null`` -:id: An integral, unique identifier for this user -:lastUpdated: The date and time at which the user was last modified, in :ref:`non-rfc-datetime` -:newUser: A meta field with no apparent purpose that is usually ``null`` unless explicitly set during creation or modification of a user via some API endpoint -:phoneNumber: The user's phone number -:postalCode: The postal code of the area in which the user resides -:publicSshKey: The user's public key used for the SSH protocol -:registrationSent: If the user was created using the :ref:`to-api-users-register` endpoint, this will be the date and time at which the registration email was sent - otherwise it will be ``null`` -:role: The integral, unique identifier of the highest-privilege role assigned to this user -:rolename: The name of the highest-privilege role assigned to this user -:stateOrProvince: The name of the state or province where this user resides -:tenant: The name of the tenant to which this user belongs -:tenantId: The integral, unique identifier of the tenant to which this user belongs -:uid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user - now it is always ``null`` -:username: The user's username - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Thu, 13 Dec 2018 17:24:23 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: QKvGSIwSdreMI/OdgWv9WQfI/C1JbXSoQGGospTGfCVUJ32XNWMhmREGzojWsilW8os8b14TGYeyMLUWunf2Ug== - Content-Length: 661 - - { "alerts": [ - { - "level": "success", - "text": "User update was successful." - } - ], - "response": { - "registrationSent": null, - "email": "not@real.email", - "tenantId": 1, - "city": "not a real city", - "tenant": "root", - "id": 2, - "company": "not a real company", - "rolename": "admin", - "phoneNumber": "not a real phone number", - "country": "not a real country", - "fullName": "Not a real Full Name", - "publicSshKey": "not a real ssh key", - "uid": null, - "stateOrProvince": "not a real state or province", - "lastUpdated": "2018-12-12 16:26:32.821187+00", - "username": "admin", - "newUser": false, - "addressLine2": "not a real address either", - "role": 1, - "addressLine1": "not a real address", - "postalCode": "not a real postal code", - "gid": null - }} diff --git a/docs/source/api/v2/users_register.rst b/docs/source/api/v2/users_register.rst deleted file mode 100644 index 8ca76172b7..0000000000 --- a/docs/source/api/v2/users_register.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-users-register: - -****************** -``users/register`` -****************** - -``POST`` -======== -Register a user and send registration email. - -:Auth. Required: Yes -:Roles Required: "admin" or "operations" -:Response Type: ``undefined`` - -Request Structure ------------------ -:email: Email address of the new user The given email is validated (circuitously) by `GitHub user asaskevich's regular expression `_ . Note that it can't actually distinguish a valid, deliverable, email address but merely ensure the email is in a commonly-found format. -:role: The integral, unique identifier of the highest permissions :term:`Role` which will be afforded to the new user. It restricts the allowed values to identifiers for :term:`Roles` with at most the same permissions level as the requesting user. -:tenantId: A field containing the integral, unique identifier of the :term:`Tenant` to which the new user will belong. It restricts the allowed values to identifiers for :term:`Tenants` within the requesting user's :term:`Tenant`'s permissions. - -.. code-block:: http - :caption: Request Example - - POST /api/2.0/users/register HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 - Accept: */* - Cookie: mojolicious=... - Content-Length: 59 - Content-Type: application/json - - { - "email": "test@example.com", - "role": 3, - "tenantId": 1 - } - -Response Structure ------------------- -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate - Content-Type: application/json - Date: Thu, 13 Dec 2018 22:03:22 GMT - X-Server-Name: traffic_ops_golang/ - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: yvf++Oqxvu3uOIAYbWLUgJKxZ4T60Mi5H9eGTxrKLxnRsHw0PdDIrThbTnWtATBkak4vU/dPHLLXKW85LUTEWg== - Content-Length: 160 - - { "alerts": [ - { - "level": "success", - "text": "Sent user registration to test@example.com with the following permissions [ role: read-only | tenant: root ]" - } - ]} diff --git a/docs/source/api/v2/vault_bucket_bucket_key_key_values.rst b/docs/source/api/v2/vault_bucket_bucket_key_key_values.rst deleted file mode 100644 index b234c84ea4..0000000000 --- a/docs/source/api/v2/vault_bucket_bucket_key_key_values.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. _to-api-v2-vault-bucket-bucket-key-key-values: - -********************************************** -``vault/bucket/{{bucket}}/key/{{key}}/values`` -********************************************** -Retrieves the `object `_ stored under a given `key `_ from a given `bucket `_ in :ref:`tv-overview`. - -.. deprecated:: ATCv6 - -``GET`` -======= -:Auth. Required: Yes -:Roles Required: "admin" -:Response Type: Object - -Request Structure ------------------ -.. table:: Request Path Parameters - - +--------+------------------------------------------+ - | Name | Description | - +========+==========================================+ - | bucket | The bucket that the key is stored under | - +--------+------------------------------------------+ - | key | The key that the object is stored under | - +--------+------------------------------------------+ - -.. code-block:: http - :caption: Request Example - - GET /api/2.0/vault/bucket/ssl/key/demo1-latest/values HTTP/1.1 - User-Agent: python-requests/2.22.0 - Accept-Encoding: gzip, deflate - Accept: */* - Connection: keep-alive - Cookie: mojolicious=... - -Response Structure ------------------- -The response structure varies according to what is stored. Top-level keys will always be ``String`` type, but the values can be any type. - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Encoding: gzip - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Sun, 23 Feb 2020 23:29:27 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: LUq4+MUCgIqxBWqbuA/Pbsdq5Qfs7vPUcZ0Cu2FcOUyP0X8xXit3BJrdOLA+dSSJ3tSQ7Qij1+0ahzuouuLT7Q== - X-Server-Name: traffic_ops_golang/ - Date: Sun, 23 Feb 2020 22:29:27 GMT - Transfer-Encoding: chunked - - { - "alerts": [ - { - "text": "This endpoint is deprecated, and will be removed in the future", - "level": "warning" - }], - "response": { - "cdn": "CDN-in-a-Box", - "certificate": { - "crt": "...", - "csr": "...", - "key": "..." - }, - "deliveryservice": "demo1", - "hostname": "*.demo1.mycdn.ciab.test", - "key": "demo1", - "version": 1 - } - } diff --git a/docs/source/api/v2/vault_ping.rst b/docs/source/api/v2/vault_ping.rst deleted file mode 100644 index 5cde60d74e..0000000000 --- a/docs/source/api/v2/vault_ping.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. -.. _to-api-v2-vault-ping: - -************** -``vault/ping`` -************** - -``GET`` -======= -Pings Traffic Vault to retrieve status. - -:Auth. Required: Yes -:Roles Required: "read-only" -:Response Type: Object - -Request Structure ------------------ -No parameters available. - -Response Properties -------------------- -:status: The status returned from the ping request to the Traffic Vault server -:server: The Traffic Vault server that was pinged - -.. code-block:: http - :caption: Response Example - - HTTP/1.1 200 OK - Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie - Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE - Access-Control-Allow-Origin: * - Content-Type: application/json - Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 25 Feb 2020 15:37:54 GMT; Max-Age=3600; HttpOnly - Whole-Content-Sha512: z9P1NkxGebPncUhaChDHtYKYI+XVZfhE6Y84TuwoASZFIMfISELwADLpvpPTN+wwnzBfREksLYn+0313QoBWhA== - X-Server-Name: traffic_ops_golang/ - Date: Tue, 25 Feb 2020 14:37:55 GMT - Content-Length: 90 - - { "response": - { - "status": "OK", - "server": "trafficvault.infra.ciab.test:8087" - } - } diff --git a/docs/source/api/v3/cdns_name_snapshot.rst b/docs/source/api/v3/cdns_name_snapshot.rst index 9b3cbd6abd..e726d01701 100644 --- a/docs/source/api/v3/cdns_name_snapshot.rst +++ b/docs/source/api/v3/cdns_name_snapshot.rst @@ -373,7 +373,7 @@ Response Structure "dnssec.enabled": "false", "domain_name": "mycdn.ciab.test", "federationmapping.polling.interval": "60000", - "federationmapping.polling.url": "https://${toHostname}/api/2.0/federations/all", + "federationmapping.polling.url": "https://${toHostname}/api/3.0/federations/all", "geolocation.polling.interval": "86400000", "geolocation.polling.url": "https://trafficops.infra.ciab.test:443/GeoLite2-City.mmdb.gz", "keystore.maintenance.interval": "300", diff --git a/docs/source/api/v3/cdns_name_snapshot_new.rst b/docs/source/api/v3/cdns_name_snapshot_new.rst index 152e5b78c4..33da88af5e 100644 --- a/docs/source/api/v3/cdns_name_snapshot_new.rst +++ b/docs/source/api/v3/cdns_name_snapshot_new.rst @@ -375,7 +375,7 @@ Response Structure "dnssec.enabled": "false", "domain_name": "mycdn.ciab.test", "federationmapping.polling.interval": "60000", - "federationmapping.polling.url": "https://${toHostname}/api/2.0/federations/all", + "federationmapping.polling.url": "https://${toHostname}/api/3.0/federations/all", "geolocation.polling.interval": "86400000", "geolocation.polling.url": "https://trafficops.infra.ciab.test:443/GeoLite2-City.mmdb.gz", "keystore.maintenance.interval": "300", diff --git a/docs/source/api/v4/cdns_name_snapshot.rst b/docs/source/api/v4/cdns_name_snapshot.rst index f658106ed0..0309995139 100644 --- a/docs/source/api/v4/cdns_name_snapshot.rst +++ b/docs/source/api/v4/cdns_name_snapshot.rst @@ -370,7 +370,7 @@ Response Structure "dnssec.enabled": "false", "domain_name": "mycdn.ciab.test", "federationmapping.polling.interval": "60000", - "federationmapping.polling.url": "https://${toHostname}/api/2.0/federations/all", + "federationmapping.polling.url": "https://${toHostname}/api/4.0/federations/all", "geolocation.polling.interval": "86400000", "geolocation.polling.url": "https://static.infra.ciab.test:443/GeoLite2-City.mmdb.gz", "keystore.maintenance.interval": "300", diff --git a/docs/source/api/v4/cdns_name_snapshot_new.rst b/docs/source/api/v4/cdns_name_snapshot_new.rst index d6fc6e3947..911f1ee73d 100644 --- a/docs/source/api/v4/cdns_name_snapshot_new.rst +++ b/docs/source/api/v4/cdns_name_snapshot_new.rst @@ -370,7 +370,7 @@ Response Structure "dnssec.enabled": "false", "domain_name": "mycdn.ciab.test", "federationmapping.polling.interval": "60000", - "federationmapping.polling.url": "https://${toHostname}/api/2.0/federations/all", + "federationmapping.polling.url": "https://${toHostname}/api/4.0/federations/all", "geolocation.polling.interval": "86400000", "geolocation.polling.url": "https://static.infra.ciab.test:443/GeoLite2-City.mmdb.gz", "keystore.maintenance.interval": "300", diff --git a/docs/source/development/documentation_guidelines.rst b/docs/source/development/documentation_guidelines.rst index 93d56833d6..05b9cd3de1 100644 --- a/docs/source/development/documentation_guidelines.rst +++ b/docs/source/development/documentation_guidelines.rst @@ -211,7 +211,7 @@ The "Response Example" must **always** exist. "TODO" is **not** an acceptable Re - The ``Content-Type`` header sent by :manpage:`curl(1)` (and possibly others) is always ``application/x-www-form-urlencoded`` regardless of the actual content (unless overridden). Virtually all payloads accepted by the API must be JSON, so this should be modified to reflect that when appropriate e.g. ``application/json``. - API output is often beautified by inserting line breaks and indentation, which will make the ``Content-Length`` header (if any) incorrect. Don't worry about fixing that - just try to leave the output as close as possible to what will actually be returned by leaving it the way it is. -File names should reflect the request path of the endpoint, e.g. a file for an endpoint of the Traffic Ops API ``/api/2.0/foo/{{fooID}}/bar/{{barID}}`` should be named ``foo_fooID_bar_barID.rst``. Similarly, reference labels linking to the document title for API route pages should follow the convention: ``-api-`` in all lowercase where ```` is an abbreviated Traffic Control component name e.g. ``to`` and ```` is the request path e.g. ``foo_bar``. So a label for an endpoint of the Traffic Ops API at ``/api/2.0/foo_bar/{{ID}}`` should be ``to-api-foo_bar-id``. +File names should reflect the request path of the endpoint, e.g. a file for an endpoint of the Traffic Ops API ``/api/4.0/foo/{{fooID}}/bar/{{barID}}`` should be named ``foo_fooID_bar_barID.rst``. Similarly, reference labels linking to the document title for API route pages should follow the convention: ``-api-`` in all lowercase where ```` is an abbreviated Traffic Control component name e.g. ``to`` and ```` is the request path e.g. ``foo_bar``. So a label for an endpoint of the Traffic Ops API at ``/api/4.0/foo_bar/{{ID}}`` should be ``to-api-foo_bar-id``. Extension --------- diff --git a/docs/source/development/traffic_ops.rst b/docs/source/development/traffic_ops.rst index 51174f8076..eefc63c8c2 100644 --- a/docs/source/development/traffic_ops.rst +++ b/docs/source/development/traffic_ops.rst @@ -167,8 +167,6 @@ Traffic Ops Project Tree Overview - tocookie/ - Defines the method of generating the ``mojolicious`` cookie used by Traffic Ops for authentication - vendor/ - contains "vendored" Go packages from third party sources - - v1-client - The official Traffic Ops Go client package for working with the version 1 :ref:`to-api`. - - v2-client - The official Traffic Ops Go client package for working with the version 2 :ref:`to-api`. - v3-client - The official Traffic Ops Go client package for working with the version 3 :ref:`to-api`. - v4-client - The official Traffic Ops Go client package for working with the version 4 :ref:`to-api`. - vendor/ - contains "vendored" Go packages from third party sources