API 레퍼런스

Kafka Topic

이 페이지의 내용

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

Cluster 소속 Topic, Message Definition·사용 설명 항목.

Topic 조회#

GET /api/messaging-clusters/{cluster_id}/topics

q·sort·page·per_page를 모두 생략하면 전체 배열을 반환합니다. 다른 query·중복 키와 본문은 400이며 조건 헤더는 무시합니다.

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

Parameter

이름	위치	타입	필수	설명
`cluster_id`	path	`string`	예
`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 응답 본문

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

이름	타입	필수	설명
`name`	`string`	예
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예
`partition_count`	`integer \| null`	예
`cleanup_policy`	`any[] \| null`	예
`time_retention_ms`	`integer \| null`	예
`retention_order_description`	`string`	예
`external_references`	`Kafka.ExternalReference[]`	예
`message_definitions`	`MessageDefinition[]`	예
`usages`	`Usage[]`	예
`cluster_id`	`string`	예
`id`	`string`	예
`created_at`	`string(date-time)`	예
`updated_at`	`string(date-time)`	예

Topic 생성#

POST /api/messaging-clusters/{cluster_id}/topics

Topic 본문은 4194304바이트 이하(초과 413)입니다. 부모 Cluster가 없으면 404 CLUSTER_NOT_FOUND입니다. query는 400이며 조건 헤더는 무시합니다.

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

Parameter

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

요청 본문

application/json · 필수: 예

타입: TopicCreate

이름	타입	필수	설명
`name`	`string`	예
`summary`	`string`	아니요	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	아니요
`partition_count`	`integer \| null`	아니요
`cleanup_policy`	`any[] \| null`	아니요
`time_retention_ms`	`integer \| null`	아니요
`retention_order_description`	`string`	아니요
`external_references`	`Kafka.ExternalReference[]`	아니요
`message_definitions`	`MessageDefinition[]`	아니요
`usages`	`UsageInput[]`	아니요

응답

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

201 응답 본문

타입: Topic

이름	타입	필수	설명
`name`	`string`	예
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예
`partition_count`	`integer \| null`	예
`cleanup_policy`	`any[] \| null`	예
`time_retention_ms`	`integer \| null`	예
`retention_order_description`	`string`	예
`external_references`	`Kafka.ExternalReference[]`	예
`message_definitions`	`MessageDefinition[]`	예
`usages`	`Usage[]`	예
`cluster_id`	`string`	예
`id`	`string`	예
`created_at`	`string(date-time)`	예
`updated_at`	`string(date-time)`	예

Topic 조회#

GET /api/kafka-topics/{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 응답 본문

타입: Topic

이름	타입	필수	설명
`name`	`string`	예
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예
`partition_count`	`integer \| null`	예
`cleanup_policy`	`any[] \| null`	예
`time_retention_ms`	`integer \| null`	예
`retention_order_description`	`string`	예
`external_references`	`Kafka.ExternalReference[]`	예
`message_definitions`	`MessageDefinition[]`	예
`usages`	`Usage[]`	예
`cluster_id`	`string`	예
`id`	`string`	예
`created_at`	`string(date-time)`	예
`updated_at`	`string(date-time)`	예

Topic 전체 수정#

PUT /api/kafka-topics/{id}

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

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

Parameter

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

요청 본문

application/json · 필수: 예

타입: TopicUpdate

이름	타입	필수	설명
`name`	`string`	예
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예
`partition_count`	`integer \| null`	예
`cleanup_policy`	`any[] \| null`	예
`time_retention_ms`	`integer \| null`	예
`retention_order_description`	`string`	예
`external_references`	`Kafka.ExternalReference[]`	예
`message_definitions`	`MessageDefinition[]`	예
`usages`	`UsageInput[]`	예

응답

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

200 응답 본문

타입: Topic

이름	타입	필수	설명
`name`	`string`	예
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예
`partition_count`	`integer \| null`	예
`cleanup_policy`	`any[] \| null`	예
`time_retention_ms`	`integer \| null`	예
`retention_order_description`	`string`	예
`external_references`	`Kafka.ExternalReference[]`	예
`message_definitions`	`MessageDefinition[]`	예
`usages`	`Usage[]`	예
`cluster_id`	`string`	예
`id`	`string`	예
`created_at`	`string(date-time)`	예
`updated_at`	`string(date-time)`	예

Topic 삭제#

DELETE /api/kafka-topics/{id}

query·본문은 400입니다. 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`	오류

현재 Organization 전체 Topic 조회#

GET /api/kafka-topics

현재 Organization의 default Workspace 안의 모든 Cluster 소속 Topic을 조회합니다. cluster_id를 포함한 기존 객체 배열을 반환합니다. q·sort·page·per_page는 다른 Catalog 목록과 같은 공통 목록 규칙을 따릅니다. 페이지 옵션을 생략하면 전체 배열을 반환합니다. 쓰기는 지원하지 않습니다(Allow: GET).

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

