API 레퍼런스

Service

이 페이지의 내용

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

Service CRUD와 API 구현·Repository·Database·Key Pattern·Kafka 사용 연결과 역조회.

Service 목록#

GET /api/services

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

Parameter

이름	위치	타입	필수	설명
`handle`	query	`string`	아니요	handle 정확 일치 필터. 앞뒤 공백 제거·소문자 정규화 후 비교하며 형식이 맞지 않으면 400 INVALID_REQUEST입니다. 기존 q·sort·page·per_page와 함께 사용할 수 있습니다. 결과는 최대 1건입니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`status`	`string`	예	수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. 값: `planned`, `active`, `retired`

Service 생성#

POST /api/services

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

요청 본문

application/json · 필수: 예

JSON 객체 하나, UTF-8·중복 키·미정의 필드 엄격 검사, 본문 최대 64 KiB. 일반 필드 검증은 조건 평가 전이며 참조 Service 존재 검사는 조건 평가 뒤입니다.

타입: CreateService

이름	타입	필수	설명
`handle`	`string`	예	필수. 앞뒤 공백 제거·소문자 정규화 후 3~39자의 영문 소문자·숫자·단일 하이픈만 허용하며 정규화한 값을 저장합니다. 같은 Organization의 같은 Catalog에서 이미 사용 중이면 409 HANDLE_CONFLICT, 형식 오류는 422 VALIDATION_FAILED(오류 field /handle, code invalid_format)입니다.
`name`	`string`	예	앞뒤 U+0020 공백 제거 후 1~200 유니코드 코드 포인트. 제어문자는 제거 전에 거부하며 범위는 U+0000~U+001F·U+007F~U+009F입니다. 다른 유니코드 공백·정규화는 적용하지 않습니다. 정규화 전 입력에는 maxLength 200을 적용하지 않습니다.
`summary`	`string`	아니요	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	아니요	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`status`	`string`	아니요	수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. 값: `planned`, `active`, `retired`

응답

상태	설명
`201`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`413`	PAYLOAD_TOO_LARGE
`415`	UNSUPPORTED_MEDIA_TYPE
`422`	VALIDATION_FAILED
`500`	INTERNAL_ERROR

201 응답 본문

타입: Service

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`status`	`string`	예	수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. 값: `planned`, `active`, `retired`

Service 상세#

GET /api/services/{id}

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-None-Match`	header	`string`	아니요	상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. 와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다.

응답

상태	설명
`200`	성공
`304`	If-None-Match 약한 비교 일치, 본문·Content-Type 없음
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

타입: Service

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`status`	`string`	예	수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. 값: `planned`, `active`, `retired`

Service 전체 수정#

PUT /api/services/{id}

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-Match`	header	`string`	예	대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다.

요청 본문

application/json · 필수: 예

타입: ReplaceService

이름	타입	필수	설명
`handle`	`string`	아니요	선택. 생략하면 저장된 값을 유지합니다. 앞뒤 공백 제거·소문자 정규화 후 3~39자의 영문 소문자·숫자·단일 하이픈만 허용하며 정규화한 값을 저장합니다. 같은 Organization의 같은 Catalog에서 이미 사용 중이면 409 HANDLE_CONFLICT, 형식 오류는 422 VALIDATION_FAILED(오류 field /handle, code invalid_format)입니다.
`name`	`string`	예	앞뒤 U+0020 공백 제거 후 1~200 유니코드 코드 포인트. 제어문자는 제거 전에 거부하며 범위는 U+0000~U+001F·U+007F~U+009F입니다. 다른 유니코드 공백·정규화는 적용하지 않습니다. 정규화 전 입력에는 maxLength 200을 적용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`status`	`string`	예	수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. 값: `planned`, `active`, `retired`

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`412`	PRECONDITION_FAILED
`413`	PAYLOAD_TOO_LARGE
`415`	UNSUPPORTED_MEDIA_TYPE
`422`	VALIDATION_FAILED
`428`	PRECONDITION_REQUIRED
`500`	INTERNAL_ERROR

