← Back to Home

API設計の原則：REST vs GraphQLと、長く使われるAPIの作り方

#API#Backend#Architecture#WebDesign

API Design Concept

モダンなWebアプリケーション開発において、フロントエンドとバックエンドを結ぶ「API（Application Programming Interface）」は、屋台骨とも言える非常に重要な要素です。 一度公開されたAPIは、多くのクライアント（Web、モバイルアプリ、外部連携など）に使われるため、後からの変更が困難です。そのため、最初の「設計」がその後の開発効率や保守性を大きく左右します。

この記事では、API設計の2大潮流であるRESTとGraphQLの比較から、使いやすく堅牢なAPIを構築するための普遍的な原則までを、2500文字以上のボリュームで詳しく解説します。

1. REST vs GraphQL：どちらを選ぶべきか？

現在、API設計には大きく分けて「REST（REpresentational State Transfer）」と「GraphQL」の2つの選択肢があります。

REST（リソース指向）

  • 特徴: URL（リソース）とHTTPメソッド（GET, POST, PUT, DELETE）を組み合わせて操作を記述する。
  • メリット: シンプルで学習コストが低い、HTTPのキャッシュが効きやすい、ツールが豊富。
  • デメリット: オーバースフェッチ（不要なデータまで取得してしまう）や、アンダーフェッチ（1画面作るのに何度もリクエストが必要）が起きやすい。

GraphQL（クエリ指向）

  • 特徴: クライアントが必要なデータ構造をクエリとして投げ、1回のリクエストで取得する。
  • メリット: オーバースフェッチが皆無、型安全な開発が可能、スキーマを介した強力な自動補完。
  • デメリット: 学習コストが比較的高い、キャッシュの扱いが複雑、サーバーサイドの実装負荷が増える場合がある。

選定の基準: 基本的には汎用性の高いRESTが推奨されますが、複雑なデータ構造を持ち、フロントエンドの要求が多岐にわたる場合はGraphQLが強力な武器となります。

2.RESTful API設計のゴールデンルール

REST形式を採用する場合、以下のルールを守ることで、直感的で予測可能なAPIになります。

① リソースは名詞で表現する

URLには「動作」を含めず、操作対象となる「名詞（リソース）」を使用します。

  • ❌ GET /getUsers
  • ✅ GET /users

② HTTPメソッドを正しく使い分ける

リソースに対する操作は、URLではなくメソッドで表現します。

  • GET: 取得
  • POST: 新規作成
  • PUT: 全置換（または更新）
  • PATCH: 部分更新
  • DELETE: 削除

③ 適切なステータスコードを返す

APIの結果を判定するために、HTTPステータスコードを正しく活用します。

  • 200 OK: 成功
  • 201 Created: 作成成功
  • 400 Bad Request: クライアント側のリクエストミス（バリデーションエラーなど）
  • 401 Unauthorized: 未認証
  • 403 Forbidden: 権限不足
  • 404 Not Found: リソースが存在しない
  • 500 Internal Server Error: サーバー側のバグ

3. 使いやすさを左右するディテール設計

命名規則の統一

snake_case なのか camelCase なのか、チームやプロジェクト全体で一貫させることが重要です。一般的に、JSONを扱うAPIではJavaScriptとの親和性が高い camelCase が好まれる傾向にあります。

エラーレスポンスの構造化

エラーが起きた際、「何が原因で」「どうすればいいのか」をクライアントが機械的に判断できるフォーマットで返します。

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "メールアドレスの形式が正しくありません。",
    "details": [
      { "field": "email", "issue": "invalid_format" }
    ]
  }
}

フィルタリング・ソート・ページネーション

大量のデータを扱う場合、クエリパラメータでの制御が必須です。

  • GET /users?sort=created_at&order=desc&limit=20&offset=40 このように、共通のルールを設けることで、フロントエンド開発者は迷わずに済みます。

4. APIの「寿命」を延ばすために

APIは一度作ると捨てられません。将来の変更に備える知恵が必要です。

バージョニングを最初から入れる

機能追加や破壊的変更が必要になった際、古いクライアントを壊さないためにバージョンをURLに含めるのが一般的です。

  • https://api.example.com/v1/users

セキュリティの担保

  • 認証・認可: JWT (JSON Web Token) や OAuth2 を適切に使用する。
  • レート制限 (Rate Limiting): 特定のIPからの過剰なアクセスを制限し、サーバーを保護する。
  • CORSの設定: 許可されたオリジンからのみアクセスできるようにする。

まとめ：良いAPIは「美しい設計図」

優れたAPIは、まるで丁寧に書かれた取扱説明書のように、ドキュメントを見なくても使い方が想像できるものです。

  1. 予測可能性: 似たようなリソースは似たようなURLと挙動であること。
  2. 安全性: エラーが適切に処理され、不正なアクセスが遮断されていること。
  3. 拡張性: 将来の変更にも柔軟に対応できる構造であること。

これらを意識して設計されたAPIは、開発チーム全体の生産性を高め、最終的にはユーザーに提供するサービスの質を向上させます。技術の流行り廃りはありますが、API設計の根底にある「疎結合」と「明瞭さ」という原則は、今後も変わることはありません。

次回の記事では、APIの実装をさらに快適にする「gRPC」や「tRPC」といった技術についても触れていきたいと思います！