第 5 章
APIドキュメンテーションとガバナンス
Web APIは作成して終わりではありません。多くの開発者やシステムに利用されるAPIは、正確な「ドキュメンテーション」と、変更に対するルールである「ガバナンス」が不可欠です。
第5章では、OpenAPIを用いた現代的なドキュメント管理手法と、APIを安全に変更・維持するためのガバナンス設計について解説します。
1. スキーマファースト開発とOpenAPI
現代のAPI開発では、コードを書く前にAPIの仕様を記述する 「スキーマファースト開発（Schema-first Development）」 が主流です。この中心的な標準規格が OpenAPI Specification (OAS)（旧Swagger）です。
Rendering diagram...
graph TD
A[1. OpenAPI仕様書を書く <br> YAML/JSON] --> B(2. 自動ツールによる活用)
B --> C[フロントエンド: <br> モックサーバーで並行開発]
B --> D[バックエンド: <br> スキーマ駆動バリデーション]
B --> E[自動ドキュメント: <br> Swagger UI / Redoc]
B --> F[SDK生成: <br> クライアントコード自動生成]
style A fill:#eff6ff,stroke:#3b82f6,stroke-width:2px
style B fill:#f0fdf4,stroke:#22c55e,stroke-width:2px
スキーマファーストの利点
- 並行開発の実現: バックエンドの実装完了を待たずに、定義されたスキーマからモックサーバー（Prism等）を立ち上げてフロントエンドが開発を進められます。
- 仕様の齟齬の削減: 仕様が明文化されるため、結合テスト時のパラメータ名の違いなどのイライラが解消されます。
- ドキュメントの自動化: 定義ファイル（YAML/JSON）からインタラクティブなAPIドキュメント（Swagger UIやRedoc）を常に最新の状態で配信できます。
2. APIのバージョニング管理
APIをアップデートする際、既存のクライアントを壊さないためにバージョニングが必要です。主に以下の3つの手法があります。
| バージョニング手法 | 指定方法の例 | メリット | デメリット |
|---|---|---|---|
| パス（URI） | https://api.example.com/v1/users |
最も直感的でキャッシュしやすい | バージョンごとにURLが変わり、移行コストが高い |
| クエリパラメータ | https://api.example.com/users?version=1 |
シンプルに実装できる | ルーティングやキャッシュ管理が複雑になる |
| カスタムヘッダー | Accept: application/vnd.company.v1+json |
URLが常に一定に保たれる | ブラウザでの動作確認やキャッシュが難しくなる |
セマンティックバージョニングの適用
一般的に、APIのバージョン表現には セマンティックバージョニング（SemVer）（例: vMajor.Minor.Patch）が参考にされます。
- Major (破壊的変更): 後方互換性のないAPIの変更（エンドポイントの削除、必須パラメータの追加など）。URLの
/v1/を/v2/に変更する。 - Minor (機能追加): 後方互換性がある機能の追加（任意パラメータの追加、新しいエンドポイントの追加）。
- Patch (バグ修正): 後方互換性があるバグ修正（ドキュメントの修正、内部ロジックの改善）。
3. 後方互換性と非推奨化（Deprecation）
APIをアップグレードする際、古いバージョンを即座に停止することはできません。以下の手順を踏んで安全に移行（ディプリケーション）を進めます。
安全な廃止フロー
Rendering diagram...
sequenceDiagram
autonumber
Developer->>API: 1. 新バージョン v2 を公開
Developer->>API: 2. 旧バージョン v1 に Deprecation ヘッダーを設定
Client->>API: 3. v1 をリクエスト
API-->>Client: 4. レスポンス + Deprecation/Sunset ヘッダーを返す
Client->>Developer: 5. クライアントが検知し、順次 v2 へ移行
Developer->>API: 6. 十分な猶予期間ののち、v1 を廃止 (Sunset)
Deprecationヘッダー: レスポンスヘッダーにDeprecation: trueや、廃止予定日を示すSunsetヘッダーを含めることで、クライアントの開発者へ移行を促します。- ドキュメントの更新: APIドキュメント上に
deprecatedフラグを立て、非推奨であることを視覚的に明示します。
APIドキュメントと適切なバージョニングルールを整備することで、開発者にとって信頼性が高く、長く持続可能なAPIを提供できるようになります。