diff --git a/docs/api-naming-guide.md b/docs/api-naming-guide.md new file mode 100644 index 00000000..91eb9db0 --- /dev/null +++ b/docs/api-naming-guide.md @@ -0,0 +1,240 @@ +# QueryPie 제품 및 API 명칭 지침 + +이 문서는 QueryPie 제품 및 QueryPie ACP External API 문서 작성 시 사용할 명칭 및 지칭에 대한 가이드입니다. + +## 개요 + +제품명이 QueryPie에서 QueryPie ACP (Access Control Platform)로 변경됨에 따라, 문서에서 사용하는 명칭도 일관되게 유지해야 합니다. +이 가이드는 제품명과 API 명칭에 대한 일관된 사용을 위한 기준을 제공합니다. + +## QueryPie 제품명 가이드 + +### 1. 공식 제품명 + +**"QueryPie ACP"** (권장) +- 현재 공식 제품명 +- 모든 문서에서 제품을 지칭할 때 사용 +- 사용 예시: + - "QueryPie ACP는 통합 액세스 제어 솔루션입니다." + - "QueryPie ACP 관리자 매뉴얼" + +**"QueryPie Access Control Platform"** (전체명) +- 첫 언급 시 또는 공식적인 맥락에서 사용 +- 약어 (ACP)를 함께 표기하는 것을 권장 +- 사용 예시: + - "QueryPie Access Control Platform (ACP)은..." + - 이후에는 "QueryPie ACP"로 간략히 사용 가능 + +### 2. 제품 구성 요소 + +QueryPie ACP는 다음 4가지 핵심 구성 요소로 이루어져 있습니다: + +- **DAC (Database Access Controller)**: 데이터베이스 액세스 제어 및 감사 +- **SAC (System Access Controller)**: 시스템 및 서버 액세스 제어 +- **KAC (Kubernetes Access Controller)**: Kubernetes 클러스터 액세스 제어 +- **WAC (Web Access Controller)**: 웹 애플리케이션 액세스 제어 + +**사용 가이드:** +- 구성 요소를 언급할 때는 약어와 전체명을 함께 표기 +- 예시: "DAC (Database Access Controller)", "SAC (System Access Controller)" +- 반복 사용 시에는 약어만 사용 가능: "DAC", "SAC", "KAC", "WAC" + +### 3. 제품명 사용 규칙 + +| 상황 | 권장 명칭 | 예시 | +|------|----------|------| +| 문서 제목 | QueryPie ACP | "QueryPie ACP 제품 문서" | +| 첫 언급 | QueryPie Access Control Platform (ACP) | "QueryPie Access Control Platform (ACP)은..." | +| 일반 언급 | QueryPie ACP | "QueryPie ACP의 기능" | +| 구성 요소 | DAC (Database Access Controller) | "DAC (Database Access Controller)는..." | + +### 4. 레거시 명칭 처리 + +**"QueryPie"** (단독 사용) +- 레거시 명칭으로, 현재는 사용하지 않음 +- 기존 문서나 레거시 참조에서만 사용 +- 새로운 문서 작성 시에는 "QueryPie ACP" 사용 + +**주의사항:** +- 기존 문서에서 "QueryPie"를 발견하면 "QueryPie ACP"로 업데이트 권장 +- API 문서에서는 "QueryPie ACP External API" 사용 + +## QueryPie ACP External API 명칭 가이드 + +### API 명칭 체계 + +#### 1. 공식 명칭 (문서 제목, 주요 섹션) + +**"QueryPie ACP External API"** (권장) +- 제품명을 포함하여 명확함 +- "External"을 포함하여 웹 콘솔 외부에서 사용하는 API임을 구분 +- 사용 예시: + - 문서 제목: "QueryPie ACP External API 레퍼런스" + - 주요 섹션: "QueryPie ACP External API 소개" + +**"QueryPie ACP API"** (대안) +- 더 간결한 표현 +- "External"이 생략되어도 문맥상 명확한 경우 사용 가능 + +#### 2. 간략 명칭 (본문 내 반복 사용) + +**"ACP External API"** 또는 **"ACP API"** +- 제품명이 이미 언급된 후 반복 사용 시 +- 사용 예시: + - "QueryPie ACP External API는 RESTful API 방식으로 구현된 API입니다." + - "ACP External API를 사용하면 다음을 수행할 수 있습니다:" + +#### 3. 버전별 명칭 + +**전체 명칭:** +- "QueryPie ACP External API V2" / "ACP External API V2" +- "QueryPie ACP External API V0.9" / "ACP External API V0.9" + +**간략 명칭:** +- "V2 API" +- "V0.9 API" + +#### 4. API와 제품명의 관계 + +- API 문서에서 제품명을 언급할 때는 "QueryPie ACP" 사용 +- API는 제품의 기능이므로 "QueryPie ACP의 External API" 또는 "QueryPie ACP External API"로 표현 + +### API 명칭 사용 가이드 + +| 상황 | 권장 명칭 | 예시 | +|------|----------|------| +| 문서 제목 | QueryPie ACP External API | "QueryPie ACP External API 레퍼런스" | +| 첫 언급 | QueryPie ACP External API | "QueryPie ACP External API는..." | +| 반복 사용 | ACP External API | "ACP External API를 사용하면..." | +| 버전 구분 | ACP External API V2 | "ACP External API V2는..." | +| 간략 표현 | ACP API | 문맥상 명확한 경우 | + +### API 명칭 선택 기준 + +1. **문서 제목/주요 섹션**: "QueryPie ACP External API" 사용 +2. **첫 언급**: "QueryPie ACP External API" 사용 +3. **반복 사용**: "ACP External API" 또는 "ACP API" 사용 +4. **버전 구분**: "ACP External API V2" 또는 "V2 API" 사용 +5. **제품명과의 구분**: 제품명은 "QueryPie ACP", API는 "External API"로 구분 + +## 통합 명칭 체계 요약 + +### 제품명 + +1. **공식 제품명**: "QueryPie ACP" +2. **전체명**: "QueryPie Access Control Platform (ACP)" (첫 언급 시) +3. **구성 요소**: "DAC (Database Access Controller)", "SAC (System Access Controller)", "KAC (Kubernetes Access Controller)", "WAC (Web Access Controller)" + +### API 명칭 + +1. **공식 명칭**: "QueryPie ACP External API" +2. **간략 명칭**: "ACP External API" 또는 "ACP API" +3. **버전별**: "ACP External API V2", "ACP External API V0.9" + +## 사용 예시 + +### 제품명 사용 예시 + +```markdown +# QueryPie ACP 제품 문서 + +## QueryPie Access Control Platform (ACP)이란? + +QueryPie Access Control Platform (ACP)은 통합 액세스 제어 솔루션입니다. +QueryPie ACP는 DAC, SAC, KAC, WAC를 단일 플랫폼으로 제공합니다. + +### 핵심 구성 요소 + +- **DAC (Database Access Controller)**: 데이터베이스 액세스 제어 및 감사 +- **SAC (System Access Controller)**: 시스템 및 서버 액세스 제어 +- **KAC (Kubernetes Access Controller)**: Kubernetes 클러스터 액세스 제어 +- **WAC (Web Access Controller)**: 웹 애플리케이션 액세스 제어 +``` + +### API 문서 제목 및 소개 + +```markdown +# QueryPie ACP External API 레퍼런스 + +QueryPie ACP External API 레퍼런스 문서에 오신 것을 환영합니다. +이 문서는 QueryPie Access Control Platform (ACP)과 프로그래밍 방식으로 상호작용할 수 있는 RESTful API에 대한 종합적인 가이드를 제공합니다. + +## API 소개 + +QueryPie ACP External API는 RESTful API 방식으로 구현된 API입니다. +ACP External API를 사용하면 다음을 수행할 수 있습니다: +``` + +### 버전 정보 + +```markdown +## API 버전 + +QueryPie ACP External API는 두 가지 버전을 지원합니다: + +### V2 API + +- **현재 권장되는 API 버전**입니다. +- QueryPie ACP 버전 9.16.1부터 지원됩니다. +- 호출 경로: `{querypie url}/api/external/v2/` +- 기존 V0.9 API와 호환되지 않습니다. +- V0.9 API와는 다른 엔드포인트 구조와 요청/응답 형식을 사용합니다. + +### V0.9 API + +- **레거시 API 버전**으로, Version 9.16 이전에 제공하던 API입니다. +- **2026년 상반기 릴리즈에서 Deprecate 예정**입니다. +- **2026년 하반기 릴리즈에서 제거 예정**입니다. +``` + +### 상세 문서 링크 + +```markdown +### 버전 11.4.1 + +- [ACP External API V2](api-reference/11.4.1/v2) - 현행 API (권장) +- [ACP External API V0.9](api-reference/11.4.1/v0.9) - 레거시 API (Deprecate 예정) +``` + +## 주의사항 + +### 제품명 관련 + +1. **일관성 유지**: 모든 문서에서 "QueryPie ACP"를 제품명으로 일관되게 사용해야 합니다. +2. **레거시 명칭**: "QueryPie" 단독 사용은 피하고, "QueryPie ACP"로 통일합니다. +3. **구성 요소**: DAC, SAC, KAC, WAC 언급 시 첫 사용 시에는 전체명과 함께 표기합니다. +4. **약어 사용**: "ACP"는 "Access Control Platform"의 약어임을 명확히 합니다. + +### API 명칭 관련 + +1. **제품명과의 구분**: "QueryPie ACP"는 제품명, "External API"는 API 기능을 지칭합니다. +2. **첫 언급 시**: "QueryPie ACP External API" 전체 명칭을 사용하고, 이후에는 "ACP External API"로 간략히 사용할 수 있습니다. +3. **버전 정보**: V0.9 API는 Deprecate 예정이므로 이를 명시해야 합니다. +4. **일관성**: 문서 전체에서 API 명칭을 일관되게 사용해야 합니다. + +## 체크리스트 + +문서 작성 시 다음 사항을 확인하세요: + +### 제품명 체크리스트 + +- [ ] 제품명이 "QueryPie ACP"로 통일되어 있는가? +- [ ] 첫 언급 시 "QueryPie Access Control Platform (ACP)"로 표기했는가? +- [ ] 구성 요소(DAC, SAC, KAC, WAC) 첫 언급 시 전체명을 함께 표기했는가? +- [ ] 레거시 "QueryPie" 단독 사용이 없는가? + +### API 명칭 체크리스트 + +- [ ] 문서 제목에 "QueryPie ACP External API"를 사용했는가? +- [ ] 첫 언급 시 전체 명칭을 사용했는가? +- [ ] 반복 사용 시 간략 명칭("ACP External API")을 적절히 사용했는가? +- [ ] 버전 정보가 명확히 표기되어 있는가? +- [ ] V0.9 API Deprecate 정보가 포함되어 있는가? + +## 참고 + +- 이 가이드는 QueryPie ACP 제품명 변경에 따라 작성되었습니다. +- 모든 문서 작성 시 이 가이드를 참조하여 일관된 명칭을 사용해주세요. +- 명칭 관련 문의사항이 있으면 문서 팀에 문의해주세요. +- 이 가이드는 필요에 따라 업데이트될 수 있습니다. + diff --git a/src/app/[lang]/api-reference/[acpVersion]/[apiVersion]/page.tsx b/src/app/[lang]/api-reference/[acpVersion]/[apiVersion]/page.tsx index e210fe14..558d48ff 100644 --- a/src/app/[lang]/api-reference/[acpVersion]/[apiVersion]/page.tsx +++ b/src/app/[lang]/api-reference/[acpVersion]/[apiVersion]/page.tsx @@ -91,19 +91,19 @@ function getLocalizedText( switch (lang) { case 'ko': return { - title: `QueryPie ACP API 레퍼런스 - ${upperApiVersion}`, - description: `이 페이지는 QueryPie ACP API ${upperApiVersion} (버전 ${acpVersion})의 전체 OpenAPI 명세서를 제공합니다.`, + title: `QueryPie ACP External API 레퍼런스 - ${upperApiVersion}`, + description: `이 페이지는 QueryPie ACP External API ${upperApiVersion} (버전 ${acpVersion})의 전체 OpenAPI 명세서를 제공합니다.`, }; case 'ja': return { - title: `QueryPie ACP APIリファレンス - ${upperApiVersion}`, - description: `このページは、QueryPie ACP API ${upperApiVersion} (バージョン ${acpVersion}) の完全なOpenAPI仕様書を提供します。`, + title: `QueryPie ACP External APIリファレンス - ${upperApiVersion}`, + description: `このページは、QueryPie ACP External API ${upperApiVersion} (バージョン ${acpVersion}) の完全なOpenAPI仕様書を提供します。`, }; case 'en': default: return { - title: `QueryPie ACP API Reference - ${upperApiVersion}`, - description: `This page provides the complete OpenAPI specification for QueryPie ACP API ${upperApiVersion} (Version ${acpVersion}).`, + title: `QueryPie ACP External API Reference - ${upperApiVersion}`, + description: `This page provides the complete OpenAPI specification for QueryPie ACP External API ${upperApiVersion} (Version ${acpVersion}).`, }; } } @@ -148,7 +148,7 @@ export async function generateMetadata(props: { /** * API Reference Page Component * - * Displays the OpenAPI specification for a specific QueryPie API version. + * Displays the OpenAPI specification for a specific QueryPie ACP External API version. * Replaces the functionality of the v2.mdx file. */ export default async function ApiReferencePage(props: { diff --git a/src/components/openapi-viewer/OpenApiViewer.tsx b/src/components/openapi-viewer/OpenApiViewer.tsx index ccf9fcf5..3dda51ff 100644 --- a/src/components/openapi-viewer/OpenApiViewer.tsx +++ b/src/components/openapi-viewer/OpenApiViewer.tsx @@ -31,6 +31,11 @@ interface OpenApiSpec { version?: string; 'x-querypie-version'?: string; description?: string; + contact?: { + name?: string; + url?: string; + email?: string; + }; 'x-logo'?: { url?: string; altText?: string; @@ -84,7 +89,7 @@ export function OpenApiViewer({ return res.json(); }) .then((data: OpenApiSpec) => { - // Remove x-logo from spec to prevent Redoc from rendering default logo + // Remove x-logo and contact from spec to prevent Redoc from rendering them // Also update title and description if title/description props are provided const modifiedSpec = { ...data }; if (!modifiedSpec.info) { @@ -93,6 +98,9 @@ export function OpenApiViewer({ if (modifiedSpec.info['x-logo']) { delete modifiedSpec.info['x-logo']; } + if (modifiedSpec.info.contact) { + delete modifiedSpec.info.contact; + } // Override title and description with props if provided if (title) { modifiedSpec.info.title = title; diff --git a/src/content/en/_meta.ts b/src/content/en/_meta.ts index d7e55499..d08ab166 100644 --- a/src/content/en/_meta.ts +++ b/src/content/en/_meta.ts @@ -25,7 +25,6 @@ export default { 'api-reference': { type: 'page', title: 'API Reference', - display: 'hidden', }, contactUs: { type: 'page', diff --git a/src/content/en/api-reference/11.4.1/_meta.ts b/src/content/en/api-reference/11.4.1/_meta.ts index da47dfe2..dad75737 100644 --- a/src/content/en/api-reference/11.4.1/_meta.ts +++ b/src/content/en/api-reference/11.4.1/_meta.ts @@ -1,11 +1,14 @@ -export default { +import type { MetaRecord } from 'nextra'; + +const meta: MetaRecord = { v2: { - title: 'V2 API', - type: 'page', + title: 'External API v2', + href: 'api-reference/11.4.1/v2', }, 'v0.9': { - title: 'V0.9 API', - type: 'page', + title: 'External API v0.9', + href: 'api-reference/11.4.1/v0.9', }, }; +export default meta; diff --git a/src/content/en/api-reference/11.4.1/v0.9.mdx b/src/content/en/api-reference/11.4.1/v0.9.mdx deleted file mode 100644 index 089482e6..00000000 --- a/src/content/en/api-reference/11.4.1/v0.9.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: API Reference - V0.9 -description: QueryPie API V0.9 Specification for version 11.4.1 -sidebarTitle: V0.9 API ---- - -import { OpenApiViewer } from '@/components/openapi-viewer'; - -# QueryPie API Reference - V0.9 - -This page provides the complete OpenAPI specification for QueryPie API V0.9 (version 11.4.1). - - - diff --git a/src/content/en/api-reference/11.4.1/v2.mdx b/src/content/en/api-reference/11.4.1/v2.mdx deleted file mode 100644 index a6f81c83..00000000 --- a/src/content/en/api-reference/11.4.1/v2.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: API Reference - V2 -description: QueryPie API V2 Specification for version 11.4.1 -sidebarTitle: V2 API ---- - -import { OpenApiViewer } from '@/components/openapi-viewer'; - -# QueryPie API Reference - V2 - -This page provides the complete OpenAPI specification for QueryPie API V2 (version 11.4.1). - - - diff --git a/src/content/en/api-reference/_meta.ts b/src/content/en/api-reference/_meta.ts index b1753968..fdb15ff7 100644 --- a/src/content/en/api-reference/_meta.ts +++ b/src/content/en/api-reference/_meta.ts @@ -1,7 +1,13 @@ -export default { +import type { MetaRecord } from 'nextra'; + +const meta: MetaRecord = { '11.4.1': { title: 'Version 11.4.1', - type: 'page', + theme: { + collapsed: false, + }, }, }; +export default meta; + diff --git a/src/content/ja/_meta.ts b/src/content/ja/_meta.ts index 1e8474dc..23464017 100644 --- a/src/content/ja/_meta.ts +++ b/src/content/ja/_meta.ts @@ -25,7 +25,6 @@ export default { 'api-reference': { type: 'page', title: 'APIリファレンス', - display: 'hidden', }, contactUs: { type: 'page', diff --git a/src/content/ja/api-reference/11.4.1/_meta.ts b/src/content/ja/api-reference/11.4.1/_meta.ts index da47dfe2..dad75737 100644 --- a/src/content/ja/api-reference/11.4.1/_meta.ts +++ b/src/content/ja/api-reference/11.4.1/_meta.ts @@ -1,11 +1,14 @@ -export default { +import type { MetaRecord } from 'nextra'; + +const meta: MetaRecord = { v2: { - title: 'V2 API', - type: 'page', + title: 'External API v2', + href: 'api-reference/11.4.1/v2', }, 'v0.9': { - title: 'V0.9 API', - type: 'page', + title: 'External API v0.9', + href: 'api-reference/11.4.1/v0.9', }, }; +export default meta; diff --git a/src/content/ja/api-reference/11.4.1/v0.9.mdx b/src/content/ja/api-reference/11.4.1/v0.9.mdx deleted file mode 100644 index edc04dbd..00000000 --- a/src/content/ja/api-reference/11.4.1/v0.9.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: APIリファレンス - V0.9 -description: QueryPie API V0.9仕様書 (バージョン 11.4.1) -sidebarTitle: V0.9 API ---- - -import { OpenApiViewer } from '@/components/openapi-viewer'; - -# QueryPie APIリファレンス - V0.9 - -このページは、QueryPie API V0.9 (バージョン 11.4.1) の完全なOpenAPI仕様書を提供します。 - - - diff --git a/src/content/ja/api-reference/11.4.1/v2.mdx b/src/content/ja/api-reference/11.4.1/v2.mdx deleted file mode 100644 index a22bee24..00000000 --- a/src/content/ja/api-reference/11.4.1/v2.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: APIリファレンス - V2 -description: QueryPie API V2仕様書 (バージョン 11.4.1) -sidebarTitle: V2 API ---- - -import { OpenApiViewer } from '@/components/openapi-viewer'; - -# QueryPie APIリファレンス - V2 - -このページは、QueryPie API V2 (バージョン 11.4.1) の完全なOpenAPI仕様書を提供します。 - - - diff --git a/src/content/ja/api-reference/_meta.ts b/src/content/ja/api-reference/_meta.ts index 34afeae9..fdb15ff7 100644 --- a/src/content/ja/api-reference/_meta.ts +++ b/src/content/ja/api-reference/_meta.ts @@ -1,7 +1,13 @@ -export default { +import type { MetaRecord } from 'nextra'; + +const meta: MetaRecord = { '11.4.1': { - title: 'バージョン 11.4.1', - type: 'page', + title: 'Version 11.4.1', + theme: { + collapsed: false, + }, }, }; +export default meta; + diff --git a/src/content/ko/_meta.ts b/src/content/ko/_meta.ts index 56210b49..574abe16 100644 --- a/src/content/ko/_meta.ts +++ b/src/content/ko/_meta.ts @@ -25,7 +25,6 @@ export default { 'api-reference': { type: 'page', title: 'API 레퍼런스', - display: 'hidden', }, contactUs: { type: 'page', diff --git a/src/content/ko/api-reference/11.4.1/_meta.ts b/src/content/ko/api-reference/11.4.1/_meta.ts index da47dfe2..dad75737 100644 --- a/src/content/ko/api-reference/11.4.1/_meta.ts +++ b/src/content/ko/api-reference/11.4.1/_meta.ts @@ -1,11 +1,14 @@ -export default { +import type { MetaRecord } from 'nextra'; + +const meta: MetaRecord = { v2: { - title: 'V2 API', - type: 'page', + title: 'External API v2', + href: 'api-reference/11.4.1/v2', }, 'v0.9': { - title: 'V0.9 API', - type: 'page', + title: 'External API v0.9', + href: 'api-reference/11.4.1/v0.9', }, }; +export default meta; diff --git a/src/content/ko/api-reference/11.4.1/v0.9.mdx b/src/content/ko/api-reference/11.4.1/v0.9.mdx deleted file mode 100644 index d3b49023..00000000 --- a/src/content/ko/api-reference/11.4.1/v0.9.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: API 레퍼런스 - V0.9 -description: QueryPie API V0.9 명세서 (버전 11.4.1) -sidebarTitle: V0.9 API ---- - -import { OpenApiViewer } from '@/components/openapi-viewer'; - -# QueryPie API 레퍼런스 - V0.9 - -이 페이지는 QueryPie API V0.9 (버전 11.4.1)의 전체 OpenAPI 명세서를 제공합니다. - - - diff --git a/src/content/ko/api-reference/11.4.1/v2.mdx b/src/content/ko/api-reference/11.4.1/v2.mdx deleted file mode 100644 index eec14ff6..00000000 --- a/src/content/ko/api-reference/11.4.1/v2.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: API 레퍼런스 - V2 -description: QueryPie API V2 명세서 (버전 11.4.1) -sidebarTitle: V2 API ---- - -import { OpenApiViewer } from '@/components/openapi-viewer'; - -# QueryPie API 레퍼런스 - V2 - -이 페이지는 QueryPie API V2 (버전 11.4.1)의 전체 OpenAPI 명세서를 제공합니다. - - - diff --git a/src/content/ko/api-reference/_meta.ts b/src/content/ko/api-reference/_meta.ts index 17619ff6..fdb15ff7 100644 --- a/src/content/ko/api-reference/_meta.ts +++ b/src/content/ko/api-reference/_meta.ts @@ -1,7 +1,13 @@ -export default { +import type { MetaRecord } from 'nextra'; + +const meta: MetaRecord = { '11.4.1': { - title: '버전 11.4.1', - type: 'page', + title: 'Version 11.4.1', + theme: { + collapsed: false, + }, }, }; +export default meta; + diff --git a/src/content/ko/api-reference/index.mdx b/src/content/ko/api-reference/index.mdx index 15974491..a63eba88 100644 --- a/src/content/ko/api-reference/index.mdx +++ b/src/content/ko/api-reference/index.mdx @@ -1,44 +1,234 @@ --- title: API 레퍼런스 -description: QueryPie API 레퍼런스 문서 +description: QueryPie ACP API 레퍼런스 문서 --- # API 레퍼런스 -QueryPie API 레퍼런스 문서에 오신 것을 환영합니다. 이 섹션은 QueryPie REST API에 대한 포괄적인 문서를 제공합니다. - -## 사용 가능한 버전 - -### 버전 11.4.1 -- [V2 API](/ko/api-reference/11.4.1/v2) - 최신 API 버전 -- [V0.9 API](/ko/api-reference/11.4.1/v0.9) - 레거시 API 버전 +QueryPie ACP External API 레퍼런스 문서에 오신 것을 환영합니다. +이 문서는 QueryPie Access Control Platform (ACP)과 프로그래밍 방식으로 상호작용할 수 있는 RESTful API에 대한 종합적인 가이드를 제공합니다. ## API 소개 -QueryPie API를 사용하면 QueryPie Access Control Platform (ACP)과 프로그래밍 방식으로 상호작용할 수 있습니다. API를 사용하여 다음을 수행할 수 있습니다: +QueryPie ACP External API는 [RESTful API](https://restfulapi.net/) 방식으로 구현된 API입니다. +QueryPie ACP의 주요 기능을 웹 콘솔 외부에서도 사용할 수 있도록 합니다. +현재 **180개 이상의 엔드포인트**를 제공합니다. +QueryPie ACP의 다양한 관리 기능을 프로그래밍 방식으로 제어할 수 있습니다. + +ACP External API를 사용하면 다음을 수행할 수 있습니다: - 사용자, 그룹 및 역할 관리 - 데이터베이스 연결 및 서버 구성 +- 액세스 권한 제어 및 정책 관리 - 감사 로그 및 보고서 모니터링 -- 액세스 권한 제어 -- 기타 다양한 기능 +- Kubernetes 클러스터 관리 +- 워크플로우 및 승인 프로세스 관리 +- 보안 설정 및 인증 관리 +- 기타 다양한 관리 기능 + +## 시작하기 + +QueryPie ACP External API를 사용하기 위한 빠른 시작 가이드는 다음과 같습니다: + +### 1. API 토큰 획득 + +모든 API 요청에는 인증이 필요합니다. +QueryPie ACP 관리자로부터 API 토큰을 획득해야 합니다. +API 토큰 생성 및 관리 방법에 대한 자세한 내용은 [API 토큰 문서](/ko/administrator-manual/general/system/api-token)를 참조하세요. + +### 2. API 호출 기본 구조 + +API 호출 시 다음 정보가 필요합니다: + +- **기본 URL**: `{querypie url}/api/external/v2/` +- **인증 헤더**: `Authorization: {api token}` +- **Content-Type**: `application/json` + +### 3. API 호출 예시 + +다음은 curl을 사용한 기본 API 호출 예시입니다: + +```bash +curl -X GET "https://your-querypie-instance.com/api/external/v2/users" \ + -H "Authorization: your-api-token" \ + -H "Content-Type: application/json" +``` + +### 4. 대화형 문서 활용 + +아래의 버전별 상세 문서에서 대화형 API 문서를 통해 각 엔드포인트를 탐색하고 테스트할 수 있습니다. ## 인증 -모든 API 요청에는 인증이 필요합니다. API 토큰을 획득하고 사용하는 방법에 대한 자세한 내용은 [API 토큰 문서](/ko/administrator-manual/general/system/api-token)를 참조하세요. +모든 API 요청에는 인증이 필요합니다. +API 토큰을 `Authorization` 헤더에 포함하여 요청해야 합니다. + +### Authorization 헤더 형식 + +``` +Authorization: {api token} +``` + +### API 토큰 관리 + +- API 토큰은 Owner 권한 사용자 또는 해당 메뉴 접근 권한이 있는 관리자가 발급할 수 있습니다. +- 토큰은 최초 발급 시에만 전체 노출됩니다. +- 이후에는 앞의 8자리를 제외한 나머지를 마스킹하여 표시합니다. +- 토큰 키를 분실한 경우, 기존 키를 삭제하고 새로 발급받아 사용하는 것을 권장합니다. + +API 토큰 생성, 수정, 삭제에 대한 자세한 내용은 [API 토큰 문서](/ko/administrator-manual/general/system/api-token)를 참조하세요. + +## 주요 기능 영역 + +QueryPie ACP External API는 관리자 웹 콘솔의 기능 구조에 대응하도록 구현되어 있습니다. +다음과 같은 주요 기능 영역으로 구성되어 있습니다: + +### General (일반 관리) + +#### User Management (사용자 관리) + +- **User Management API**: 사용자 생성, 수정, 삭제 및 상태 관리 +- **User Group Management API**: 사용자 그룹 관리 +- **Group Member Operations API**: 그룹 멤버십 관리 +- **Users - Allowed Zone Mapping API**: 사용자별 IP 접근 제어 설정 + +#### Workflow Management (워크플로우 관리) + +- **Workflow Requests API**: 워크플로우 요청 관리 +- **Workflow Approval Delegation Logs API**: 워크플로우 승인 위임 로그 조회 + +#### System (시스템 관리) + +- **Security Settings API**: QueryPie ACP 보안 설정 조회 및 구성 +- **Authentication API (Beta)**: 인증 설정 관리 (베타) +- **Jobs API**: 작업 이력 조회 (클라우드 프로바이더 동기화 등) +- **Secret Stores API**: 외부 시크릿 스토어 관리 (HashiCorp Vault 등) + +### Databases (데이터베이스 관리) + +#### Connection Management (연결 관리) + +- **DB Connections API**: 데이터베이스 연결 관리 +- **DB Connection Member Operations API**: 데이터베이스 연결 멤버십 관리 +- **Cloud Providers for DB API**: 데이터베이스용 클라우드 프로바이더 관리 + +#### DB Access Control (데이터베이스 접근 제어) + +- **DB Access Control API**: 데이터베이스 접근 제어 관리 +- **DB Access Control Logs API**: 데이터베이스 접근 권한 부여/해제 이력 조회 +- **Privileges API**: 데이터베이스 권한 관리 + +#### Policies (정책 관리) + +- **Data Policy Management API**: 데이터 접근 정책 관리 +- **Policy Rules API**: 정책 규칙 관리 (데이터 마스킹, 데이터 접근, 민감 데이터 정책) +- **Manual Policy Exception Management API**: 수동 정책 예외 관리 + +#### Ledger Management (Ledger 관리) + +- **Ledger Table Policy API**: Ledger 테이블 정책 관리 +- **Ledger Approval Rules API**: Ledger 승인 규칙 관리 + +### Servers (서버 관리) + +#### Connection Management (연결 관리) + +- **Servers API**: 서버 등록 및 관리 +- **Server Groups API**: 서버 그룹 관리 +- **Server Groups Owners API**: 서버 그룹 소유자 관리 +- **Server Cloud Providers API**: 서버 클라우드 프로바이더 관리 +- **Server SSH Key Configurations API**: 서버 SSH 키 설정 +- **Server Tags API**: 서버 태그 관리 + +#### Server Account Management (서버 계정 관리) + +- **Server Accounts API**: 서버 OS 계정 관리 + +#### Server Access Control (서버 접근 제어) + +- **Server Access Control API**: 서버 접근 제어 관리 +- **Server Roles API**: 서버 역할 관리 +- **Server Policy API**: 서버 정책 관리 +- **Direct Permissions API**: 서버 직접 권한 관리 +- **Command Templates API**: 서버 명령 템플릿 관리 + +### Kubernetes (Kubernetes 관리) + +#### Connection Management (연결 관리) + +- **Kubernetes Clusters API**: Kubernetes 클러스터 관리 + +#### K8s Access Control (Kubernetes 접근 제어) + +- **Kubernetes Access Control API**: Kubernetes 액세스 제어 관리 +- **Kubernetes Cluster Role API**: Kubernetes 클러스터 역할 관리 +- **Kubernetes Cluster Policy API**: Kubernetes 클러스터 정책 관리 + +### Web Apps (웹 앱 관리) + +#### Connection Management (연결 관리) + +- **Web Apps API**: 웹 앱 관리 + +### Audit (감사 및 모니터링) + +#### General Logs (일반 로그) + +- **User Access History API**: 사용자 로그인/로그아웃 이력 조회 +- **Activity Logs API**: QueryPie ACP 설정 변경 이력 조회 +- **Admin Role History API**: 관리자 권한 부여/변경/해제 이력 조회 + +#### Database Logs (데이터베이스 로그) + +- **Query Audit API**: 쿼리 실행 감사 로그 조회 +- **DB Access History API**: 데이터베이스 접근 이력 조회 +- **DB Account Lock History API**: 데이터베이스 계정 잠금 이력 조회 +- **DB Account Locks API**: 데이터베이스 계정 잠금 상태 조회 및 해제 +- **DML Snapshots API**: DML 스냅샷 조회 (INSERT/UPDATE/DELETE 실행 전후 데이터) + +#### Reports (보고서) + +- **Audit Log Export API**: 감사 로그 내보내기 ## API 버전 -QueryPie API는 두 가지 버전을 지원합니다: +QueryPie ACP External API는 두 가지 버전을 지원합니다: -- **V2**: 현재 권장되는 API 버전 -- **V0.9**: 레거시 API 버전 (하위 호환성을 위해 유지됨) +### V2 API -## 시작하기 +- **현재 권장되는 API 버전**입니다. +- QueryPie ACP 버전 9.16.1부터 지원됩니다. +- 호출 경로: `{querypie url}/api/external/v2/` +- 기존 V0.9 API와 호환되지 않습니다. +- V0.9 API와는 다른 엔드포인트 구조와 요청/응답 형식을 사용합니다. +- 더 많은 기능과 개선된 구조를 제공합니다. + +### V0.9 API + +- **레거시 API 버전**으로, Version 9.16 이전에 제공하던 API입니다. +- **2026년 상반기 릴리즈에서 Deprecate 예정**입니다. +- **2026년 하반기 릴리즈에서 제거 예정**입니다. +- 하위 호환성을 위해 현재까지 유지되고 있습니다. +- 기존 시스템과의 통합을 위해 제한적으로 지원됩니다. +- 호출 경로: `{querypie url}/api/external/v0.9/` + +### 버전 선택 가이드 + +- 새로운 프로젝트나 통합의 경우 **V2 API** 사용을 강력히 권장합니다. +- V0.9 API는 Deprecate 예정이므로, 가능한 한 빠른 시일 내에 V2 API로 마이그레이션하는 것을 권장합니다. +- V0.9에서 V2로의 마이그레이션을 고려하는 경우, 각 버전의 상세 문서를 참조하여 차이점을 확인하세요. + +## 상세 문서 + +각 버전별 상세 API 문서는 대화형 문서 형식으로 제공됩니다. +모든 엔드포인트의 상세한 명세, 요청/응답 예시, 파라미터 설명 등을 확인할 수 있습니다. + +### 버전 11.4.1 -1. QueryPie 관리자로부터 API 토큰을 획득합니다 -2. `Authorization` 헤더를 사용하여 API 요청에 토큰을 포함합니다 -3. 아래의 대화형 문서를 사용하여 API 엔드포인트를 탐색합니다 +- [ACP External API V2](api-reference/11.4.1/v2) - 현행 API (권장) +- [ACP External API V0.9](api-reference/11.4.1/v0.9) - 레거시 API (Deprecate 예정) -자세한 내용은 [관리자 매뉴얼](/ko/administrator-manual)을 참조하세요. +## 관련 문서 +- [API 토큰 관리](/ko/administrator-manual/general/system/api-token) - API 토큰 생성 및 관리 방법 +- [Administrator Manual](/ko/administrator-manual) - QueryPie ACP 관리자 매뉴얼