# Plume API調査結果
**調査日**: 2025-11-15
**対象**: Plume CMS REST API
**リポジトリ**: https://github.com/Plume-org/Plume
---
## 🎯 調査サマリー
Plume CMSはREST APIを提供していますが、**公式ドキュメントは基本的な認証情報のみで、詳細なエンドポイント仕様は不明**です。
---
## ✅ 確認できた情報
### 1. 認証方式: OAuth2
**フロー**:
1. アプリ登録: `POST /api/v1/apps`
2. トークン取得: `GET /api/v1/oauth2`
3. API呼び出し: `Authorization: Bearer <token>` ヘッダー
**参考**:
- [公式APIドキュメント](https://docs.joinplu.me/api/)
- [GitHub Issue #275](https://github.com/Plume-org/Plume/issues/275) (2018年実装)
### 2. エンドポイント: /api/v1/apps
**目的**: アプリケーション登録
**リクエスト** (推測):
```json
POST /api/v1/apps
Content-Type: application/json
{
"name": "アプリ名",
"website": "https://example.com" (optional),
"redirect_uri": "https://example.com/callback" (optional)
}
```
**レスポンス** (不明):
- `client_id`と`client_secret`を返すと推測されるが、詳細は未確認
**ソースコード**: `plume-api/src/apps.rs`
### 3. エンドポイント: /api/v1/oauth2
**目的**: アクセストークン取得
**リクエスト**:
```
GET /api/v1/oauth2?client_id=xxx&client_secret=yyy&scopes=read+write&username=user&password=pass
```
**パラメータ**:
- `client_id` (required)
- `client_secret` (required)
- `scopes` (required) - `+`区切り
- `username` (required)
- `password` (required)
**レスポンス**:
```json
{
"token": "<YOUR TOKEN HERE>"
}
```
### 4. スコープ
以下のスコープが利用可能：
| スコープ | 説明 |
|---------|------|
| `read` | 全体読み取り |
| `write` | 全体書き込み |
| `read:SCOPE` | 特定領域の読み取り (例: `read:posts`) |
| `write:SCOPE` | 特定領域の書き込み (例: `write:posts`) |
**注**: 具体的なSCOPE値のリストは不明
### 5. 認証ヘッダー
```
Authorization: Bearer <YOUR TOKEN HERE>
```
---
## ❓ 不明な点
### 記事関連エンドポイント
以下は**推測**です：
| エンドポイント | メソッド | 説明 | 確証 |
|--------------|---------|------|-----|
| `/api/v1/blogs` | GET | ブログ一覧 | ❌ 未確認 |
| `/api/v1/blogs/:id` | GET | ブログ詳細 | ❌ 未確認 |
| `/api/v1/blogs/:id/articles` | GET | 記事一覧 | ❌ 未確認 |
| `/api/v1/blogs/:id/articles/:id` | GET | 記事詳細 | ❌ 未確認 |
| `/api/v1/blogs/:id/articles` | POST | 記事作成 | ❌ 未確認 |
| `/api/v1/blogs/:id/articles/:id` | PUT | 記事更新 | ❌ 未確認 |
| `/api/v1/blogs/:id/articles/:id` | DELETE | 記事削除 | ❌ 未確認 |
**ソースコード**: `plume-api/src/posts.rs` に実装があるが、詳細は未調査
### ユーザー関連エンドポイント
| エンドポイント | メソッド | 説明 | 確証 |
|--------------|---------|------|-----|
| `/api/v1/users/me` または `/api/v1/auth/me` | GET | 現在のユーザー情報 | ❌ 未確認 |
### レスポンス形式
- 記事オブジェクトのフィールド構造は不明
- エラーレスポンスの形式は不明
- ページネーション仕様は不明
---
## 🔍 追加調査が必要な項目
### 優先度: 高 🔴
1. **実際のPlumeインスタンスでのAPI検証**
- テスト用Plumeサーバーを立ち上げる
- 各エンドポイントにcurlでリクエスト
- レスポンス形式を記録
2. **posts.rs の詳細調査**
- `/api/v1/posts` なのか `/api/v1/blogs/:id/articles` なのか
- リクエスト/レスポンスのフィールド
- エラーレスポンスの形式
3. **認証フローの実践**
- アプリ登録の実際のレスポンス
- トークン取得の実際のレスポンス
- トークンの有効期限とリフレッシュ
### 優先度: 中 🟡
4. **エラーハンドリング**
- 401, 403, 404, 500エラーのレスポンス形式
- バリデーションエラーの形式
5. **ページネーション**
- 記事一覧のページネーション方式 (offset/cursor)
- レスポンスに含まれるメタデータ
6. **その他の機能**
- カテゴリ、タグ、メディアのエンドポイント
- コメント、いいね機能のエンドポイント
---
## 💡 現在の実装方針
### モックAPIとの差分管理
現在の`tests/integration/utils/mockApi.ts`は以下の推測に基づいて実装：
| 項目 | モックの実装 | 実際のAPI (推測) | 確認方法 |
|-----|-------------|-----------------|---------|
| 認証方式 | トークンベース | OAuth2 | ✅ 確認済み |
| ベースURL | `/api` | `/api/v1` | ❓ 要確認 |
| ユーザー情報 | `/api/users/me` | `/api/v1/users/me` | ❓ 要確認 |
| 記事一覧 | `/api/blogs/:id/articles` | 不明 | ❓ 要確認 |
| 記事詳細 | `/api/blogs/:id/articles/:id` | 不明 | ❓ 要確認 |
### 次のステップ
CODEX MCPの推奨に従い、以下の順で進める：
1. ✅ **API仕様調査** (このドキュメント)
2. ⬜ **PlumeApiClientの設定注入 (DI) 実装**
- `baseUrl`, `authProvider`, `transport`を注入可能に
- モックと実APIを切り替え可能に
3. ⬜ **エラーハンドリング強化**
- リトライ機構
- タイムアウト処理
- 詳細なエラー情報
4. ⬜ **実APIスモークテスト**
- 環境変数で実行制御
- 最小限のhappy pathから
---
## 📚 参考資料
- [Plume公式ドキュメント](https://docs.joinplu.me/)
- [Plume API Documentation](https://docs.joinplu.me/api/)
- [GitHub: Plume-org/Plume](https://github.com/Plume-org/Plume)
- [GitHub Issue #275: API authentication](https://github.com/Plume-org/Plume/issues/275)
- [plume-api/src/apps.rs](https://github.com/Plume-org/Plume/blob/main/plume-api/src/apps.rs)
- [plume-api/src/posts.rs](https://github.com/Plume-org/Plume/blob/main/plume-api/src/posts.rs)
---
## 🚨 重要な注意事項
**現時点では実際のPlume APIの詳細仕様が不明なため、以下の対応を推奨**:
1. モックAPIベースのTDDを継続
2. 実APIとの差分を吸収する抽象化層を実装
3. 環境変数による切り替え機構を用意
4. 実API検証は別途スモークテストとして実装
これにより、API仕様が判明次第、最小限の変更で対応可能になります。
