diff --git a/CHANGELOG.md b/CHANGELOG.md index 87ef292d53..de7f94c732 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -59,6 +59,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/). - [#7600](https://github.com/apache/trafficcontrol/pull/7600) *t3c* changed default go-direct command line arg to be old to avoid unexpected config changes upon upgrade. ### Fixed +- [#6318](https://github.com/apache/trafficcontrol/issues/6318) *Docs* Included docs for POST, PUT, DELETE (v3,v4,v5) for statuses and statuses{id} - [#7561](https://github.com/apache/trafficcontrol/pull/7561) *Traffic Ops* *Traffic Ops* Fixed `ASN` V5 apis to respond with `RFC3339` date/time Format. - [#7598](https://github.com/apache/trafficcontrol/pull/7598) *Traffic Ops* Fixes Server Capability V5 Type Name Minor version - [#7570](https://github.com/apache/trafficcontrol/pull/7570) *Traffic Ops* Fixes `deliveryservice_request_comments` v5 apis to respond with `RFC3339` date/time Format. diff --git a/docs/source/api/v3/statuses.rst b/docs/source/api/v3/statuses.rst index 4b5af05958..7b298c61ec 100644 --- a/docs/source/api/v3/statuses.rst +++ b/docs/source/api/v3/statuses.rst @@ -94,3 +94,64 @@ Response Structure "name": "REPORTED" } ]} + +``POST`` +======== +Creates a Server :term:`Status`. + +:Auth. Required: Yes +:Roles Required: None +:Permissions Required: STATUS:CREATE, STATUS:READ +:Response Type: Array + +Request Structure +----------------- +:description: Create a :term:`Status` with this description +:name: Create a :term:`Status` with this name + +.. code-block:: http + :caption: Request Example + + POST /api/3.0/statuses HTTP/1.1 + Host: trafficops.infra.ciab.test + User-Agent: curl/7.47.0 + Accept: */* + Cookie: mojolicious=... + + { "description": "test", "name": "example" } + +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=Wed, 21 Jun 2023 19:25:41 GMT; Max-Age=3600; HttpOnly + Whole-Content-Sha512: 49FsWlQoEywA+MwYHFXcYmnLokUI4CWeDJLh8BGRB8V4ju9DckzvUUkFNGa7oXvDgEBpsxI4HoPuk8TCluvLTw== + X-Server-Name: traffic_ops_golang/ + Date: Wed, 21 Jun 2023 18:25:41 GMT + Content-Length: 78 + + { "alerts": [ + { + "text": "status was created.", + "level": "success" + } + ],"response": [ + { + "description": "test", + "id": 31, + "lastUpdated": "2023-06-21 12:21:52-06", + "name": "example" + } + ]} diff --git a/docs/source/api/v3/statuses_id.rst b/docs/source/api/v3/statuses_id.rst new file mode 100644 index 0000000000..b142a47335 --- /dev/null +++ b/docs/source/api/v3/statuses_id.rst @@ -0,0 +1,216 @@ +.. +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. + +.. _to-api-v3-statuses-id: + +******************* +``statuses/{{ID}}`` +******************* + +``GET`` +======= +Retrieves a list of all server :term:`Statuses`. + +:Auth. Required: Yes +:Roles Required: None +:Permissions Required: STATUS:READ +: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/3.0/statuses/3 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" + } + ]} + +``PUT`` +======= +Updates a :term:`Status`. + +:Auth. Required: Yes +:Roles Required: "admin" or "operations" +:Permissions Required: STATUS:UPDATE, STATUS:READ +:Response Type: Array + +Request Structure +----------------- +:description: The description of the updated :term:`Status` +:name: The name of the updated :term:`Status` + +.. code-block:: http + :caption: Request Example + + PUT /api/3.0/statuses/29 HTTP/1.1 + Host: trafficops.infra.ciab.test + User-Agent: curl/8.1.2 + Accept: */* + Cookie: mojolicious=... + + { "description": "test", "name": "example" } + +Response Structure +------------------ +:description: A short description of the status +:id: The integral, unique identifier of the desired :abbr:`Status`-to-:term:`Cache Group` association +:lastUpdated: The time and date this server entry was last updated 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=Tue, 20 Jun 2023 23:00:16 GMT; Max-Age=3600; HttpOnly + Whole-Content-Sha512: FuS3TkVosxHtpxRGMJ2on+WnFdYTNSPjxz/Gh1iT4UCJ2/P0twUbAGQ3tTx9EfGiAzg9CNQiVUFGnYjJZ6NCpg== + X-Server-Name: traffic_ops_golang/ + Date: Tue, 20 Feb 2023 21:51:55 GMT + Content-Length: 46 + + { + "alerts": [ + { + "text": "status was updated.", + "level": "success" + } + ], + "response": { + "description": "test", + "id": 29, + "lastUpdated": "2023-06-20 16:05:16-06" + "name": "example" + } + } + +``DELETE`` +========== +Deletes a :term:`Status`. + +:Auth. Required: Yes +:Roles Required: "admin" or "operations" +:Permissions Required: STATUS:DELETE, STATUS:READ +:Response Type: Object + +Request Structure +----------------- +.. table:: Request Path Parameters + + +------+----------+---------------------------------------------------------------------------------------------+ + | Name | Required | Description | + +======+==========+=============================================================================================+ + | id | yes | The integral, unique identifier of the desired :abbr:`Status`-to-:term:`Server` association | + +------+----------+---------------------------------------------------------------------------------------------+ + +.. code-block:: http + :caption: Request Example + + DELETE /api/3.0/statuses/18 HTTP/1.1 + User-Agent: curl/8.1.2 + 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=Thu, 15 Jun 2023 22:37:37 GMT; Max-Age=3600; HttpOnly + Whole-Content-Sha512: T8wtKKwyOKKVwDwoNCNvETllsByDiEe4CrpeS7Zdox+rXMgPb3FBlKmmgu4CpxbWdhpiODKqKn+gsSq5K4yvIQ== + X-Server-Name: traffic_ops_golang/ + Date: Thu, 15 Jun 2023 21:41:18 GMT + Content-Length: 62 + + { + "alerts": [ + { + "text": "status was deleted.", + "level": "success" + } + ] + } diff --git a/docs/source/api/v4/statuses.rst b/docs/source/api/v4/statuses.rst index fb3d8207e3..9ce9889851 100644 --- a/docs/source/api/v4/statuses.rst +++ b/docs/source/api/v4/statuses.rst @@ -97,7 +97,7 @@ Response Structure ]} ``POST`` -========== +======== Creates a Server :term:`Status`. :Auth. Required: Yes diff --git a/docs/source/api/v4/statuses_id.rst b/docs/source/api/v4/statuses_id.rst index 28d6d2d3bb..b91e548911 100644 --- a/docs/source/api/v4/statuses_id.rst +++ b/docs/source/api/v4/statuses_id.rst @@ -15,9 +15,9 @@ .. _to-api-v4-statuses-id: -********************* +******************* ``statuses/{{ID}}`` -********************* +******************* ``GET`` ======= @@ -113,7 +113,7 @@ Request Structure .. code-block:: http :caption: Request Example - POST /api/4.0/statuses/3 HTTP/1.1 + PUT /api/4.0/statuses/3 HTTP/1.1 Host: trafficops.infra.ciab.test User-Agent: curl/7.47.0 Accept: */* @@ -156,3 +156,60 @@ Response Structure "lastUpdated": "2018-12-10 19:11:17+00", } ]} + +``DELETE`` +========== +Deletes a :term:`Status`. + +:Auth. Required: Yes +:Roles Required: "admin" or "operations" +:Permissions Required: STATUS:DELETE, STATUS:READ +:Response Type: Object + +Request Structure +----------------- +.. table:: Request Path Parameters + + +------+----------+---------------------------------------------------------------------------------------------+ + | Name | Required | Description | + +======+==========+=============================================================================================+ + | id | yes | The integral, unique identifier of the desired :abbr:`Status`-to-:term:`Server` association | + +------+----------+---------------------------------------------------------------------------------------------+ + +.. code-block:: http + :caption: Request Example + + DELETE /api/4.0/statuses/18 HTTP/1.1 + User-Agent: curl/8.1.2 + 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=Thu, 15 Jun 2023 22:37:37 GMT; Max-Age=3600; HttpOnly + Whole-Content-Sha512: T8wtKKwyOKKVwDwoNCNvETllsByDiEe4CrpeS7Zdox+rXMgPb3FBlKmmgu4CpxbWdhpiODKqKn+gsSq5K4yvIQ== + X-Server-Name: traffic_ops_golang/ + Date: Thu, 15 Jun 2023 21:41:18 GMT + Content-Length: 62 + + { + "alerts": [ + { + "text": "status was deleted.", + "level": "success" + } + ] + } diff --git a/docs/source/api/v5/statuses.rst b/docs/source/api/v5/statuses.rst index 3ccf081e72..73a64ca762 100644 --- a/docs/source/api/v5/statuses.rst +++ b/docs/source/api/v5/statuses.rst @@ -97,7 +97,7 @@ Response Structure ]} ``POST`` -========== +======== Creates a Server :term:`Status`. :Auth. Required: Yes diff --git a/docs/source/api/v5/statuses_id.rst b/docs/source/api/v5/statuses_id.rst index 159bd43bca..1ecb83a0fd 100644 --- a/docs/source/api/v5/statuses_id.rst +++ b/docs/source/api/v5/statuses_id.rst @@ -15,9 +15,9 @@ .. _to-api-statuses-id: -********************* +******************* ``statuses/{{ID}}`` -********************* +******************* ``GET`` ======= @@ -113,7 +113,7 @@ Request Structure .. code-block:: http :caption: Request Example - POST /api/5.0/statuses/3 HTTP/1.1 + PUT /api/5.0/statuses/3 HTTP/1.1 Host: trafficops.infra.ciab.test User-Agent: curl/7.47.0 Accept: */* @@ -156,3 +156,60 @@ Response Structure "lastUpdated": "2018-12-10 19:11:17+00", } ]} + +``DELETE`` +========== +Deletes a :term:`Status`. + +:Auth. Required: Yes +:Roles Required: "admin" or "operations" +:Permissions Required: STATUS:DELETE, STATUS:READ +:Response Type: Object + +Request Structure +----------------- +.. table:: Request Path Parameters + + +------+----------+---------------------------------------------------------------------------------------------+ + | Name | Required | Description | + +======+==========+=============================================================================================+ + | id | yes | The integral, unique identifier of the desired :abbr:`Status`-to-:term:`Server` association | + +------+----------+---------------------------------------------------------------------------------------------+ + +.. code-block:: http + :caption: Request Example + + DELETE /api/5.0/statuses/18 HTTP/1.1 + User-Agent: curl/8.1.2 + 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=Thu, 15 Jun 2023 22:37:37 GMT; Max-Age=3600; HttpOnly + Whole-Content-Sha512: T8wtKKwyOKKVwDwoNCNvETllsByDiEe4CrpeS7Zdox+rXMgPb3FBlKmmgu4CpxbWdhpiODKqKn+gsSq5K4yvIQ== + X-Server-Name: traffic_ops_golang/ + Date: Thu, 15 Jun 2023 21:41:18 GMT + Content-Length: 62 + + { + "alerts": [ + { + "text": "status was deleted.", + "level": "success" + } + ] + }