API reference

Kafka Cluster

On this page

This page is generated from the public contract. Descriptions are shown in the original Korean.

논리 Kafka Cluster.

Cluster 조회#

GET /api/messaging-clusters

본문은 400이며 q·sort·page·per_page 외 query·중복 키는 400입니다. 조건 헤더는 무시합니다.

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`handle`	query	`string`	No	handle 정확 일치 필터. 앞뒤 공백 제거·소문자 정규화 후 비교하며 형식이 맞지 않으면 400 INVALID_REQUEST입니다. 기존 q·sort·page·per_page와 함께 사용할 수 있습니다. 결과는 최대 1건입니다.
`q`	query	`string`	No	앞뒤 U+0020 제거, 대소문자 구분 리터럴 부분 검색(name·summary·description 중 하나라도 일치하면 포함)
`sort`	query	`string`	No	생략 시 기존 기본 순서(name 오름차순, ID 오름차순) 유지 Values: `name`, `-name`
`page`	query	`integer`	No	page·per_page 중 하나라도 있으면 페이지 모드. 생략 시 1
`per_page`	query	`integer`	No	생략 시 100, 최대 500

Responses

Status	Description
`200`	성공. 페이지 모드에서만 X-Pagination-* 헤더를 반환합니다.
`400`	오류
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	ORGANIZATION_UNVERIFIED: 현재 Organization 또는 Agent 토큰의 Organization이 인증 대기입니다.
`404`	오류
`405`	오류
`409`	ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`500`	오류

200 response body

An array (Cluster[]). The table lists item fields.

Name	Type	Required	Description
`name`	`string`	Yes
`summary`	`string`	Yes	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	Yes
`environment_description`	`string`	Yes
`external_references`	`Kafka.ExternalReference[]`	Yes
`product`	`"kafka"`	Yes
`id`	`string`	Yes
`handle`	`string`	Yes	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`created_at`	`string(date-time)`	Yes
`updated_at`	`string(date-time)`	Yes

Cluster 생성#

POST /api/messaging-clusters

Cluster 본문은 65536바이트 이하(초과 413)입니다. query는 400이며 조건 헤더는 무시합니다.

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`Origin`	header	`string`	No	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

Request body

application/json · Required: Yes

Type: ClusterCreate

Name	Type	Required	Description
`handle`	`string`	Yes	필수. 앞뒤 공백 제거·소문자 정규화 후 3~39자의 영문 소문자·숫자·단일 하이픈만 허용하며 정규화한 값을 저장합니다. 같은 Organization의 같은 Catalog에서 이미 사용 중이면 409 HANDLE_CONFLICT, 형식 오류는 422 VALIDATION_FAILED(오류 field handle, code invalid_format)입니다.
`name`	`string`	Yes
`summary`	`string`	No	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	No
`environment_description`	`string`	No
`external_references`	`Kafka.ExternalReference[]`	No
`product`	`"kafka"`	Yes

Responses

Status	Description
`201`	성공
`400`	오류
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`404`	오류
`405`	오류
`409`	오류 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`413`	오류
`415`	오류
`422`	오류
`500`	오류

201 response body

Type: Cluster

Name	Type	Required	Description
`name`	`string`	Yes
`summary`	`string`	Yes	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	Yes
`environment_description`	`string`	Yes
`external_references`	`Kafka.ExternalReference[]`	Yes
`product`	`"kafka"`	Yes
`id`	`string`	Yes
`handle`	`string`	Yes	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`created_at`	`string(date-time)`	Yes
`updated_at`	`string(date-time)`	Yes

Cluster 조회#

GET /api/messaging-clusters/{id}

query·본문은 400입니다. If-None-Match가 약한 비교로 일치하면 304와 ETag를 반환합니다.

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes
`If-None-Match`	header	`string`	No	약한 비교, 태그 목록 또는 *

Responses

Status	Description
`200`	성공
`304`	성공
`400`	오류
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	ORGANIZATION_UNVERIFIED: 현재 Organization 또는 Agent 토큰의 Organization이 인증 대기입니다.
`404`	오류
`405`	오류
`409`	ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`500`	오류

200 response body

Type: Cluster

Name	Type	Required	Description
`name`	`string`	Yes
`summary`	`string`	Yes	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	Yes
`environment_description`	`string`	Yes
`external_references`	`Kafka.ExternalReference[]`	Yes
`product`	`"kafka"`	Yes
`id`	`string`	Yes
`handle`	`string`	Yes	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`created_at`	`string(date-time)`	Yes
`updated_at`	`string(date-time)`	Yes

Cluster 전체 수정#

PUT /api/messaging-clusters/{id}

Cluster 본문은 65536바이트 이하(초과 413)입니다. If-Match는 단일 강한 태그가 필수이며 누락 428·형식 오류 400·불일치 412입니다.

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes
`If-Match`	header	`string`	Yes	단일 강한 태그, 누락 428
`Origin`	header	`string`	No	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

Request body

application/json · Required: Yes