Parameter

이름	위치	타입	필수	설명
`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이 인증 대기입니다.
`405`	지원하지 않는 Method. HEAD 응답에는 본문이 없습니다.
`409`	ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`500`	오류

200 응답 본문

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

이름	타입	필수	설명
`name`	`string`	예
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예
`partition_count`	`integer \| null`	예
`cleanup_policy`	`any[] \| null`	예
`time_retention_ms`	`integer \| null`	예
`retention_order_description`	`string`	예
`external_references`	`Kafka.ExternalReference[]`	예
`message_definitions`	`MessageDefinition[]`	예
`usages`	`Usage[]`	예
`cluster_id`	`string`	예
`id`	`string`	예
`created_at`	`string(date-time)`	예
`updated_at`	`string(date-time)`	예

사용 설명 한 항목 추가 또는 교체#

PUT /api/kafka-topics/{topic_id}/usages/{id}

Topic 상세 ETag가 필수입니다. 같은 ID는 교체, 없는 ID는 배열 끝에 추가합니다. 같은 ID·정규화된 내용이면 시각·revision을 유지합니다. stale ETag는 내용 일치보다 먼저 412로 거부합니다. 성공은 최신 Topic이며 ETag는 상세 GET으로 다시 읽습니다.

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

Parameter

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

요청 본문

application/json · 필수: 예

UTF-8 JSON 64 KiB 이하. ID는 본문 대신 경로에 지정합니다.

타입: UsageBody

이름	타입	필수	설명
`direction`	`any`	예	값: `producer`, `consumer`
`application_name`	`string`	예
`description`	`string`	예
`consumer_group`	`string \| null`	예
`service_id`	`string \| null`	아니요	선택적 사용 Service 참조. 현재 Organization의 Service ID이며 생략·null은 미연결입니다. 없는 Service는 422 service_id / not_found입니다. application_name에서 추정해 연결하지 않습니다.

응답

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

200 응답 본문

타입: Topic

이름	타입	필수	설명
`name`	`string`	예
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예
`partition_count`	`integer \| null`	예
`cleanup_policy`	`any[] \| null`	예
`time_retention_ms`	`integer \| null`	예
`retention_order_description`	`string`	예
`external_references`	`Kafka.ExternalReference[]`	예
`message_definitions`	`MessageDefinition[]`	예
`usages`	`Usage[]`	예
`cluster_id`	`string`	예
`id`	`string`	예
`created_at`	`string(date-time)`	예
`updated_at`	`string(date-time)`	예

사용 설명 한 항목 삭제#

DELETE /api/kafka-topics/{topic_id}/usages/{id}

Topic 상세 ETag가 필수입니다. 항목이 이미 없으면 최신 ETag에서 no-op입니다. stale ETag는 412입니다. 성공은 최신 Topic이며 ETag는 상세 GET으로 다시 읽습니다.

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

Parameter

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

응답

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

200 응답 본문

타입: Topic

이름	타입	필수	설명
`name`	`string`	예
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예
`partition_count`	`integer \| null`	예
`cleanup_policy`	`any[] \| null`	예
`time_retention_ms`	`integer \| null`	예
`retention_order_description`	`string`	예
`external_references`	`Kafka.ExternalReference[]`	예
`message_definitions`	`MessageDefinition[]`	예
`usages`	`Usage[]`	예
`cluster_id`	`string`	예
`id`	`string`	예
`created_at`	`string(date-time)`	예
`updated_at`	`string(date-time)`	예

Topic 생성 후보 사전 검증#

POST /api/messaging-clusters/{cluster_id}/topics/validate

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

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

Parameter

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

요청 본문

application/json · 필수: 예

타입: TopicCreate

이름	타입	필수	설명
`name`	`string`	예
`summary`	`string`	아니요	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	아니요
`partition_count`	`integer \| null`	아니요
`cleanup_policy`	`any[] \| null`	아니요
`time_retention_ms`	`integer \| null`	아니요
`retention_order_description`	`string`	아니요
`external_references`	`Kafka.ExternalReference[]`	아니요
`message_definitions`	`MessageDefinition[]`	아니요
`usages`	`UsageInput[]`	아니요

응답

상태	설명
`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`

Topic 수정 후보 사전 검증#

PUT /api/kafka-topics/{id}/validate

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

Parameter

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

요청 본문

application/json · 필수: 예

타입: TopicUpdate

이름	타입	필수	설명
`name`	`string`	예
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예
`partition_count`	`integer \| null`	예
`cleanup_policy`	`any[] \| null`	예
`time_retention_ms`	`integer \| null`	예
`retention_order_description`	`string`	예
`external_references`	`Kafka.ExternalReference[]`	예
`message_definitions`	`MessageDefinition[]`	예
`usages`	`UsageInput[]`	예

응답

상태	설명
`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`