From 4334d34fc563551f95a774ac743998d518ee147c Mon Sep 17 00:00:00 2001
From: Yash Mayya <yash.mayya@gmail.com>
Date: Tue, 2 May 2023 12:40:05 +0530
Subject: [PATCH 1/3] KAFKA-14876: Document the new 'PUT
 /connectors/{name}/stop' REST API for Connect

---
 docs/connect.html | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/connect.html b/docs/connect.html
index b947bea3832a2..4f6ed2091fcec 100644
--- a/docs/connect.html
+++ b/docs/connect.html
@@ -301,7 +301,8 @@ <h4><a id="connect_rest" href="#connect_rest">REST API</a></h4>
         <li><code>GET /connectors/{name}/tasks</code> - get a list of tasks currently running for a connector</li>
         <li><code>GET /connectors/{name}/tasks/{taskid}/status</code> - get current status of the task, including if it is running, failed, paused, etc., which worker it is assigned to, and error information if it has failed</li>
         <li><code>PUT /connectors/{name}/pause</code> - pause the connector and its tasks, which stops message processing until the connector is resumed</li>
-        <li><code>PUT /connectors/{name}/resume</code> - resume a paused connector (or do nothing if the connector is not paused)</li>
+        <li><code>PUT /connectors/{name}/stop</code> - stop the connector and its tasks, and also remove its tasks from the Connect cluster. This is different from the paused state where the tasks aren't stopped and removed, but only suspended.</li>
+        <li><code>PUT /connectors/{name}/resume</code> - resume a paused or stopped connector (or do nothing if the connector is not paused or stopped)</li>
         <li><code>POST /connectors/{name}/restart?includeTasks=&lt;true|false&gt;&amp;onlyFailed=&lt;true|false&gt;</code> - restart a connector and its tasks instances.
             <ul>
                 <li>the "includeTasks" parameter specifies whether to restart the connector instance and task instances ("includeTasks=true") or just the connector instance ("includeTasks=false"), with the default ("false") preserving the same behavior as earlier versions.</li>

From 0aff90d1bbbdf5fb7c7dfa8d704d5f5721709b11 Mon Sep 17 00:00:00 2001
From: Yash Mayya <yash.mayya@gmail.com>
Date: Tue, 2 May 2023 21:33:37 +0530
Subject: [PATCH 2/3] Update docs/connect.html

Co-authored-by: Chris Egerton <fearthecellos@gmail.com>
---
 docs/connect.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/connect.html b/docs/connect.html
index 4f6ed2091fcec..2c91dabc09a6c 100644
--- a/docs/connect.html
+++ b/docs/connect.html
@@ -300,7 +300,7 @@ <h4><a id="connect_rest" href="#connect_rest">REST API</a></h4>
         <li><code>GET /connectors/{name}/status</code> - get current status of the connector, including if it is running, failed, paused, etc., which worker it is assigned to, error information if it has failed, and the state of all its tasks</li>
         <li><code>GET /connectors/{name}/tasks</code> - get a list of tasks currently running for a connector</li>
         <li><code>GET /connectors/{name}/tasks/{taskid}/status</code> - get current status of the task, including if it is running, failed, paused, etc., which worker it is assigned to, and error information if it has failed</li>
-        <li><code>PUT /connectors/{name}/pause</code> - pause the connector and its tasks, which stops message processing until the connector is resumed</li>
+        <li><code>PUT /connectors/{name}/pause</code> - pause the connector and its tasks, which stops message processing until the connector is resumed. Any resources claimed by its tasks are left allocated, which allows the connector to begin processing data quickly once it is resumed.</li>
         <li><code>PUT /connectors/{name}/stop</code> - stop the connector and its tasks, and also remove its tasks from the Connect cluster. This is different from the paused state where the tasks aren't stopped and removed, but only suspended.</li>
         <li><code>PUT /connectors/{name}/resume</code> - resume a paused or stopped connector (or do nothing if the connector is not paused or stopped)</li>
         <li><code>POST /connectors/{name}/restart?includeTasks=&lt;true|false&gt;&amp;onlyFailed=&lt;true|false&gt;</code> - restart a connector and its tasks instances.

From 2f529bcd955841a5b7fe5d2e32c7442fd5982c0d Mon Sep 17 00:00:00 2001
From: Yash Mayya <yash.mayya@gmail.com>
Date: Tue, 2 May 2023 22:37:35 +0530
Subject: [PATCH 3/3] Reword stop API documentation

---
 docs/connect.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/connect.html b/docs/connect.html
index 2c91dabc09a6c..e88cefee8de1f 100644
--- a/docs/connect.html
+++ b/docs/connect.html
@@ -301,7 +301,7 @@ <h4><a id="connect_rest" href="#connect_rest">REST API</a></h4>
         <li><code>GET /connectors/{name}/tasks</code> - get a list of tasks currently running for a connector</li>
         <li><code>GET /connectors/{name}/tasks/{taskid}/status</code> - get current status of the task, including if it is running, failed, paused, etc., which worker it is assigned to, and error information if it has failed</li>
         <li><code>PUT /connectors/{name}/pause</code> - pause the connector and its tasks, which stops message processing until the connector is resumed. Any resources claimed by its tasks are left allocated, which allows the connector to begin processing data quickly once it is resumed.</li>
-        <li><code>PUT /connectors/{name}/stop</code> - stop the connector and its tasks, and also remove its tasks from the Connect cluster. This is different from the paused state where the tasks aren't stopped and removed, but only suspended.</li>
+        <li><code>PUT /connectors/{name}/stop</code> - stop the connector and shut down its tasks, deallocating any resources claimed by its tasks. This is more efficient from a resource usage standpoint than pausing the connector, but can cause it to take longer to begin processing data once resumed.</li>
         <li><code>PUT /connectors/{name}/resume</code> - resume a paused or stopped connector (or do nothing if the connector is not paused or stopped)</li>
         <li><code>POST /connectors/{name}/restart?includeTasks=&lt;true|false&gt;&amp;onlyFailed=&lt;true|false&gt;</code> - restart a connector and its tasks instances.
             <ul>