Apache Helix REST API
REST API for managing Apache Helix clusters, instances, resources, and partition state assignments, including ideal state queries and external view inspection.
OpenAPI Specification
openapi: 3.0.3
info:
title: Apache Helix REST API
version: 1.0.0
description: REST API for managing Apache Helix clusters, instances, resources,
and partition state assignments in distributed systems.
contact:
email: [email protected]
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:9100
description: Helix REST Service
tags:
- name: Clusters
description: Cluster management operations
- name: Instances
description: Instance management operations
- name: Resources
description: Resource management operations
- name: State
description: Partition state operations
paths:
/clusters:
get:
operationId: listClusters
summary: Apache Helix List Clusters
description: List all Helix clusters managed by this controller.
tags:
- Clusters
responses:
'200':
description: Clusters listed successfully
content:
application/json:
schema:
type: object
properties:
clusters:
type: array
items:
type: string
post:
operationId: createCluster
summary: Apache Helix Create Cluster
description: Create a new Helix cluster.
tags:
- Clusters
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Cluster'
responses:
'201':
description: Cluster created
'400':
description: Invalid cluster configuration
/clusters/{clusterId}:
get:
operationId: getCluster
summary: Apache Helix Get Cluster
description: Get configuration and status of a specific Helix cluster.
tags:
- Clusters
parameters:
- name: clusterId
in: path
required: true
schema:
type: string
description: Cluster name
responses:
'200':
description: Cluster retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/Cluster'
'404':
description: Cluster not found
delete:
operationId: deleteCluster
summary: Apache Helix Delete Cluster
description: Delete a Helix cluster and all its associated ZooKeeper data.
tags:
- Clusters
parameters:
- name: clusterId
in: path
required: true
schema:
type: string
responses:
'200':
description: Cluster deleted
'404':
description: Cluster not found
/clusters/{clusterId}/instances:
get:
operationId: listInstances
summary: Apache Helix List Instances
description: List all instances (participants) registered in a Helix cluster.
tags:
- Instances
parameters:
- name: clusterId
in: path
required: true
schema:
type: string
responses:
'200':
description: Instances listed
content:
application/json:
schema:
type: object
properties:
instances:
type: array
items:
$ref: '#/components/schemas/Instance'
/clusters/{clusterId}/instances/{instanceName}:
get:
operationId: getInstance
summary: Apache Helix Get Instance
description: Get configuration and state of a specific Helix instance.
tags:
- Instances
parameters:
- name: clusterId
in: path
required: true
schema:
type: string
- name: instanceName
in: path
required: true
schema:
type: string
description: Instance name (e.g. localhost_12913)
responses:
'200':
description: Instance retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/Instance'
'404':
description: Instance not found
/clusters/{clusterId}/resources:
get:
operationId: listResources
summary: Apache Helix List Resources
description: List all resources managed in a Helix cluster.
tags:
- Resources
parameters:
- name: clusterId
in: path
required: true
schema:
type: string
responses:
'200':
description: Resources listed
content:
application/json:
schema:
type: object
properties:
resources:
type: array
items:
type: string
/clusters/{clusterId}/resources/{resourceName}:
get:
operationId: getResource
summary: Apache Helix Get Resource
description: Get configuration and ideal state of a specific Helix resource.
tags:
- Resources
parameters:
- name: clusterId
in: path
required: true
schema:
type: string
- name: resourceName
in: path
required: true
schema:
type: string
responses:
'200':
description: Resource retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/Resource'
'404':
description: Resource not found
/clusters/{clusterId}/resources/{resourceName}/externalView:
get:
operationId: getExternalView
summary: Apache Helix Get External View
description: Get the current external view showing actual partition state assignments
across instances.
tags:
- State
parameters:
- name: clusterId
in: path
required: true
schema:
type: string
- name: resourceName
in: path
required: true
schema:
type: string
responses:
'200':
description: External view retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalView'
/clusters/{clusterId}/resources/{resourceName}/idealState:
get:
operationId: getIdealState
summary: Apache Helix Get Ideal State
description: Get the ideal state (desired partition placement) for a Helix resource.
tags:
- State
parameters:
- name: clusterId
in: path
required: true
schema:
type: string
- name: resourceName
in: path
required: true
schema:
type: string
responses:
'200':
description: Ideal state retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/IdealState'
components:
schemas:
Cluster:
type: object
description: Helix cluster configuration and state
properties:
id:
type: string
description: Cluster name
example: my-cluster
controller:
type: string
description: Active controller node
example: controller_host_12345
paused:
type: boolean
description: Whether the cluster is paused
example: false
disabledInstances:
type: array
items:
type: string
description: List of disabled instances
liveInstances:
type: array
items:
type: string
description: List of live instances
Instance:
type: object
description: Helix cluster instance (participant) configuration
properties:
id:
type: string
description: Instance name
example: localhost_12913
hostName:
type: string
description: Hostname of the instance
example: localhost
port:
type: integer
description: Port number
example: 12913
enabled:
type: boolean
description: Whether the instance is enabled
example: true
tags:
type: array
items:
type: string
description: Instance tags
Resource:
type: object
description: Helix resource configuration
properties:
id:
type: string
description: Resource name
example: my-resource
stateModelDefRef:
type: string
description: State model definition reference
example: MasterSlave
numPartitions:
type: integer
description: Number of partitions
example: 16
replicas:
type: string
description: Replication factor
example: '3'
rebalanceMode:
type: string
description: Rebalance strategy
example: FULL_AUTO
Partition:
type: object
description: Helix partition state assignment across instances
properties:
id:
type: string
description: Partition name
example: my-resource_0
instanceStateMap:
type: object
description: Map of instance to state
example:
localhost_12913: MASTER
localhost_12914: SLAVE
ExternalView:
type: object
description: Current external view showing actual partition states across instances
properties:
id:
type: string
description: Resource name
example: my-resource
mapFields:
type: object
description: Map of partition to instance state map
IdealState:
type: object
description: Desired ideal state for resource partition placement
properties:
id:
type: string
description: Resource name
example: my-resource
stateModelDefRef:
type: string
description: State model reference
example: MasterSlave
mapFields:
type: object
description: Map of partition to desired instance state map