RESTful API データモデリング - RESTful APIのデータモデリング：適切なリソースの粒度と凝集度を見極める

RESTful APIのデータモデリング：適切なリソースの粒度と凝集度を見極める

Tags: RESTful API, データモデリング, リソース設計, 凝集度, 粒度

RESTful APIを設計する際、どのようなデータを一つのリソースとして表現し、どこまで関連情報を含めるか、あるいは分離するかは、APIの使いやすさ、パフォーマンス、保守性に大きく影響する重要な判断点です。これはデータモデリングにおける「リソースの粒度」と「凝集度」に関わる課題であり、多くのエンジニアが設計時に悩むポイントの一つではないでしょうか。

本記事では、RESTful APIにおけるリソースの粒度と凝集度について解説し、適切な設計を行うための考え方や具体的なパターンをご紹介します。

RESTful APIにおけるリソースの粒度と凝集度とは

まず、リソースの粒度と凝集度という言葉がAPI設計において何を意味するのかを整理します。

リソースの粒度 (Granularity)
- 一つのリソースが表現するデータや機能の「細かさ」や「範囲」を指します。
- 粒度が「粗い」とは、一つのリソースが多くの情報や関連する複数のエンティティを含む状態を指します。
- 粒度が「細かい」とは、一つのリソースが少数の情報や単一のエンティティに限定される状態を指します。
リソースの凝集度 (Cohesion)
- 一つのリソース内に含まれるデータや機能が、どの程度関連性が高いか、まとまっているかを示す度合いです。
- 凝集度が高いリソースは、その内部要素が密接に関連しており、一緒に利用されることが多いデータの集まりです。
- 凝集度が低いリソースは、その内部要素間の関連性が薄く、ばらばらに利用される可能性のあるデータの集まりです。

これらの概念は密接に関連しています。一般的に、粒度が粗いリソースは凝集度が高い（ただし、意図しない場合は低い凝集度になる可能性もある）、粒度が細かいリソースは凝集度が高い傾向にあります（単一のエンティティを表現するため）。

なぜリソースの粒度と凝集度が重要なのか

リソースの粒度と凝集度の設計は、以下のようなAPIの特性に直接影響を与えます。

パフォーマンス:
- 粒度が粗すぎるリソースは、不要なデータをクライアントに送信する可能性があり、帯域幅の無駄や処理遅延の原因となります。
- 粒度が細かすぎるリソースは、一つの操作のために複数のAPIリクエストが必要になる場合があり、ネットワークのラウンドトリップが増加し、全体の応答時間が長くなる可能性があります（いわゆるN+1問題）。
保守性:
- 適切な粒度・凝集度のリソースは、責任範囲が明確になり、変更や拡張が容易になります。
- 低凝集度のリソースは、どこを変更しても他の部分に影響を与える可能性があるため、保守が困難になります。
- 粒度が不適切だと、APIのバージョンアップや後方互換性の維持が難しくなることがあります。
使いやすさ (Usability):
- クライアントが必要とする情報が効率的に取得できるか、直感的にリソース構造を理解できるかは、粒度と凝集度にかかっています。
- 極端な粒度や低い凝集度は、APIクライアント側の実装を複雑にする要因となります。

これらの理由から、設計段階でリソースの粒度と凝集度について十分に検討することが不可欠です。

適切な粒度・凝集度を見極めるための考え方

では、どのようにして適切な粒度と凝集度を見極めれば良いのでしょうか。万能なルールはありませんが、以下の点を考慮すると判断の手助けになります。

クライアントの利用パターン: 最も重要な考慮事項です。クライアントがそのデータをどのように利用するのか、どのような情報を一度に必要とするのかを分析します。常にセットで必要とされるデータは、一つのリソースにまとめることを検討します。逆に、ほとんどの場合不要だが、特定の状況でのみ必要となるようなデータは分離を検討します。
データのライフサイクル: データが作成、更新、削除されるライフサイクルが同じか異なるかを考慮します。一緒に作成・更新・削除されるデータは、一つのリソースまたは密接に関連したリソースとして扱う方が自然です。
データの変更頻度: 頻繁に変更されるデータとほとんど変更されないデータが混在している場合、これらを分離することでキャッシュ戦略が容易になるなど、メリットがある場合があります。
データの量と構造: 非常に大きなデータや、複雑な構造を持つデータを一つのリソースに含めると、レスポンスが大きくなりすぎたり、扱いが難しくなったりします。
権限やアクセス制御: データの一部に対してのみアクセス権限が異なる場合、それらのデータを別のリソースとして分離することで、権限管理がシンプルになります。
ビジネス上の概念: データがビジネス上、一つのまとまりとして認識されているかどうかも重要なヒントになります。例えば、「注文」とその「注文明細」は、ビジネス上は強く関連していますが、データ構造としては親子関係を持つ別のまとまりとして扱われることが一般的です。

