You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@trafficcontrol.apache.org by GitBox <gi...@apache.org> on 2021/11/08 23:49:38 UTC

[GitHub] [trafficcontrol] ocket8888 opened a new pull request #6342: Add/update documentation for content invalidation jobs in TO API v4

ocket8888 opened a new pull request #6342:
URL: https://github.com/apache/trafficcontrol/pull/6342


   This PR makes updates to the documentation for Content Invalidation Jobs as they appear in the unstable TO API version 4.0, including the "Quick How-To" guide, the API documentation, adds an overview page and a glossary term, and links usages of the term to the glossary. This also adds a couple missing GoDoc comments, and changes the `InvalidationJobV4.String` behavior to output a representation without any control characters (previously contained a couple dozen tabs and about a half dozen newlines).
   
   <hr/>
   
   ## Which Traffic Control components are affected by this PR?
   <!-- Please delete all components from this list that are NOT affected by this PR.
   Feel free to add the name of a tool or script that is affected but not on the list.
   -->
   - Documentation
   - Traffic Control Cache Config (T3C, formerly ORT)
   - Traffic Control Health Client (tc-health-client)
   - Traffic Control Client <!-- Please specify which (Python, Go, or Java) -->
   - Traffic Monitor
   - Traffic Ops
   - Traffic Portal
   - Traffic Router
   - Traffic Stats
   - Grove
   - CDN in a Box
   - Automation <!-- Please specify which (GitHub Actions, Docker images, Ansible Roles, etc.) -->
   - unknown
   
   ## What is the best way to verify this PR?
   <!-- Please include here ALL the steps necessary to test your PR.
   If your PR has tests (and most should), provide the steps needed to run the tests.
   If not, please provide step-by-step instructions to test the PR manually and explain why your PR does not need tests. -->
   
   
   ## If this is a bugfix, which Traffic Control versions contained the bug?
   <!-- Delete this section if the PR is not a bugfix, or if the bug is only in the master branch.
   Examples:
   - 5.1.2
   - 5.1.3 (RC1)
    -->
   
   
   ## PR submission checklist
   - [x] This PR has tests <!-- If not, please delete this text and explain why this PR does not need tests. -->
   - [x] This PR has documentation <!-- If not, please delete this text and explain why this PR does not need documentation. -->
   - [x] This PR has a CHANGELOG.md entry <!-- A fix for a bug from an ATC release, an improvement, or a new feature should have a changelog entry. -->
   - [x] This PR **DOES NOT FIX A SERIOUS SECURITY VULNERABILITY** (see [the Apache Software Foundation's security guidelines](https://apache.org/security) for details)
   
   <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you 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.
   -->
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@trafficcontrol.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



[GitHub] [trafficcontrol] TaylorCFrey commented on a change in pull request #6342: Add/update documentation for content invalidation jobs in TO API v4

Posted by GitBox <gi...@apache.org>.
TaylorCFrey commented on a change in pull request #6342:
URL: https://github.com/apache/trafficcontrol/pull/6342#discussion_r747868380



##########
File path: docs/source/api/v2/jobs.rst
##########
@@ -108,9 +109,9 @@ Response Structure
 
 ``POST``
 ========
-Creates a new content invalidation job.
+Creates a new :term:`Content Invalidation Jobs`.

Review comment:
       Should be singular

##########
File path: docs/source/admin/traffic_portal/usingtrafficportal.rst
##########
@@ -645,21 +645,21 @@ Tools
 
 Invalidate Content
 ------------------
-Here, specific assets can be invalidated in all caches of a :term:`Delivery Service`, forcing content to be updated from the origin. Specifically, this *doesn't* mean that :term:`cache servers` will immediately remove items from their caches, but rather will fetch new copies whenever a request is made matching the 'Asset URL' regular expression. This behavior persists until the Invalidate Content Job's :abbr:`TTL (Time To Live)` expires.
+Here, specific assets can be invalidated in all caches of a :term:`Delivery Service`, forcing content to be updated from the origin. Specifically, this *doesn't* mean that :term:`cache servers` will immediately remove items from their caches, but rather will fetch new copies whenever a request is made matching the 'Asset URL' regular expression. This behavior persists until the :term:`Content Invalidate Content Job`'s :ref:`job-ttl` expires.
 
-.. Warning:: This method forces :term:`cache servers` to "re-validate" content, so in order to work properly the :term:`Origin` needs to support revalidation according to section 4.3.2 of :rfc:`7234`.
+.. warning:: This method forces :term:`cache servers` to "re-validate" content, so in order to work properly the :term:`Origin` needs to support revalidation according to section 4.3.2 of :rfc:`7234`.
 
 Each entry in the table on this page has the following fields:
 
-:term:`Delivery Service`: The :term:`Delivery Service` to which to apply this Invalidate Content Job

Review comment:
       Thanks for fixing the formatting for these fields here as well.

##########
File path: docs/source/api/v4/jobs.rst
##########
@@ -109,269 +108,236 @@ Response Structure
 
 ``POST``
 ========
-Creates a new content invalidation job.
+Creates a new :term:`Content Invalidation Jobs`.
 
-.. caution:: Creating a 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 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.
+.. 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]_
-:Permissions Required: JOB:CREATE, JOB:READ, DELIVERY-SERVICE:READ, DELIVERY-SERVICE:UPDATE
-:Response Type:  Object
+:Auth. Required:       Yes
+:Roles Required:       "operations" or "admin"\ [#tenancy]_
+:Permissions Required: JOB:CREATE, JOB:READ, DELIVERY-SERVICE:READ, DELIVERY-SERVICE:UPDATE\ [#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 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.
+:deliveryService:  The :ref:`job-ds`
+:invalidationType: The :ref:`job-invalidation-type`
+:regex:            The :ref:`job-regex`
+:startTime:        The :ref:`job-start-time`
+:ttl:              The :ref:`job-ttl`
 
 .. code-block:: http
 	:caption: Request Example
 
 	POST /api/4.0/jobs HTTP/1.1
-	Host: trafficops.infra.ciab.test
-	User-Agent: python-requests/2.20.1
+	User-Agent: python-requests/2.25.1
 	Accept-Encoding: gzip, deflate
 	Accept: */*
 	Connection: keep-alive
 	Cookie: mojolicious=...
-	Content-Length: 80
+	Transfer-Encoding: chunked
 	Content-Type: application/json
 
 	{
 		"deliveryService": "demo1",
-		"startTime": 1560893311219,
-		"regex": "/.*",
-		"ttl": "121m"
+		"invalidationType": "REFRESH",
+		"regex": "/.+",
+		"startTime": "2021-11-09T01:02:03Z",
+		"ttlHours": 72
 	}
 
+
 Response Structure
 ------------------
-:assetUrl:        A regular expression - matching URLs will be operated upon according to ``keyword``
-:createdBy:       The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which this job operates
-:id:              An integral, unique identifier for this job
-:keyword:         A keyword that represents the operation being performed by the job:
-
-	PURGE
-		This 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 job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime:  The date and time at which the job began, in a non-standard format
+:assetUrl:         The :ref:`job-asset-url`
+:createdBy:        The :ref:`job-created-by`
+:deliveryService:  The :ref:`job-ds`
+:id:               The :ref:`job-id`.
+:invalidationType: The :ref:`job-invalidation-type`
+:ttlHours:         The :ref:`job-ttl`
+:startTime:        The :ref:`job-start-time`
 
 .. 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/4.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==
+	Location: https://localhost:6443/api/4.0/jobs?id=1
+	Permissions-Policy: interest-cohort=()
+	Set-Cookie: mojolicious=...
+	Vary: Accept-Encoding
 	X-Server-Name: traffic_ops_golang/
-	Date: Tue, 18 Jun 2019 19:37:06 GMT
-	Content-Length: 238
+	Date: Mon, 08 Nov 2021 15:44:46 GMT
+	Content-Length: 265
 
 	{
 		"alerts": [
 			{
-				"text": "Invalidation Job creation was successful",
+				"text": "Invalidation (REFRESH) request created for http://origin.infra.ciab.test/.+, start:2021-11-09 01:02:03 +0000 UTC end 2021-11-12 01:02:03 +0000 UTC",
 				"level": "success"
 			}
 		],
 		"response": {
-			"assetUrl": "http://origin.infra.ciab.test/.*",
+			"id": 1,
+			"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"
+			"ttlHours": 72,
+			"invalidationType": "REFRESH",
+			"startTime": "2021-11-09T01:02:03Z"
 		}
 	}
 
 
+
 ``PUT``
 =======
-Replaces an existing content invalidation job with a new one provided in the request. This method of editing a content invalidation job does not prevent the requesting user from changing fields that normally only have one value. Use with care.
+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 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 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.
+.. 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]_
-:Permissions Required: JOB:UPDATE, DELIVERY-SERVICE:UPDATE, JOB:READ, DELIVERY-SERVICE:READ
-:Response Type:  Object
+:Auth. Required:       Yes
+:Roles Required:       "operations" or "admin"\ [#tenancy]_
+:Permissions Required: JOB:UPDATE, DELIVERY-SERVICE:UPDATE, JOB:READ, DELIVERY-SERVICE:READ\ [#tenancy]_
+:Response Type:        Object
 
 Request Structure
 -----------------
 .. table:: Query Parameters
 
-	+------+----------+--------------------------------------------------------------------------------+
-	| Name | Required | Description                                                                    |
-	+======+==========+================================================================================+
-	| id   | yes      | The integral, unique identifier of the 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 job\ [#readonly]_
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which this job operates\ [#readonly]_ - unlike POST_ request payloads, this cannot be an integral, unique identifier
-:id:              An integral, unique identifier for this job\ [#readonly]_
-:keyword:         A keyword that represents the operation being performed by the job. It can have any (string) value, but the only value with any meaning to Traffic Control is:
-
-	PURGE
-		This job will prevent caching of URLs matching the ``assetUrl`` until it is removed (or its Time to Live expires)
+	+------+----------+----------------------------------------------------------------------------------------+
+	| Name | Required | Description                                                                            |
+	+======+==========+========================================================================================+
+	| id   | yes      | The integral, unique identifier of the :term:`Content Invalidation Job` being modified |
+	+------+----------+----------------------------------------------------------------------------------------+
 
-:parameters: A string containing space-separated key/value pairs - delimited by colons (:kbd:`:`\ s) representing parameters associated with the job. In practice, any string can be passed as a 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.
+:assetUrl:         The :ref:`job-asset-url` - the scheme and authority parts of the regular expression cannot be changed
+:createdBy:        The :ref:`job-created-by`\ [#immutable]_
+:deliveryService:  The :ref:`job-ds`\ [#immutable]_
+:id:               The :ref:`job-id`\ [#immutable]_
+:invalidationType: The :ref:`job-invalidation-type`
+:ttlHours:         The :ref:`job-ttl`
+:startTime:        The :ref:`job-start-time`
 
 .. code-block:: http
 	:caption: Request Example
 
-	PUT /api/4.0/jobs?id=3 HTTP/1.1
-	Host: trafficops.infra.ciab.test
-	User-Agent: python-requests/2.20.1
+	PUT /api/4.0/jobs?id=1 HTTP/1.1
+	User-Agent: python-requests/2.25.1
 	Accept-Encoding: gzip, deflate
 	Accept: */*
 	Connection: keep-alive
 	Cookie: mojolicious=...
-	Content-Length: 188
-	Content-Type: application/json
+	Content-Length: 191
 
 	{
-		"assetUrl": "http://origin.infra.ciab.test/.*",
+		"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"
+		"id": 1,
+		"invalidationType": "REFETCH",
+		"startTime": "2021-11-09T01:02:03Z",
+		"ttlHours": 72
 	}
 
+
 Response Structure
 ------------------
-:assetUrl:        A regular expression - matching URLs will be operated upon according to ``keyword``
-:createdBy:       The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which this job operates
-:id:              An integral, unique identifier for this job
-:keyword:         A keyword that represents the operation being performed by the job:
-
-	PURGE
-		This 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 job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime:  The date and time at which the job began, in a non-standard format
+:assetUrl:         The :ref:`job-asset-url`
+:createdBy:        The :ref:`job-created-by`
+:deliveryService:  The :ref:`job-ds`
+:id:               The :ref:`job-id`.
+:invalidationType: The :ref:`job-invalidation-type`
+:ttlHours:         The :ref:`job-ttl`
+:startTime:        The :ref:`job-start-time`
 
 .. 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==
+	Permissions-Policy: interest-cohort=()
+	Set-Cookie: mojolicious=...
+	Vary: Accept-Encoding
 	X-Server-Name: traffic_ops_golang/
-	Date: Wed, 19 Jun 2019 13:38:59 GMT
-	Content-Length: 234
+	Date: Mon, 08 Nov 2021 16:43:35 GMT
+	Content-Length: 266
 
-	{ "alerts": [{
-		"text": "Content invalidation job updated",
-		"level": "success"
-	}],
+	{ "alerts": [
+		{
+			"text": "Invalidation request created for http://origin.infra.ciab.test/.+, start: 2021-11-09 01:02:03 +0000 UTC end: 2021-11-12 01:02:03 +0000 UTC invalidation type: REFETCH",
+			"level": "success"
+		}
+	],
 	"response": {
-		"assetUrl": "http://origin.infra.ciab.test/.*",
+		"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"
+		"id": 1,
+		"invalidationType": "REFETCH",
+		"startTime": "2021-11-09T01:02:03Z",
+		"ttlHours": 72
 	}}
 
 
 ``DELETE``
 ==========
-Deletes a content invalidation job.
+Deletes a :term:`Content Invalidation Job`.
 
-.. tip:: 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 jobs that are no longer useful.
+.. tip:: Content :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 jobs that are no longer useful.

Review comment:
       Extra `Content` at the beginning.

##########
File path: docs/source/admin/quick_howto/content_invalidation.rst
##########
@@ -22,8 +22,6 @@ Invalidating content on the CDN is sometimes necessary when the :term:`Origin` w
 
 .. impl-detail:: Given the size of a typical Traffic Control CDN and the amount of content that can be cached in it, removing the content from all the caches may take a long time. To speed up content invalidation, Traffic Control does not try to remove the content from the caches, but it makes the content inaccessible using the `regex_revalidate plugin for Apache Traffic Server <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/regex_revalidate.en.html>`_. This forces a "re-validation" of the content.
 
-.. Warning:: This method forces :term:`cache servers` to "re-validate" content, so in order to work properly the :term:`Origin` needs to support revalidation according to section 4.3.2 of :rfc:`7234`.
-

Review comment:
       How come this section was removed?

##########
File path: docs/source/api/v2/jobs.rst
##########
@@ -204,9 +205,9 @@ Response Structure
 
 ``PUT``
 =======
-Replaces an existing content invalidation job with a new one provided in the request. This method of editing a content invalidation job does not prevent the requesting user from changing fields that normally only have one value. Use with care.
+Replaces an existing :term:`Content Invalidation Jobs` with a new one provided in the request. This method of editing a :term:`Content Invalidation Jobs` does not prevent the requesting user from changing fields that normally only have one value. Use with care.

Review comment:
       Singular for both occurences.

##########
File path: docs/source/api/v2/jobs.rst
##########
@@ -307,11 +308,11 @@ Response Structure
 
 ``DELETE``
 ==========
-Deletes a content invalidation job.
+Deletes a :term:`Content Invalidation Job`.
 
-.. tip:: 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 jobs that are no longer useful.
+.. tip:: Content :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.

Review comment:
       Extra `Content` word at the beginning.

##########
File path: docs/source/api/v3/jobs.rst
##########
@@ -291,7 +292,7 @@ Response Structure
 	Content-Length: 234
 
 	{ "alerts": [{
-		"text": "Content invalidation job updated",
+		"text": "Content invalidation :term:`Content Invalidation Job` updated",

Review comment:
       I think this should remain _job_, no `:term:Content Invalidation Job`

##########
File path: docs/source/api/v2/jobs.rst
##########
@@ -371,7 +372,7 @@ Response Structure
 
 	{ "alerts": [
 		{
-			"text": "Content invalidation job was deleted",
+			"text": "Content invalidation :term:`job` was deleted",

Review comment:
       I think this should remain _job_, no `:term:`

##########
File path: docs/source/admin/traffic_portal/usingtrafficportal.rst
##########
@@ -645,21 +645,21 @@ Tools
 
 Invalidate Content
 ------------------
-Here, specific assets can be invalidated in all caches of a :term:`Delivery Service`, forcing content to be updated from the origin. Specifically, this *doesn't* mean that :term:`cache servers` will immediately remove items from their caches, but rather will fetch new copies whenever a request is made matching the 'Asset URL' regular expression. This behavior persists until the Invalidate Content Job's :abbr:`TTL (Time To Live)` expires.
+Here, specific assets can be invalidated in all caches of a :term:`Delivery Service`, forcing content to be updated from the origin. Specifically, this *doesn't* mean that :term:`cache servers` will immediately remove items from their caches, but rather will fetch new copies whenever a request is made matching the 'Asset URL' regular expression. This behavior persists until the :term:`Content Invalidate Content Job`'s :ref:`job-ttl` expires.
 
-.. Warning:: This method forces :term:`cache servers` to "re-validate" content, so in order to work properly the :term:`Origin` needs to support revalidation according to section 4.3.2 of :rfc:`7234`.
+.. warning:: This method forces :term:`cache servers` to "re-validate" content, so in order to work properly the :term:`Origin` needs to support revalidation according to section 4.3.2 of :rfc:`7234`.
 
 Each entry in the table on this page has the following fields:
 
-:term:`Delivery Service`: The :term:`Delivery Service` to which to apply this Invalidate Content Job
+:Delivery Service: The :term:`Delivery Service` to which to apply this :term:`Content Invalidation Job`
 :Asset URL:        A URL or regular expression which describes the asset(s) to be invalidated
-:Parameters:       So far, the only use for this is setting a :abbr:`TTL (Time To Live)` over which the Invalidate Content Job shall remain active
-:Start:            An effective start time until which the job is delayed
-:Created By:       The user name of the person who created this Invalidate Content Job
+:Parameters:       So far, the only use for this is setting a :abbr:`TTL (Time To Live)` over which the :term:`Content Invalidation Job` shall remain active

Review comment:
       The columns displayed here after REFETCH are now:
   - Delivery Service (Stays the same)
   - Asset URL (Stays the same)
   - TTL (Hours) - Replaces the `Parameter` column
   - Start (UTC) (Stays the same)
   - Expires (UTC) (Previously existed as well. Start + TTL)
   - Created By (Stays the same)
   - Invalidation Type - REFRESH | REFETCH

##########
File path: docs/source/api/v3/jobs.rst
##########
@@ -108,9 +109,9 @@ Response Structure
 
 ``POST``
 ========
-Creates a new content invalidation job.
+Creates a new :term:`Content Invalidation Jobs`.

Review comment:
       Singular here.

##########
File path: docs/source/api/v2/jobs.rst
##########
@@ -291,7 +292,7 @@ Response Structure
 	Content-Length: 234
 
 	{ "alerts": [{
-		"text": "Content invalidation job updated",
+		"text": "Content invalidation :term:`job` updated",

Review comment:
       I think this should remain _job_, no `:term:`

##########
File path: lib/go-tc/invalidationjobs.go
##########
@@ -511,18 +515,16 @@ type InvalidationJobV40 struct {
 	StartTime        time.Time `json:"startTime"`
 }
 
+// String implements the fmt.Stringer interface by providing a textual
+// representation of the InvalidationJobV4.
 func (job InvalidationJobV4) String() string {
-
-	ID := strconv.FormatUint(job.ID, 10)
-	TTLHours := strconv.FormatUint(uint64(job.TTLHours), 10)
-	StartTime := job.StartTime.String()
-
-	return fmt.Sprintf("{\nID:\t\t\t\t\t%s,\nAssetURL:\t\t\t%s,\nCreatedBy:\t\t\t%s,\nDeliveryService:\t%s,\nTTLHours:\t\t\t%s,\nInvalidationType:\t%s,\nStartTime:\t\t\t%s,\n}",
-		ID,
+	return fmt.Sprintf(`InvalidationJobV4{ID: %d, AssetURL: "%s", CreatedBy: "%s", DeliveryService: "%s", TTLHours: %d, InvalidationType: "%s", StartTime: "%s"}`,

Review comment:
       Nice cleanup.

##########
File path: docs/source/admin/traffic_portal/usingtrafficportal.rst
##########
@@ -645,21 +645,21 @@ Tools
 
 Invalidate Content
 ------------------
-Here, specific assets can be invalidated in all caches of a :term:`Delivery Service`, forcing content to be updated from the origin. Specifically, this *doesn't* mean that :term:`cache servers` will immediately remove items from their caches, but rather will fetch new copies whenever a request is made matching the 'Asset URL' regular expression. This behavior persists until the Invalidate Content Job's :abbr:`TTL (Time To Live)` expires.
+Here, specific assets can be invalidated in all caches of a :term:`Delivery Service`, forcing content to be updated from the origin. Specifically, this *doesn't* mean that :term:`cache servers` will immediately remove items from their caches, but rather will fetch new copies whenever a request is made matching the 'Asset URL' regular expression. This behavior persists until the :term:`Content Invalidate Content Job`'s :ref:`job-ttl` expires.

Review comment:
       I think the term should be `Content Invalidation Job` to clear the warning.

##########
File path: docs/source/overview/jobs.rst
##########
@@ -0,0 +1,137 @@
+..
+..
+.. 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.
+..
+
+.. _jobs:
+
+*************************
+Content Invalidation Jobs
+*************************
+:dfn:`Content Invalidation Jobs`, or simply "jobs" as they are sometimes known, are ways of forcing :term:`cache servers` to treat content as no longer valid, bypassing their normal caching policies.
+
+In general, this *should* be unnecessary, because a well-behaved :term:`Origin` *should* be setting its HTTP caching headers properly, so that content is only considered valid for some appropriate time intervals. Occasionally, however, an :term:`Origin` will be too optimistic with its caching instructions, and when content needs to be updated, :term:`cache servers` need to be informed that they must check back with the :term:`Origin`. Content Invalidation Jobs allow this to be done for specific patterns of assets, so that :term:`cache servers` will check back in with the :term:`Origin` and verify that the content they have cached is still valid.
+
+The model for Content Invalidation Job as API objects is given in :ref:`jobs-model` as a TypeScript interface.
+
+.. _jobs-model:
+
+.. code-block:: typescript
+	:caption: Content Invalidation Job as a Typescript interface.
+
+	/** This is the form used to create a new Content Invalidation Job */
+	interface ContentInvalidationJobCreationRequest {
+		deliveryService: string;
+		invalidationType: "REFRESH" | "REFETCH";
+		regex: `/${string}` | `\\/${string}`; // must also be a valid RegExp
+		startTime: Date; // RFC3339 string
+		ttlHours: number;
+	}
+
+	/**
+	 * This is the form used to return representations of Content Invalidation
+	 * Requests to clients.
+	 */
+	interface ContentInvalidationJob {
+		assetUrl: string;
+		createdBy: string;
+		deliveryService: string;
+		id: number;
+		invalidationType: "REFRESH" | "REFETCH";
+		startTime: Date; // RFC3339 string
+		ttlHours: number;
+	}
+
+.. _job-asset-url:
+
+Asset URL
+---------
+This property only appears in responses from the :ref:`to-api`, and has no effect in requests. The :dfn:`Asset URL` is constructed from the `Regular Expression`_ used in the creation of a Content Invalidation Job and the :ref:`ds-origin-url` of the :term:`Delivery Service` for which it was created. It is a URL that has a valid regular expression as its path (and may not be "percent-encoded" where a normal URL typically would be). Requests from CDN clients for content that matches this pattern will trigger Content Invalidation behavior.
+
+.. _job-created-by:
+
+Created By
+----------
+The username of the user who created the Content Invalidation Job is stored as the :dfn:`Created By` property of the Content Invalidation Job.

Review comment:
       Not sure if you want to add the `:term:` for both _Content Invalidation Job_ here, or throughout this page really. Given how consistent it is used throughout the API docs and elsewhere I thought I'd bring it up, however I am fine with it either way here.

##########
File path: docs/source/api/v3/jobs.rst
##########
@@ -371,7 +372,7 @@ Response Structure
 
 	{ "alerts": [
 		{
-			"text": "Content invalidation job was deleted",
+			"text": "Content invalidation :term:`Content Invalidation Job` was deleted",

Review comment:
       I think this should remain _job_, no `:term:Content Invalidation Job`

##########
File path: docs/source/overview/profiles_and_parameters.rst
##########
@@ -708,6 +707,15 @@ header
 
 	.. caution:: If a single :ref:`Profile <profiles>` has multiple "header" Parameters for the same `Config File`_ with different :ref:`Values <parameter-value>`, the actual header is undefined (but will be one of those Parameters' :ref:`Values <parameter-value>`).
 
+.. _parameter-name-refetch_enabled:

Review comment:
       This is really eloquently explained. Nice!

##########
File path: docs/source/overview/jobs.rst
##########
@@ -0,0 +1,137 @@
+..
+..
+.. 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.
+..
+
+.. _jobs:
+
+*************************
+Content Invalidation Jobs
+*************************
+:dfn:`Content Invalidation Jobs`, or simply "jobs" as they are sometimes known, are ways of forcing :term:`cache servers` to treat content as no longer valid, bypassing their normal caching policies.
+
+In general, this *should* be unnecessary, because a well-behaved :term:`Origin` *should* be setting its HTTP caching headers properly, so that content is only considered valid for some appropriate time intervals. Occasionally, however, an :term:`Origin` will be too optimistic with its caching instructions, and when content needs to be updated, :term:`cache servers` need to be informed that they must check back with the :term:`Origin`. Content Invalidation Jobs allow this to be done for specific patterns of assets, so that :term:`cache servers` will check back in with the :term:`Origin` and verify that the content they have cached is still valid.
+
+The model for Content Invalidation Job as API objects is given in :ref:`jobs-model` as a TypeScript interface.

Review comment:
       This line is resulting in a duplicated "as a Typescript interface"...
   
   ```
   [...] given in Content Invalidation Job as a Typescript interface. as a TypeScript interface.
   ```

##########
File path: docs/source/api/v4/jobs.rst
##########
@@ -21,38 +21,37 @@
 
 ``GET``
 =======
-Retrieve content invalidation jobs.
+Retrieve :term:`Content Invalidation Jobs`.
 
-:Auth. Required: Yes
-:Roles Required: None\ [#tenancy]_
-:Permissions Required: JOB:READ, DELIVERY-SERVICE:READ
-:Response Type:  Array
+:Auth. Required:       Yes
+:Roles Required:       None\ [#tenancy]_
+:Permissions Required: JOB:READ, DELIVERY-SERVICE:READ\ [#tenancy]_
+:Response Type:        Array
 
 Request Structure
 -----------------
 .. table:: Request Query Parameters
 
-	+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-	| Name                 | Required | Description                                                                                                                                                      |
-	+======================+==========+==================================================================================================================================================================+
-	| assetUrl             | no       | Return only invalidation jobs that operate on URLs by matching this regular expression                                                                           |
-	+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-	| cdn                  | no       | Return only invalidation jobs for delivery services with this CDN name                                                                                           |
-	+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-	| createdBy            | no       | Return only invalidation jobs that were created by the user with this username                                                                                   |
-	+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-	| deliveryService      | no       | Return only invalidation jobs that operate on the :term:`Delivery Service` with this :ref:`ds-xmlid`                                                             |
-	+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-	| dsId                 | no       | Return only invalidation jobs pending on the :term:`Delivery Service` identified by this integral, unique identifier                                             |
-	+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-	| id                   | no       | Return only the single invalidation job identified by this integral, unique identifer                                                                            |
-	+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-	| keyword              | no       | Return only invalidation jobs that have this "keyword" - only "PURGE" should exist                                                                               |
-	+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-	| maxRevalDurationDays | no       | Return only 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 invalidation jobs created by the user identified by this integral, unique identifier                                                                 |
-	+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+	+----------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+
+	| Name                 | Required | Description                                                                                                                          |
+	+======================+==========+======================================================================================================================================+
+	| assetUrl             | no       | Return only :term:`Content Invalidation Jobs` with this :ref:`job-asset-url`                                                         |
+	+----------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+
+	| cdn                  | no       | Return only :term:`Content Invalidation Jobs` for :term:`Delivery Services` within the CDN with this 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` with this :ref:`job-id`                                                      |
+	+----------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+
+	| maxRevalDurationDays | no       | Return only :term:`Content Invalidation Jobs` with a :ref:`job-start-time` 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

Review comment:
       Looks like this mighta been missed, but the Response Structure for `GET` has changed here. The fields returned are:
   
   assetUrl (Remains the same)
   createdBy (Remains the same)
   deliveryService (Remains the same)
   ~keyword~ (Removed)
   ~parameters~ (Removed)
   startTime (Remains the same)
   ttlHours (Added, replaces `parameters`)
   invalidationType (Added) -`REFRESH` | `REFETCH`
   
   Also, the response example will need to be updated too.
   
   A crude example of the returned object:
   ```json
   {
         "id": 9,
         "assetUrl": "http://test-ds.local.tld/another/other/to/content\\.jpg",
         "createdBy": "admin",
         "deliveryService": "test-ds",
         "ttlHours": 24,
         "invalidationType": "REFRESH",
         "startTime": "2021-11-05T10:24:00.37-06:00"
     }
     ```

##########
File path: docs/source/overview/jobs.rst
##########
@@ -0,0 +1,137 @@
+..
+..
+.. 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.
+..
+
+.. _jobs:
+
+*************************
+Content Invalidation Jobs
+*************************
+:dfn:`Content Invalidation Jobs`, or simply "jobs" as they are sometimes known, are ways of forcing :term:`cache servers` to treat content as no longer valid, bypassing their normal caching policies.
+
+In general, this *should* be unnecessary, because a well-behaved :term:`Origin` *should* be setting its HTTP caching headers properly, so that content is only considered valid for some appropriate time intervals. Occasionally, however, an :term:`Origin` will be too optimistic with its caching instructions, and when content needs to be updated, :term:`cache servers` need to be informed that they must check back with the :term:`Origin`. Content Invalidation Jobs allow this to be done for specific patterns of assets, so that :term:`cache servers` will check back in with the :term:`Origin` and verify that the content they have cached is still valid.
+
+The model for Content Invalidation Job as API objects is given in :ref:`jobs-model` as a TypeScript interface.
+
+.. _jobs-model:
+
+.. code-block:: typescript
+	:caption: Content Invalidation Job as a Typescript interface.
+
+	/** This is the form used to create a new Content Invalidation Job */
+	interface ContentInvalidationJobCreationRequest {
+		deliveryService: string;
+		invalidationType: "REFRESH" | "REFETCH";
+		regex: `/${string}` | `\\/${string}`; // must also be a valid RegExp
+		startTime: Date; // RFC3339 string
+		ttlHours: number;
+	}
+
+	/**
+	 * This is the form used to return representations of Content Invalidation
+	 * Requests to clients.
+	 */
+	interface ContentInvalidationJob {
+		assetUrl: string;
+		createdBy: string;
+		deliveryService: string;
+		id: number;
+		invalidationType: "REFRESH" | "REFETCH";
+		startTime: Date; // RFC3339 string
+		ttlHours: number;
+	}
+
+.. _job-asset-url:
+
+Asset URL
+---------
+This property only appears in responses from the :ref:`to-api`, and has no effect in requests. The :dfn:`Asset URL` is constructed from the `Regular Expression`_ used in the creation of a Content Invalidation Job and the :ref:`ds-origin-url` of the :term:`Delivery Service` for which it was created. It is a URL that has a valid regular expression as its path (and may not be "percent-encoded" where a normal URL typically would be). Requests from CDN clients for content that matches this pattern will trigger Content Invalidation behavior.

Review comment:
       It is possible to edit this field in a `PUT` request.

##########
File path: docs/source/overview/jobs.rst
##########
@@ -0,0 +1,137 @@
+..
+..
+.. 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.
+..
+
+.. _jobs:
+
+*************************
+Content Invalidation Jobs
+*************************
+:dfn:`Content Invalidation Jobs`, or simply "jobs" as they are sometimes known, are ways of forcing :term:`cache servers` to treat content as no longer valid, bypassing their normal caching policies.
+
+In general, this *should* be unnecessary, because a well-behaved :term:`Origin` *should* be setting its HTTP caching headers properly, so that content is only considered valid for some appropriate time intervals. Occasionally, however, an :term:`Origin` will be too optimistic with its caching instructions, and when content needs to be updated, :term:`cache servers` need to be informed that they must check back with the :term:`Origin`. Content Invalidation Jobs allow this to be done for specific patterns of assets, so that :term:`cache servers` will check back in with the :term:`Origin` and verify that the content they have cached is still valid.
+
+The model for Content Invalidation Job as API objects is given in :ref:`jobs-model` as a TypeScript interface.
+
+.. _jobs-model:
+
+.. code-block:: typescript
+	:caption: Content Invalidation Job as a Typescript interface.
+
+	/** This is the form used to create a new Content Invalidation Job */
+	interface ContentInvalidationJobCreationRequest {
+		deliveryService: string;
+		invalidationType: "REFRESH" | "REFETCH";
+		regex: `/${string}` | `\\/${string}`; // must also be a valid RegExp
+		startTime: Date; // RFC3339 string
+		ttlHours: number;
+	}
+
+	/**
+	 * This is the form used to return representations of Content Invalidation
+	 * Requests to clients.
+	 */
+	interface ContentInvalidationJob {
+		assetUrl: string;
+		createdBy: string;
+		deliveryService: string;
+		id: number;
+		invalidationType: "REFRESH" | "REFETCH";
+		startTime: Date; // RFC3339 string
+		ttlHours: number;
+	}
+
+.. _job-asset-url:
+
+Asset URL
+---------
+This property only appears in responses from the :ref:`to-api`, and has no effect in requests. The :dfn:`Asset URL` is constructed from the `Regular Expression`_ used in the creation of a Content Invalidation Job and the :ref:`ds-origin-url` of the :term:`Delivery Service` for which it was created. It is a URL that has a valid regular expression as its path (and may not be "percent-encoded" where a normal URL typically would be). Requests from CDN clients for content that matches this pattern will trigger Content Invalidation behavior.
+
+.. _job-created-by:
+
+Created By
+----------
+The username of the user who created the Content Invalidation Job is stored as the :dfn:`Created By` property of the Content Invalidation Job.
+
+.. _job-ds:
+
+Delivery Service
+----------------
+A Content Invalidation Job can only act on content for a single :term:`Delivery Service` - invalidating content for multiple :term:`Delivery Services` requires multiple Content Invalidation Jobs. The :dfn:`Delivery Service` property of a Content Invalidation Job holds the :ref:`ds-xmlid` of the :term:`Delivery Service` on which it operates.
+
+.. versionchanged:: 4.0
+	In earlier API versions, this property was allowed to be either the integral, unique identifier of the target :term:`Delivery Service`, *or* its :ref:`ds-xmlid` - this is no longer the case, but it should always be safe to use the :ref:`ds-xmlid` in any case.
+
+.. _job-id:
+
+ID
+--
+The integral, unique identifier for the Content Invalidation Job, assigned to it upon its creation.
+
+.. _job-invalidation-type:
+
+Invalidation Type
+-----------------
+:dfn:`Invalidation Type` defines how a :term:`cache server` should go about ensuring that its cache is valid.
+
+The normal operating mode for a Content Invalidation Job is to force the :term:`cache server` to send a request to the :term:`Origin` to verify that its cache is valid. If that is the case, no extra work is done and business as usual resumes. However, some :term:`Origins` are misconfigured and do not respond as required by HTTP specification. In this case, it is strongly advised to fix the :term:`Origin` so that it properly implements HTTP. However, if an :term:`Origin` is sending cache-able responses to requests, and cannot be trusted to verify the validity of cached content based on cache-controlling HTTP headers (e.g. :mailheader:`If-Modified-Since`) instead returning responses like ``304 Not Modified`` *even when the content has in fact been modified*, **and** if correcting this behavior is not an option, then the :term:`cache server` may be forced to pretend that the content it has was actually invalidated by the :term:`Origin` and must be completely re-fetched.
+
+The two values allowed for a Content Invalidation Job's Invalidation Type are:
+
+REFRESH

Review comment:
       The explanation is excellent.

##########
File path: docs/source/overview/jobs.rst
##########
@@ -0,0 +1,137 @@
+..
+..
+.. 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.
+..
+
+.. _jobs:
+
+*************************
+Content Invalidation Jobs
+*************************
+:dfn:`Content Invalidation Jobs`, or simply "jobs" as they are sometimes known, are ways of forcing :term:`cache servers` to treat content as no longer valid, bypassing their normal caching policies.
+
+In general, this *should* be unnecessary, because a well-behaved :term:`Origin` *should* be setting its HTTP caching headers properly, so that content is only considered valid for some appropriate time intervals. Occasionally, however, an :term:`Origin` will be too optimistic with its caching instructions, and when content needs to be updated, :term:`cache servers` need to be informed that they must check back with the :term:`Origin`. Content Invalidation Jobs allow this to be done for specific patterns of assets, so that :term:`cache servers` will check back in with the :term:`Origin` and verify that the content they have cached is still valid.
+
+The model for Content Invalidation Job as API objects is given in :ref:`jobs-model` as a TypeScript interface.
+
+.. _jobs-model:
+
+.. code-block:: typescript
+	:caption: Content Invalidation Job as a Typescript interface.
+
+	/** This is the form used to create a new Content Invalidation Job */
+	interface ContentInvalidationJobCreationRequest {
+		deliveryService: string;
+		invalidationType: "REFRESH" | "REFETCH";
+		regex: `/${string}` | `\\/${string}`; // must also be a valid RegExp
+		startTime: Date; // RFC3339 string
+		ttlHours: number;
+	}
+
+	/**
+	 * This is the form used to return representations of Content Invalidation
+	 * Requests to clients.
+	 */
+	interface ContentInvalidationJob {
+		assetUrl: string;
+		createdBy: string;
+		deliveryService: string;
+		id: number;
+		invalidationType: "REFRESH" | "REFETCH";
+		startTime: Date; // RFC3339 string
+		ttlHours: number;
+	}
+
+.. _job-asset-url:
+
+Asset URL
+---------
+This property only appears in responses from the :ref:`to-api`, and has no effect in requests. The :dfn:`Asset URL` is constructed from the `Regular Expression`_ used in the creation of a Content Invalidation Job and the :ref:`ds-origin-url` of the :term:`Delivery Service` for which it was created. It is a URL that has a valid regular expression as its path (and may not be "percent-encoded" where a normal URL typically would be). Requests from CDN clients for content that matches this pattern will trigger Content Invalidation behavior.
+
+.. _job-created-by:
+
+Created By
+----------
+The username of the user who created the Content Invalidation Job is stored as the :dfn:`Created By` property of the Content Invalidation Job.
+
+.. _job-ds:
+
+Delivery Service
+----------------
+A Content Invalidation Job can only act on content for a single :term:`Delivery Service` - invalidating content for multiple :term:`Delivery Services` requires multiple Content Invalidation Jobs. The :dfn:`Delivery Service` property of a Content Invalidation Job holds the :ref:`ds-xmlid` of the :term:`Delivery Service` on which it operates.

Review comment:
       Same `:term:` question as above and below. Fine either way.

##########
File path: docs/source/api/v4/jobs.rst
##########
@@ -109,269 +108,236 @@ Response Structure
 
 ``POST``
 ========
-Creates a new content invalidation job.
+Creates a new :term:`Content Invalidation Jobs`.
 
-.. caution:: Creating a 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 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.
+.. 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]_
-:Permissions Required: JOB:CREATE, JOB:READ, DELIVERY-SERVICE:READ, DELIVERY-SERVICE:UPDATE
-:Response Type:  Object
+:Auth. Required:       Yes
+:Roles Required:       "operations" or "admin"\ [#tenancy]_
+:Permissions Required: JOB:CREATE, JOB:READ, DELIVERY-SERVICE:READ, DELIVERY-SERVICE:UPDATE\ [#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 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.
+:deliveryService:  The :ref:`job-ds`
+:invalidationType: The :ref:`job-invalidation-type`
+:regex:            The :ref:`job-regex`
+:startTime:        The :ref:`job-start-time`
+:ttl:              The :ref:`job-ttl`
 
 .. code-block:: http
 	:caption: Request Example
 
 	POST /api/4.0/jobs HTTP/1.1
-	Host: trafficops.infra.ciab.test
-	User-Agent: python-requests/2.20.1
+	User-Agent: python-requests/2.25.1
 	Accept-Encoding: gzip, deflate
 	Accept: */*
 	Connection: keep-alive
 	Cookie: mojolicious=...
-	Content-Length: 80
+	Transfer-Encoding: chunked
 	Content-Type: application/json
 
 	{
 		"deliveryService": "demo1",
-		"startTime": 1560893311219,
-		"regex": "/.*",
-		"ttl": "121m"
+		"invalidationType": "REFRESH",
+		"regex": "/.+",
+		"startTime": "2021-11-09T01:02:03Z",
+		"ttlHours": 72
 	}
 
+
 Response Structure
 ------------------
-:assetUrl:        A regular expression - matching URLs will be operated upon according to ``keyword``
-:createdBy:       The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which this job operates
-:id:              An integral, unique identifier for this job
-:keyword:         A keyword that represents the operation being performed by the job:
-
-	PURGE
-		This 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 job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime:  The date and time at which the job began, in a non-standard format
+:assetUrl:         The :ref:`job-asset-url`
+:createdBy:        The :ref:`job-created-by`
+:deliveryService:  The :ref:`job-ds`
+:id:               The :ref:`job-id`.
+:invalidationType: The :ref:`job-invalidation-type`
+:ttlHours:         The :ref:`job-ttl`
+:startTime:        The :ref:`job-start-time`
 
 .. 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/4.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==
+	Location: https://localhost:6443/api/4.0/jobs?id=1
+	Permissions-Policy: interest-cohort=()
+	Set-Cookie: mojolicious=...
+	Vary: Accept-Encoding
 	X-Server-Name: traffic_ops_golang/
-	Date: Tue, 18 Jun 2019 19:37:06 GMT
-	Content-Length: 238
+	Date: Mon, 08 Nov 2021 15:44:46 GMT
+	Content-Length: 265
 
 	{
 		"alerts": [
 			{
-				"text": "Invalidation Job creation was successful",
+				"text": "Invalidation (REFRESH) request created for http://origin.infra.ciab.test/.+, start:2021-11-09 01:02:03 +0000 UTC end 2021-11-12 01:02:03 +0000 UTC",
 				"level": "success"
 			}
 		],
 		"response": {
-			"assetUrl": "http://origin.infra.ciab.test/.*",
+			"id": 1,
+			"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"
+			"ttlHours": 72,
+			"invalidationType": "REFRESH",
+			"startTime": "2021-11-09T01:02:03Z"
 		}
 	}
 
 
+
 ``PUT``
 =======
-Replaces an existing content invalidation job with a new one provided in the request. This method of editing a content invalidation job does not prevent the requesting user from changing fields that normally only have one value. Use with care.
+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 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 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.
+.. 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]_
-:Permissions Required: JOB:UPDATE, DELIVERY-SERVICE:UPDATE, JOB:READ, DELIVERY-SERVICE:READ
-:Response Type:  Object
+:Auth. Required:       Yes
+:Roles Required:       "operations" or "admin"\ [#tenancy]_
+:Permissions Required: JOB:UPDATE, DELIVERY-SERVICE:UPDATE, JOB:READ, DELIVERY-SERVICE:READ\ [#tenancy]_
+:Response Type:        Object
 
 Request Structure
 -----------------
 .. table:: Query Parameters
 
-	+------+----------+--------------------------------------------------------------------------------+
-	| Name | Required | Description                                                                    |
-	+======+==========+================================================================================+
-	| id   | yes      | The integral, unique identifier of the 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 job\ [#readonly]_
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which this job operates\ [#readonly]_ - unlike POST_ request payloads, this cannot be an integral, unique identifier
-:id:              An integral, unique identifier for this job\ [#readonly]_
-:keyword:         A keyword that represents the operation being performed by the job. It can have any (string) value, but the only value with any meaning to Traffic Control is:
-
-	PURGE
-		This job will prevent caching of URLs matching the ``assetUrl`` until it is removed (or its Time to Live expires)
+	+------+----------+----------------------------------------------------------------------------------------+
+	| Name | Required | Description                                                                            |
+	+======+==========+========================================================================================+
+	| id   | yes      | The integral, unique identifier of the :term:`Content Invalidation Job` being modified |
+	+------+----------+----------------------------------------------------------------------------------------+
 
-:parameters: A string containing space-separated key/value pairs - delimited by colons (:kbd:`:`\ s) representing parameters associated with the job. In practice, any string can be passed as a 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.
+:assetUrl:         The :ref:`job-asset-url` - the scheme and authority parts of the regular expression cannot be changed
+:createdBy:        The :ref:`job-created-by`\ [#immutable]_
+:deliveryService:  The :ref:`job-ds`\ [#immutable]_
+:id:               The :ref:`job-id`\ [#immutable]_
+:invalidationType: The :ref:`job-invalidation-type`
+:ttlHours:         The :ref:`job-ttl`
+:startTime:        The :ref:`job-start-time`
 
 .. code-block:: http
 	:caption: Request Example
 
-	PUT /api/4.0/jobs?id=3 HTTP/1.1
-	Host: trafficops.infra.ciab.test
-	User-Agent: python-requests/2.20.1
+	PUT /api/4.0/jobs?id=1 HTTP/1.1
+	User-Agent: python-requests/2.25.1
 	Accept-Encoding: gzip, deflate
 	Accept: */*
 	Connection: keep-alive
 	Cookie: mojolicious=...
-	Content-Length: 188
-	Content-Type: application/json
+	Content-Length: 191
 
 	{
-		"assetUrl": "http://origin.infra.ciab.test/.*",
+		"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"
+		"id": 1,
+		"invalidationType": "REFETCH",
+		"startTime": "2021-11-09T01:02:03Z",
+		"ttlHours": 72
 	}
 
+
 Response Structure
 ------------------
-:assetUrl:        A regular expression - matching URLs will be operated upon according to ``keyword``
-:createdBy:       The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which this job operates
-:id:              An integral, unique identifier for this job
-:keyword:         A keyword that represents the operation being performed by the job:
-
-	PURGE
-		This 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 job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime:  The date and time at which the job began, in a non-standard format
+:assetUrl:         The :ref:`job-asset-url`
+:createdBy:        The :ref:`job-created-by`
+:deliveryService:  The :ref:`job-ds`
+:id:               The :ref:`job-id`.

Review comment:
       Extra 'full stop' at the end




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@trafficcontrol.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



[GitHub] [trafficcontrol] zrhoffman merged pull request #6342: Add/update documentation for content invalidation jobs in TO API v4

Posted by GitBox <gi...@apache.org>.
zrhoffman merged pull request #6342:
URL: https://github.com/apache/trafficcontrol/pull/6342


   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@trafficcontrol.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #6342: Add/update documentation for content invalidation jobs in TO API v4

Posted by GitBox <gi...@apache.org>.
ocket8888 commented on a change in pull request #6342:
URL: https://github.com/apache/trafficcontrol/pull/6342#discussion_r747904446



##########
File path: docs/source/admin/traffic_portal/usingtrafficportal.rst
##########
@@ -645,21 +645,21 @@ Tools
 
 Invalidate Content
 ------------------
-Here, specific assets can be invalidated in all caches of a :term:`Delivery Service`, forcing content to be updated from the origin. Specifically, this *doesn't* mean that :term:`cache servers` will immediately remove items from their caches, but rather will fetch new copies whenever a request is made matching the 'Asset URL' regular expression. This behavior persists until the Invalidate Content Job's :abbr:`TTL (Time To Live)` expires.
+Here, specific assets can be invalidated in all caches of a :term:`Delivery Service`, forcing content to be updated from the origin. Specifically, this *doesn't* mean that :term:`cache servers` will immediately remove items from their caches, but rather will fetch new copies whenever a request is made matching the 'Asset URL' regular expression. This behavior persists until the :term:`Content Invalidate Content Job`'s :ref:`job-ttl` expires.
 
-.. Warning:: This method forces :term:`cache servers` to "re-validate" content, so in order to work properly the :term:`Origin` needs to support revalidation according to section 4.3.2 of :rfc:`7234`.
+.. warning:: This method forces :term:`cache servers` to "re-validate" content, so in order to work properly the :term:`Origin` needs to support revalidation according to section 4.3.2 of :rfc:`7234`.
 
 Each entry in the table on this page has the following fields:
 
-:term:`Delivery Service`: The :term:`Delivery Service` to which to apply this Invalidate Content Job

Review comment:
       I think that was probably my fault, from a search/replace I did back when I added "Delivery Service" to the glossary.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@trafficcontrol.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #6342: Add/update documentation for content invalidation jobs in TO API v4

Posted by GitBox <gi...@apache.org>.
ocket8888 commented on a change in pull request #6342:
URL: https://github.com/apache/trafficcontrol/pull/6342#discussion_r747905464



##########
File path: docs/source/overview/jobs.rst
##########
@@ -0,0 +1,137 @@
+..
+..
+.. 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.
+..
+
+.. _jobs:
+
+*************************
+Content Invalidation Jobs
+*************************
+:dfn:`Content Invalidation Jobs`, or simply "jobs" as they are sometimes known, are ways of forcing :term:`cache servers` to treat content as no longer valid, bypassing their normal caching policies.
+
+In general, this *should* be unnecessary, because a well-behaved :term:`Origin` *should* be setting its HTTP caching headers properly, so that content is only considered valid for some appropriate time intervals. Occasionally, however, an :term:`Origin` will be too optimistic with its caching instructions, and when content needs to be updated, :term:`cache servers` need to be informed that they must check back with the :term:`Origin`. Content Invalidation Jobs allow this to be done for specific patterns of assets, so that :term:`cache servers` will check back in with the :term:`Origin` and verify that the content they have cached is still valid.
+
+The model for Content Invalidation Job as API objects is given in :ref:`jobs-model` as a TypeScript interface.
+
+.. _jobs-model:
+
+.. code-block:: typescript
+	:caption: Content Invalidation Job as a Typescript interface.
+
+	/** This is the form used to create a new Content Invalidation Job */
+	interface ContentInvalidationJobCreationRequest {
+		deliveryService: string;
+		invalidationType: "REFRESH" | "REFETCH";
+		regex: `/${string}` | `\\/${string}`; // must also be a valid RegExp
+		startTime: Date; // RFC3339 string
+		ttlHours: number;
+	}
+
+	/**
+	 * This is the form used to return representations of Content Invalidation
+	 * Requests to clients.
+	 */
+	interface ContentInvalidationJob {
+		assetUrl: string;
+		createdBy: string;
+		deliveryService: string;
+		id: number;
+		invalidationType: "REFRESH" | "REFETCH";
+		startTime: Date; // RFC3339 string
+		ttlHours: number;
+	}
+
+.. _job-asset-url:
+
+Asset URL
+---------
+This property only appears in responses from the :ref:`to-api`, and has no effect in requests. The :dfn:`Asset URL` is constructed from the `Regular Expression`_ used in the creation of a Content Invalidation Job and the :ref:`ds-origin-url` of the :term:`Delivery Service` for which it was created. It is a URL that has a valid regular expression as its path (and may not be "percent-encoded" where a normal URL typically would be). Requests from CDN clients for content that matches this pattern will trigger Content Invalidation behavior.
+
+.. _job-created-by:
+
+Created By
+----------
+The username of the user who created the Content Invalidation Job is stored as the :dfn:`Created By` property of the Content Invalidation Job.

Review comment:
       In general I don't use `term` for the overview section that describes the term. The flow of understanding for a term with an overview section is
   
   1. See the term
   1. Click on it, which takes you to a one-paragraph (max) glossary entry explanation
   1. Click on the seealso link to go to the overview section if you need more detailed information
   
   doesn't make sense to me to put a loop in that flow.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@trafficcontrol.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #6342: Add/update documentation for content invalidation jobs in TO API v4

Posted by GitBox <gi...@apache.org>.
ocket8888 commented on a change in pull request #6342:
URL: https://github.com/apache/trafficcontrol/pull/6342#discussion_r747904146



##########
File path: docs/source/admin/quick_howto/content_invalidation.rst
##########
@@ -22,8 +22,6 @@ Invalidating content on the CDN is sometimes necessary when the :term:`Origin` w
 
 .. impl-detail:: Given the size of a typical Traffic Control CDN and the amount of content that can be cached in it, removing the content from all the caches may take a long time. To speed up content invalidation, Traffic Control does not try to remove the content from the caches, but it makes the content inaccessible using the `regex_revalidate plugin for Apache Traffic Server <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/regex_revalidate.en.html>`_. This forces a "re-validation" of the content.
 
-.. Warning:: This method forces :term:`cache servers` to "re-validate" content, so in order to work properly the :term:`Origin` needs to support revalidation according to section 4.3.2 of :rfc:`7234`.
-

Review comment:
       I moved it to the section on "Invalidation Type" in the overview, which is linked to now from this section




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@trafficcontrol.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org