Type: ClusterUpdate

Name	Type	Required	Description
`handle`	`string`	No	선택. 생략하면 저장된 값을 유지합니다. 앞뒤 공백 제거·소문자 정규화 후 3~39자의 영문 소문자·숫자·단일 하이픈만 허용하며 정규화한 값을 저장합니다. 같은 Organization의 같은 Catalog에서 이미 사용 중이면 409 HANDLE_CONFLICT, 형식 오류는 422 VALIDATION_FAILED(오류 field handle, code invalid_format)입니다.
`name`	`string`	Yes
`summary`	`string`	Yes	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	Yes
`environment_description`	`string`	Yes
`external_references`	`Kafka.ExternalReference[]`	Yes

Responses

Status	Description
`200`	성공
`400`	오류
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`404`	오류
`405`	오류
`409`	오류 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`412`	오류
`413`	오류
`415`	오류
`422`	오류
`428`	오류
`500`	오류

200 response body

Type: Cluster

Name	Type	Required	Description
`name`	`string`	Yes
`summary`	`string`	Yes	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	Yes
`environment_description`	`string`	Yes
`external_references`	`Kafka.ExternalReference[]`	Yes
`product`	`"kafka"`	Yes
`id`	`string`	Yes
`handle`	`string`	Yes	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`created_at`	`string(date-time)`	Yes
`updated_at`	`string(date-time)`	Yes

Cluster 삭제#

DELETE /api/messaging-clusters/{id}

query·본문은 400입니다. 소속 Topic이 있으면 409입니다. If-Match는 단일 강한 태그가 필수이며 누락 428·형식 오류 400·불일치 412입니다.

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes
`If-Match`	header	`string`	Yes	단일 강한 태그, 누락 428
`Origin`	header	`string`	No	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

Responses

Status	Description
`204`	성공
`400`	오류
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`404`	오류
`405`	오류
`409`	오류 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`412`	오류
`428`	오류
`500`	오류

Cluster 생성 후보 사전 검증#

POST /api/messaging-clusters/validate

실제 저장과 같은 본문·인증·검사 순서를 사용하며 저장하지 않습니다. 성공은 관찰 시점의 유효성으로 저장 성공·ID 예약·충돌 방지를 보장하지 않습니다. ETag·Location은 반환하지 않습니다. 검증 성공 전후 Catalog·자식 데이터·revision·updated_at은 유지되며, SELECT FOR UPDATE 잠금이 발생할 수 있습니다.

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`Origin`	header	`string`	No	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

Request body

application/json · Required: Yes

Type: ClusterCreate

Name	Type	Required	Description
`handle`	`string`	Yes	필수. 앞뒤 공백 제거·소문자 정규화 후 3~39자의 영문 소문자·숫자·단일 하이픈만 허용하며 정규화한 값을 저장합니다. 같은 Organization의 같은 Catalog에서 이미 사용 중이면 409 HANDLE_CONFLICT, 형식 오류는 422 VALIDATION_FAILED(오류 field handle, code invalid_format)입니다.
`name`	`string`	Yes
`summary`	`string`	No	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	No
`environment_description`	`string`	No
`external_references`	`Kafka.ExternalReference[]`	No
`product`	`"kafka"`	Yes

Responses

Status	Description
`200`	저장 없는 검증 성공
`400`	오류
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`404`	오류
`405`	오류
`409`	오류 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`413`	오류
`415`	오류
`422`	오류
`500`	오류

200 response body

Type: ValidationResult

Name	Type	Required	Description
`valid`	`true`	Yes
`operation`	`string`	Yes	Values: `create`, `update`

Cluster 수정 후보 사전 검증#

PUT /api/messaging-clusters/{id}/validate

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes
`If-Match`	header	`string`	Yes	단일 강한 태그, 누락 428
`Origin`	header	`string`	No	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

Request body

application/json · Required: Yes

Type: ClusterUpdate

Name	Type	Required	Description
`handle`	`string`	No	선택. 생략하면 저장된 값을 유지합니다. 앞뒤 공백 제거·소문자 정규화 후 3~39자의 영문 소문자·숫자·단일 하이픈만 허용하며 정규화한 값을 저장합니다. 같은 Organization의 같은 Catalog에서 이미 사용 중이면 409 HANDLE_CONFLICT, 형식 오류는 422 VALIDATION_FAILED(오류 field handle, code invalid_format)입니다.
`name`	`string`	Yes
`summary`	`string`	Yes	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	Yes
`environment_description`	`string`	Yes
`external_references`	`Kafka.ExternalReference[]`	Yes

Responses

Status	Description
`200`	저장 없는 검증 성공
`400`	오류
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`404`	오류
`405`	오류
`409`	오류 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`412`	오류
`413`	오류
`415`	오류
`422`	오류
`428`	오류
`500`	오류

200 response body

Type: ValidationResult

Name	Type	Required	Description
`valid`	`true`	Yes
`operation`	`string`	Yes	Values: `create`, `update`