diff --git a/src/content/en/api-reference.mdx b/src/content/en/api-reference.mdx new file mode 100644 index 00000000..39ebd16e --- /dev/null +++ b/src/content/en/api-reference.mdx @@ -0,0 +1,234 @@ +--- +title: API Reference +description: QueryPie ACP API Reference Documentation +--- + +# API Reference + +Welcome to the QueryPie ACP External API Reference documentation. +This document provides a comprehensive guide to the RESTful API that allows you to interact programmatically with QueryPie Access Control Platform (ACP). + +## About the API + +QueryPie ACP External API is implemented as a [RESTful API](https://restfulapi.net/). +It enables you to use the main features of QueryPie ACP outside of the web console. +It currently provides **more than 180 endpoints**. +You can control various management features of QueryPie ACP programmatically. + +With ACP External API, you can: + +- Manage users, groups, and roles +- Configure database connections and servers +- Control access permissions and manage policies +- Monitor audit logs and reports +- Manage Kubernetes clusters +- Manage workflows and approval processes +- Manage security settings and authentication +- And many other management features + +## Getting Started + +Here is a quick start guide for using QueryPie ACP External API: + +### 1. Obtain an API Token + +All API requests require authentication. +You need to obtain an API token from the QueryPie ACP administrator. +For detailed information on creating and managing API tokens, please refer to the [API Token documentation](administrator-manual/general/system/api-token). + +### 2. Basic API Call Structure + +The following information is required when making API calls: + +- **Base URL**: `{querypie url}/api/external/v2/` +- **Authorization Header**: `Authorization: {api token}` +- **Content-Type**: `application/json` + +### 3. API Call Example + +The following is a basic API call example using curl: + +```bash +curl -X GET "https://your-querypie-instance.com/api/external/v2/users" \ + -H "Authorization: your-api-token" \ + -H "Content-Type: application/json" +``` + +### 4. Using Interactive Documentation + +In the detailed documentation by version below, you can explore and test each endpoint through the interactive API documentation. + +## Authentication + +All API requests require authentication. +You must include the API token in the `Authorization` header when making requests. + +### Authorization Header Format + +``` +Authorization: {api token} +``` + +### API Token Management + +- API tokens can be issued by users with Owner permissions or administrators with access to the relevant menu. +- The token is fully displayed only when first issued. +- After that, all characters except the first 8 characters are masked. +- If you lose the token key, we recommend deleting the existing key and issuing a new one. + +For detailed information on creating, modifying, and deleting API tokens, please refer to the [API Token documentation](administrator-manual/general/system/api-token). + +## Main Feature Areas + +QueryPie ACP External API is implemented to correspond to the feature structure of the administrator web console. +It consists of the following main feature areas: + +### General (General Management) + +#### User Management (User Management) + +- **User Management API**: User creation, modification, deletion, and status management +- **User Group Management API**: User group management +- **Group Member Operations API**: Group membership management +- **Users - Allowed Zone Mapping API**: IP access control settings per user + +#### Workflow Management (Workflow Management) + +- **Workflow Requests API**: Workflow request management +- **Workflow Approval Delegation Logs API**: Workflow approval delegation log queries + +#### System (System Management) + +- **Security Settings API**: QueryPie ACP security settings query and configuration +- **Authentication API (Beta)**: Authentication settings management (Beta) +- **Jobs API**: Job history queries (cloud provider synchronization, etc.) +- **Secret Stores API**: External secret store management (HashiCorp Vault, etc.) + +### Databases (Database Management) + +#### Connection Management (Connection Management) + +- **DB Connections API**: Database connection management +- **DB Connection Member Operations API**: Database connection membership management +- **Cloud Providers for DB API**: Cloud provider management for databases + +#### DB Access Control (Database Access Control) + +- **DB Access Control API**: Database access control management +- **DB Access Control Logs API**: Database access permission grant/revoke history queries +- **Privileges API**: Database privilege management + +#### Policies (Policy Management) + +- **Data Policy Management API**: Data access policy management +- **Policy Rules API**: Policy rule management (data masking, data access, sensitive data policies) +- **Manual Policy Exception Management API**: Manual policy exception management + +#### Ledger Management (Ledger Management) + +- **Ledger Table Policy API**: Ledger table policy management +- **Ledger Approval Rules API**: Ledger approval rule management + +### Servers (Server Management) + +#### Connection Management (Connection Management) + +- **Servers API**: Server registration and management +- **Server Groups API**: Server group management +- **Server Groups Owners API**: Server group owner management +- **Server Cloud Providers API**: Server cloud provider management +- **Server SSH Key Configurations API**: Server SSH key configuration +- **Server Tags API**: Server tag management + +#### Server Account Management (Server Account Management) + +- **Server Accounts API**: Server OS account management + +#### Server Access Control (Server Access Control) + +- **Server Access Control API**: Server access control management +- **Server Roles API**: Server role management +- **Server Policy API**: Server policy management +- **Direct Permissions API**: Server direct permission management +- **Command Templates API**: Server command template management + +### Kubernetes (Kubernetes Management) + +#### Connection Management (Connection Management) + +- **Kubernetes Clusters API**: Kubernetes cluster management + +#### K8s Access Control (Kubernetes Access Control) + +- **Kubernetes Access Control API**: Kubernetes access control management +- **Kubernetes Cluster Role API**: Kubernetes cluster role management +- **Kubernetes Cluster Policy API**: Kubernetes cluster policy management + +### Web Apps (Web App Management) + +#### Connection Management (Connection Management) + +- **Web Apps API**: Web app management + +### Audit (Audit and Monitoring) + +#### General Logs (General Logs) + +- **User Access History API**: User login/logout history queries +- **Activity Logs API**: QueryPie ACP configuration change history queries +- **Admin Role History API**: Administrator permission grant/change/revoke history queries + +#### Database Logs (Database Logs) + +- **Query Audit API**: Query execution audit log queries +- **DB Access History API**: Database access history queries +- **DB Account Lock History API**: Database account lock history queries +- **DB Account Locks API**: Database account lock status queries and release +- **DML Snapshots API**: DML snapshot queries (data before and after INSERT/UPDATE/DELETE execution) + +#### Reports (Reports) + +- **Audit Log Export API**: Audit log export + +## API Versions + +QueryPie ACP External API supports two versions: + +### V2 API + +- This is the **currently recommended API version**. +- Supported since QueryPie ACP version 9.16.1. +- Call path: `{querypie url}/api/external/v2/` +- Not compatible with the existing V0.9 API. +- Uses a different endpoint structure and request/response format than the V0.9 API. +- Provides more features and an improved structure. + +### V0.9 API + +- Legacy API version that was provided before Version 9.16. +- Scheduled to be deprecated in the first half of 2026. +- Scheduled to be removed in the second half of 2026. +- Currently maintained for backward compatibility. +- Limited support for integration with existing systems. +- Call path: `{querypie url}/api/external/v0.9/` + +### Version Selection Guide + +- For new projects or integrations, **using the V2 API is strongly recommended**. +- Since the V0.9 API is scheduled to be deprecated, we recommend migrating to the V2 API as soon as possible. +- If you are considering migrating from V0.9 to V2, please refer to the detailed documentation for each version to check the differences. + +## Detailed Documentation + +Detailed API documentation for each version is provided in an interactive documentation format. +You can check detailed specifications for all endpoints, request/response examples, parameter descriptions, and more. + +### Version 11.4.1 + +- [ACP External API V2](api-reference/11.4.1/v2) - Current API (Recommended) +- [ACP External API V0.9](api-reference/11.4.1/v0.9) - Legacy API (Scheduled for Deprecation) + +## Related Documentation + +- [API Token Management](administrator-manual/general/system/api-token) - How to create and manage API tokens +- [Administrator Manual](administrator-manual) - QueryPie ACP Administrator Manual diff --git a/src/content/en/api-reference/index.mdx b/src/content/en/api-reference/index.mdx deleted file mode 100644 index 2d180b05..00000000 --- a/src/content/en/api-reference/index.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: API Reference -description: QueryPie API Reference Documentation ---- - -# API Reference - -Welcome to the QueryPie API Reference documentation. This section provides comprehensive documentation for the QueryPie REST API. - -## Available Versions - -### Version 11.4.1 -- [V2 API](/en/api-reference/11.4.1/v2) - Latest API version -- [V0.9 API](/en/api-reference/11.4.1/v0.9) - Legacy API version - -## About the API - -The QueryPie API allows you to programmatically interact with QueryPie Access Control Platform (ACP). You can use the API to: - -- Manage users, groups, and roles -- Configure database connections and servers -- Monitor audit logs and reports -- Control access permissions -- And much more - -## Authentication - -All API requests require authentication. Please refer to the [API Token documentation](/en/administrator-manual/general/system/api-token) for details on how to obtain and use API tokens. - -## API Versions - -QueryPie API supports two versions: - -- **V2**: The current and recommended API version -- **V0.9**: Legacy API version (maintained for backward compatibility) - -## Getting Started - -1. Obtain an API token from the QueryPie administrator -2. Include the token in your API requests using the `Authorization` header -3. Explore the API endpoints using the interactive documentation below - -For more information, please refer to the [Administrator Manual](/en/administrator-manual). - diff --git a/src/content/ja/api-reference.mdx b/src/content/ja/api-reference.mdx new file mode 100644 index 00000000..8edca86d --- /dev/null +++ b/src/content/ja/api-reference.mdx @@ -0,0 +1,234 @@ +--- +title: APIリファレンス +description: QueryPie ACP APIリファレンスドキュメント +--- + +# APIリファレンス + +QueryPie ACP External APIリファレンスドキュメントへようこそ。 +このドキュメントは、QueryPie Access Control Platform (ACP) とプログラム的にやり取りできるRESTful APIに関する包括的なガイドを提供します。 + +## APIについて + +QueryPie ACP External APIは、[RESTful API](https://restfulapi.net/)方式で実装されたAPIです。 +QueryPie ACPの主要機能をWebコンソール以外でも使用できるようにします。 +現在、**180以上のエンドポイント**を提供しています。 +QueryPie ACPの様々な管理機能をプログラム的に制御できます。 + +ACP External APIを使用すると、以下を実行できます: + +- ユーザー、グループ、ロールの管理 +- データベース接続とサーバーの設定 +- アクセス権限の制御とポリシーの管理 +- 監査ログとレポートの監視 +- Kubernetesクラスターの管理 +- ワークフローと承認プロセスの管理 +- セキュリティ設定と認証の管理 +- その他多くの管理機能 + +## はじめに + +QueryPie ACP External APIを使用するためのクイックスタートガイドは以下の通りです: + +### 1. APIトークンの取得 + +すべてのAPIリクエストには認証が必要です。 +QueryPie ACP管理者からAPIトークンを取得する必要があります。 +APIトークンの作成と管理方法の詳細については、[APIトークンドキュメント](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トークンを`Authorization`ヘッダーに含めてリクエストする必要があります。 + +### Authorizationヘッダーの形式 + +``` +Authorization: {api token} +``` + +### APIトークンの管理 + +- APIトークンは、Owner権限を持つユーザーまたは該当メニューへのアクセス権限を持つ管理者が発行できます。 +- トークンは最初に発行された時のみ完全に表示されます。 +- その後は、最初の8文字を除いた残りの文字がマスキングされて表示されます。 +- トークンキーを紛失した場合、既存のキーを削除して新しく発行することをお勧めします。 + +APIトークンの作成、変更、削除の詳細については、[APIトークンドキュメント](administrator-manual/general/system/api-token)を参照してください。 + +## 主要機能領域 + +QueryPie ACP External APIは、管理者Webコンソールの機能構造に対応するように実装されています。 +以下の主要機能領域で構成されています: + +### 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 (Webアプリ管理) + +#### Connection Management (接続管理) + +- **Web Apps API**: Webアプリの管理 + +### 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 ACP External APIは、2つのバージョンをサポートしています: + +### 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年前半リリースで非推奨予定です。 +- 2026年後半リリースで削除予定です。 +- 下位互換性のために現在まで維持されています。 +- 既存システムとの統合のために限定的にサポートされています。 +- 呼び出しパス: `{querypie url}/api/external/v0.9/` + +### バージョン選択ガイド + +- 新しいプロジェクトや統合の場合、**V2 APIの使用を強く推奨**します。 +- V0.9 APIは非推奨予定のため、可能な限り早急にV2 APIに移行することをお勧めします。 +- V0.9からV2への移行を検討する場合は、各バージョンの詳細ドキュメントを参照して、違いを確認してください。 + +## 詳細ドキュメント + +各バージョン別の詳細APIドキュメントは、インタラクティブなドキュメント形式で提供されています。 +すべてのエンドポイントの詳細な仕様、リクエスト/レスポンスの例、パラメータの説明などを確認できます。 + +### バージョン 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 (非推奨予定) + +## 関連ドキュメント + +- [APIトークン管理](administrator-manual/general/system/api-token) - APIトークンの作成と管理方法 +- [管理者マニュアル](administrator-manual) - QueryPie ACP管理者マニュアル diff --git a/src/content/ja/api-reference/index.mdx b/src/content/ja/api-reference/index.mdx deleted file mode 100644 index 4383eba8..00000000 --- a/src/content/ja/api-reference/index.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: APIリファレンス -description: QueryPie APIリファレンスドキュメント ---- - -# APIリファレンス - -QueryPie APIリファレンスドキュメントへようこそ。このセクションでは、QueryPie REST APIに関する包括的なドキュメントを提供します。 - -## 利用可能なバージョン - -### バージョン 11.4.1 -- [V2 API](/ja/api-reference/11.4.1/v2) - 最新のAPIバージョン -- [V0.9 API](/ja/api-reference/11.4.1/v0.9) - レガシーAPIバージョン - -## APIについて - -QueryPie APIを使用すると、QueryPie Access Control Platform (ACP) とプログラム的にやり取りできます。APIを使用して以下を実行できます: - -- ユーザー、グループ、ロールの管理 -- データベース接続とサーバーの設定 -- 監査ログとレポートの監視 -- アクセス権限の制御 -- その他多くの機能 - -## 認証 - -すべてのAPIリクエストには認証が必要です。APIトークンの取得と使用方法の詳細については、[APIトークンドキュメント](/ja/administrator-manual/general/system/api-token)を参照してください。 - -## APIバージョン - -QueryPie APIは2つのバージョンをサポートしています: - -- **V2**: 現在推奨されているAPIバージョン -- **V0.9**: レガシーAPIバージョン (下位互換性のために維持) - -## はじめに - -1. QueryPie管理者からAPIトークンを取得します -2. `Authorization`ヘッダーを使用してAPIリクエストにトークンを含めます -3. 以下のインタラクティブなドキュメントを使用してAPIエンドポイントを探索します - -詳細については、[管理者マニュアル](/ja/administrator-manual)を参照してください。 - diff --git a/src/content/ko/api-reference/index.mdx b/src/content/ko/api-reference.mdx similarity index 93% rename from src/content/ko/api-reference/index.mdx rename to src/content/ko/api-reference.mdx index a63eba88..3093fa44 100644 --- a/src/content/ko/api-reference/index.mdx +++ b/src/content/ko/api-reference.mdx @@ -34,7 +34,7 @@ QueryPie ACP External API를 사용하기 위한 빠른 시작 가이드는 다 모든 API 요청에는 인증이 필요합니다. QueryPie ACP 관리자로부터 API 토큰을 획득해야 합니다. -API 토큰 생성 및 관리 방법에 대한 자세한 내용은 [API 토큰 문서](/ko/administrator-manual/general/system/api-token)를 참조하세요. +API 토큰 생성 및 관리 방법에 대한 자세한 내용은 [API 토큰 문서](administrator-manual/general/system/api-token)를 참조하세요. ### 2. API 호출 기본 구조 @@ -76,7 +76,7 @@ Authorization: {api token} - 이후에는 앞의 8자리를 제외한 나머지를 마스킹하여 표시합니다. - 토큰 키를 분실한 경우, 기존 키를 삭제하고 새로 발급받아 사용하는 것을 권장합니다. -API 토큰 생성, 수정, 삭제에 대한 자세한 내용은 [API 토큰 문서](/ko/administrator-manual/general/system/api-token)를 참조하세요. +API 토큰 생성, 수정, 삭제에 대한 자세한 내용은 [API 토큰 문서](administrator-manual/general/system/api-token)를 참조하세요. ## 주요 기능 영역 @@ -205,9 +205,9 @@ QueryPie ACP External API는 두 가지 버전을 지원합니다: ### V0.9 API -- **레거시 API 버전**으로, Version 9.16 이전에 제공하던 API입니다. -- **2026년 상반기 릴리즈에서 Deprecate 예정**입니다. -- **2026년 하반기 릴리즈에서 제거 예정**입니다. +- 레거시 API 버전으로, Version 9.16 이전에 제공하던 API입니다. +- 2026년 상반기 릴리즈에서 Deprecate 예정입니다. +- 2026년 하반기 릴리즈에서 제거 예정입니다. - 하위 호환성을 위해 현재까지 유지되고 있습니다. - 기존 시스템과의 통합을 위해 제한적으로 지원됩니다. - 호출 경로: `{querypie url}/api/external/v0.9/` @@ -230,5 +230,5 @@ QueryPie ACP External API는 두 가지 버전을 지원합니다: ## 관련 문서 -- [API 토큰 관리](/ko/administrator-manual/general/system/api-token) - API 토큰 생성 및 관리 방법 -- [Administrator Manual](/ko/administrator-manual) - QueryPie ACP 관리자 매뉴얼 +- [API 토큰 관리](administrator-manual/general/system/api-token) - API 토큰 생성 및 관리 방법 +- [Administrator Manual](administrator-manual) - QueryPie ACP 관리자 매뉴얼