API設計

RESTらしいAPIとは何かを、リソースのモデル化とURL設計、そしてRichardson成熟度モデルという「設計の段階」から学びます。HTTPメソッドの意味そのものではなく、「なぜ名詞でモデル化するのか」「statelessが何を可能にするのか」「HATEOASは何を解こうとし、現実にどう扱われているか」といった設計判断とトレードオフに焦点を当てます。RESTとRPCの思想の違いも押さえます。

公開したAPIを止めずに変え続けるための設計判断を扱います。何が破壊的変更で何が非破壊かの線引き、バージョニング方式ごとのトレードオフ、非推奨(deprecation)の伝え方までを、RFCやGoogle AIP・GraphQL仕様といった一次情報にもとづいて確認します。「なぜその進化戦略を選ぶか」を土台から理解することが狙いです。

APIが返すレスポンスそのものをどう設計するかを学びます。ページネーションの方式選択、エラー応答の構造化、日時や金額の表現、nullと未指定の区別など、クライアントが安全に使い続けられる表現の設計判断を扱います。RFC 9457やRFC 8288などの一次仕様と公開ガイドラインを土台にしています。

RESTだけがAPIの答えではありません。この章ではgRPC(HTTP/2上のバイナリRPC)とGraphQL(クライアントが必要な項目を問い合わせる単一エンドポイント)の設計思想を、それぞれが何を最適化しているかという観点から学びます。公開API・内部マイクロサービス・多様なクライアントという状況ごとに、なぜその方式を選ぶのかを判断できるようになることが目標です。

APIを「実装の副産物」ではなく「先に合意する契約」として扱う設計プロセスを学びます。OpenAPI仕様でインターフェースを機械可読に記述し、そこからコード生成・モック・契約テスト・後方互換チェックを回すことで、実装とドキュメントの乖離や連携の壊れをどう防ぐかを、なぜその順序で設計するのかという観点から問います。

公開APIを長く安定運用するための設計を、レート制限・冪等キー・認可フロー・Webhook・ページ分割・キャッシュ・廃止移行という運用の観点から2択で確認します。プロトコルの再説明ではなく、上限や回復時間をどう伝えるか、再送で二重実行をどう防ぐか、といった「なぜその運用設計にするか」を土台から理解することを狙います。