This page is generated from the public contract. Descriptions are shown in the original Korean.
Service CRUD와 API 구현·Repository·Database·Key Pattern·Kafka 사용 연결과 역조회.
Service 목록#
GET /api/services
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 | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (Service[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 서버 생성·불변 ID. |
handle | string | Yes | 같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다. |
name | string | Yes | 앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다. |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | 공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다. |
created_at | string(date-time) | Yes | 생성 후 불변. 생성 시 updated_at과 같은 값. |
updated_at | string(date-time) | Yes | 같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다. |
status | string | Yes | 수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. Values: planned, active, retired |
Service 생성#
POST /api/services
Authentication: Session cookie or Agent token
Request body
application/json · Required: Yes
JSON 객체 하나, UTF-8·중복 키·미정의 필드 엄격 검사, 본문 최대 64 KiB. 일반 필드 검증은 조건 평가 전이며 참조 Service 존재 검사는 조건 평가 뒤입니다.
Type: CreateService
| 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 | 앞뒤 U+0020 공백 제거 후 1~200 유니코드 코드 포인트. 제어문자는 제거 전에 거부하며 범위는 U+0000~U+001F·U+007F~U+009F입니다. 다른 유니코드 공백·정규화는 적용하지 않습니다. 정규화 전 입력에는 maxLength 200을 적용하지 않습니다. |
summary | string | No | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | No | 공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다. |
status | string | No | 수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. Values: planned, active, retired |
Responses
| Status | Description |
|---|---|
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 response body
Type: Service
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 서버 생성·불변 ID. |
handle | string | Yes | 같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다. |
name | string | Yes | 앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다. |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | 공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다. |
created_at | string(date-time) | Yes | 생성 후 불변. 생성 시 updated_at과 같은 값. |
updated_at | string(date-time) | Yes | 같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다. |
status | string | Yes | 수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. Values: planned, active, retired |
Service 상세#
GET /api/services/{id}
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-None-Match | header | string | No | 상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 *를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. *와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다. |
Responses
| Status | Description |
|---|---|
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 response body
Type: Service
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 서버 생성·불변 ID. |
handle | string | Yes | 같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다. |
name | string | Yes | 앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다. |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | 공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다. |
created_at | string(date-time) | Yes | 생성 후 불변. 생성 시 updated_at과 같은 값. |
updated_at | string(date-time) | Yes | 같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다. |
status | string | Yes | 수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. Values: planned, active, retired |
Service 전체 수정#
PUT /api/services/{id}
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-Match | header | string | Yes | 대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다. |
Request body
application/json · Required: Yes
JSON 객체 하나, UTF-8·중복 키·미정의 필드 엄격 검사, 본문 최대 64 KiB. 일반 필드 검증은 조건 평가 전이며 참조 Service 존재 검사는 조건 평가 뒤입니다.
Type: ReplaceService
| 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 | 앞뒤 U+0020 공백 제거 후 1~200 유니코드 코드 포인트. 제어문자는 제거 전에 거부하며 범위는 U+0000~U+001F·U+007F~U+009F입니다. 다른 유니코드 공백·정규화는 적용하지 않습니다. 정규화 전 입력에는 maxLength 200을 적용하지 않습니다. |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | 공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다. |
status | string | Yes | 수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. Values: planned, active, retired |
Responses
| Status | Description |
|---|---|
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 response body
Type: Service
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 서버 생성·불변 ID. |
handle | string | Yes | 같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다. |
name | string | Yes | 앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다. |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | 공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다. |
created_at | string(date-time) | Yes | 생성 후 불변. 생성 시 updated_at과 같은 값. |
updated_at | string(date-time) | Yes | 같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다. |
status | string | Yes | 수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. Values: planned, active, retired |
미연결 Service 삭제#
DELETE /api/services/{id}
API 구현·Repository·Database·Key Pattern·Table·Collection·Cassandra Table 연결 또는 Kafka 사용 설명의 참조가 남은 Service는 409 SERVICE_IN_USE입니다. 연쇄 삭제·자동 해제하지 않습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-Match | header | string | Yes | 대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다. |
Responses
| Status | Description |
|---|---|
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만 조회합니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
q | query | string | No | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (API[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 서버 생성·불변 ID. |
handle | string | Yes | 같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다. |
name | string | Yes | 앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다. |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | 공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다. |
base_urls | BaseURL[] | Yes | API 소유 호출 기준 주소 목록. 저장 순서를 그대로 반환하며 정규화 후 같은 주소는 한 번만 있습니다. 주소가 없으면 빈 배열입니다. 소속 Endpoint는 이 목록을 공통으로 사용합니다. |
created_at | string(date-time) | Yes | 생성 후 불변. 생성 시 updated_at과 같은 값. |
updated_at | string(date-time) | Yes | 같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다. |
security | SecurityDeclaration | Yes |
Service 연결 Repository 집합 조회#
GET /api/services/{id}/repository-links
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-None-Match | header | string | No | 상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 *를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. *와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다. |
Responses
| Status | Description |
|---|---|
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 response body
Type: ServiceRepositories
| Name | Type | Required | Description |
|---|---|---|---|
service_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
repository_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
Service 연결 Repository 집합 전체 교체#
PUT /api/services/{id}/repository-links
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-Match | header | string | Yes | 대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다. |
Request body
application/json · Required: Yes
JSON 객체 하나, UTF-8·중복 키·미정의 필드 엄격 검사, 본문 최대 64 KiB. 일반 필드 검증은 조건 평가 전이며 참조 Repository 존재 검사는 조건 평가 뒤입니다.
Type: ReplaceServiceRepositories
| Name | Type | Required | Description |
|---|---|---|---|
repository_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
Responses
| Status | Description |
|---|---|
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 response body
Type: ServiceRepositories
| Name | Type | Required | Description |
|---|---|---|---|
service_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
repository_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
Service의 연결 Repository 목록#
GET /api/services/{id}/repositories
현재 Organization의 부모 Service·연결·Repository Metadata를 같은 읽기 전용 Snapshot에서 조회합니다. 빈 집합은 빈 배열, 미존재·다른 Organization의 Service는 404입니다. ETag를 반환하거나 조건 헤더를 평가하지 않습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
q | query | string | No | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (Repository[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
handle | string | Yes | 같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다. |
name | string | Yes | |
git_url | string | Yes | 수동 기록한 HTTPS·SSH URL 또는 SCP 형태 SSH 주소. |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | 공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다. |
created_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
external_identity | RepositoryExternalIdentity | Yes | 같은 Organization에서 유일한 외부 키. PUT 생략은 보존, 명시적 null은 해제합니다. |
Repository의 연결 Service 목록#
GET /api/repositories/{id}/services
현재 Organization의 부모 Repository·연결·Service Metadata를 같은 읽기 전용 Snapshot에서 조회합니다. 빈 집합은 빈 배열, 미존재·다른 Organization의 Repository는 404입니다. ETag를 반환하거나 조건 헤더를 평가하지 않습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
q | query | string | No | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (Service[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 서버 생성·불변 ID. |
handle | string | Yes | 같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다. |
name | string | Yes | 앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다. |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | 공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다. |
created_at | string(date-time) | Yes | 생성 후 불변. 생성 시 updated_at과 같은 값. |
updated_at | string(date-time) | Yes | 같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다. |
status | string | Yes | 수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. Values: 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를 반환하거나 조건 헤더를 평가하지 않습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
q | query | string | No | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (ServiceKafkaUsage[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
topic_id | string | Yes | |
topic_name | string | Yes | |
cluster_id | string | Yes | |
cluster_name | string | Yes | |
usage_id | string | Yes | |
direction | any | Yes | Values: producer, consumer |
application_name | string | Yes | |
description | string | Yes | |
consumer_group | string | null | Yes |
Database 연결 Service 집합 조회#
GET /api/databases/{id}/service-links
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-None-Match | header | string | No | 상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 *를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. *와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다. |
Responses
| Status | Description |
|---|---|
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 response body
Type: DatabaseServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
database_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
Database 연결 Service 집합 전체 교체#
PUT /api/databases/{id}/service-links
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-Match | header | string | Yes | 대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다. |
Request body
application/json · Required: Yes
JSON 객체 하나, UTF-8·중복 키·미정의 필드 엄격 검사, 본문 최대 64 KiB. 일반 필드 검증은 조건 평가 전이며 참조 Service 존재 검사는 조건 평가 뒤입니다.
Type: ReplaceDatabaseServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
Responses
| Status | Description |
|---|---|
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 response body
Type: DatabaseServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
database_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
Database의 직접 연결 Service 목록#
GET /api/databases/{id}/services
같은 Snapshot의 Database·직접 연결·Service Metadata를 조회합니다. 자동 상속하지 않으며 빈 집합은 빈 배열, 다른 경계·미존재 부모는 404입니다. ETag는 없습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
q | query | string | No | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (Service[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 서버 생성·불변 ID. |
handle | string | Yes | 같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다. |
name | string | Yes | 앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다. |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | 공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다. |
created_at | string(date-time) | Yes | 생성 후 불변. 생성 시 updated_at과 같은 값. |
updated_at | string(date-time) | Yes | 같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다. |
status | string | Yes | 수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. Values: 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는 없습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
q | query | string | No | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (ServiceDatastore[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
name | string | Yes | |
summary | string | Yes | |
database_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
database_name | string | Yes | |
engine | string | Yes |
KeyPattern 연결 Service 집합 조회#
GET /api/key-patterns/{id}/service-links
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-None-Match | header | string | No | 상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 *를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. *와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다. |
Responses
| Status | Description |
|---|---|
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 response body
Type: KeyPatternServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
key_pattern_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
KeyPattern 연결 Service 집합 전체 교체#
PUT /api/key-patterns/{id}/service-links
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-Match | header | string | Yes | 대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다. |
Request body
application/json · Required: Yes
JSON 객체 하나, UTF-8·중복 키·미정의 필드 엄격 검사, 본문 최대 64 KiB. 일반 필드 검증은 조건 평가 전이며 참조 Service 존재 검사는 조건 평가 뒤입니다.
Type: ReplaceKeyPatternServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
Responses
| Status | Description |
|---|---|
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 response body
Type: KeyPatternServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
key_pattern_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
KeyPattern의 직접 연결 Service 목록#
GET /api/key-patterns/{id}/services
같은 Snapshot의 KeyPattern·직접 연결·Service Metadata를 조회합니다. 자동 상속하지 않으며 빈 집합은 빈 배열, 다른 경계·미존재 부모는 404입니다. ETag는 없습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
q | query | string | No | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (Service[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 서버 생성·불변 ID. |
handle | string | Yes | 같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다. |
name | string | Yes | 앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다. |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | 공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다. |
created_at | string(date-time) | Yes | 생성 후 불변. 생성 시 updated_at과 같은 값. |
updated_at | string(date-time) | Yes | 같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다. |
status | string | Yes | 수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. Values: planned, active, retired |
Service의 직접 연결 KeyPattern 목록#
GET /api/services/{id}/key-patterns
같은 Snapshot의 Service·직접 연결·리소스와 현재 부모 Database를 조회합니다. name은 Database 이름 또는 Key Pattern template이며 q는 name 부분 일치, 정렬은 name·id 순입니다. 빈 집합은 빈 배열, 다른 경계·미존재 Service는 404입니다. ETag는 없습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
q | query | string | No | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (ServiceDatastore[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
name | string | Yes | |
summary | string | Yes | |
database_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
database_name | string | Yes | |
engine | string | Yes |
Table 연결 Service 집합 조회#
GET /api/tables/{id}/service-links
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-None-Match | header | string | No | 상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 *를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. *와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다. |
Responses
| Status | Description |
|---|---|
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 response body
Type: TableServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
table_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
Table 연결 Service 집합 전체 교체#
PUT /api/tables/{id}/service-links
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-Match | header | string | Yes | 대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다. |
Request body
application/json · Required: Yes
JSON 객체 하나, UTF-8·중복 키·미정의 필드 엄격 검사, 본문 최대 64 KiB. 일반 필드 검증은 조건 평가 전이며 참조 Service 존재 검사는 조건 평가 뒤입니다.
Type: ReplaceTableServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
Responses
| Status | Description |
|---|---|
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 response body
Type: TableServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
table_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
Table의 직접 연결 Service 목록#
GET /api/tables/{id}/services
같은 Snapshot의 Table·직접 연결·Service Metadata를 조회합니다. 자동 상속하지 않으며 빈 집합은 빈 배열, 다른 경계·미존재 부모는 404입니다. ETag는 없습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
q | query | string | No | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (Service[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 서버 생성·불변 ID. |
handle | string | Yes | 같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다. |
name | string | Yes | 앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다. |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | 공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다. |
created_at | string(date-time) | Yes | 생성 후 불변. 생성 시 updated_at과 같은 값. |
updated_at | string(date-time) | Yes | 같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다. |
status | string | Yes | 수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. Values: 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는 없습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
q | query | string | No | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (ServiceDatastore[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
name | string | Yes | |
summary | string | Yes | |
database_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
database_name | string | Yes | |
engine | string | Yes |
Collection 연결 Service 집합 조회#
GET /api/collections/{id}/service-links
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-None-Match | header | string | No | 상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 *를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. *와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다. |
Responses
| Status | Description |
|---|---|
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 response body
Type: CollectionServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
collection_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
Collection 연결 Service 집합 전체 교체#
PUT /api/collections/{id}/service-links
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-Match | header | string | Yes | 대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다. |
Request body
application/json · Required: Yes
JSON 객체 하나, UTF-8·중복 키·미정의 필드 엄격 검사, 본문 최대 64 KiB. 일반 필드 검증은 조건 평가 전이며 참조 Service 존재 검사는 조건 평가 뒤입니다.
Type: ReplaceCollectionServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
Responses
| Status | Description |
|---|---|
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 response body
Type: CollectionServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
collection_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
Collection의 직접 연결 Service 목록#
GET /api/collections/{id}/services
같은 Snapshot의 Collection·직접 연결·Service Metadata를 조회합니다. 자동 상속하지 않으며 빈 집합은 빈 배열, 다른 경계·미존재 부모는 404입니다. ETag는 없습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
q | query | string | No | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (Service[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 서버 생성·불변 ID. |
handle | string | Yes | 같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다. |
name | string | Yes | 앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다. |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | 공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다. |
created_at | string(date-time) | Yes | 생성 후 불변. 생성 시 updated_at과 같은 값. |
updated_at | string(date-time) | Yes | 같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다. |
status | string | Yes | 수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. Values: planned, active, retired |
Service의 직접 연결 Collection 목록#
GET /api/services/{id}/collections
같은 Snapshot의 Service·직접 연결·리소스와 현재 부모 Database를 조회합니다. name은 Collection 이름이며 q는 name 부분 일치, 정렬은 name·id 순입니다. 빈 집합은 빈 배열, 다른 경계·미존재 Service는 404입니다. ETag는 없습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
q | query | string | No | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (ServiceDatastore[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
name | string | Yes | |
summary | string | Yes | |
database_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
database_name | string | Yes | |
engine | string | Yes |
CassandraTable 연결 Service 집합 조회#
GET /api/cassandra-tables/{id}/service-links
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-None-Match | header | string | No | 상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 *를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. *와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다. |
Responses
| Status | Description |
|---|---|
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 response body
Type: CassandraTableServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
cassandra_table_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
CassandraTable 연결 Service 집합 전체 교체#
PUT /api/cassandra-tables/{id}/service-links
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-Match | header | string | Yes | 대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다. |
Request body
application/json · Required: Yes
JSON 객체 하나, UTF-8·중복 키·미정의 필드 엄격 검사, 본문 최대 64 KiB. 일반 필드 검증은 조건 평가 전이며 참조 Service 존재 검사는 조건 평가 뒤입니다.
Type: ReplaceCassandraTableServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
Responses
| Status | Description |
|---|---|
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 response body
Type: CassandraTableServiceLinks
| Name | Type | Required | Description |
|---|---|---|---|
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
cassandra_table_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
service_ids | string[] | Yes | 0개 이상. 중복은 422. 정렬 순서는 의미가 없고 응답은 ID 오름차순입니다. |
CassandraTable의 직접 연결 Service 목록#
GET /api/cassandra-tables/{id}/services
같은 Snapshot의 CassandraTable·직접 연결·Service Metadata를 조회합니다. 자동 상속하지 않으며 빈 집합은 빈 배열, 다른 경계·미존재 부모는 404입니다. ETag는 없습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
q | query | string | No | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (Service[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 서버 생성·불변 ID. |
handle | string | Yes | 같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다. |
name | string | Yes | 앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다. |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | 공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다. |
created_at | string(date-time) | Yes | 생성 후 불변. 생성 시 updated_at과 같은 값. |
updated_at | string(date-time) | Yes | 같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다. |
status | string | Yes | 수동 생명주기 제안. 도입 예정·사용 중·사용 종료이며 실시간 가용성이 아닙니다. Values: planned, active, retired |
Service의 직접 연결 CassandraTable 목록#
GET /api/services/{id}/cassandra-tables
같은 Snapshot의 Service·직접 연결·리소스와 현재 부모 Database를 조회합니다. name은 Cassandra Table 이름이며 q는 name 부분 일치, 정렬은 name·id 순입니다. 빈 집합은 빈 배열, 다른 경계·미존재 Service는 404입니다. ETag는 없습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
q | query | string | No | name에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록. |
sort | query | string | No | name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: name, -name |
page | query | integer | No | 1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1. |
per_page | query | integer | No | 1~500 정수. 생략 시 100. |
Responses
| Status | Description |
|---|---|
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 response body
An array (ServiceDatastore[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
name | string | Yes | |
summary | string | Yes | |
database_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
database_name | string | Yes | |
engine | string | Yes |
API 제공 Service 조회#
GET /api/apis/{api_id}/service
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
api_id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-None-Match | header | string | No | 상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 *를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. *와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다. |
Responses
| Status | Description |
|---|---|
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 response body
Type: APIService
| Name | Type | Required | Description |
|---|---|---|---|
api_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
service_id | string | null | Yes | |
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |
API 제공 Service 확정#
PUT /api/apis/{api_id}/service
제공 Service를 문자열 ID 또는 null로 확정합니다. Metadata revision은 바꾸지 않습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
api_id | path | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
If-Match | header | string | Yes | 대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다. |
Request body
application/json · Required: Yes
JSON 객체 하나, UTF-8·중복 키·미정의 필드 엄격 검사, 본문 최대 4 MiB. 일반 필드 검증은 조건 평가 전이며 참조 Service 존재 검사는 조건 평가 뒤입니다.
Type: ReplaceAPIService
| Name | Type | Required | Description |
|---|---|---|---|
service_id | string | null | Yes |
Responses
| Status | Description |
|---|---|
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 response body
Type: APIService
| Name | Type | Required | Description |
|---|---|---|---|
api_id | string | Yes | Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다. |
service_id | string | null | Yes | |
updated_at | string(date-time) | Yes | 서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다. |