From 863e7e9a0fe73225f0dd3ad7e7f3f16160f9f198 Mon Sep 17 00:00:00 2001 From: heneriknguyen Date: Thu, 22 Jun 2023 10:52:59 -0600 Subject: [PATCH 1/6] Included docs for POST,PUT,DELETE for v3,v4,v5 of statuses and statusesID --- docs/source/api/v3/statuses.rst | 173 +++++++++++++++++++++++++++++ docs/source/api/v4/statuses.rst | 112 +++++++++++++++++++ docs/source/api/v4/statuses_id.rst | 59 ++++++++++ docs/source/api/v5/statuses.rst | 112 +++++++++++++++++++ docs/source/api/v5/statuses_id.rst | 57 ++++++++++ 5 files changed, 513 insertions(+) diff --git a/docs/source/api/v3/statuses.rst b/docs/source/api/v3/statuses.rst index 4b5af05958..5c748c34bd 100644 --- a/docs/source/api/v3/statuses.rst +++ b/docs/source/api/v3/statuses.rst @@ -94,3 +94,176 @@ 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" + } + ]} + +``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: ``undefined`` + +Request Structure +----------------- + +.. 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" + } + ] + } \ No newline at end of file diff --git a/docs/source/api/v4/statuses.rst b/docs/source/api/v4/statuses.rst index fb3d8207e3..01d90063d6 100644 --- a/docs/source/api/v4/statuses.rst +++ b/docs/source/api/v4/statuses.rst @@ -156,3 +156,115 @@ Response Structure "lastUpdated": "2018-12-10 19:11:17+00", } ]} + +``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/4.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: ``undefined`` + +Request Structure +----------------- + +.. 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/v4/statuses_id.rst b/docs/source/api/v4/statuses_id.rst index 28d6d2d3bb..cfc4d44af6 100644 --- a/docs/source/api/v4/statuses_id.rst +++ b/docs/source/api/v4/statuses_id.rst @@ -156,3 +156,62 @@ 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: ``undefined`` + +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..7bf7e02681 100644 --- a/docs/source/api/v5/statuses.rst +++ b/docs/source/api/v5/statuses.rst @@ -156,3 +156,115 @@ Response Structure "lastUpdated": "2018-12-10 19:11:17+00", } ]} + +``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/5.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: ``undefined`` + +Request Structure +----------------- + +.. 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" + } + ] + } diff --git a/docs/source/api/v5/statuses_id.rst b/docs/source/api/v5/statuses_id.rst index 159bd43bca..5fc178c7e4 100644 --- a/docs/source/api/v5/statuses_id.rst +++ b/docs/source/api/v5/statuses_id.rst @@ -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: ``undefined`` + +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" + } + ] + } From 6cb45bac1ff827d231ed2063a9484c9256e5859a Mon Sep 17 00:00:00 2001 From: heneriknguyen Date: Thu, 22 Jun 2023 11:25:12 -0600 Subject: [PATCH 2/6] Added CHANGELOG description for changes made --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e578712b8..ec041a14ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,6 +57,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/). - [#7469](https://github.com/apache/trafficcontrol/pull/7469) *Traffic Ops* Changed logic to not report empty or missing cookies into TO error.log. ### Fixed +- [#6318](https://github.com/apache/trafficcontrol/issues/6318) *Docs* Included docs for POST, PUT, DELETE (v3,v4,v5) for statuses and statuses{id} - [#7312](https://github.com/apache/trafficcontrol/issues/7312) *Docs* Changing docs for CDN locks for DELETE response structure v4 and v5. - [#7572](https://github.com/apache/trafficcontrol/pull/7572) *Traffic Ops* Fixes Delivery Service Requests V5 apis docs with RFC3339 date/time Format - [#7539](https://github.com/apache/trafficcontrol/pull/7539) *Traffic Monitor* Use stats_over_http timestamp to calculate bandwidth for TM's health. From c43e427ef708b28bc3753d588f5a2e710b70a98d Mon Sep 17 00:00:00 2001 From: heneriknguyen Date: Wed, 28 Jun 2023 09:59:47 -0600 Subject: [PATCH 3/6] Fixed docs structure for v4 and v5. Also added statuses_id for v3 and fixed statuses v3 doc structure. --- docs/source/api/v3/statuses.rst | 112 --------------- docs/source/api/v3/statuses_id.rst | 210 +++++++++++++++++++++++++++++ docs/source/api/v4/statuses.rst | 112 --------------- docs/source/api/v4/statuses_id.rst | 2 +- docs/source/api/v5/statuses.rst | 111 --------------- docs/source/api/v5/statuses_id.rst | 2 +- 6 files changed, 212 insertions(+), 337 deletions(-) create mode 100644 docs/source/api/v3/statuses_id.rst diff --git a/docs/source/api/v3/statuses.rst b/docs/source/api/v3/statuses.rst index 5c748c34bd..083d4a7382 100644 --- a/docs/source/api/v3/statuses.rst +++ b/docs/source/api/v3/statuses.rst @@ -155,115 +155,3 @@ Response Structure "name": "example" } ]} - -``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: ``undefined`` - -Request Structure ------------------ - -.. 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" - } - ] - } \ No newline at end of file diff --git a/docs/source/api/v3/statuses_id.rst b/docs/source/api/v3/statuses_id.rst new file mode 100644 index 0000000000..26c28bfab1 --- /dev/null +++ b/docs/source/api/v3/statuses_id.rst @@ -0,0 +1,210 @@ +.. +.. +.. 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: ``undefined`` + +Request Structure +----------------- + +.. 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" + } + ] + } \ No newline at end of file diff --git a/docs/source/api/v4/statuses.rst b/docs/source/api/v4/statuses.rst index 01d90063d6..fb3d8207e3 100644 --- a/docs/source/api/v4/statuses.rst +++ b/docs/source/api/v4/statuses.rst @@ -156,115 +156,3 @@ Response Structure "lastUpdated": "2018-12-10 19:11:17+00", } ]} - -``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/4.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: ``undefined`` - -Request Structure ------------------ - -.. 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/v4/statuses_id.rst b/docs/source/api/v4/statuses_id.rst index f372863db6..d86b4d9d71 100644 --- a/docs/source/api/v4/statuses_id.rst +++ b/docs/source/api/v4/statuses_id.rst @@ -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: */* diff --git a/docs/source/api/v5/statuses.rst b/docs/source/api/v5/statuses.rst index 7bf7e02681..5d3d5e2aed 100644 --- a/docs/source/api/v5/statuses.rst +++ b/docs/source/api/v5/statuses.rst @@ -157,114 +157,3 @@ Response Structure } ]} -``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/5.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: ``undefined`` - -Request Structure ------------------ - -.. 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" - } - ] - } diff --git a/docs/source/api/v5/statuses_id.rst b/docs/source/api/v5/statuses_id.rst index 3dd21df321..22430ad4e7 100644 --- a/docs/source/api/v5/statuses_id.rst +++ b/docs/source/api/v5/statuses_id.rst @@ -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: */* From 210bf4bbd6abd481f01d0e823256bf34942b9b48 Mon Sep 17 00:00:00 2001 From: heneriknguyen Date: Wed, 28 Jun 2023 10:42:54 -0600 Subject: [PATCH 4/6] Fixed response type for DELETE (v3,v4,v5) in statuses_id, and included request structure table for DELETE v3 in statuses_id --- docs/source/api/v3/statuses_id.rst | 9 ++++++++- docs/source/api/v4/statuses_id.rst | 2 +- docs/source/api/v5/statuses_id.rst | 2 +- 3 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/source/api/v3/statuses_id.rst b/docs/source/api/v3/statuses_id.rst index 26c28bfab1..165016f099 100644 --- a/docs/source/api/v3/statuses_id.rst +++ b/docs/source/api/v3/statuses_id.rst @@ -166,10 +166,17 @@ Deletes a :term:`Status`. :Auth. Required: Yes :Roles Required: "admin" or "operations" :Permissions Required: STATUS:DELETE, STATUS:READ -:Response Type: ``undefined`` +: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 diff --git a/docs/source/api/v4/statuses_id.rst b/docs/source/api/v4/statuses_id.rst index d86b4d9d71..a986863046 100644 --- a/docs/source/api/v4/statuses_id.rst +++ b/docs/source/api/v4/statuses_id.rst @@ -164,7 +164,7 @@ Deletes a :term:`Status`. :Auth. Required: Yes :Roles Required: "admin" or "operations" :Permissions Required: STATUS:DELETE, STATUS:READ -:Response Type: ``undefined`` +:Response Type: Object Request Structure ----------------- diff --git a/docs/source/api/v5/statuses_id.rst b/docs/source/api/v5/statuses_id.rst index 22430ad4e7..13c96c4f08 100644 --- a/docs/source/api/v5/statuses_id.rst +++ b/docs/source/api/v5/statuses_id.rst @@ -164,7 +164,7 @@ Deletes a :term:`Status`. :Auth. Required: Yes :Roles Required: "admin" or "operations" :Permissions Required: STATUS:DELETE, STATUS:READ -:Response Type: ``undefined`` +:Response Type: Object Request Structure ----------------- From 5b454b79ed9beba4210cccdf032162ff23aa94aa Mon Sep 17 00:00:00 2001 From: heneriknguyen Date: Thu, 29 Jun 2023 11:15:28 -0600 Subject: [PATCH 5/6] Delete extra new line in statuses v5 --- docs/source/api/v5/statuses.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/api/v5/statuses.rst b/docs/source/api/v5/statuses.rst index 5d3d5e2aed..25c56e6b44 100644 --- a/docs/source/api/v5/statuses.rst +++ b/docs/source/api/v5/statuses.rst @@ -155,5 +155,4 @@ Response Structure "id": 3, "lastUpdated": "2018-12-10 19:11:17+00", } - ]} - + ]} \ No newline at end of file From a263376ed8b22d642b71bad96939f8f217d29a07 Mon Sep 17 00:00:00 2001 From: heneriknguyen Date: Thu, 29 Jun 2023 12:53:54 -0600 Subject: [PATCH 6/6] Fixed white space and formatting of statuses and statuses_id (v3,v4,v5) --- docs/source/api/v3/statuses.rst | 2 +- docs/source/api/v3/statuses_id.rst | 7 +++---- docs/source/api/v4/statuses.rst | 2 +- docs/source/api/v4/statuses_id.rst | 6 ++---- docs/source/api/v5/statuses.rst | 4 ++-- docs/source/api/v5/statuses_id.rst | 4 ++-- 6 files changed, 11 insertions(+), 14 deletions(-) diff --git a/docs/source/api/v3/statuses.rst b/docs/source/api/v3/statuses.rst index 083d4a7382..7b298c61ec 100644 --- a/docs/source/api/v3/statuses.rst +++ b/docs/source/api/v3/statuses.rst @@ -96,7 +96,7 @@ Response Structure ]} ``POST`` -========== +======== Creates a Server :term:`Status`. :Auth. Required: Yes diff --git a/docs/source/api/v3/statuses_id.rst b/docs/source/api/v3/statuses_id.rst index 165016f099..b142a47335 100644 --- a/docs/source/api/v3/statuses_id.rst +++ b/docs/source/api/v3/statuses_id.rst @@ -13,12 +13,11 @@ .. limitations under the License. .. - .. _to-api-v3-statuses-id: -********************* +******************* ``statuses/{{ID}}`` -********************* +******************* ``GET`` ======= @@ -214,4 +213,4 @@ Response Structure "level": "success" } ] - } \ No newline at end of file + } 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 a986863046..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`` ======= @@ -213,5 +213,3 @@ Response Structure } ] } - - diff --git a/docs/source/api/v5/statuses.rst b/docs/source/api/v5/statuses.rst index 25c56e6b44..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 @@ -155,4 +155,4 @@ Response Structure "id": 3, "lastUpdated": "2018-12-10 19:11:17+00", } - ]} \ No newline at end of file + ]} diff --git a/docs/source/api/v5/statuses_id.rst b/docs/source/api/v5/statuses_id.rst index 13c96c4f08..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`` =======