4-4 画面・API設計
UI and API Design
1. 画面設計の基本
1.1 画面設計の目的
画面設計は、ユーザーがシステムと対話するインターフェースを定義する。 使いやすさ（ユーザビリティ）と業務効率の両立が求められる。
| 設計成果物 | 内容 | 目的 |
|---|---|---|
| 画面一覧 | システムの全画面リスト | スコープの確認 |
| 画面遷移図 | 画面間の遷移関係 | ナビゲーションの設計 |
| 画面レイアウト | 各画面の配置設計 | 開発の指針 |
| 画面項目定義 | 入出力項目の詳細 | 実装仕様の明確化 |
1.2 UI設計の原則
使いやすいUIを設計するための原則がある。
| 原則 | 説明 | 実践例 |
|---|---|---|
| 一貫性 | 同じ操作は同じ結果をもたらす | ボタンの配置、色の意味を統一 |
| フィードバック | 操作結果を即座に伝える | 処理中表示、成功/エラーメッセージ |
| 可視性 | 現在の状態が見てわかる | 選択状態のハイライト、進捗表示 |
| エラー防止 | ミスを起こしにくい設計 | 入力チェック、確認ダイアログ |
| 柔軟性 | 初心者から熟練者まで対応 | ショートカット、詳細/簡易モード |
| ミニマリズム | 不要な情報を排除 | 必要な情報のみ表示 |
ヤコブ・ニールセンが提唱したUI設計の10原則は、 ユーザビリティ評価の基準として広く参照されている。 上記の原則はその一部を抜粋したものである。
2. 画面設計書の作成
2.1 画面レイアウト
画面レイアウトは、ワイヤーフレームまたはモックアップで表現する。
| 表現方法 | 詳細度 | 用途 |
|---|---|---|
| スケッチ | 低 | アイデア出し、初期検討 |
| ワイヤーフレーム | 中 | 構造・配置の確認 |
| モックアップ | 高 | デザインの確認 |
| プロトタイプ | 最高 | 操作感の確認 |
2.2 画面項目定義
各画面の入出力項目を詳細に定義する。
| 定義項目 | 内容 |
|---|---|
| 項目ID | 一意の識別子 |
| 項目名 | 画面上の表示名 |
| 入出力区分 | 入力/出力/入出力 |
| データ型 | 文字列、数値、日付など |
| 桁数 | 最大桁数、表示桁数 |
| 必須/任意 | 入力必須かどうか |
| 入力チェック | バリデーションルール |
| 初期値 | デフォルト値 |
| 関連項目 | 連動する項目 |
2.3 画面遷移図
画面間の遷移を図示する。遷移のトリガー（ボタン押下、リンククリックなど） と遷移先を明確にする。
画面遷移図のポイント
主要な遷移パス（ハッピーパス）を明確にする。 エラー時の遷移も考慮する。 戻る操作、キャンセル操作も記載する。 共通ヘッダー・フッターからの遷移は別途整理する。
3. API設計の基本
3.1 APIとは
API（Application Programming Interface）は、 システム間でデータや機能をやり取りするためのインターフェースである。 現代のシステム開発では、フロントエンドとバックエンドの分離、 マイクロサービス連携などでAPIが重要な役割を果たす。
3.2 REST API
REST（Representational State Transfer）は、Web APIの設計スタイルとして 最も広く採用されている。
| RESTの原則 | 説明 |
|---|---|
| ステートレス | サーバーはクライアントの状態を保持しない |
| 統一インターフェース | HTTPメソッドとURIで操作を表現 |
| リソース指向 | 操作対象をリソースとして表現 |
| クライアント-サーバー分離 | フロントエンドとバックエンドの独立 |
3.3 HTTPメソッドとCRUD
REST APIではHTTPメソッドをCRUD操作に対応させる。
| HTTPメソッド | CRUD操作 | べき等性 | 例 |
|---|---|---|---|
| GET | Read（取得） | あり | GET /users/123 |
| POST | Create（作成） | なし | POST /users |
| PUT | Update（更新・全体） | あり | PUT /users/123 |
| PATCH | Update（更新・部分） | なし | PATCH /users/123 |
| DELETE | Delete（削除） | あり | DELETE /users/123 |
同じリクエストを複数回実行しても結果が同じになる性質。 GET、PUT、DELETEはべき等であるべき。 べき等なAPIは、ネットワーク障害時のリトライが安全である。
4. REST API設計のベストプラクティス
4.1 URI設計
REST APIのURI設計には守るべき原則がある。
| 原則 | 良い例 | 悪い例 |
|---|---|---|
| 名詞を使用 | /users | /getUsers |
| 複数形を使用 | /users | /user |
| 階層構造を表現 | /users/123/orders | /getUserOrders?userId=123 |
| 小文字、ハイフン | /order-items | /OrderItems, /order_items |
| バージョニング | /v1/users | バージョンなし |
4.2 HTTPステータスコード
適切なHTTPステータスコードを返すことで、クライアントに結果を明確に伝える。
| コード | 意味 | 使用場面 |
|---|---|---|
| 200 OK | 成功 | GET、PUT、PATCH成功時 |
| 201 Created | 作成成功 | POST成功時 |
| 204 No Content | 成功（レスポンスボディなし） | DELETE成功時 |
| 400 Bad Request | リクエストエラー | バリデーションエラー |
| 401 Unauthorized | 認証エラー | 未ログイン |
| 403 Forbidden | 認可エラー | 権限なし |
| 404 Not Found | リソースなし | 該当データなし |
| 500 Internal Server Error | サーバーエラー | 予期しないエラー |
4.3 レスポンス設計
APIレスポンスは一貫したフォーマットで設計する。
| 設計項目 | 推奨 |
|---|---|
| データフォーマット | JSON（Content-Type: application/json） |
| 日時フォーマット | ISO 8601形式（2024-01-15T09:30:00Z） |
| ページネーション | limit/offset または cursor方式 |
| エラーレスポンス | エラーコード、メッセージ、詳細を含む |
API設計では一貫性が非常に重要である。 命名規則、レスポンス形式、エラー処理などを API設計ガイドラインとして文書化し、チーム全体で遵守すべきである。
5. API仕様書
5.1 OpenAPI（Swagger）
OpenAPI Specification（旧Swagger）は、REST APIの仕様を記述する標準フォーマットである。 YAMLまたはJSONで記述し、ドキュメント生成やクライアントコード生成に活用できる。
| メリット | 説明 |
|---|---|
| 標準化 | 業界標準のフォーマットで記述 |
| ドキュメント生成 | Swagger UIで対話的なドキュメントを生成 |
| コード生成 | クライアント/サーバーコードの自動生成 |
| テスト | 仕様に基づいたAPIテストの自動化 |
API設計のドキュメント項目
エンドポイント（URI）、HTTPメソッド、 リクエストパラメータ（パス、クエリ、ヘッダー、ボディ）、 レスポンス（ステータスコード、ボディ）、 認証方式、レート制限、エラーコード一覧。
設計の基本を学習しました。 次は「第5章 開発・実装」で、実際のコーディングと開発プロセスについて学習しよう。
[1] Nielsen, J. (1994). Usability Engineering.
[2] Masse, M. (2011). REST API Design Rulebook.
[3] OpenAPI Initiative. OpenAPI Specification.