Author: jxue
Date: Sun May 31 05:22:22 2026
New Revision: 1934807
Log:
Site checkin for project Apache Helix :: Website
Modified:
helix/site-content/2.0.0-docs/tutorial_rest_service.html
Modified: helix/site-content/2.0.0-docs/tutorial_rest_service.html
==============================================================================
--- helix/site-content/2.0.0-docs/tutorial_rest_service.html Sun May 31
05:18:39 2026 (r1934806)
+++ helix/site-content/2.0.0-docs/tutorial_rest_service.html Sun May 31
05:22:22 2026 (r1934807)
@@ -929,6 +929,97 @@ $curl -X POST -H "Content-Type: applicat
</ul>
</section>
<section>
+ <h4 id="Helix_Stoppable_Instances_API">Helix Stoppable Instances API</h4>
+ <p>The Stoppable Instances API helps determine which instances can be
safely stopped for maintenance. It evaluates instances based on health checks,
zone distribution, and custom criteria.</p>
+ <ul>
+ <li> <p><b>“/clusters/{clusterName}/instances/stoppable”</b></p>
+ <ul>
+ <li>Evaluates instances and returns those that can be safely
stopped</li>
+ <li><b>POST</b> - Get stoppable instances with specified criteria</li>
+ </ul> <p>Request body parameters:</p>
+ <ul>
+ <li><code>instance_based</code> - Selection base for stoppable check
(non_zone_based, zone_based, cross_zone_based)</li>
+ <li><code>instances</code> - List of instances to evaluate</li>
+ <li><code>to_be_stopped_instances</code> - Instances presumed to be
already stopped</li>
+ <li><code>skip_custom_check_if_instance_not_alive</code> - Skip custom
checks if instance is not alive</li>
+ <li><code>zone_order</code> - Order of zones for zone-based
selection</li>
+ <li><code>skip_stoppable_check_list</code> - List of health checks to
skip</li>
+ <li><code>customized_values</code> - Custom input for health checks</li>
+ </ul> <p>Example:</p>
+ <div class="source">
+ <pre><code>curl -X POST -H "Content-Type: application/json" \
+http://localhost:1234/admin/v2/clusters/myCluster/instances/stoppable \
+-d '{
+ "instance_based": "zone_based",
+ "instances": ["host1:1234", "host2:1234", "host3:1234"],
+ "to_be_stopped_instances": [],
+ "skip_custom_check_if_instance_not_alive": false,
+ "zone_order": ["zone1", "zone2", "zone3"]
+}'
+</code></pre>
+ </div> <p>Response:</p>
+ <div class="source">
+ <pre><code>{
+ "instance_stoppable_parallel": ["host1:1234", "host2:1234"],
+ "instance_not_stoppable_with_reasons": {
+ "host3:1234": ["HELIX:INSTANCE_NOT_EXIST"]
+ }
+}
+</code></pre>
+ </div> </li>
+ <li>
<p><b>“/clusters/{clusterName}/instances/stoppable/{instanceName}”</b></p>
+ <ul>
+ <li>Check if a specific instance is stoppable</li>
+ <li><b>GET</b> - Check if the instance can be stopped</li>
+ </ul> <p>Response:</p>
+ <div class="source">
+ <pre><code>{
+ "stoppable": true,
+ "failedChecks": []
+}
+</code></pre>
+ </div> <p>Or if not stoppable:</p>
+ <div class="source">
+ <pre><code>{
+ "stoppable": false,
+ "failedChecks": [
+ "HELIX:HAS_ASSIGNED_PARTITIONS",
+ "CUSTOM_INSTANCE_HEALTH_FAILURE:CustomHealthCheck"
+ ]
+}
+</code></pre>
+ </div> </li>
+ </ul>
+ <p><b>Health Check Categories</b></p>
+ <p>The stoppable check supports multiple health check categories:</p>
+ <ul>
+ <li><code>HELIX_OWN_CHECK</code> - Built-in Helix health checks</li>
+ <li><code>CUSTOM_INSTANCE_CHECK</code> - Custom instance-level health
checks</li>
+ <li><code>CUSTOM_PARTITION_CHECK</code> - Custom partition-level health
checks</li>
+ <li><code>CUSTOM_AGGREGATED_CHECK</code> - Custom aggregated health
checks</li>
+ </ul>
+ <p><b>Built-in Health Checks</b></p>
+ <ul>
+ <li><code>HAS_ASSIGNED_PARTITIONS</code> - Instance has partitions
assigned</li>
+ <li><code>IS_NOT_EVICTABLE</code> - Instance cannot be evicted</li>
+ <li><code>IS_NOT_ENABLED</code> - Instance is not enabled</li>
+ <li><code>HAS_DISABLED_PARTITION</code> - Instance has disabled
partitions</li>
+ <li><code>IS_MAINTENANCE_MODE</code> - Cluster is in maintenance mode</li>
+ </ul>
+ <p><b>Skipping Health Checks</b></p>
+ <p>Use <code>skip_stoppable_check_list</code> to skip specific checks:</p>
+ <div class="source">
+ <pre><code>curl -X POST -H "Content-Type: application/json" \
+http://localhost:1234/admin/v2/clusters/myCluster/instances/stoppable \
+-d '{
+ "instance_based": "non_zone_based",
+ "instances": ["host1:1234"],
+ "skip_stoppable_check_list": ["HAS_ASSIGNED_PARTITIONS", "IS_NOT_EVICTABLE"]
+}'
+</code></pre>
+ </div>
+ </section>
+ <section>
<h4 id="Helix_Workflow_and_its_sub-resources">Helix Workflow and its
sub-resources</h4>
<ul>
<li> <p><b>“/clusters/{clusterName}/workflows”</b></p>
