学習ロードマップ
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 章
エッジで動く Web アプリの設計・実装・運用を一巡し、API が置かれる実行環境の肌感を起点に据える。リクエストがどこで処理されるかを意識することで、以降の設計判断の土台を作る役割。
REST・gRPC・GraphQL を横断し、各方式の使い分けとテスト・セキュリティまでを通して学ぶ。本ロードマップの背骨となる段階で、設計様式の地図をここで完成させる。
手を動かして API を設計・実装し、前段で得た概念を実装の手応えへ落とし込む。読むだけでなく作る経験を挟むことで、設計判断が腹落ちする実践の節目となる。
モノリシックからマイクロサービスへの進化を軸に、システム全体の中で API をどう配置するかを学ぶ。個々の API 設計を超え、アーキテクチャ視点で道を俯瞰する段階。
Python による Web 開発から機械学習・データ分析までの実務を通し、API が現場でどう組み込まれるかを補強する。設計知識を具体的な実装文脈へ接続する役割。
Spring Boot 3 で API を備えた Web アプリを入門から組み立て、Java 生態系での実装手段を一つ手に入れる。設計の知識を別フレームワークで再現し、応用力を広げる締めくくり。
読む順に並べています。まずは1冊目から始めましょう。
エッジで動く Web アプリの設計・実装・運用を一巡し、API が置かれる実行環境の肌感を起点に据える。リクエストがどこで処理されるかを意識することで、以降の設計判断の土台を作る役割。
まず読む1冊 Cloudflare Workers 実践ガイド 〜 エッジで実現するWebアプリケーションの設計・実装・運用 〜 見る →