# POST /api/workflow/diff — 候補workflow差分取得

一覧: [Yagra Workflow Studio API エンドポイント一覧](./index.md)
最終更新: `2026-02-14`

## 1. 概要

- 目的: 現在状態と候補状態の差分を計算し、validation結果を返す。
- 利用者/権限: ローカル Studio 利用者。
- 副作用: なし。

## 2. リクエスト

### 2.1 ヘッダー

| 項目 | 必須 | 値 | 説明 |
| --- | --- | --- | --- |
| Content-Type | Yes | application/json | JSONボディ送信 |

### 2.2 パスパラメータ

なし。

### 2.3 クエリパラメータ

なし。

### 2.4 リクエストボディ

| field | type | required | 制約 | 説明 |
| --- | --- | --- | --- | --- |
| workflow | object | Yes | mapping | 候補workflow |
| ui_state | object | Yes | mapping | 候補ui_state |
| base_revision | string | Yes | non-empty推奨 | 差分基準revision |

### 2.5 リクエスト例

```bash
curl -X POST 'http://127.0.0.1:8787/api/workflow/diff' \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow": {},
    "ui_state": {},
    "base_revision": "9e9b..."
  }'
```

## 3. レスポンス

### 3.1 成功レスポンス

| Status | 条件 | 説明 |
| --- | --- | --- |
| 200 | 正常終了 | 差分とvalidation結果 |

### 3.2 レスポンスボディ

| field | type | nullable | 説明 |
| --- | --- | --- | --- |
| base_revision | string | No | 現在revision |
| candidate_revision | string | No | 候補revision |
| summary | object | No | 差分件数サマリ |
| changes | object[] | No | 変更イベント（`kind`,`path`,`before`,`after`） |
| yaml_unified_diff | string | No | unified diff |
| validation_report | object | No | `is_valid`,`issues[]` |

### 3.3 成功レスポンス例

```json
{
  "base_revision": "9e9b...",
  "candidate_revision": "f0aa...",
  "summary": {"total": 1, "nodes": 0, "edges": 0, "params": 1, "ui_state": 0, "other": 0},
  "changes": [],
  "yaml_unified_diff": "@@ ...",
  "validation_report": {"is_valid": true, "issues": []}
}
```

## 4. エラー

| Status | type | message例 | 発生条件 | クライアント対応 |
| --- | --- | --- | --- | --- |
| 400 | `base_revision must be a string` | - | 型不正 | 入力修正 |
| 400 | `workflow must be a mapping` | - | 型不正 | 入力修正 |
| 400 | `ui_state must be a mapping` | - | 型不正 | 入力修正 |
| 400 | invalid_payload | ... | 候補payloadが不正 | 入力修正 |
| 409 | studio_target_required | workflow target is not selected | ターゲット未選択 | `/api/studio/open/create` |
| 409 | revision_conflict | - | `base_revision` 不一致 | 再読み込み |
| 422 | load_failed | ... | 現在workflow読み込み失敗 | ファイル修正 |

## 5. 備考

- 保存前の事前確認API。状態は変更しない。

## 6. 実装同期メモ

- 関連実装ファイル: `src/yagra/adapters/inbound/workflow_studio_server.py`
- 関連テスト: `tests/integration/test_workflow_studio_api.py`
- 未解決事項: なし
