API 레퍼런스

Kafka Cluster

이 페이지의 내용

이 페이지는 공개 계약에서 생성하며 설명은 원문(한국어) 그대로 표시합니다.

논리 Kafka Cluster.

Cluster 조회#

GET /api/messaging-clusters

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

인증: 세션 쿠키 또는 Agent 토큰

Parameter

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

응답

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

200 응답 본문

배열(Cluster[])이며 표는 항목의 필드입니다.

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

Cluster 생성#

POST /api/messaging-clusters

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

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

요청 본문

application/json · 필수: 예

타입: ClusterCreate

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

응답

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

201 응답 본문

타입: Cluster

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

Cluster 조회#

GET /api/messaging-clusters/{id}

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

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예
`If-None-Match`	header	`string`	아니요	약한 비교, 태그 목록 또는 *

응답

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

200 응답 본문

타입: Cluster

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

Cluster 전체 수정#

PUT /api/messaging-clusters/{id}

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

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예
`If-Match`	header	`string`	예	단일 강한 태그, 누락 428
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

요청 본문

application/json · 필수: 예

타입: ClusterUpdate

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

응답

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

200 응답 본문

타입: Cluster

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

Cluster 삭제#

DELETE /api/messaging-clusters/{id}

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

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예
`If-Match`	header	`string`	예	단일 강한 태그, 누락 428
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

응답

상태	설명
`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 잠금이 발생할 수 있습니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

요청 본문

application/json · 필수: 예

타입: ClusterCreate

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

응답

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

200 응답 본문

타입: ValidationResult

이름	타입	필수	설명
`valid`	`true`	예
`operation`	`string`	예	값: `create`, `update`

Cluster 수정 후보 사전 검증#

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

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예
`If-Match`	header	`string`	예	단일 강한 태그, 누락 428
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

요청 본문

application/json · 필수: 예

타입: ClusterUpdate

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

응답

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

200 응답 본문

타입: ValidationResult

이름	타입	필수	설명
`valid`	`true`	예
`operation`	`string`	예	값: `create`, `update`