IT 技書の森

API ファーストデザイン

実装の前に API の仕様を設計・合意し、フロントエンドとバックエンドの並行開発を可能にするアプローチ

API設計

API ファーストデザインとは

API ファーストデザインは、バックエンドの実装を始める前に API の仕様 (エンドポイント、リクエスト/レスポンスの形式、エラーコード) を設計し、チーム間で合意するアプローチである。OpenAPI (Swagger) 仕様書を先に作成し、フロントエンドとバックエンドが並行して開発を進められる。

従来の「コードファースト」では、バックエンドが API を実装してからフロントエンドが開発を始めるため、バックエンド完成待ちのボトルネックが発生する。API ファーストはこの依存関係を断ち切る。

コードファーストとの比較

観点 API ファースト コードファースト
設計タイミング 実装前に仕様を確定 実装しながら仕様を決定
並行開発 フロント/バックが同時に開発可能 バックエンド完成待ちが発生
仕様書 常に最新 (仕様が正) コードと乖離しやすい
初期コスト 仕様設計に時間がかかる すぐに実装を開始できる
仕様変更 変更の影響が事前に分かる 実装後に気づいて手戻り
チーム間コミュニケーション 仕様書が共通言語になる 口頭やチャットに依存

実践の流れ

1. OpenAPI 仕様書の作成

openapi: 3.0.3
info:
  title: Order API
  version: 1.0.0
paths:
  /orders:
    post:
      summary: 注文を作成する
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: 注文が作成された
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: バリデーションエラー
        '409':
          description: 在庫不足

エンドポイント、リクエスト/レスポンスのスキーマ、エラーレスポンスを先に定義する。エラーケースの設計を後回しにしがちだが、API ファーストではこの段階で網羅する。

2. モックサーバーで並行開発

フロントエンドは Prism や MSW (Mock Service Worker) を使い、仕様書からモックサーバーを自動生成して開発を開始する。バックエンドの完成を待つ必要がない。

# Prism でモックサーバーを起動
npx @stoplight/prism-cli mock openapi.yaml --port 4010

3. コントラクトテストで整合性を検証

バックエンドの実装が仕様書に準拠しているかを自動テストで検証する。仕様書とコードの乖離を CI で検出できる。

API ファーストが効果を発揮する場面

  • フロントエンドとバックエンドが別チーム (または別の開発者) の場合
  • モバイルアプリと Web アプリが同じ API を共有する場合
  • 外部パートナーに API を公開する場合
  • マイクロサービス間の API 設計

逆に、1 人で全スタックを開発する小規模プロジェクトでは、コードファーストの方が効率的な場合もある。

AWS での活用

API Gateway + OpenAPI

API Gateway は OpenAPI 仕様書のインポートをサポートしている。SAM テンプレートの DefinitionBody に仕様書を埋め込めば、API の定義を IaC として管理できる。

仕様書を変更すると API Gateway の設定が自動的に更新されるため、仕様とインフラの一致が保証される。

リクエストバリデーション

API Gateway のリクエストバリデーション機能を使えば、OpenAPI スキーマに基づいてリクエストを自動検証できる。不正なリクエストは Lambda に到達する前に 400 エラーで弾かれるため、Lambda 側のバリデーションコードを削減できる。

よくある失敗パターン

仕様書を書いたが更新しない

最初に仕様書を作成しても、実装中の変更を仕様書に反映しないと、仕様書が嘘になる。CI に仕様書と実装の整合性チェックを組み込み、乖離を自動検出する仕組みが必要だ。

過度に詳細な仕様を最初から書く

全エンドポイントの全フィールドを最初から完璧に定義しようとすると、仕様設計だけで数週間かかる。まず主要なエンドポイントの骨格を定義し、詳細は実装と並行して詰めるのが現実的だ。

実務での活用方法は関連書籍にも詳しい。

関連用語