C0urante commented on code in PR #13915: URL: https://github.com/apache/kafka/pull/13915#discussion_r1245532972
########## 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 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}/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. Note that the offsets for a connector can be only modified via the offsets management endpoints if it is in the stopped state</li> Review Comment: ```suggestion <li id="connect_stopconnector"><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. Note that the offsets for a connector can be only modified via the offsets management endpoints if it is in the stopped state</li> ``` ########## docs/connect.html: ########## @@ -313,7 +313,22 @@ <h4><a id="connect_rest" href="#connect_rest">REST API</a></h4> <li><code>DELETE /connectors/{name}</code> - delete a connector, halting all tasks and deleting its configuration</li> <li><code>GET /connectors/{name}/topics</code> - get the set of topics that a specific connector is using since the connector was created or since a request to reset its set of active topics was issued</li> <li><code>PUT /connectors/{name}/topics/reset</code> - send a request to empty the set of active topics of a connector</li> - <li><code>GET /connectors/{name}/offsets</code> - get the current offsets for a connector (see <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-875%3A+First-class+offsets+support+in+Kafka+Connect">KIP-875</a> for more details)</li> + <li>Offsets management endpoints (see <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-875%3A+First-class+offsets+support+in+Kafka+Connect">KIP-875</a> for more details): + <ul> + <li><code>GET /connectors/{name}/offsets</code> - get the current offsets for a connector</li> + <li><code>DELETE /connectors/{name}/offsets</code> - reset the offsets for a connector. The connector must exist and must be in the stopped state</li> + <li><code>PATCH /connectors/{name}/offsets</code> - alter the offsets for a connector. The connector must exist and must be in the stopped state. The request body should be a JSON object containing a JSON array <code>offsets</code> field, similar to the response body of the <code>GET /connectors/{name}/offsets</code> endpoint</li> Review Comment: ```suggestion <li><code>DELETE /connectors/{name}/offsets</code> - reset the offsets for a connector. The connector must exist and must be in the stopped state (see <a href="#connect_stopconnector"><code>PUT /connectors/{name}/stop</code></a>)</li> <li><code>PATCH /connectors/{name}/offsets</code> - alter the offsets for a connector. The connector must exist and must be in the stopped state (see <a href="#connect_stopconnector"><code>PUT /connectors/{name}/stop</code></a>). The request body should be a JSON object containing a JSON array <code>offsets</code> field, similar to the response body of the <code>GET /connectors/{name}/offsets</code> endpoint</li> ``` ########## docs/connect.html: ########## @@ -313,7 +313,13 @@ <h4><a id="connect_rest" href="#connect_rest">REST API</a></h4> <li><code>DELETE /connectors/{name}</code> - delete a connector, halting all tasks and deleting its configuration</li> <li><code>GET /connectors/{name}/topics</code> - get the set of topics that a specific connector is using since the connector was created or since a request to reset its set of active topics was issued</li> <li><code>PUT /connectors/{name}/topics/reset</code> - send a request to empty the set of active topics of a connector</li> - <li><code>GET /connectors/{name}/offsets</code> - get the current offsets for a connector (see <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-875%3A+First-class+offsets+support+in+Kafka+Connect">KIP-875</a> for more details)</li> + <li>Offsets management REST APIs (see <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-875%3A+First-class+offsets+support+in+Kafka+Connect">KIP-875</a> for more details): + <ul> + <li><code>GET /connectors/{name}/offsets</code> - get the current offsets for a connector</li> + <li><code>DELETE /connectors/{name}/offsets</code> - reset the offsets for a connector. The connector must exist and must be in the stopped state.</li> + <li><code>PATCH /connectors/{name}/offsets</code> - alter the offsets for a connector. The connector must exist and must be in the stopped state. The request body should be a JSON object containing a JSON array <code>offsets</code> field, similar to the response body of the <code>GET /connectors/{name}/offsets</code> REST API.</li> Review Comment: The example is great, thanks 👍 ########## docs/connect.html: ########## @@ -313,7 +313,22 @@ <h4><a id="connect_rest" href="#connect_rest">REST API</a></h4> <li><code>DELETE /connectors/{name}</code> - delete a connector, halting all tasks and deleting its configuration</li> <li><code>GET /connectors/{name}/topics</code> - get the set of topics that a specific connector is using since the connector was created or since a request to reset its set of active topics was issued</li> <li><code>PUT /connectors/{name}/topics/reset</code> - send a request to empty the set of active topics of a connector</li> - <li><code>GET /connectors/{name}/offsets</code> - get the current offsets for a connector (see <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-875%3A+First-class+offsets+support+in+Kafka+Connect">KIP-875</a> for more details)</li> + <li>Offsets management endpoints (see <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-875%3A+First-class+offsets+support+in+Kafka+Connect">KIP-875</a> for more details): + <ul> + <li><code>GET /connectors/{name}/offsets</code> - get the current offsets for a connector</li> + <li><code>DELETE /connectors/{name}/offsets</code> - reset the offsets for a connector. The connector must exist and must be in the stopped state</li> + <li><code>PATCH /connectors/{name}/offsets</code> - alter the offsets for a connector. The connector must exist and must be in the stopped state. The request body should be a JSON object containing a JSON array <code>offsets</code> field, similar to the response body of the <code>GET /connectors/{name}/offsets</code> endpoint</li> + An example request body for the <code>FileStreamSourceConnector</code>: + <pre class="line-numbers"><code class="json"> +{"offsets": [{"partition": {"filename": "test.txt"}, "offset": {"position": 30}}]} Review Comment: We can make this prettier: ```suggestion { "offsets": [ { "partition": { "filename": "test.txt" }, "offset": { "position": 30 } } ] } ``` ########## docs/connect.html: ########## @@ -313,7 +313,22 @@ <h4><a id="connect_rest" href="#connect_rest">REST API</a></h4> <li><code>DELETE /connectors/{name}</code> - delete a connector, halting all tasks and deleting its configuration</li> <li><code>GET /connectors/{name}/topics</code> - get the set of topics that a specific connector is using since the connector was created or since a request to reset its set of active topics was issued</li> <li><code>PUT /connectors/{name}/topics/reset</code> - send a request to empty the set of active topics of a connector</li> - <li><code>GET /connectors/{name}/offsets</code> - get the current offsets for a connector (see <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-875%3A+First-class+offsets+support+in+Kafka+Connect">KIP-875</a> for more details)</li> + <li>Offsets management endpoints (see <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-875%3A+First-class+offsets+support+in+Kafka+Connect">KIP-875</a> for more details): + <ul> + <li><code>GET /connectors/{name}/offsets</code> - get the current offsets for a connector</li> + <li><code>DELETE /connectors/{name}/offsets</code> - reset the offsets for a connector. The connector must exist and must be in the stopped state</li> + <li><code>PATCH /connectors/{name}/offsets</code> - alter the offsets for a connector. The connector must exist and must be in the stopped state. The request body should be a JSON object containing a JSON array <code>offsets</code> field, similar to the response body of the <code>GET /connectors/{name}/offsets</code> endpoint</li> + An example request body for the <code>FileStreamSourceConnector</code>: + <pre class="line-numbers"><code class="json"> +{"offsets": [{"partition": {"filename": "test.txt"}, "offset": {"position": 30}}]} + </code></pre> + An example request body for the <code>FileStreamSinkConnector</code>: + <pre class="line-numbers"><code class="json"> +{"offsets": [{"partition": {"kafka_topic": "test", "kafka_partition": 0}, "offset": {"kafka_offset": 5}}, {"partition": {"kafka_topic": "test", "kafka_partition": 1}, "offset": null}]} Review Comment: We can make this prettier: ```suggestion { "offsets": [ { "partition": { "kafka_topic": "test", "kafka_partition": 0 }, "offset": { "kafka_offset": 5 } }, { "partition": { "kafka_topic": "test", "kafka_partition": 1 }, "offset": null } ] } ``` -- 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-unsubscr...@kafka.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org