200 응답 본문

타입: Service

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`status`	`string`	예	수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. 값: `planned`, `active`, `retired`

미연결 Service 삭제#

DELETE /api/services/{id}

API 구현·Repository·Database·Key Pattern·Table·Collection·Cassandra Table 연결 또는 Kafka 사용 설명의 참조가 남은 Service는 409 SERVICE_IN_USE입니다. 연쇄 삭제·자동 해제하지 않습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-Match`	header	`string`	예	대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다.

응답

상태	설명
`204`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`412`	PRECONDITION_FAILED
`428`	PRECONDITION_REQUIRED
`500`	INTERNAL_ERROR

Service가 구현하는 API 목록#

GET /api/services/{id}/apis

apis.service_id가 현재 Service를 가리키는 API만 조회합니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`base_urls`	`BaseURL[]`	예	API 소유 호출 기준 주소 목록. 저장 순서를 그대로 반환하며 정규화 후 같은 주소는 한 번만 있습니다. 주소가 없으면 빈 배열입니다. 소속 Endpoint는 이 목록을 공통으로 사용합니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`security`	`SecurityDeclaration`	예

Service 연결 Repository 집합 조회#

GET /api/services/{id}/repository-links

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-None-Match`	header	`string`	아니요	상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. 와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다.

응답

상태	설명
`200`	성공
`304`	If-None-Match 약한 비교 일치, 본문·Content-Type 없음
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

타입: ServiceRepositories

이름	타입	필수	설명
`service_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`repository_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.

Service 연결 Repository 집합 전체 교체#

PUT /api/services/{id}/repository-links

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-Match`	header	`string`	예	대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다.

요청 본문

application/json · 필수: 예

JSON 객체 하나, UTF-8·중복 키·미정의 필드 엄격 검사, 본문 최대 64 KiB. 일반 필드 검증은 조건 평가 전이며 참조 Repository 존재 검사는 조건 평가 뒤입니다.

타입: ReplaceServiceRepositories

이름	타입	필수	설명
`repository_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`412`	PRECONDITION_FAILED
`413`	PAYLOAD_TOO_LARGE
`415`	UNSUPPORTED_MEDIA_TYPE
`422`	VALIDATION_FAILED
`428`	PRECONDITION_REQUIRED
`500`	INTERNAL_ERROR

200 응답 본문

타입: ServiceRepositories

이름	타입	필수	설명
`service_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`repository_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.

Service의 연결 Repository 목록#

GET /api/services/{id}/repositories

현재 Organization의 부모 Service·연결·Repository Metadata를 같은 읽기 전용 Snapshot에서 조회합니다. 빈 집합은 빈 배열, 미존재·다른 Organization의 Service는 404입니다. ETag를 반환하거나 조건 헤더를 평가하지 않습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예
`git_url`	`string`	예	수동 기록한 HTTPS·SSH URL 또는 SCP 형태 SSH 주소.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`external_identity`	`RepositoryExternalIdentity`	예	같은 Organization에서 유일한 외부 키. PUT 생략은 보존, 명시적 null은 해제합니다.

Repository의 연결 Service 목록#

GET /api/repositories/{id}/services

현재 Organization의 부모 Repository·연결·Service Metadata를 같은 읽기 전용 Snapshot에서 조회합니다. 빈 집합은 빈 배열, 미존재·다른 Organization의 Repository는 404입니다. ETag를 반환하거나 조건 헤더를 평가하지 않습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`status`	`string`	예	수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. 값: `planned`, `active`, `retired`

Service를 참조하는 Kafka 사용 설명 목록#

GET /api/services/{id}/kafka-usages

