You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficcontrol.apache.org by rs...@apache.org on 2023/06/29 19:31:43 UTC
[trafficcontrol] branch master updated: Included docs for POST,PUT,DELETE for v3,v4,v5 of statuses and statusesID (#7588)
This is an automated email from the ASF dual-hosted git repository.
rshah pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git
The following commit(s) were added to refs/heads/master by this push:
new 5d2d866898 Included docs for POST,PUT,DELETE for v3,v4,v5 of statuses and statusesID (#7588)
5d2d866898 is described below
commit 5d2d86689897e347e6b21871e908a2205232bd7e
Author: heneriknguyen <77...@users.noreply.github.com>
AuthorDate: Thu Jun 29 13:31:36 2023 -0600
Included docs for POST,PUT,DELETE for v3,v4,v5 of statuses and statusesID (#7588)
* Included docs for POST,PUT,DELETE for v3,v4,v5 of statuses and statusesID
* Added CHANGELOG description for changes made
* Fixed docs structure for v4 and v5. Also added statuses_id for v3 and fixed statuses v3 doc structure.
* Fixed response type for DELETE (v3,v4,v5) in statuses_id, and included request structure table for DELETE v3 in statuses_id
* Delete extra new line in statuses v5
* Fixed white space and formatting of statuses and statuses_id (v3,v4,v5)
---
CHANGELOG.md | 1 +
docs/source/api/v3/statuses.rst | 61 ++++++++++++++++
docs/source/api/{v5 => v3}/statuses_id.rst | 108 ++++++++++++++++++++++-------
docs/source/api/v4/statuses.rst | 2 +-
docs/source/api/v4/statuses_id.rst | 63 ++++++++++++++++-
docs/source/api/v5/statuses.rst | 2 +-
docs/source/api/v5/statuses_id.rst | 63 ++++++++++++++++-
7 files changed, 267 insertions(+), 33 deletions(-)
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/v5/statuses_id.rst b/docs/source/api/v3/statuses_id.rst
similarity index 69%
copy from docs/source/api/v5/statuses_id.rst
copy to docs/source/api/v3/statuses_id.rst
index 159bd43bca..b142a47335 100644
--- a/docs/source/api/v5/statuses_id.rst
+++ b/docs/source/api/v3/statuses_id.rst
@@ -13,11 +13,11 @@
.. limitations under the License.
..
-.. _to-api-statuses-id:
+.. _to-api-v3-statuses-id:
-*********************
+*******************
``statuses/{{ID}}``
-*********************
+*******************
``GET``
=======
@@ -59,7 +59,7 @@ Request Structure
.. code-block:: http
:caption: Request Example
- GET /api/5.0/statuses/3 HTTP/1.1
+ GET /api/3.0/statuses/3 HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*
@@ -101,9 +101,9 @@ Response Structure
Updates a :term:`Status`.
:Auth. Required: Yes
-:Roles Required: None
+:Roles Required: "admin" or "operations"
:Permissions Required: STATUS:UPDATE, STATUS:READ
-:Response Type: Array
+:Response Type: Array
Request Structure
-----------------
@@ -113,9 +113,9 @@ Request Structure
.. code-block:: http
:caption: Request Example
- POST /api/5.0/statuses/3 HTTP/1.1
+ PUT /api/3.0/statuses/29 HTTP/1.1
Host: trafficops.infra.ciab.test
- User-Agent: curl/7.47.0
+ User-Agent: curl/8.1.2
Accept: */*
Cookie: mojolicious=...
@@ -124,8 +124,8 @@ Request Structure
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`
+: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
@@ -137,22 +137,80 @@ Response Structure
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==
+ 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: Mon, 10 Dec 2018 20:56:59 GMT
- Content-Length: 167
-
- { "alerts": [
- {
- "text": "status was created.",
- "level": "success"
- }
- ],"response": [
- {
+ 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"
- "id": 3,
- "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/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"
+ }
+ ]
+ }