# 画面設計書 17-APIビュー画面

## 概要

本ドキュメントは、Payload CMSの管理画面における「APIビュー画面」の設計仕様を定義するものである。ドキュメントのAPIレスポンスをJSON形式で確認できる画面である。

### 本画面の処理概要

APIビュー画面は、現在表示中のドキュメントがREST APIを通じてどのようなJSON形式で返却されるかをリアルタイムで確認できるデバッグ・開発支援画面である。

**業務上の目的・背景**：Payload CMSはヘッドレスCMSとして、フロントエンドアプリケーションにREST APIを通じてデータを提供する。開発者は、フロントエンド実装時にAPIレスポンスの構造を確認する必要がある。この画面により、管理画面上で直接APIレスポンスを確認でき、Postmanや curl などの外部ツールを使わずに効率的な開発が可能となる。また、depth（深度）やlocale（ロケール）などのパラメータを変更しながらレスポンスの変化を確認できる。

**画面へのアクセス方法**：ドキュメント編集画面のタブメニューから「API」を選択、またはURLで `/{admin}/collections/{collectionSlug}/{docId}/api` に直接アクセスすることで表示される。

**主要な操作・処理内容**：
1. ドキュメントのAPIレスポンスをJSON形式で表示
2. depth（関連データの深さ）パラメータの変更
3. locale（ロケール）パラメータの変更
4. draft（ドラフト）フラグの切り替え
5. authenticated（認証あり/なし）の切り替え
6. フルスクリーン表示の切り替え
7. API URLのコピー

**画面遷移**：
- 遷移元：ドキュメント編集画面
- 遷移先：ドキュメント編集画面（戻る）

**権限による表示制御**：ドキュメントの `read` 権限を持つユーザーがAPIビューを閲覧可能。authenticatedをオフにすると、認証なしでのAPIレスポンスを確認できる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | REST API | 主機能 | ドキュメントのAPIレスポンス表示 |
| 12 | GraphQL API | 補助機能 | GraphQLレスポンス形式での表示（対応時） |
| 30 | Admin UI | 補助機能 | JSONビューワーUIのレンダリング |

## 画面種別

詳細（APIデバッグ）

## URL/ルーティング

- コレクション: `/{adminRoute}/collections/{collectionSlug}/{docId}/api`
- グローバル: `/{adminRoute}/globals/{globalSlug}/api`

パラメータ:
- `{adminRoute}`: 管理画面のベースパス
- `{collectionSlug}`: コレクションスラッグ
- `{docId}`: ドキュメントID
- `{globalSlug}`: グローバルスラッグ

クエリパラメータ:
- `depth`: 関連データの深さ（デフォルト: config.defaultDepth）
- `locale`: 取得するロケール
- `draft`: ドラフトデータを取得するか

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 必須 | 説明 |
|--------|----------|---------|------|------|
| depth | 入力 | number | No | 関連データの深さ（0-10） |
| locale | 入力 | string | No | 取得するロケール |
| draft | 入力 | boolean | No | ドラフトデータを含めるか |
| authenticated | 入力 | boolean | No | 認証付きリクエストか |
| jsonData | 出力 | object | - | APIレスポンスのJSONデータ |
| fetchURL | 出力 | string | - | 実際のAPIエンドポイントURL |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| API URL | string | 現在のAPIエンドポイントURL（コピー可能） |
| Draft チェックボックス | boolean | ドラフトデータ取得フラグ |
| Authenticated チェックボックス | boolean | 認証フラグ |
| Locale セレクター | Select | ロケール選択（多言語時） |
| Depth 入力 | NumberField | 深さ指定（0-10） |
| JSON表示エリア | JSONViewer | フォーマット済みJSONの表示 |
| フルスクリーンボタン | Button | 表示エリアの最大化 |

## イベント仕様

### 1-APIレスポンス表示

画面表示時にドキュメントのAPIレスポンスを取得して表示する。

**処理フロー**：
1. useDocumentInfo() から id, collectionSlug, globalSlug を取得
2. 初期データ（initialData）を設定
3. fetchURL を構築（serverURL + apiRoute + endpoint + params）
4. データが変わるたびに useEffect で fetch を実行

### 2-パラメータ変更

depth、locale、draft、authenticated の変更時にAPIを再取得する。

**処理フロー**：
1. フォームフィールドの値が変更される
2. URLSearchParams を再構築
3. fetchURL が更新される
4. useEffect が発火し、新しいデータを fetch
5. JSONビューを更新

### 3-フルスクリーン切り替え

JSON表示エリアをフルスクリーンにする。

**処理フロー**：
1. フルスクリーンボタンをクリック
2. fullscreen state を toggle
3. CSSクラスを適用してUIを最大化

### 4-API URLコピー

現在のAPI URLをクリップボードにコピーする。

**処理フロー**：
1. CopyToClipboardコンポーネントをクリック
2. fetchURL をクリップボードにコピー
3. 成功フィードバックを表示

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| APIレスポンス取得 | {collectionSlug} / globals | SELECT | ドキュメントデータ取得（読み取り専用） |

### テーブル別更新項目詳細

