アーキテクチャ レッスン5
API設計
REST・GraphQLなどのAPIスタイルの違いと、一貫性・拡張性のあるAPIを設計するための指針を学ぶ
APIスタイルの選択肢
サービス間や、クライアントとサーバー間でデータをやり取りする方式には複数のスタイルがあります。 どれか1つが常に優れているわけではなく、要件に応じた適材適所の選択が必要です。
REST
リソース指向。HTTPの意味論とキャッシュの仕組みに乗りやすく、仕様がシンプル
GraphQL
クライアントが必要なデータ形状を1回のクエリで指定できる。多様なクライアントを持つ場合に有利
gRPC
スキーマ駆動でバイナリ通信。サービス間の内部通信で高いパフォーマンスが必要な場合に有利
RESTの設計原則
RESTは「リソース」を中心にURLを設計し、操作の種類をHTTPメソッドで表現します。
GET /users 一覧取得
GET /users/123 1件取得
POST /users 新規作成
PUT /users/123 全体更新
PATCH /users/123 部分更新
DELETE /users/123 削除
// 悪い例(動詞をURLに含めてしまう)
GET /getUserList
POST /createNewUserレスポンスのステータスコードも意味を持たせます(200=成功、201=作成成功、400=不正なリクエスト、 404=存在しない、500=サーバーエラー、など)。
GraphQLの特徴と向き不向き
GraphQLはクライアントが「何を(フィールド)」「どんな形で」欲しいかをクエリとして送り、 サーバーはそれに応じたレスポンスを返します。
# クライアントが必要なフィールドだけを指定
query {
user(id: "123") {
name
posts(limit: 3) {
title
}
}
}
# REST であれば /users/123 と /users/123/posts?limit=3
# の2回のリクエストが必要になりがちなケース| 観点 | REST | GraphQL |
|---|---|---|
| データ取得の柔軟性 | エンドポイント固定のレスポンス形状 | クエリで必要な形状を指定できる |
| HTTPキャッシュ | GETのURL単位でキャッシュしやすい | クエリが可変なため独自のキャッシュ設計が必要 |
| 向いている場面 | シンプルなCRUD、公開APIなど仕様の単純さが重要な場合 | 多様なクライアント(Web/モバイル)が異なるデータ形状を必要とする場合 |
一貫性と拡張性のための指針
バージョニング
/v1/users のようにバージョンを明示し、破壊的変更は新バージョンとして提供する
命名規則の統一
複数形/単数形やキャメルケース/スネークケースをAPI全体で統一する
一貫したエラーレスポンス
エラーコード・メッセージの形式を統一し、クライアント側が機械的にハンドリングできるようにする
ポイント
- REST・GraphQL・gRPCはそれぞれ得意分野が異なり、要件に応じて選ぶ適材適所の関係にある
- RESTはリソース指向でURLを設計し、操作の種類はHTTPメソッドで表現する
- バージョニングと一貫したエラー形式は、クライアントを壊さず変更を続けるための土台になる
確認クイズ
1 / 3RESTの設計原則として適切なものはどれか？