RESTful API データモデリング - RESTful APIにおけるリソースIDのデータモデリング：UUID vs シーケンシャルID

RESTful APIにおけるリソースIDのデータモデリング：UUID vs シーケンシャルID

Tags: RESTful API, データモデリング, ID設計, UUID, シーケンシャルID

はじめに

RESTful APIを設計する上で、各リソースを一意に識別するためのIDは不可欠な要素です。このIDの設計は、APIの使いやすさ、パフォーマンス、そしてセキュリティに大きく影響します。特に、どのような形式のIDを採用するかは重要な決定事項の一つです。

よく用いられるIDの形式には、データベースの連番で生成される「シーケンシャルID（連番ID）」と、重複の可能性が非常に低いランダムな文字列である「UUID（Universally Unique Identifier）」またはGUID（Globally Unique Identifier）があります。

本記事では、これら二つのID形式の特徴と、RESTful APIのデータモデリングにおいて考慮すべき点について解説します。

RESTful APIにおけるリソースIDの役割

APIにおけるリソースIDは、主に以下の役割を担います。

一意性の保証: システム全体で特定のリソースを一意に識別します。
リソースの参照: APIエンドポイントのパスなどで、操作対象のリソースを指定するために使用されます。
リレーションの表現: 異なるリソース間の関連を示すために、外部キーとして利用されます。
永続的な識別子: リソースが作成されてから削除されるまで、そのリソースを指し示す固定の識別子となります。

これらの役割を踏まえ、APIの要件に合ったID形式を選択する必要があります。

主要なID設計パターンとそのAPIモデリング

ここでは、シーケンシャルIDとUUID/GUIDに焦点を当て、それぞれの特徴とAPI設計上の考慮事項を説明します。

1. シーケンシャルID (Auto-increment ID)

シーケンシャルIDは、一般的にデータベースのオートインクリメント機能などによって自動的に割り振られる連番の整数値です。

特徴:
- 主に数値（整数）です。
- 新しいリソースが作成されるたびに、既存の最大値に1などが加算されて生成されます。
- 生成は非常に高速です。
- データベースによっては主キーとして非常に効率的です。
APIでの表現例:
- パスパラメータ: /users/123
- レスポンスボディ: {"id": 123, "name": "山田太郎", ...}
メリット:
- 人間にとって読みやすく、覚えやすい形式です。
- 数値であるため、URLの長さなどを短く抑えられます。
- データベースでのインデックスや結合処理において、多くの場合効率が良いとされます。
デメリット:
- 推測可能性: IDが連番であるため、他のリソースのIDを容易に推測できてしまいます。例えば、ID 123 のユーザーが存在する場合、124 や 122 のユーザーが存在する可能性が高いと推測できます。
- 分散システムでの課題: 複数のシステムやデータベースで独立してIDを生成する場合、衝突を避けるための工夫が必要になります。
- データベース依存: IDの生成戦略がデータベースに強く依存します。
API設計上の考慮事項: シーケンシャルIDをAPIでそのまま公開する場合、その推測可能性からセキュリティリスクが生じます。例えば、/users/{id} のようなエンドポイントで、認証されていないユーザーがシーケンシャルIDを順に試すことで、他のユーザーの情報に不正にアクセスできてしまう可能性があります（IDOR: Insecure Direct Object Reference）。このリスクを軽減するためには、IDによるリソースアクセスに対して、必ず厳格な認証・認可チェックを実装する必要があります。

2. UUID/GUID (Universally Unique Identifier / Globally Unique Identifier)

UUID/GUIDは、標準化されたアルゴリズムに基づいて生成される128ビットの値で、非常に高い確率で一意性が保証される識別子です。通常はハイフン区切りの16進数文字列として表現されます（例: a1b2c3d4-e5f6-7890-1234-567890abcdef）。

