+
+ | REST endpoint
+ |
+ Client API method
+ |
+ Comments
+ |
+
+
+ GET /ping
+ |
+ N/A
+ |
+ Already present in the current API. I suggest switching to the HEAD version below.
+ |
+
+
+ HEAD /ping
+ |
+ Ping(ctx context.Context) error
+ |
+ Already present in the current API (named IsReaperUp). I suggest returning only error instead of (bool, error).
+ |
+
+
+ POST /login
+ |
+ Login(ctx context.Context, username string, password string) error
+ |
+
+ |
+
+
+ GET /jwt
+ |
+ N/A
+ |
+ WIll be used underneath by Login to generate the JWT token.
+ |
+
+
+ POST /logout
+ |
+ Logout(ctx context.Context) error
+ |
+
+ |
+
+
+ |
+ |
+ IsAuthenticated() bool
+ |
+ Non-endpoint method. returns true if the client has been authenticated through a successful call to Login.
+
+Authenticated clients will send the authentication token along with every request to the Reaper backend.
+ |
+
+
+
+
+
+## Cluster Resource
+
+
+### Methods
+
+Two existing methods are actually a combination of REST method calls in a loop:
+
+```
+// GetClusters fetches all clusters. This function is async and may return before any or all results are
+// available. The concurrency is currently determined by min(5, NUM_CPUS).
+GetClusters(ctx context.Context) <-chan GetClusterResult
+
+// GetClustersSync fetches all clusters in a synchronous or blocking manner. Note that this function fails
+// fast if there is an error and no clusters will be returned.
+GetClustersSync(ctx context.Context) ([]*Cluster, error)
+```
+
+I am not sure that these should be preserved. Applications can easily reproduce their behavior themselves if necessary using the proposed API below.
+
+
+
+
+ | REST endpoint
+ |
+ Client API method
+ |
+ Comments
+ |
+
+
+ GET /cluster
+ |
+ ClusterNames(ctx context.Context, seedHost string) ([]string, error)
+ |
+ Already present in the current API. Suffix Names because it's only a list of names, not entities.
+ |
+
+
+ GET /cluster/{cluster_name}
+ |
+ Cluster(ctx context.Context, name string, renderOptions *ClusterRenderOptions) (*Cluster, error)
+ |
+ Already present in the current API.
+ |
+
+
+ GET /cluster/{cluster_name}/tables
+ |
+ ClusterSchema(ctx context.Context, name string) (map[string]*Keyspace, error)
+ |
+ Schema rather than Tables since it is a map of tables keyed by keyspace.
+ |
+
+
+ POST /cluster
+
+POST /cluster/auth
+ |
+ CreateCluster(ctx context.Context, seed string, jmxOptions *ClusterJmxOptions) (string, error)
+ |
+ Already present in the current API. Will use the special /auth endpoint if authenticated, otherwise the regular one.
+ |
+
+
+ PUT /cluster/{cluster_name}
+
+PUT /cluster/{cluster_name}/auth
+ |
+ UpdateCluster(ctx context.Context, name string, newSeed string, jmxOptions *ClusterJmxOptions) error
+ |
+ Already present in the current API. Will use the special /auth endpoint if authenticated, otherwise the regular one.
+ |
+
+
+ DELETE /cluster/{cluster_name}
+ |
+ DeleteCluster(ctx context.Context, name string, force bool) error
+ |
+ Already present in the current API.
+ |
+
+
+
+
+### Types
+
+Note: the `NodeState` struct attempts to capture datacenter and rack names in a user-friendly manner, but does not correspond 1:1 with the JSON payload and will require a custom JSON unmarshaller. The current API already does this translation.
+
+```
+type Cluster struct {
+ Name string
+ JmxUsername string
+ JmxPasswordSet bool
+ Seeds []string
+ RepairRuns []*RepairRun
+ RepairSchedules []*RepairSchedule
+ NodeStates []*NodeState
+}
+
+type Keyspace struct {
+ Name string
+ Tables map[string]*Table
+}
+
+type Table struct {
+ Name string
+}
+
+type NodeState struct {
+ SourceNode string
+ TotalLoad float64
+ Endpoints []string
+ Datacenters map[string]*Datacenter
+}
+
+type Datacenter struct {
+ Name string
+ Racks map[string]*Rack
+}
+
+type Rack struct {
+ Name string
+ Endpoints []*Endpoint
+}
+
+type Endpoint struct {
+ Endpoint string
+ Datacenter string
+ Rack string
+ HostId string
+ Status string
+ Severity float64
+ ReleaseVersion string
+ Tokens string
+ Load float64
+}
+```
+
+
+
+## RepairRun Resource
+
+
+### Methods
+
+
+
+
+ | REST endpoint
+ |
+ Client API method
+ |
+ Comments
+ |
+
+
+ GET /repair_run
+ |
+ RepairRuns(ctx context.Context, searchOptions *RepairRunSearchOptions) ([]*RepairRun, error)
+ |
+
+ |
+
+
+ GET /repair_run/cluster/{cluster_name}
+ |
+ N/A
+ |
+ Not mapped, can be achieved with the method above + search options
+ |
+
+
+ GET /repair_run/{id}
+ |
+ RepairRun(ctx context.Context, repairRunId uuid.UUID) (*RepairRun, error)
+ |
+
+ |
+
+
+ POST /repair_run
+ |
+ CreateRepairRun(ctx context.Context, cluster string, keyspace string, owner string, options *RepairRunCreateOptions) (uuid.UUID, error)
+ |
+
+ |
+
+
+ PUT /repair_run/{id}
+ |
+ N/A
+ |
+ Deprecated REST endpoint, moved to \
+PUT repair_run/{id}/state/{state}
+ |
+
+
+ PUT /repair_run/{id}/intensity/{intensity}
+ |
+ UpdateRepairRun(ctx context.Context, repairRunId uuid.UUID, newIntensity Intensity) error
+ |
+ Only intensity can be changed.
+ |
+
+
+ PUT /repair_run/{id}/state/{state}
+ |
+ StartRepairRun(ctx context.Context, repairRunId uuid.UUID) error
+
+ResumeRepairRun(ctx context.Context, repairRunId uuid.UUID) error
+ |
+ Two API methods to better distinguish start from resume. Endpoint will be called with state = RUNNING
+ |
+
+
+ PUT /repair_run/{id}/state/{state}
+ |
+ PauseRepairRun(ctx context.Context, repairRunId uuid.UUID) error
+ |
+ Endpoint will be called with state = PAUSED
+ |
+
+
+ GET /repair_run/{id}/segments
+ |
+ RepairRunSegments(ctx context.Context, repairRunId uuid.UUID) ([]*RepairSegment, error)
+ |
+
+ |
+
+
+ PUT /repair_run/{id}/state/{state}
+ |
+ AbortRepairRun(ctx context.Context, repairRunId uuid.UUID) error
+ |
+ Endpoint will be called with state = ABORTED
+ |
+
+
+ GET /repair_run/{id}/segments
+ |
+ RepairRunSegments(ctx context.Context, repairRunId uuid.UUID) ([]*RepairSegment, error)
+ |
+
+ |
+
+
+ POST /repair_run/{id}/segments/abort/{segment_id}
+ |
+ AbortRepairRunSegment(ctx context.Context, repairRunId uuid.UUID, segmentId uuid.UUID) error
+ |
+
+ |
+
+
+ DELETE /repair_run/{id}
+ |
+ DeleteRepairRun(ctx context.Context, repairRunId uuid.UUID, owner string) error
+ |
+
+ |
+
+
+ POST /repair_run/purge
+ |
+ PurgeRepairRuns(ctx context.Context) (int, error)
+ |
+
+ |
+
+
+
+### Types
+
+```
+type RepairRun struct {
+ Id uuid.UUID
+ Cluster string
+ Owner string
+ Keyspace string
+ Tables []string
+ Cause string
+ State RepairRunState
+ Intensity Intensity
+ IncrementalRepair bool
+ TotalSegments int
+ RepairParallelism RepairParallelism
+ SegmentsRepaired int
+ LastEvent string
+ Duration string
+ Nodes []string
+ Datacenters []string
+ IgnoredTables []string
+ RepairThreadCount int
+ RepairUnitId uuid.UUID
+}
+
+type RepairSegment struct {
+ Id uuid.UUID
+ RunId uuid.UUID
+ RepairUnitId uuid.UUID
+ TokenRange *Segment
+ FailCount int
+ State RepairSegmentState
+ Coordinator string
+ StartTime *time.Time
+ EndTime *time.Time
+ Replicas map[string]string
+}
+
+type Segment struct {
+ BaseRange *TokenRange
+ TokenRanges []*TokenRange
+ Replicas map[string]string
+}
+
+type TokenRange struct {
+ Start *big.Int `json:"start"`
+ End *big.Int `json:"end"`
+}
+
+type Intensity = float64
+
+type RepairRunState string
+
+const (
+ RepairRunStateNotStarted = RepairRunState("NOT_STARTED")
+ RepairRunStateRunning = RepairRunState("RUNNING")
+ RepairRunStateError = RepairRunState("ERROR")
+ RepairRunStateDone = RepairRunState("DONE")
+ RepairRunStatePaused = RepairRunState("PAUSED")
+ RepairRunStateAborted = RepairRunState("ABORTED")
+ RepairRunStateDeleted = RepairRunState("DELETED")
+)
+
+func (s RepairRunState) isActive() bool {
+ return s == RepairRunStateRunning || s == RepairRunStatePaused
+}
+
+func (s RepairRunState) isTerminated() bool {
+ return s == RepairRunStateDone || s == RepairRunStateError || s == RepairRunStateAborted || s == RepairRunStateDeleted
+}
+
+type RepairSegmentState string
+
+const (
+ RepairSegmentStateNotStarted = RepairSegmentState("NOT_STARTED")
+ RepairSegmentStateRunning = RepairSegmentState("RUNNING")
+ RepairSegmentStateDone = RepairSegmentState("DONE")
+ RepairSegmentStateStarted = RepairSegmentState("STARTED")
+)
+
+type RepairParallelism string
+
+const (
+ RepairParallelismSequential = RepairParallelism("SEQUENTIAL")
+ RepairParallelismParallel = RepairParallelism("PARALLEL")
+ RepairParallelismDatacenterAware = RepairParallelism("DATACENTER_AWARE")
+)
+
+type RepairRunSearchOptions struct {
+
+ // Only return repair runs belonging to this cluster.
+ Cluster string `url:"cluster_name,omitempty"`
+
+ // Only return repair runs belonging to this keyspace.
+ Keyspace string `url:"keyspace_name,omitempty"`
+
+ // Restrict the search to repair runs whose states are in this list
+ States []RepairRunState `url:"state,comma,omitempty"`
+}
+
+type RepairRunCreateOptions struct {
+
+ // Allows to specify which tables are targeted by a repair run. When this parameter is omitted, then the
+ // repair run will target all the tables in its target keyspace.
+ Tables []string `url:"tables,comma,omitempty"`
+
+ // Allows to specify a list of tables that should not be repaired. Cannot be used in conjunction with Tables.
+ IgnoredTables []string `url:"blacklistedTables,comma,omitempty"`
+
+ // Identifies the process, or cause that cause the repair to run.
+ Cause string `url:"cause,omitempty"`
+
+ // Defines the amount of segments per node to create for the repair run. The value must be >0 and <=1000.
+ SegmentCountPerNode int `url:"segmentCountPerNode,omitempty"`
+
+ // Defines the used repair parallelism for repair run.
+ RepairParallelism RepairParallelism `url:"repairParallelism,omitempty"`
+
+ // Defines the used repair parallelism for repair run.
+ Intensity Intensity `url:"intensity,omitempty"`
+
+ // Defines if incremental repair should be done.
+ IncrementalRepair bool `url:"incrementalRepair,omitempty"`
+
+ // Allows to specify a list of nodes whose tokens should be repaired.
+ Nodes []string `url:"nodes,comma,omitempty"`
+
+ // Allows to specify a list of datacenters to repair.
+ Datacenters []string `url:"datacenters,comma,omitempty"`
+
+ // Defines the thread count to use for repair. Since Cassandra 2.2, repairs can be performed with
+ // up to 4 threads in order to parallelize the work on different token ranges.
+ RepairThreadCount int `url:"repairThreadCount,omitempty"`
+}
+```
+
+## RepairSchedule Resource
+
+
+### Methods
+
+
+
+
+ | REST endpoint
+ |
+ Client API method
+ |
+ Comments
+ |
+
+
+ GET /repair_schedule
+ |
+ RepairSchedules(ctx context.Context, searchOptions *RepairScheduleSearchOptions) ([]*RepairSchedule, error)
+ |
+ Already present in the current PR #3.
+ |
+
+
+ GET /repair_schedule/{id}
+ |
+ RepairSchedule(ctx context.Context, repairScheduleId uuid.UUID) (*RepairSchedule, error)
+ |
+
+ |
+
+
+ POST /repair_schedule
+ |
+ CreateRepairSchedule(ctx context.Context, cluster string, keyspace string, owner string, scheduleDaysBetween int, options *RepairScheduleCreateOptions) (uuid.UUID, error)
+ |
+
+ |
+
+
+ POST /repair_schedule/start/{id}
+ |
+ StartRepairSchedule(ctx context.Context, repairScheduleId uuid.UUID) error
+ |
+
+ |
+
+
+ PUT /repair_schedule/{id}
+ |
+ PauseRepairSchedule(ctx context.Context, repairScheduleId uuid.UUID) error
+ |
+ Endpoint will be called with state = PAUSED
+ |
+
+
+ PUT /repair_schedule/{id}
+ |
+ ResumeRepairSchedule(ctx context.Context, repairScheduleId uuid.UUID) error
+ |
+ Endpoint will be called with state = ACTIVE. Contrary to RepairRun, resuming a RepairSchedule is not the same as starting one.
+ |
+
+
+ GET /repair_schedule/{clusterName}/{id}/percent_repaired
+ |
+ RepairSchedulePercentRepaired(ctx context.Context, cluster string, repairScheduleId uuid.UUID) ([]*PercentRepairedMetric, error)
+ |
+
+ |
+
+
+ DELETE /repair_schedule/{id}
+ |
+ DeleteRepairSchedule(ctx context.Context, repairScheduleId uuid.UUID, owner string) error
+ |
+
+ |
+
+
+
+### Types
+
+```
+type RepairSchedule struct {
+ Id uuid.UUID
+ Owner string
+ Cluster string
+ Keyspace string
+ Tables []string
+ State RepairScheduleState
+ Intensity Intensity
+ IncrementalRepair bool
+ RepairParallelism RepairParallelism
+ DaysBetween int
+ Nodes []string
+ Datacenters []string
+ IgnoredTables []string
+ SegmentCountPerNode int
+ RepairThreadCount int
+ RepairUnitId uuid.UUID
+}
+
+type RepairScheduleSearchOptions struct {
+
+ // Only return repair schedules belonging to this cluster.
+ Cluster string `url:"clusterName,omitempty"`
+
+ // Only return repair schedules belonging to this keyspace.
+ Keyspace string `url:"keyspace,omitempty"`
+}
+
+type RepairScheduleCreateOptions struct {
+
+ // Allows to specify which tables are targeted by a repair run. When this parameter is omitted, then the
+ // repair run will target all the tables in its target keyspace.
+ Tables []string `url:"tables,comma,omitempty"`
+
+ // Allows to specify a list of tables that should not be repaired. Cannot be used in conjunction with Tables.
+ IgnoredTables []string `url:"blacklistedTables,comma,omitempty"`
+
+ // Defines the amount of segments per node to create for the repair run. The value must be >0 and <=1000.
+ SegmentCountPerNode int `url:"segmentCountPerNode,omitempty"`
+
+ // Defines the used repair parallelism for repair run.
+ RepairParallelism RepairParallelism `url:"repairParallelism,omitempty"`
+
+ // Defines the used repair parallelism for repair run.
+ Intensity Intensity `url:"intensity,omitempty"`
+
+ // Defines if incremental repair should be done.
+ IncrementalRepair bool `url:"incrementalRepair,omitempty"`
+
+ // When to trigger the next repair run. If not specified, defaults to the next day, at start of day.
+ TriggerTime *time.Time `url:"scheduleTriggerTime,omitempty"`
+
+ // Allows to specify a list of nodes whose tokens should be repaired.
+ Nodes []string `url:"nodes,comma,omitempty"`
+
+ // Allows to specify a list of datacenters to repair.
+ Datacenters []string `url:"datacenters,comma,omitempty"`
+
+ // Defines the thread count to use for repair. Since Cassandra 2.2, repairs can be performed with
+ // up to 4 threads in order to parallelize the work on different token ranges.
+ RepairThreadCount int `url:"repairThreadCount,omitempty"`
+}
+
+type PercentRepairedMetric struct {
+ Cluster string
+ Node string
+ RepairScheduleId uuid.UUID
+ Keyspace string
+ Table string
+ PercentRepaired int
+}
+
+type RepairScheduleState string
+
+const (
+ RepairScheduleStateActive = RepairScheduleState("ACTIVE")
+ RepairScheduleStatePaused = RepairScheduleState("PAUSED")
+ RepairScheduleStateDeleted = RepairScheduleState("DELETED")
+)
+```
+
+## Snapshot Resource
+
+
+### Methods
+
+Methods in this resource come in pairs: one for a specific node, one for a cluster-wide equivalent. They are distinguished by "[VERB]NodeSnapshot"vs "[VERB]ClusterSnapshot".
+
+
+
+
+ | REST endpoint
+ |
+ Client API method
+ |
+ Comments
+ |
+
+
+ GET /snapshot/{clusterName}/{host}
+ |
+ NodeSnapshots(ctx context.Context, cluster string, node string) ([]*Snapshot, error)
+ |
+
+ |
+
+
+ GET /snapshot/cluster/{clusterName}
+ |
+ ClusterSnapshots(ctx context.Context, cluster string) ([]*Snapshot, error)
+ |
+
+ |
+
+
+ POST /snapshot/{clusterName}/{node}
+ |
+ CreateNodeSnapshot(ctx context.Context, cluster string, node string, options *NodeSnapshotCreateOptions) (string, error)
+ |
+
+ |
+
+
+ POST /snapshot/cluster/{clusterName
+ |
+ CreateClusterSnapshot(ctx context.Context, cluster string, options *ClusterSnapshotCreateOptions) (string, error)
+ |
+
+ |
+
+
+ DELETE /snapshot/{clusterName}/{host}/{snapshotName}
+ |
+ DeleteNodeSnapshot(ctx context.Context, cluster string, node string, snapshot string) error
+ |
+
+ |
+
+
+ DELETE /snapshot/cluster/{clusterName}/{snapshotName}
+ |
+ DeleteClusterSnapshot(ctx context.Context, cluster string, snapshot string) error
+ |
+
+ |
+
+
+
+
+
+### Types
+
+
+```
+type Snapshot struct {
+ Name string
+ Node string
+ Cluster string
+ Keyspace string
+ Table string
+ TrueSize float64
+ SizeOnDisk float64
+ Owner string
+ Cause string
+ CreationTime *time.Time
+}
+
+type NodeSnapshotCreateOptions struct {
+ // The name of the snapshot. If omitted, a default name will be generated.
+ Name string `url:"name,omitempty"`
+
+ // The keyspace to create a snapshot for. If omitted, all keyspaces will be snapshot.
+ Keyspace string `url:"keyspace,omitempty"`
+}
+
+type ClusterSnapshotCreateOptions struct {
+ NodeSnapshotCreateOptions
+
+ // The owner of the snapshot. If omitted, the owner will be "reaper".
+ Owner string `url:"owner,omitempty"`
+
+ // The cause of the snapshot. If omitted, the cause will be "Snapshot taken with Reaper".
+ Cause string `url:"cause,omitempty"`
+}
+```
+
+## Node Resource
+
+TODO
+
+
+## Diagnostic Events Resource
+
+TODO