学習ロードマップ
API 設計のベストプラクティス
REST / GraphQL / RPC を横断して、保守しやすく拡張しやすい API を設計するためのロードマップ。既存 API を整える視点も含む。
SCROLL TO BEGIN
学習ロードマップ
REST / GraphQL / RPC を横断して、保守しやすく拡張しやすい API を設計するためのロードマップ。既存 API を整える視点も含む。
このロードマップが扱うもの
このロードマップは、公開 API や社内 API の設計に責任を持ちたいバックエンド / プラットフォームエンジニアを対象にしています。学び終えたときには、リソース設計、エラー/バージョニング、認証/認可、ドキュメントと契約まで、スタイルを問わずチームで合意できる API を設計・レビューできる状態を目指します。
このロードマップの全体像
このロードマップは、公開 API や社内 API の設計に責任を持ちたいバックエンド / プラットフォームエンジニアを対象にしています。学び終えたときには、リソース設計、エラー/バージョニング、認証/認可、ドキュメントと契約まで、スタイルを問わずチームで合意できる API を設計・レビューできる状態を目指します。
1. API の目的とスタイル選定: REST / GraphQL / gRPC / Webhook の特性と、ユースケースごとの向き不向きを整理します。 2. リソースとユースケースのモデリング: ドメイン駆動の発想で、URI や型の切り方、集約単位を決める訓練をします。 3. エラー・ページング・フィルタの定型化: エラーコード体系、ページングの種類、クエリパラメータ規則を標準化し、クライアントの書きやすさを上げます。 4. バージョニングと後方互換性: 破壊的変更の避け方、deprecation 運用、スキーマ互換性チェックをフローに組み込みます。 5. 認証・認可・レート制限: OAuth2/OIDC、スコープ、テナント分離、レート制限と冪等性設計を実装レベルで押さえます。 6. ドキュメントと契約のメンテナンス: OpenAPI / スキーマ、例示、変更履歴、コントラクトテストを継続的に回す仕組みを作ります。
API は「書く」より「変えない / 変え方を決める」方が難しい領域です。初期にドメインモデルが曖昧だと、後から URI やフィールドを直すコストが跳ね上がります。認可やレート制限を途中から足すのも大仕事なので、最初から横断的な枠組みとして設計する必要があります。周辺では、HTTP の基礎、OAuth2/OIDC、DB スキーマとドメイン駆動設計、OpenAPI / JSON Schema、テスト戦略、API ゲートウェイと BFF パターン、ロギング/可観測性を並行して押さえておくと、スタイル選択と運用判断が具体的になります。
ロードマップ
第 1 章