현재 Organization의 부모 Service와 이 Service를 참조하는 Kafka 사용 설명을 Topic·Cluster 이름과 함께 같은 읽기 전용 Snapshot에서 조회합니다. 정렬은 topic_name·cluster_name·topic_id·usage_id 순이고 sort=-name은 역순, q는 topic_name의 부분 문자열입니다. 편집은 Topic의 사용 설명 경로에서만 합니다. 빈 집합은 빈 배열, 미존재·다른 Organization의 Service는 404입니다. ETag를 반환하거나 조건 헤더를 평가하지 않습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`topic_id`	`string`	예
`topic_name`	`string`	예
`cluster_id`	`string`	예
`cluster_name`	`string`	예
`usage_id`	`string`	예
`direction`	`any`	예	값: `producer`, `consumer`
`application_name`	`string`	예
`description`	`string`	예
`consumer_group`	`string \| null`	예

Database 연결 Service 집합 조회#

GET /api/databases/{id}/service-links

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-None-Match`	header	`string`	아니요	상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. 와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다.

응답

상태	설명
`200`	성공
`304`	If-None-Match 약한 비교 일치, 본문·Content-Type 없음
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

타입: DatabaseServiceLinks

이름	타입	필수	설명
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`database_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

Database 연결 Service 집합 전체 교체#

PUT /api/databases/{id}/service-links

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-Match`	header	`string`	예	대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다.

요청 본문

application/json · 필수: 예

타입: ReplaceDatabaseServiceLinks

이름	타입	필수	설명
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`412`	PRECONDITION_FAILED
`413`	PAYLOAD_TOO_LARGE
`415`	UNSUPPORTED_MEDIA_TYPE
`422`	VALIDATION_FAILED
`428`	PRECONDITION_REQUIRED
`500`	INTERNAL_ERROR

200 응답 본문

타입: DatabaseServiceLinks

이름	타입	필수	설명
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`database_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

Database의 직접 연결 Service 목록#

GET /api/databases/{id}/services

같은 Snapshot의 Database·직접 연결·Service Metadata를 조회합니다. 자동 상속하지 않으며 빈 집합은 빈 배열, 다른 경계·미존재 부모는 404입니다. ETag는 없습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`status`	`string`	예	수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. 값: `planned`, `active`, `retired`

Service의 직접 연결 Database 목록#

GET /api/services/{id}/databases

같은 Snapshot의 Service·직접 연결·리소스와 현재 부모 Database를 조회합니다. name은 Database 이름 또는 Key Pattern template이며 q는 name 부분 일치, 정렬은 name·id 순입니다. 빈 집합은 빈 배열, 다른 경계·미존재 Service는 404입니다. ETag는 없습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`name`	`string`	예
`summary`	`string`	예
`database_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`database_name`	`string`	예
`engine`	`string`	예

KeyPattern 연결 Service 집합 조회#

GET /api/key-patterns/{id}/service-links

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-None-Match`	header	`string`	아니요	상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. 와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다.

응답

상태	설명
`200`	성공
`304`	If-None-Match 약한 비교 일치, 본문·Content-Type 없음
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

타입: KeyPatternServiceLinks

이름	타입	필수	설명
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`key_pattern_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

KeyPattern 연결 Service 집합 전체 교체#

PUT /api/key-patterns/{id}/service-links

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-Match`	header	`string`	예	대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다.

요청 본문

application/json · 필수: 예

타입: ReplaceKeyPatternServiceLinks

이름	타입	필수	설명
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`412`	PRECONDITION_FAILED
`413`	PAYLOAD_TOO_LARGE
`415`	UNSUPPORTED_MEDIA_TYPE
`422`	VALIDATION_FAILED
`428`	PRECONDITION_REQUIRED
`500`	INTERNAL_ERROR

200 응답 본문

타입: KeyPatternServiceLinks

이름	타입	필수	설명
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`key_pattern_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

KeyPattern의 직접 연결 Service 목록#

GET /api/key-patterns/{id}/services

같은 Snapshot의 KeyPattern·직접 연결·Service Metadata를 조회합니다. 자동 상속하지 않으며 빈 집합은 빈 배열, 다른 경계·미존재 부모는 404입니다. ETag는 없습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`status`	`string`	예	수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. 값: `planned`, `active`, `retired`

Service의 직접 연결 KeyPattern 목록#

GET /api/services/{id}/key-patterns

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`name`	`string`	예
`summary`	`string`	예
`database_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`database_name`	`string`	예
`engine`	`string`	예