この画面はデータの読み取り専用であり、データベースへの書き込みは発生しない。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| - | エラー | Error parsing response | JSONパースエラー時 |
| - | エラー | Error making request | リクエストエラー時 |

## 例外処理

| 例外状態 | 対応 |
|---------|------|
| JSONパースエラー | toast.error('Error parsing response') を表示 |
| ネットワークエラー | toast.error('Error making request') を表示 |
| 認証エラー（authenticatedオフ時） | APIレスポンスにエラーが含まれる |

## 備考

- APIViewはクライアントコンポーネント（'use client'）として実装されている
- useSearchParams() でURLパラメータを読み取り、フォーム状態を同期
- fetchはcredentials: authenticated ? 'include' : 'omit' で認証を制御
- Accept-Language ヘッダーで i18n.language を送信
- トラッシュ内ドキュメントの場合は trash=true パラメータが追加される
- RenderJSONコンポーネントでJSONをシンタックスハイライト表示
- MinimizeMaximizeIconでフルスクリーン切り替えアイコンを表示

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

APIビュー画面で扱うデータ構造の理解が重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.client.tsx | `packages/next/src/views/API/index.client.tsx` | コンポーネントの状態変数（行66-73） |

**読解のコツ**: このコンポーネントは完全にクライアントサイドで動作する。useDocumentInfo()からドキュメント情報を取得し、REST APIを直接呼び出す。

#### Step 2: エントリーポイントを理解する

APIビュー画面のエントリーポイントとなるファイルを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.tsx | `packages/next/src/views/API/index.tsx` | APIView関数（サーバー側、ほぼ空） |
| 2-2 | index.client.tsx | `packages/next/src/views/API/index.client.tsx` | APIViewClient（メインロジック） |

**主要処理フロー**:
1. **行29-30**: useDocumentInfo() でドキュメント情報取得
2. **行43-47**: collectionConfig/globalConfig の取得
3. **行53-64**: draftsEnabled と docEndpoint の設定
4. **行66-73**: state の初期化（data, draft, locale, depth, authenticated, fullscreen）
5. **行77-82**: URLパラメータの構築
6. **行84-88**: fetchURL の構築
7. **行90-115**: useEffect でデータ fetch

#### Step 3: UI構造を理解する

フォームとJSON表示のUI構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.client.tsx | `packages/next/src/views/API/index.client.tsx` | レンダリング部分（行117-220） |

**主要UI構成**:
- **行133-139**: API URL表示とコピーボタン
- **行140-201**: Form（draft, authenticated, locale, depth の設定）
- **行203-217**: JSON表示エリアとフルスクリーンボタン

### プログラム呼び出し階層図

```
APIView (API/index.tsx) - サーバーコンポーネント
    │
    └─ APIViewClient (API/index.client.tsx) - クライアントコンポーネント
           │
           ├─ useDocumentInfo() - ドキュメント情報取得
           │   └─ id, collectionSlug, globalSlug, initialData
           │
           ├─ useConfig() - 設定取得
           │   └─ defaultDepth, localization, serverURL, apiRoute
           │
           ├─ useSearchParams() - URLパラメータ取得
           │
           ├─ getEntityConfig() - エンティティ設定取得
           │
           ├─ formatAdminURL() - fetchURL構築
           │
           ├─ fetch() - API呼び出し
           │   └─ credentials, Accept-Language
           │
           └─ RenderJSON - JSON表示
```

### データフロー図

```
[入力]                       [処理]                              [出力]

useDocumentInfo ───▶ APIViewClient ───▶ JSON表示
  - id                        │
  - collectionSlug            ├─▶ fetchURL構築
  - initialData               │      └─▶ serverURL + apiRoute + endpoint + params
                              │
フォーム入力 ─────────────────┤
  - depth                     ├─▶ fetch()
  - locale                    │      └─▶ credentials, headers
  - draft                     │
  - authenticated             ├─▶ JSON parse
                              │
                              └─▶ RenderJSON
                                     └─▶ シンタックスハイライト表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.tsx | `packages/next/src/views/API/index.tsx` | ソース | APIビュー画面のサーバーコンポーネント |
| index.client.tsx | `packages/next/src/views/API/index.client.tsx` | ソース | APIビュー画面のクライアントコンポーネント |
| RenderJSON/index.tsx | `packages/next/src/views/API/RenderJSON/index.tsx` | ソース | JSONシンタックスハイライト表示 |
| LocaleSelector/index.tsx | `packages/next/src/views/API/LocaleSelector/index.tsx` | ソース | ロケール選択コンポーネント |
| index.scss | `packages/next/src/views/API/index.scss` | スタイル | APIビューのスタイル定義 |
| CopyToClipboard | `packages/ui/src/elements/CopyToClipboard/index.tsx` | ソース | クリップボードコピーコンポーネント |
| CheckboxField | `packages/ui/src/fields/Checkbox/index.tsx` | ソース | チェックボックスフィールド |
| NumberField | `packages/ui/src/fields/Number/index.tsx` | ソース | 数値入力フィールド |
| MinimizeMaximizeIcon | `packages/ui/src/icons/MinimizeMaximize/index.tsx` | ソース | フルスクリーンアイコン |
