Coordinator API Endpoints

Scope

이 문서는 Redis Stream Coordinator가 제공하는 HTTP API endpoint catalog이다. Endpoint의 목록, 인증, mutation 여부, 중복 요청 처리, 요청/응답 핵심 필드만 한 곳에 정리한다.

Endpoint 검색, schema, example, curl snippet은 Scalar API Reference를 우선 사용한다. 실제 실행 환경에서는 http://localhost:8080/scalar로도 확인할 수 있다. 이 Markdown 문서는 설계 관점의 API contract summary로 유지한다. operationId는 생성형 클라이언트에서 사용하는 공개 API 식별자이므로, 의도적인 프로토콜 변경 시에만 변경한다.

상세 동작은 다음 문서를 기준으로 한다.

• heartbeat/reconciliation flow: 02-coordinator-architecture.md
• group state와 assignment model: 03-group-assignment-model.md
• shard scale과 routing: 04-resharding-routing.md
• config, monitoring, metrics: 06-data-config-observability.md

Base Contract

Base path:

/coord/v1

Common headers:

Content-Type: application/json
Accept: application/json
Authorization: Bearer <token-from-POST-/coord/v1/auth/login>
X-Request-Id: <caller-generated-id>

X-Request-Id는 선택값이지만 admin mutation, Terraform apply, CI automation, incident replay에서는 강하게 권장한다. 값이 있으면 coordinator audit log에 기록한다.

Path parameters:

Auth policy:

Common response fields:

Common status codes:

Endpoint Index

Admin API

Create Group

POST /coord/v1/streams/{streamPrefix}

초기 stream shard metadata와 shard count를 생성한다. 공식 create path는 streamPrefix만 받는다. Consumer group은 consumer runtime configuration에서 오며 heartbeat를 통해 수렴한다.

Request body:

Response summary:

Duplicate request behavior:

• stream prefix에 coordinator metadata가 이미 있으면 409 Conflict로 거절한다.
• POST /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}는 이전 automation 호환용으로만 남긴다.

Get Group Metadata

GET /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}

Returns group source-of-truth metadata. This is an admin/debug endpoint, not the member heartbeat assignment channel.

Response summary:

Delete Group

DELETE /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}

Inactive group의 coordinator metadata를 삭제한다. Live member가 정상 leave할 수 없는 운영 복구 상황에서만 force=true를 사용한다.

Request body:

Response summary:

Failure behavior:

• group이 없으면 404 Not Found와 GROUP_NOT_FOUND를 반환한다.
• live member가 있고 force=false이면 422 Unprocessable Entity로 거절한다.

Get Producer Routing Metadata

GET /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}/producer-routing

Returns the routing metadata that producers need to route partition keys to Redis Stream shards. This endpoint is read-only and does not create streams, change shard counts, or mutate group assignment.

Producer routing formula:

shardIndex = routeV1(partitionKey, shardCount)
streamKey = format(streamKeyPattern, shardIndex)

routeV1 is a fixed protocol contract, not group metadata. The starter computes a 32-bit Murmur3 hash and maps it into [0, shardCount) using deterministic rejection sampling so 2^32 % shardCount tail values do not create modulo bias. Future incompatible routing changes must use a new protocol/API version instead of storing per-group hash settings.

Routing is deterministic only for the returned shardCount, routing protocol, and partition key. After shard scale-out/in, the same partition key may route to a different stream key. The coordinator does not provide global event id deduplication across every shard.

Response summary:

Scale Stream

POST /coord/v1/streams/{streamPrefix}/scale

Stream prefix의 shard scale-out/in을 시작한다. Consumer group은 이 요청 path에 포함하지 않는다. 해당 stream을 읽는 모든 consumer group은 다음 heartbeat에서 변경된 shard set을 보고 각자 assignment를 재계산한다.

Scale-in 완료는 heartbeat만으로 판단하지 않는다. 제거 대상 shard에 live owner가 있으면 coordinator는 heartbeat revoke progress를 기다린다. Live member가 모두 expire되면 Redis-level drain check로 진행하고, 제거 대상 shard의 모든 Redis consumer group이 pending=0과 known lag=0을 보고할 때만 완료한다.

Duplicate-sensitive workload는 이 endpoint 호출 전에 producer를 멈추고 in-flight publish retry를 drain해야 한다.