具体的な設計パターンと例

上記の考慮事項を踏まえ、リソースの粒度と凝集度に関する具体的な設計パターンをいくつかご紹介します。

パターン1：包括的なリソース（高凝集度）

関連性の高いデータを一つのリソースにまとめて表現するパターンです。

例: ユーザー情報と基本的なプロフィール

ユーザーID、名前、メールアドレスといった基本情報と、表示名、自己紹介などの基本的なプロフィール情報は、多くのアプリケーションでユーザーと共に利用されることが多いです。これらを一つのリソースとして設計することが考えられます。

APIエンドポイント例: GET /users/{id}
レスポンスJSON例:

{
  "id": "user123",
  "username": "johndoe",
  "email": "john.doe@example.com",
  "profile": {
    "displayName": "John Doe",
    "bio": "Software Engineer.",
    "profileImageUrl": "https://example.com/profiles/johndoe.jpg"
  }
}

メリット:
- クライアントは1回のAPIリクエストで必要な情報の大半を取得できます。ネットワークのラウンドトリップを削減できます。
- 関連データがまとまっているため、データの整合性を保ちやすいです。
デメリット:
- クライアントがプロフィールの情報だけ欲しい場合でも、ユーザー基本情報も一緒に取得することになり、不要なデータ転送が発生する可能性があります。
- プロフィールの更新など、データの一部だけを更新する場合でも、リソース全体を受け取る必要が生じやすいです（ただし、PATCHメソッドで部分更新をサポートすることで緩和できます）。
- データ量が大きくなると、レスポンスサイズが増加します。
このパターンが向いているケース:
- 含まれるデータが常にセットで利用される場合。
- 含まれるデータ量が比較的少なく、レスポンスサイズへの影響が小さい場合。
- データの更新がリソース全体で行われることが多い場合（または部分更新をしっかり設計できる場合）。

パターン2：分割されたリソース（低凝集度、ただし各リソース内は高凝集度）

関連性はありつつも、利用頻度や更新頻度、あるいはデータ量が異なるデータを別のリソースとして分離するパターンです。各分割されたリソース自体は、それぞれの責務範囲内で高凝集であるべきです。

例: ユーザー情報と詳細プロフィール/設定

ユーザーの基本情報とは別に、詳細なプロフィール情報（住所、電話番号など）や、ユーザー固有の設定情報（通知設定、プライバシー設定など）は、利用頻度が低かったり、権限管理が異なったりすることがあります。これらを分割して別のリソースとして提供することが考えられます。

