# 画面で使うAPIのポリシー

画面が表示と操作に必要とする項目、返すデータ量、サーバーの制約、更新結果の整合性をAPIの契約として確認する。

## 応答項目

| 条件 | 判定 |
|------|------|
| 表示や操作に必要な識別子、状態、関連項目が応答に含まれる | OK |
| 必要な項目がないため、別の項目を意味の違う値として表示する | REJECT |
| 一覧と詳細で必要な項目、件数、認可範囲が違い、応答契約を分ける | OK |
| 詳細のために全件一覧を取得して、不足する項目をクライアントで補う | REJECT |
| 関連データを個別リクエストで大量に取得し、通信回数が増えて画面の応答時間の要件を満たせない | REJECT |

APIを分けるか同じ応答を使うかは、必要な項目、件数、認可、更新頻度、実際のデータ量で決める。名前だけで専用性を決めない。

## データ量とページング

固定された小さい集合は全件を一度に返せる。大きくなり得る結果は、サーバーが上限を検証し、ページの順序と続き方を応答へ含める。

| 条件 | 判定 |
|------|------|
| 件数上限が仕様と実データから説明できる小さい集合を全件返す | OK |
| ページサイズ、sort、filterをクライアントが指定し、サーバーが型・権限・上限を検証する | OK |
| クライアントの指定を無制限に受け、結果量や応答時間の上限がない | REJECT |
| 大きくなり得る一覧を上限なしで全件返す | REJECT |
| cursorにsort、filter、tenant、snapshotなど結果を決める条件がなく、ページが重複・欠落する | REJECT |

クライアントから受けたページサイズは、サーバーが整数か、正の値か、主体の権限範囲に適合するかを確認し、サーバーが定めた最大値へ収める。省略時の値や最大値をクライアントの都合だけで決めず、取得量と応答時間を守るサーバー側の契約として扱う。

クライアントが件数を指定できるかどうかではなく、実際の最大件数、権限の範囲、応答時間、cursorの安定性で判定する。

## 集計と業務判定

受信済みの有限なデータを画面用に並べ替えたり合計したりする処理と、サーバーが確定する値を分ける。大量データ、最新性、認可、業務状態に関わる集計や判定は、サーバーが結果と対象範囲を返す。

| 条件 | 判定 |
|------|------|
| 上限のある小さい一覧を、受信した項目だけから表示用に合計する | OK |
| 大量または上限不明の全件を取得して件数・合計・判定を行う | REJECT |
| 在庫、権限、生成可否、業務状態の確定をクライアントだけで行う | REJECT |
| サーバーが集計値や判定結果を計算し、対象範囲や時点とともに返す | OK |
| 集計結果と明細の対象範囲や更新時点が違い、どの結果を表示したか分からない | REJECT |

## 認可と更新

サーバーは、認証された主体、対象リソース、tenant、現在状態、操作権限を確認してから更新する。クライアントの表示や許可操作の判断を最終判定として受け取らない。

| 条件 | 判定 |
|------|------|
| サーバーが対象と主体を再取得し、現在の認可と状態を確認してから更新する | OK |
| tenant・所有者・対象IDの条件が検索と更新の両方に適用される | OK |
| 権限不足、対象なし、状態競合、入力不備を同じ成功応答にする | REJECT |
| 入力修正、再ログイン、競合解消、再試行など、画面で必要な対応が異なる失敗を応答から区別できない | REJECT |
| versionまたはETagの一致を条件に原子的に更新し、競合を成功にしない | OK |
| 同じ操作の再送で重複作成が起きるのに、idempotencyまたは重複判定がない | REJECT |

取得と更新が同時に起きる場合は、返す結果の時点、古い書き込みの拒否、ページをつなぐ順序、再試行条件をAPIから読めるようにする。ETag、version、idempotency key、snapshot cursorは、実際の競合条件に対応するときに使う。