# REST API ドキュメント > GEO Wiki Pro バックエンド REST API の完全なリファレンスマニュアル --- ## 概要 GEO Wiki Pro は RESTful スタイルの HTTP API を提供し、すべてのエンドポイントは `/api/v1/` パス下にあります。公開エンドポイントは認証不要で、管理エンドポイントには JWT 認証と管理者ロールが必要です。 ### 基本情報 | 項目 | 説明 | |------|------| | ベース URL | `https://your-domain.com/api/v1` | | 認証方法 | JWT（httpOnly cookie） | | CSRF 保護 | Double-submit cookie HMAC | | コンテンツタイプ | `application/json` | | レート制限 | グローバル 300 リクエスト/分、認証エンドポイント 10 リクエスト/分 | ### レスポンス形式 **成功レスポンス：** ```json { "success": true, "data": { ... } } ``` **ページネーションレスポンス：** ```json { "success": true, "data": [ ... ], "pagination": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 } } ``` **エラーレスポンス：** ```json { "success": false, "message": "Not found" } ``` --- ## 公開エンドポイント 以下のエンドポイントは認証不要で、誰でもアクセスできます。 ### ドキュメントリストの取得 ``` GET /api/v1/docs ``` **クエリパラメータ：** | パラメータ | タイプ | 必須 | 説明 | |-----------|--------|------|------| | `lang` | string | いいえ | 言語コード（zh/en/jp）、デフォルト zh | | `category` | string | いいえ | カテゴリスラッグフィルタ | | `page` | number | いいえ | ページ番号、デフォルト 1 | | `limit` | number | いいえ | 1 ページあたりの件数、デフォルト 20 | **例：** ```bash curl "https://geowiki.pro/api/v1/docs?lang=en&category=can-motion&page=1&limit=10" ``` **レスポンス：** ```json { "success": true, "data": [ { "slug": "can-bus-protocol", "title": "CAN Bus Protocol", "category": "can-motion", "tags": ["can-bus", "protocol"], "author": "admin", "sort": 1, "description": "CAN bus communication protocol overview", "updated_at": "2026-05-20T10:30:00Z" } ], "pagination": { "page": 1, "limit": 10, "total": 25, "totalPages": 3 } } ``` ### 単一ドキュメントの取得 ``` GET /api/v1/docs/:slug ``` **パスパラメータ：** | パラメータ | タイプ | 説明 | |-----------|--------|------| | `slug` | string | ドキュメントスラッグ | **クエリパラメータ：** | パラメータ | タイプ | 必須 | 説明 | |-----------|--------|------|------| | `lang` | string | いいえ | 言語コード、デフォルト zh | **例：** ```bash curl "https://geowiki.pro/api/v1/docs/can-bus-protocol?lang=en" ``` **レスポンス：** ```json { "success": true, "data": { "slug": "can-bus-protocol", "title": "CAN Bus Protocol", "category": "can-motion", "tags": ["can-bus", "protocol"], "author": "admin", "sort": 1, "description": "CAN bus communication protocol overview", "content": "# CAN Bus Protocol\n\nThe Controller Area Network (CAN)...", "updated_at": "2026-05-20T10:30:00Z" } } ``` ::: note デフォルト言語以外のリクエストでは、システムはカスケードマージを実行：まず中国語ドキュメントをベースとして読み込み、ターゲット言語ドキュメントで一致するスラッグをオーバーレイします。したがって、中国語バージョンのみのドキュメントでも、英語リクエストではコンテンツを返すことができます。 ::: ### ドキュメント検索 ``` GET /api/v1/docs/search ``` **クエリパラメータ：** | パラメータ | タイプ | 必須 | 説明 | |-----------|--------|------|------| | `q` | string | はい | 検索キーワード | | `lang` | string | いいえ | 言語コード | | `category` | string | いいえ | カテゴリスラッグ | | `page` | number | いいえ | ページ番号 | | `limit` | number | いいえ | 1 ページあたりの件数 | **例：** ```bash curl "https://geowiki.pro/api/v1/docs/search?q=can+bus&lang=en&category=can-motion" ``` **レスポンス：** ```json { "success": true, "data": [ { "slug": "can-bus-protocol", "title": "CAN Bus Protocol", "description": "CAN bus communication protocol overview", "score": 0.95 } ], "pagination": { "page": 1, "limit": 20, "total": 5, "totalPages": 1 } } ``` ### カテゴリリストの取得 ``` GET /api/v1/categories ``` **レスポンス：** ```json { "success": true, "data": [ { "slug": "can-motion", "name": "CAN 运动控制", "name_en": "CAN Motion Control", "description": "CAN 总线运动控制产品文档" } ] } ``` ### タグリストの取得 ``` GET /api/v1/tags ``` **レスポンス：** ```json { "success": true, "data": [ { "slug": "can-bus", "name": "CAN 总线", "name_en": "CAN Bus" } ] } ``` ### サイト設定の取得 ``` GET /api/v1/config ``` **レスポンス：** ```json { "success": true, "data": { "hero_title": "GEO Wiki Pro", "hero_subtitle": "Technical Documentation Platform", "featured_slugs": ["quick-start", "faq"], "logo_url": "/media/logo.png", "favicon_url": "/media/favicon.ico" } } ``` ### 統合メタデータの取得 ``` GET /api/v1/meta ``` カテゴリ、タグ、通知情報の統合データを返します。 **レスポンス：** ```json { "success": true, "data": { "categories": [ ... ], "tags": [ ... ], "notice": "Important announcement text" } } ``` ### AI クローラーフィード ``` GET /api/v1/llms.txt ``` AI クローラー向けに最適化されたテキストコンテンツを返します。 ### サイトマップ ``` GET /api/v1/geo/sitemap.xml ``` XML 形式のサイトマップを返します。 ### フィードバックの送信 ``` POST /api/v1/feedback ``` **リクエストボディ：** ```json { "slug": "can-bus-protocol", "content": "Great documentation!", "rating": 5 } ``` **レスポンス：** ```json { "success": true, "data": { "id": "fb_123456" } } ``` --- ## 認証エンドポイント ### ユーザーログイン ``` POST /api/v1/auth/login ``` **リクエストボディ：** ```json { "username": "admin", "password": "your-password" } ``` **レスポンス：** ```json { "success": true, "data": { "user": { "username": "admin", "role": "admin" }, "mustChangePassword": false } } ``` ::: warning 初回ログイン时、`mustChangePassword` は `true` となり、管理機能にアクセスする前にパスワード変更エンドポイントを呼び出す必要があります。 ::: ### ユーザーログアウト ``` POST /api/v1/auth/logout ``` ### 現在のユーザー情報の取得 ``` GET /api/v1/auth/me ``` **レスポンス：** ```json { "success": true, "data": { "username": "admin", "role": "admin", "passwordChanged": true } } ``` ### パスワード変更 ``` POST /api/v1/auth/change-password ``` **リクエストボディ：** ```json { "oldPassword": "current-password", "newPassword": "new-password" } ``` ### 新規ユーザー登録 ``` POST /api/v1/auth/register ``` ::: warning このエンドポイントは管理者のみ利用可能です。 ::: **リクエストボディ：** ```json { "username": "newuser", "password": "user-password", "role": "editor" } ``` --- ## 管理エンドポイント すべての管理エンドポイントには JWT 認証と管理者/エディターロールが必要です。 ### ドキュメント管理 #### ドキュメント作成 ``` POST /api/v1/admin/docs ``` **リクエストボディ：** ```json { "slug": "my-new-doc", "title": "My New Document", "category": "support", "tags": ["guide", "tutorial"], "author": "admin", "sort": 5, "description": "A helpful guide", "content": "# My New Document\n\nContent here...", "lang": "en" } ``` ::: tip スラッグが提供されない場合、システムはタイトルから自動生成します。作成時にスラッグの重複をチェックします。 ::: #### ドキュメント更新 ``` PUT /api/v1/admin/docs/:slug ``` ドキュメントを更新すると、共有フィールド（category、tags、author、sort）が他の言語バージョンに自動同期されます。 #### ドキュメント削除 ``` DELETE /api/v1/admin/docs/:slug ``` #### ドキュメント並べ替え ``` PUT /api/v1/admin/docs/reorder ``` **リクエストボディ：** ```json { "slugs": ["doc-1", "doc-2", "doc-3"], "category": "can-motion", "lang": "zh" } ``` ::: note このエンドポイントは `PUT /api/v1/admin/docs/:slug` の前に定義する必要があります。否则、Express が `reorder` をスラッグパラメータとしてマッチングします。 ::: ### カテゴリ管理 #### カテゴリリストの取得 ``` GET /api/v1/admin/categories ``` #### カテゴリ作成 ``` POST /api/v1/admin/categories ``` **リクエストボディ：** ```json { "slug": "new-category", "name": "新分类", "name_en": "New Category", "description": "Category description" } ``` #### カテゴリ更新 ``` PUT /api/v1/admin/categories/:slug ``` #### カテゴリ削除 ``` DELETE /api/v1/admin/categories/:slug ``` ### タグ管理 #### タグリストの取得 ``` GET /api/v1/admin/tags ``` #### タグ作成 ``` POST /api/v1/admin/tags ``` **リクエストボディ：** ```json { "slug": "new-tag", "name": "新标签", "name_en": "New Tag" } ``` #### タグ削除 ``` DELETE /api/v1/admin/tags/:slug ``` ### フィードバック管理 #### フィードバックリストの取得 ``` GET /api/v1/admin/feedback ``` #### フィードバック削除 ``` DELETE /api/v1/admin/feedback/:id ``` ### メディア管理 #### メディアリストの取得 ``` GET /api/v1/admin/media ``` #### メディアファイルの削除 ``` DELETE /api/v1/admin/media/:filename ``` ### ファイルアップロード ``` POST /api/v1/media/upload ``` **リクエスト：** `multipart/form-data` | フィールド | タイプ | 必須 | 説明 | |-----------|--------|------|------| | `file` | file | はい | アップロードするファイル | ::: warning ファイルアップロードはマジックバイトで実際のタイプを検出します。ファイル名は `encodeURIComponent` でエンコードされます。 ::: **例：** ```bash curl -X POST "https://geowiki.pro/api/v1/media/upload" \ -H "Cookie: jwt=your-token" \ -F "[email protected]" ``` ### サイト設定管理 #### 完全な設定の取得 ``` GET /api/v1/admin/config ``` #### 設定の更新 ``` PUT /api/v1/admin/config ``` **リクエストボディ：** ```json { "hero_title": "My Wiki", "hero_subtitle": "Technical Documentation", "featured_slugs": ["quick-start", "faq"], "logo_url": "/media/logo.png", "favicon_url": "/media/favicon.ico", "customHeadHtml": "<meta name=\"theme-color\" content=\"#3b82f6\">" } ``` ::: note `customHeadHtml` フィールドは `<script>`、`<iframe>`、`on*` イベント属性を自動的にフィルタリングし、XSS 攻撃を防止します。 ::: ### ドラフト管理 #### ドラフトの公開 ``` POST /api/v1/admin/drafts/:slug/publish ``` #### ドラフトの拒否 ``` DELETE /api/v1/admin/drafts/:slug ``` ### ユーザー管理 #### ユーザーリストの取得 ``` GET /api/v1/admin/users ``` #### ユーザー作成 ``` POST /api/v1/admin/users ``` #### ユーザー削除 ``` DELETE /api/v1/admin/users/:username ``` ### 統計情報 ``` GET /api/v1/admin/stats ``` ドキュメント数、カテゴリ統計、タグ使用状況などのダッシュボードデータを返します。 ### 留言管理 #### 留言リストの取得 ``` GET /api/v1/admin/guestbook ``` #### 留言作成 ``` POST /api/v1/admin/guestbook ``` #### 留言更新 ``` PUT /api/v1/admin/guestbook/:id ``` #### 留言削除 ``` DELETE /api/v1/admin/guestbook/:id ``` ### GEO 分析 #### GEO 概要の取得 ``` GET /api/v1/admin/geo/overview ``` #### GEO ファイルの再生成 ``` POST /api/v1/admin/geo/rebuild ``` `llms.txt` と `sitemap.xml` の再生成をトリガーします。 --- ## HTTP ステータスコード | HTTP ステータスコード | 説明 | |---------------------|------| | 200 | 成功 | | 201 | 正常に作成 | | 400 | リクエストパラメータエラー | | 401 | 未認証またはトークン期限切れ | | 403 | 権限なし | | 404 | リソースが見つからない | | 409 | リソース競合（例：スラッグ重複） | | 429 | リクエストが多すぎ（レート制限） | | 500 | サーバー内部エラー | --- ## セキュリティメカニズム | メカニズム | 説明 | |-----------|------| | JWT 認証 | httpOnly cookie、2 時間で期限切れ | | CSRF 保護 | Double-submit cookie HMAC 検証 | | レート制限 | グローバル 300 リクエスト/分、認証エンドポイント 10 リクエスト/分 | | CSP | Helmet nonce ベースの Content Security Policy | | ファイルアップロード | マジックバイトタイプ検出 | | スラッグ検証 | 正規表現マッチング + 長度制限 + 重複チェック | --- *最終更新: 2026-06-06 | バージョン: v3.0.2*