Table 연결 Service 집합 조회#

GET /api/tables/{id}/service-links

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-None-Match`	header	`string`	아니요	상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. 와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다.

응답

상태	설명
`200`	성공
`304`	If-None-Match 약한 비교 일치, 본문·Content-Type 없음
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

타입: TableServiceLinks

이름	타입	필수	설명
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`table_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

Table 연결 Service 집합 전체 교체#

PUT /api/tables/{id}/service-links

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-Match`	header	`string`	예	대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다.

요청 본문

application/json · 필수: 예

타입: ReplaceTableServiceLinks

이름	타입	필수	설명
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`412`	PRECONDITION_FAILED
`413`	PAYLOAD_TOO_LARGE
`415`	UNSUPPORTED_MEDIA_TYPE
`422`	VALIDATION_FAILED
`428`	PRECONDITION_REQUIRED
`500`	INTERNAL_ERROR

200 응답 본문

타입: TableServiceLinks

이름	타입	필수	설명
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`table_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

Table의 직접 연결 Service 목록#

GET /api/tables/{id}/services

같은 Snapshot의 Table·직접 연결·Service Metadata를 조회합니다. 자동 상속하지 않으며 빈 집합은 빈 배열, 다른 경계·미존재 부모는 404입니다. ETag는 없습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`status`	`string`	예	수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. 값: `planned`, `active`, `retired`

Service의 직접 연결 Table 목록#

GET /api/services/{id}/tables

같은 Snapshot의 Service·직접 연결·리소스와 현재 부모 Database를 조회합니다. name은 namespace가 있으면 namespace.name, 없으면 Table 이름이며 q는 name 부분 일치, 정렬은 name·id 순입니다. 빈 집합은 빈 배열, 다른 경계·미존재 Service는 404입니다. ETag는 없습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`name`	`string`	예
`summary`	`string`	예
`database_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`database_name`	`string`	예
`engine`	`string`	예

Collection 연결 Service 집합 조회#

GET /api/collections/{id}/service-links

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-None-Match`	header	`string`	아니요	상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. 와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다.

응답

상태	설명
`200`	성공
`304`	If-None-Match 약한 비교 일치, 본문·Content-Type 없음
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

타입: CollectionServiceLinks

이름	타입	필수	설명
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`collection_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

Collection 연결 Service 집합 전체 교체#

PUT /api/collections/{id}/service-links

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-Match`	header	`string`	예	대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다.

요청 본문

application/json · 필수: 예

타입: ReplaceCollectionServiceLinks

이름	타입	필수	설명
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`412`	PRECONDITION_FAILED
`413`	PAYLOAD_TOO_LARGE
`415`	UNSUPPORTED_MEDIA_TYPE
`422`	VALIDATION_FAILED
`428`	PRECONDITION_REQUIRED
`500`	INTERNAL_ERROR

200 응답 본문

타입: CollectionServiceLinks

이름	타입	필수	설명
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`collection_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

Collection의 직접 연결 Service 목록#

GET /api/collections/{id}/services

같은 Snapshot의 Collection·직접 연결·Service Metadata를 조회합니다. 자동 상속하지 않으며 빈 집합은 빈 배열, 다른 경계·미존재 부모는 404입니다. ETag는 없습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`status`	`string`	예	수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. 값: `planned`, `active`, `retired`

Service의 직접 연결 Collection 목록#

GET /api/services/{id}/collections

같은 Snapshot의 Service·직접 연결·리소스와 현재 부모 Database를 조회합니다. name은 Collection 이름이며 q는 name 부분 일치, 정렬은 name·id 순입니다. 빈 집합은 빈 배열, 다른 경계·미존재 Service는 404입니다. ETag는 없습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`name`	`string`	예
`summary`	`string`	예
`database_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`database_name`	`string`	예
`engine`	`string`	예

CassandraTable 연결 Service 집합 조회#