Request body:

stream-level scale request는 shard count만 변경한다. consume parallelism은 consumer application이 @StreamListener(concurrency = N) 같은 runtime 설정으로 정한다. coordinator는 heartbeat로 들어온 logical member들을 관찰하고 assignment를 계산할 뿐, admin API로 consumer runtime parallelism을 변경하지 않는다.

Compatibility note: 현재 구현 단계에서는 POST /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}/scale도 남아 있지만, 운영자가 사용할 공식 scale path는 stream-scoped endpoint이다.

Response summary:

Duplicate request behavior:

• active migration이 있으면 새 migration을 만들지 않고 409 Conflict로 거절한다.
• targetShardCount가 현재 active shard count와 같으면 새 migration을 만들지 않고 no-op response로 처리한다.

Get Migration

GET /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}/migrations/{reshardingId}

Returns one migration state and drain progress.

Response summary:

Rollback Migration

POST /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}/migrations/{reshardingId}/rollback

Requests rollback inside the supported rollback window. Already-written messages in newly added shard indexes are handled by the operational drain/replay policy.

Request body:

Response summary:

Duplicate request behavior:

• migration이 이미 rollback 상태이면 현재 migration state를 반환한다.
• rollback window가 지났거나 migration state가 rollback 불가능하면 422 Unprocessable Entity로 거절한다.

Member API

Heartbeat

POST /coord/v1/streams/{streamPrefix}/groups/{consumerGroup}/members/{memberId}/heartbeat

Member liveness, owned shards, and revoke ack are reported through this endpoint. Coordinator assignment is returned in the same response. There is no separate assignment polling endpoint.

KIP-848 mapping:

• GroupId is represented by {streamPrefix, consumerGroup} in the HTTP path.
• TopicPartitions is represented by ownedShards.
• Assignment.AssignedTopicPartitions is represented by assignment.assignedShards.
• Assignment.PendingTopicPartitions is represented by assignment.pendingShards.

Request body:

Epoch validation:

• memberEpoch=0 is accepted only for a new member or a member already fenced/expired by the coordinator.
• An active member cannot reset itself by sending memberEpoch=0; the coordinator rejects it as INVALID_REQUEST.
• Positive memberEpoch must match the epoch last issued by the coordinator for that member.
• A lower positive epoch is stale and returns FENCED_MEMBER_EPOCH.
• A higher positive epoch is not coordinator-issued and returns INVALID_REQUEST.
• Negative values other than the graceful leave sentinel -1 return INVALID_REQUEST.

Response body:

Status behavior:

Mutation behavior:

• Updates member heartbeat time and member metadata.
• Stores member owned shard report as current assignment.
• Stores revoke ack progress.
• May bump group epoch when join/leave/fencing changes membership.
• Does not read, ack, retry, or modify Redis Stream messages.

Monitoring API

Monitoring API is read-only. State changes must go through Admin API or member heartbeat.

Health

GET /coord/v1/monitoring/health

Response summary:

Monitoring Session

GET /coord/v1/monitoring/session

Response summary:

Compatibility

GET /coord/v1/monitoring/compatibility

Response summary:

List Groups

GET /coord/v1/monitoring/groups

Response summary:

Get Group Monitoring Summary

GET /coord/v1/monitoring/streams/{streamPrefix}/groups/{consumerGroup}

Response summary:

List Members

GET /coord/v1/monitoring/streams/{streamPrefix}/groups/{consumerGroup}/members

Response summary:

Get Assignments

GET /coord/v1/monitoring/streams/{streamPrefix}/groups/{consumerGroup}/assignments

Response summary:

Get Consumption Progress

GET /coord/v1/monitoring/streams/{streamPrefix}/groups/{consumerGroup}/consumption

Response summary:

List Migrations

GET /coord/v1/monitoring/streams/{streamPrefix}/groups/{consumerGroup}/migrations

Response summary:

Explicitly Unsupported Endpoints

The coordinator does not provide these API surfaces in the MVP:

• producer routing mutation endpoint
• member startup desired spec sync endpoint
• direct Redis Stream read/ack endpoint
• handler/retry/DLQ/idempotency marker endpoint
• assignor selection or assignor negotiation endpoint
• Kafka wire protocol endpoint