[GitHub] [kafka] yashmayya commented on a diff in pull request #13657: KAFKA-14876: Document the new 'PUT /connectors/{name}/stop' REST API

["yashmayya (via GitHub)" <gi...@apache.org>]

yashmayya commented on code in PR #13657:
URL: https://github.com/apache/kafka/pull/13657#discussion_r1182174568


##########
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>

Review Comment:
   We can add further distinctions between pause and stop relating to altering and resetting offsets before the `3.6` release and after the rest of https://issues.apache.org/jira/browse/KAFKA-4107 lands in `trunk`.



##########
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>

Review Comment:
   I'm wondering whether it's worth documenting pause <-> stop transitions. My initial thoughts are that the vast majority of users don't even need to be aware of these state transitions so we could skip documenting them.



-- 
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: jira-unsubscribe@kafka.apache.org

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