GET /api/cassandra-tables/{id}/service-links

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-None-Match`	header	`string`	아니요	상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. 와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다.

응답

상태	설명
`200`	성공
`304`	If-None-Match 약한 비교 일치, 본문·Content-Type 없음
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

타입: CassandraTableServiceLinks

이름	타입	필수	설명
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`cassandra_table_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

CassandraTable 연결 Service 집합 전체 교체#

PUT /api/cassandra-tables/{id}/service-links

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-Match`	header	`string`	예	대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다.

요청 본문

application/json · 필수: 예

타입: ReplaceCassandraTableServiceLinks

이름	타입	필수	설명
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`412`	PRECONDITION_FAILED
`413`	PAYLOAD_TOO_LARGE
`415`	UNSUPPORTED_MEDIA_TYPE
`422`	VALIDATION_FAILED
`428`	PRECONDITION_REQUIRED
`500`	INTERNAL_ERROR

200 응답 본문

타입: CassandraTableServiceLinks

이름	타입	필수	설명
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`cassandra_table_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`service_ids`	`string[]`	예	0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다.

CassandraTable의 직접 연결 Service 목록#

GET /api/cassandra-tables/{id}/services

같은 Snapshot의 CassandraTable·직접 연결·Service Metadata를 조회합니다. 자동 상속하지 않으며 빈 집합은 빈 배열, 다른 경계·미존재 부모는 404입니다. ETag는 없습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`status`	`string`	예	수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. 값: `planned`, `active`, `retired`

Service의 직접 연결 CassandraTable 목록#

GET /api/services/{id}/cassandra-tables

같은 Snapshot의 Service·직접 연결·리소스와 현재 부모 Database를 조회합니다. name은 Cassandra Table 이름이며 q는 name 부분 일치, 정렬은 name·id 순입니다. 빈 집합은 빈 배열, 다른 경계·미존재 Service는 404입니다. ETag는 없습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`q`	query	`string`	아니요	name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

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

이름	타입	필수	설명
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`name`	`string`	예
`summary`	`string`	예
`database_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`database_name`	`string`	예
`engine`	`string`	예

API 제공 Service 조회#

GET /api/apis/{api_id}/service

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

Parameter

이름	위치	타입	필수	설명
`api_id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-None-Match`	header	`string`	아니요	상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. 와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다.

응답

상태	설명
`200`	성공
`304`	If-None-Match 약한 비교 일치, 본문·Content-Type 없음
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`500`	INTERNAL_ERROR

200 응답 본문

타입: APIService

이름	타입	필수	설명
`api_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`service_id`	`string \| null`	예
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.

API 제공 Service 확정#

PUT /api/apis/{api_id}/service

제공 Service를 문자열 ID 또는 null로 확정합니다. Metadata revision은 바꾸지 않습니다.

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

Parameter

이름	위치	타입	필수	설명
`api_id`	path	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`If-Match`	header	`string`	예	대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다.

요청 본문

application/json · 필수: 예

JSON 객체 하나, UTF-8·중복 키·미정의 필드 엄격 검사, 본문 최대 4 MiB. 일반 필드 검증은 조건 평가 전이며 참조 Service 존재 검사는 조건 평가 뒤입니다.

타입: ReplaceAPIService

이름	타입	필수	설명
`service_id`	`string \| null`	예

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	SERVICE_NOT_FOUND·API_NOT_FOUND
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·SERVICE_NAME_CONFLICT·SERVICE_IN_USE·API_IN_USE·DATABASE_IN_USE·KEY_PATTERN_IN_USE·TABLE_IN_USE·COLLECTION_IN_USE·CASSANDRA_TABLE_IN_USE
`412`	PRECONDITION_FAILED
`413`	PAYLOAD_TOO_LARGE
`415`	UNSUPPORTED_MEDIA_TYPE
`422`	VALIDATION_FAILED
`428`	PRECONDITION_REQUIRED
`500`	INTERNAL_ERROR

200 응답 본문

타입: APIService

이름	타입	필수	설명
`api_id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`service_id`	`string \| null`	예
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.