cdns/{{name}}/federations and cdns/{{name}}/federations/{{ID}} us…

…e RFC3339 timestamps (#7806) * Fix 304 Not Modified responses written with body instead of LastModified header * add V5 structures * Update GET handlers to serve v5 structures to v5-requesting clients * Update POST handler to support v5 * Update PUT handler to support v5 * Update DELETE handler to support v5 * Fix inaccuracies in old API version docs for cdnfederations * Fix RFC roles not using grave accents * Update client and client tests * Update CHANGELOG * Update TOTest * Fix dependency_license pattern * Update enroller * Fix comparison using pointers instead of values in tests * Fix improperly cased query string parameter * fix the selectMaxLastUpdatedQuery - and actually use it for that purpose * Implement IUS/ETag * Revert embedding queries from files * Add TTL minimum * Fix testing data to fit new restriction
apache · Sep 20, 2023 · de900da · de900da
1 parent 0068dd8
commit de900da
Show file tree

Hide file tree

Showing 35 changed files with 985 additions and 239 deletions.
diff --git a/.dependency_license b/.dependency_license
@@ -55,6 +55,7 @@ traffic_router/core/src/test/resources/api/.*/steering*, Apache-2.0
 traffic_router/core/src/test/resources/api/.*/federations/all, Apache-2.0
 BUILD_NUMBER$, Apache-2.0
 \.jks, Apache-2.0 # Java Key Store
+traffic_ops/traffic_ops_golang/.*\.sql, Apache-2.0 # embedded sql queries - can't have comment blocks due to github.com/jmoiron/sqlx library limitations
 
 # Images, created for this project or used under an Apache license.
 ^misc/logos/ATC-PNG\.png, Apache-2.0

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 ## [unreleased]
 - [#7665](https://github.com/apache/trafficcontrol/pull/7665) *Automation* Changes to Ansible role dataset_loader to add ATS 9 support
 - [#7802](https://github.com/apache/trafficcontrol/pull/7802) *Traffic Control Health Client* Fixed ReadMe.md typos and duplicates.
+- [#7806](https://github.com/apache/trafficcontrol/pull/7806) *Traffic Ops* `cdns/{{name}}/federations` and `cdns/{{name}}/federations/{{ID}}` use RFC3339 timestamps in APIv5
 ### Added
 - [#7672](https://github.com/apache/trafficcontrol/pull/7672) *Traffic Control Health Client* Added peer monitor flag while using `strategies.yaml`.
 - [#7609](https://github.com/apache/trafficcontrol/pull/7609) *Traffic Portal* Added Scope Query Param to SSO login.

diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
@@ -89,7 +89,7 @@ The following, reserved properties of ``summary`` are guaranteed to always have
 
 Traffic Ops's Custom Date/Time Format
 -------------------------------------
-Traffic Ops will often return responses from its API that include dates. As of the time of this writing, the vast majority of those dates are written in a non-:rfc:3339 format (this is tracked by :issue:`5911`). This is most commonly the case in the ``last_updated`` properties of objects returned as JSON-encoded documents. The format used is :samp:`{YYYY}-{MM}-{DD} {hh}:{mm}:{ss}±{ZZ}`, where ``YYYY`` is the 4-digit year, ``MM`` is the two-digit (zero padded) month, ``DD`` is the two-digit (zero padded) day of the month, ``hh`` is the two-digit (zero padded) hour of the day, ``mm`` is the two-digit (zero padded) minute of the hour, ``ss`` is the two-digit (zero padded) second of the minute, and ``ZZ`` is the two-digit (zero padded) timezone offset in hours of the date/time's local timezone from UTC (the offset can be positive or negative as indicated by a ``+`` or a ``-`` directly before it, where the sample has a ``±``).
+Traffic Ops will often return responses from its API that include dates. As of the time of this writing, the vast majority of those dates are written in a non-:RFC:`3339` format (this is tracked by :issue:`5911`). This is most commonly the case in the ``last_updated`` properties of objects returned as JSON-encoded documents. The format used is :samp:`{YYYY}-{MM}-{DD} {hh}:{mm}:{ss}±{ZZ}`, where ``YYYY`` is the 4-digit year, ``MM`` is the two-digit (zero padded) month, ``DD`` is the two-digit (zero padded) day of the month, ``hh`` is the two-digit (zero padded) hour of the day, ``mm`` is the two-digit (zero padded) minute of the hour, ``ss`` is the two-digit (zero padded) second of the minute, and ``ZZ`` is the two-digit (zero padded) timezone offset in hours of the date/time's local timezone from UTC (the offset can be positive or negative as indicated by a ``+`` or a ``-`` directly before it, where the sample has a ``±``).
 
 .. note:: In practice, all Traffic Ops API responses use the UTC timezone (offset ``+00``), but do note that this custom format is not capable of representing all timezones.
 

diff --git a/docs/source/api/v3/cdns_name_federations.rst b/docs/source/api/v3/cdns_name_federations.rst
@@ -42,7 +42,9 @@ Request Structure
 	+-----------+---------------------------------------------------------------------------------------------------------------+
 	| Name      | Description                                                                                                   |
 	+===========+===============================================================================================================+
-	| id        | Return only the federation that has this id                                                                   |
+	| id        | Return only the :term:`Federation` that has this ID                                                           |
+	+-----------+---------------------------------------------------------------------------------------------------------------+
+	| cname     | Return only those :term:`Federations` that have this CNAME                                                    |
 	+-----------+---------------------------------------------------------------------------------------------------------------+
 	| orderby   | Choose the ordering of the results - must be the name of one of the fields of the objects in the ``response`` |
 	|           | array                                                                                                         |
@@ -75,10 +77,7 @@ Response Structure
 	: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.
-
+:description: A human-readable description of the :term:`Federation`. This can be ``null`` as well as an empty string.
 :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
 
@@ -158,10 +157,7 @@ Response Structure
 ------------------
 :id:          The integral, unique identifier of the :term:`Federation`
 :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
-
+:description: The description of the :term:`Federation`
 :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
 

diff --git a/docs/source/api/v4/cdns_name_federations.rst b/docs/source/api/v4/cdns_name_federations.rst
@@ -43,7 +43,9 @@ Request Structure
 	+-----------+---------------------------------------------------------------------------------------------------------------+
 	| Name      | Description                                                                                                   |
 	+===========+===============================================================================================================+
-	| id        | Return only the federation that has this id                                                                   |
+	| id        | Return only the :term:`Federation` that has this ID                                                           |
+	+-----------+---------------------------------------------------------------------------------------------------------------+
+	| cname     | Return only those :term:`Federations` that have this CNAME                                                    |
 	+-----------+---------------------------------------------------------------------------------------------------------------+
 	| orderby   | Choose the ordering of the results - must be the name of one of the fields of the objects in the ``response`` |
 	|           | array                                                                                                         |
@@ -76,10 +78,7 @@ Response Structure
 	: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.
-
+:description: A human-readable description of the :term:`Federation`. This can be ``null`` as well as an empty string.
 :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
 
@@ -160,10 +159,7 @@ Response Structure
 ------------------
 :id:          The intergral, unique identifier of the :term:`Federation`
 :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
-
+:description: The description of the :term:`Federation`
 :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
 

diff --git a/docs/source/api/v4/deliveryservices.rst b/docs/source/api/v4/deliveryservices.rst
@@ -116,7 +116,7 @@ Response Structure
 :innerHeaderRewrite:        A set of :ref:`ds-inner-header-rw-rules`
 :ipv6RoutingEnabled:        A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service`
 :lastHeaderRewrite:         A set of :ref:`ds-last-header-rw-rules`
-:lastUpdated:               The date and time at which this :term:`Delivery Service` was last updated, in :rfc:3339 format
+:lastUpdated:               The date and time at which this :term:`Delivery Service` was last updated, in :RFC:`3339` format
 
 	.. versionchanged:: 4.0
 		Prior to API version 4.0, this property used :ref:`non-rfc-datetime`.
@@ -473,7 +473,7 @@ Response Structure
 :innerHeaderRewrite:        A set of :ref:`ds-inner-header-rw-rules`
 :ipv6RoutingEnabled:        A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service`
 :lastHeaderRewrite:         A set of :ref:`ds-last-header-rw-rules`
-:lastUpdated:               The date and time at which this :term:`Delivery Service` was last updated, in :rfc:3339 format
+:lastUpdated:               The date and time at which this :term:`Delivery Service` was last updated, in :RFC:`3339` format
 
 	.. versionchanged:: 4.0
 		Prior to API version 4.0, this property used :ref:`non-rfc-datetime`.

diff --git a/docs/source/api/v4/deliveryservices_id.rst b/docs/source/api/v4/deliveryservices_id.rst
@@ -223,7 +223,7 @@ Response Structure
 :innerHeaderRewrite:        A set of :ref:`ds-inner-header-rw-rules`
 :ipv6RoutingEnabled:        A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service`
 :lastHeaderRewrite:         A set of :ref:`ds-last-header-rw-rules`
-:lastUpdated:               The date and time at which this :term:`Delivery Service` was last updated, in :rfc:3339 format
+:lastUpdated:               The date and time at which this :term:`Delivery Service` was last updated, in :RFC:`3339` format
 
 	.. versionchanged:: 4.0
 		Prior to API version 4.0, this property used :ref:`non-rfc-datetime`.

diff --git a/docs/source/api/v4/deliveryservices_id_safe.rst b/docs/source/api/v4/deliveryservices_id_safe.rst
@@ -95,7 +95,7 @@ Response Structure
 :innerHeaderRewrite:        A set of :ref:`ds-inner-header-rw-rules`
 :ipv6RoutingEnabled:        A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service`
 :lastHeaderRewrite:         A set of :ref:`ds-last-header-rw-rules`
-:lastUpdated:               The date and time at which this :term:`Delivery Service` was last updated, in :rfc:3339 format
+:lastUpdated:               The date and time at which this :term:`Delivery Service` was last updated, in :RFC:`3339` format
 
 	.. versionchanged:: 4.0
 		Prior to API version 4.0, this property used :ref:`non-rfc-datetime`.

diff --git a/docs/source/api/v4/servers_id_deliveryservices.rst b/docs/source/api/v4/servers_id_deliveryservices.rst
@@ -103,7 +103,7 @@ Response Structure
 :innerHeaderRewrite:        A set of :ref:`ds-inner-header-rw-rules`
 :ipv6RoutingEnabled:        A boolean that defines the :ref:`ds-ipv6-routing` setting on this :term:`Delivery Service`
 :lastHeaderRewrite:         A set of :ref:`ds-last-header-rw-rules`
-:lastUpdated:               The date and time at which this :term:`Delivery Service` was last updated, in :rfc:3339 format
+:lastUpdated:               The date and time at which this :term:`Delivery Service` was last updated, in :RFC:`3339` format
 
 	.. versionchanged:: 4.0
 		Prior to API version 4.0, this property used :ref:`non-rfc-datetime`.