特徴:
- ランダム性に基づいて生成されるため、推測が困難です。
- 分散環境でも独立して生成でき、衝突の心配がほとんどありません。
- 文字列形式です。
APIでの表現例:
- パスパラメータ: /products/a1b2c3d4-e5f6-7890-1234-567890abcdef
- レスポンスボディ: {"id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "name": "商品A", ...}
メリット:
- 推測困難: ランダムな文字列であるため、IDを推測して他のリソースにアクセスするような攻撃（IDOR）に対する耐性が高いです。公開APIに適しています。
- 分散生成: 中央集権的なID生成機構が不要なため、分散システムやマイクロサービスアーキテクチャと相性が良いです。
- データベース非依存: ID生成ロジックがアプリケーション側に持てるため、特定のデータベースシステムに依存しません。
デメリット:
- 人間が読み書きしたり、覚えたりするのが困難です。
- 文字列であり、シーケンシャルIDに比べて長くなるため、URLやデータサイズが増加します。
- データベースによっては、インデックスの効率や挿入パフォーマンスがシーケンシャルIDに比べて劣る場合があります（特にランダム性が高いUUIDv4）。
API設計上の考慮事項: UUIDを使用する場合でも、認証・認可は適切に実装すべきです。UUIDは推測されにくいですが、漏洩したIDを使われる可能性はゼロではありません。また、UUIDは長い文字列となるため、APIのURL設計やレスポンス構造において、可読性やサイズへの影響を考慮する必要があります。

どちらを選ぶか？比較と使い分け

シーケンシャルIDとUUID/GUIDのどちらを選択するかは、アプリケーションの要件や特性によって判断します。

判断のポイント:

セキュリティ要件: APIが外部に公開され、特定のリソースへの直接アクセスが許可される場合、UUIDのような推測されにくいIDが推奨されます。内部利用のみでアクセス制御が厳格に行われる場合は、シーケンシャルIDも選択肢に入ります。
システム構成: マイクロサービスなど分散システムでIDを生成する場合、UUIDは独立して生成できるため適しています。モノリシックなシステムであれば、シーケンシャルIDも扱いやすい場合があります。
パフォーマンス要件: 大量のデータを扱う場合や、特定のデータベースシステムを利用している場合は、IDのサイズや生成方法がデータベースのパフォーマンスに影響する可能性があります。利用するDBシステムの特性を確認し、テストを行うことが重要です。
可読性: 人間がIDを直接参照したり、手入力したりする機会が多い場合は、シーケンシャルIDの方が利便性が高いことがあります。

例えば、一般ユーザーに公開するプロダクトAPIで、ユーザー、商品、注文などのリソースIDにはUUIDを使用し、管理画面など内部的なAPIで、ログやバッチ処理関連の一時的なデータなど、推測されることによるリスクが非常に低いリソースにはシーケンシャルIDを使用するといった使い分けも考えられます。

IDの公開範囲：内部IDと外部ID

APIで公開するIDと、データベースで実際に使用するIDを分ける「内部ID」と「外部ID」という考え方もあります。

内部ID: データベースの主キーなど、システム内部での効率的なデータ管理に使用するIDです。多くの場合、シーケンシャルIDが使われます。
外部ID: APIやUIなどで外部に公開するIDです。推測されにくく、システム内部の構造（例えばDBの連番）を隠蔽できるUUIDなどが使われます。

このアプローチを採用する場合、APIリクエストで外部IDを受け取り、内部で内部IDに変換してデータベース操作を行うというマッピング処理が必要になります。これにより、内部のデータ構造に依存せずAPIを設計できるというメリットがありますが、マッピングの管理と処理コストが発生します。

API設計上の具体的な考慮事項

URL設計: リソースを識別するためにIDはパスパラメータとして使用されるのが典型的です。 GET /users/{user_id} GET /products/{product_uuid} IDの形式に合わせて、パスパラメータのバリデーション（例: 数値であることを確認する、UUID形式であることを確認する）を適切に実装します。
リクエスト/レスポンスボディ: リソースオブジェクトの識別子として、ボディ内にIDを含めます。関連するリソースを参照する場合も、そのIDを含めるのが一般的です。 json // レスポンス例 { "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "name": "山田太郎", "email": "taro@example.com", "organization_id": 123 // 関連リソースのID（ここでは内部IDでも公開する例） } 関連リソースのIDを含める場合、そのIDがどのリソースタイプを指すのかを明確にする命名規則や構造を採用することが望ましいです。
データ型とバリデーション: APIスキーマ定義（OpenAPIなど）を利用して、IDのデータ型（integer, string, uuid formatなど）や制約を明確に定義します。これにより、クライアントは期待されるID形式を理解し、サーバー側も受け取ったIDが正しい形式であるかを検証できます。

アンチパターンに注意する

APIのリソースID設計におけるいくつかのアンチパターンを認識しておくことも重要です。

推測可能なIDをそのまま公開し、アクセス制御が不十分: シーケンシャルIDを外部公開し、認証・認可を怠ると、前述のIDOR脆弱性につながります。IDの推測されにくさに頼るのではなく、アクセス制御は常に厳格に行うべきですが、公開APIでは推測されにくいID形式を選ぶ方が安全性が高まります。
IDに意味を持たせる（セマンティックID）: 例えば、「ユーザーの種類を示すプレフィックス + 連番」のように、ID自体に業務上の意味を持たせる設計は、後から業務要件が変わった際にIDを変更する必要が生じたり、不必要な情報を外部に晒すことになったりする可能性があるため、避けるのが一般的です。IDはあくまでリソースの識別子であり、意味を持つべきではありません。
複数のIDスキームの混在による混乱: 同じ種類のリソースに対して、場合によってシーケンシャルIDとUUIDが混在するような設計は、クライアントが混乱し、実装ミスを招く原因となります。一つのリソースタイプには、原則として一つのIDスキームを適用すべきです。

まとめ

RESTful APIにおけるリソースIDの設計は、APIの安全性、保守性、スケーラビリティに深く関わる重要なステップです。シーケンシャルIDはシンプルさとデータベース効率に優れますが、推測されやすいというセキュリティリスクを伴います。一方、UUIDは高い一意性と推測されにくさから公開APIに適していますが、サイズやデータベース効率の面で考慮が必要です。

どちらの形式を選択するにしても、APIの利用シーン、セキュリティ要件、システムアーキテクチャ、そしてデータベースの特性を総合的に判断し、慎重に決定することが求められます。また、選択したID形式に合わせて、APIパスやリクエスト/レスポンス構造、そして最も重要な認証・認可の実装を適切に行うことが、堅牢なAPI設計には不可欠です。

本記事が、皆様のRESTful APIにおけるID設計の参考になれば幸いです。