APIエンドポイント例:
- 基本情報: GET /users/{id}
- 詳細プロフィール: GET /users/{id}/profile
- 設定: GET /users/{id}/settings
レスポンスJSON例:
- /users/{id} のレスポンス:
json { "id": "user123", "username": "johndoe", "email": "john.doe@example.com" // 詳細プロフィールや設定情報は含まない } * /users/{id}/profile のレスポンス:

json { "userId": "user123", "displayName": "John Doe", "bio": "Software Engineer.", "profileImageUrl": "https://example.com/profiles/johndoe.jpg", "address": { ... }, // 詳細な住所情報 "phoneNumber": "..." } * メリット: * クライアントは必要な情報だけを取得できます。帯域幅を節約できます。 * 各リソースの責務が明確になり、保守や拡張が容易になります。 * データの更新が特定の情報セットに限定されるため、シンプルになります。 * データ量の大きい部分（例：プロフィール画像データ本体など）を分離しやすくなります。 * 異なる権限レベルでのアクセス制御を実装しやすくなります（例：詳細プロフィールは本人と管理者にのみ公開）。 * デメリット: * クライアントが複数の情報セットを必要とする場合、複数のAPIリクエストが必要になり、ラウンドトリップが増加します。 * クライアント側で取得した複数のリソース情報を結合する処理が必要になる場合があります。 * このパターンが向いているケース: * 含まれるデータセット間で利用頻度や変更頻度が大きく異なる場合。 * データセット間でセキュリティ要件や権限レベルが異なる場合。 * 含まれるデータセットの一部が非常に大きい場合。 * データセットがビジネス上、独立した概念として扱われる場合。

パターン3：サブコレクションとしてのリソース

あるリソースが、別のリソースの集合を「含む」または「関連付ける」場合に、その集合を親リソースの下のサブコレクションとして表現するパターンです。これはリレーション表現の一形態でもありますが、粒度・凝集度の観点からも重要です。

例: 注文と注文明細、ブログ記事とコメント

「注文」というリソースは複数の「注文明細」を持ちます。「ブログ記事」というリソースは複数の「コメント」を持ちます。これらの「明細」や「コメント」は、それぞれが独立したリソースとしての性質を持ちつつも、強く親リソースに紐づいています。

APIエンドポイント例:
- 特定の注文を取得: GET /orders/{orderId}
- 特定の注文の明細リストを取得: GET /orders/{orderId}/items
- 特定の注文明細を取得: GET /orders/{orderId}/items/{itemId}
- 特定の記事を取得: GET /articles/{articleId}
- 特定の記事のコメントリストを取得: GET /articles/{articleId}/comments
- 特定のコメントを取得: GET /articles/{articleId}/comments/{commentId} (または /comments/{commentId} とも考えられますが、記事への紐づきが強い場合は前者も一般的です)
レスポンスJSON例:
- /orders/{orderId} のレスポンス (注文概要のみ):
json { "id": "order123", "orderDate": "2023-10-27T10:00:00Z", "totalAmount": 55.00, "status": "shipped", // 明細のリストは直接含まない "links": [ {"rel": "items", "href": "/orders/order123/items"} // 明細へのリンク ] } * /orders/{orderId}/items のレスポンス (明細リスト):

json [ { "id": "item001", "productId": "prodA", "productName": "Product A", "quantity": 2, "price": 10.00 }, { "id": "item002", "productId": "prodB", "productName": "Product B", "quantity": 1, "price": 35.00 } ] * メリット: * リソース間の階層的関係性がURL構造で明確に表現されます。 * 親リソースが持つ膨大な子リソースのリストを、親リソースの取得時とは分離して取得できます。 * 子リソースは親リソースのコンテキストで管理されることが明確になります。 * デメリット: * 深いネスト構造になりすぎると、URLが複雑になる可能性があります。 * 親リソースの情報と子リソースのリストを同時に取得したい場合に、複数リクエストが必要になるか、特別なパラメータ（例: ?_embed=items）を検討する必要があります。 * このパターンが向いているケース: * あるリソースが、別の種類のリソースの集合を論理的に包含している場合。 * 包含される側のリソースが、包含する側のリソースなしには存在しない（あるいは意味をなさない）場合。

避けるべきアンチパターン

適切な粒度・凝集度設計を行う上で、陥りがちなアンチパターンも認識しておくことが重要です。

DBスキーマの垂れ流し: データベースのテーブル構造をそのままAPIリソースの構造として公開することです。DBの設計思想とAPIの利用者の求める構造は必ずしも一致しません。DB都合の設計は、API利用者にとって理解しにくく、使いづらいものになりがちです。APIはUIやビジネスロジックの要求に基づいて設計されるべきです。
過剰な分割: 関連性の高いデータを不必要に細かく分けすぎるパターンです。例えば、ユーザー名、メールアドレス、登録日時といった常に一緒に表示されるような基本情報を、それぞれ別のリソースとして公開するようなケースです。これはクライアントに無駄な結合処理や多量のラウンドトリップを強いることになります。
低凝集度の詰め込み: 関連性の薄いデータを一つのリソースにまとめてしまうパターンです。例えば、ユーザー情報と、そのユーザーが過去に閲覧した商品リスト、さらにはシステムの設定情報までを一つの /user/{id} リソースに含めてしまうようなケースです。リソースの責務が曖昧になり、保守が困難になります。
特定のUIに最適化しすぎる: 特定の画面表示のためだけに、その画面に必要な全てのデータを一つのリソースに詰め込んでしまうパターンです。これは一見効率的に見えますが、他の画面やクライアント（モバイルアプリなど）では使えない汎用性の低いAPIになってしまいます。APIは特定のUIのためだけではなく、様々なクライアントからの利用を想定して設計されるべきです。

まとめ

RESTful APIのデータモデリングにおいて、リソースの粒度と凝集度はAPIの品質を左右する中心的な要素です。適切な粒度・凝集度を実現するためには、単にデータベース構造を反映させるのではなく、クライアントの利用パターンを深く理解し、データのライフサイクルやビジネス上の関連性を考慮することが重要です。

常にセットで利用される高関連性の高いデータは、包括的なリソースとしてまとめることを検討します。
利用頻度や変更頻度、あるいはセキュリティ要件が異なるデータは、分割されたリソースとして提供することを検討します。
親リソースに強く紐づく集合的なデータは、サブコレクションとして表現することを検討します。

これらのパターンを参考にしながら、開発するAPIの特性や想定される利用シーンに合わせて、最もバランスの取れた設計を目指してください。完璧な設計は難しいかもしれませんが、上記の考え方に基づき、意図を持って設計を行うことが、保守性が高く、利用者にとって使いやすいAPIの実現につながります。設計は一度行えば終わりではなく、APIの進化に合わせて継続的に見直し、改善していく視点も重要です。