リソースモデリングとバージョニング（りそーすもでりんぐとばーじょにんぐ）

2025年11月17日

リソースモデリングとバージョニング（りそーすもでりんぐとばーじょにんぐ）

英語表記: Resource Modeling and Versioning

概要

リソースモデリングとは、APIを通じて外部に公開するデータや機能（リソース）の構造、形式、およびそれらの関係性を体系的に定義する設計プロセスです。特に「API設計とマイクロサービス」の文脈において、RESTful API 設計の基盤となる「リソース指向」を実現するために不可欠な工程となります。バージョニングは、一度公開されたAPIのリソース定義が、機能追加や仕様変更によって将来的に変化する際に、既存のクライアントアプリケーションとの互換性を維持するための管理戦略です。この二つの要素は、APIを長期的に安定して運用し、進化させるための「API設計原則」における最も重要な柱であると言えるでしょう。

詳細解説

1. リソースモデリングの目的と構成要素

リソースモデリングの最大の目的は、APIを直感的で使いやすいものにすること、そしてAPIが提供するデータの一貫性と整合性を保証することです。RESTful API 設計では、すべてを「リソース」（名詞）として捉え、URIによって一意に識別します。このリソースの定義が曖昧だと、クライアント側はAPIをどのように操作すれば良いか分からず、結果的にAPIの利用効率が低下してしまいます。

API設計原則における重要性:
マイクロサービスアーキテクチャでは、複数のサービスが独立して開発・デプロイされます。この環境下で、外部に公開されるAPIゲートウェイや各サービスのリソース定義がバラバラだと、システム全体の複雑性が増大します。リソースモデリングを徹底することで、サービス間の境界が明確になり、疎結合（デカップリング）が促進されます。これはマイクロサービス成功の鍵を握る重要な設計原則だと私は強く考えます。

主要な構成要素:

URI設計: リソースを識別するためのパス構造を定義します。名詞の複数形を使用し、階層構造や関連性を示すことが一般的です（例: /users, /users/{id}/orders）。
表現（Representation）の定義: リソースがクライアントに返される際のデータ形式（通常はJSONまたはXML）の構造を定義します。どのフィールドを含めるか、データ型は何かなどを厳密に定めるスキーマ設計が含まれます。
状態遷移（HATEOASの考慮）: 高度なRESTful設計では、リソースの表現の中に、次に可能な操作を示すリンク情報を含めます（HATEOAS）。これにより、クライアントはAPIのドキュメントを参照せずとも、動的に操作を進めることが可能になります。

2. バージョニングの必要性と手法

APIは一度公開されると、それはクライアントとの「契約」となります。もしリソースの構造を勝手に変更してしまうと、そのAPIを利用している既存のアプリケーションは即座に動作しなくなってしまいます。バージョニングは、この契約の安定性を維持しつつ、API提供者が自由に改善や進化を続けられるようにするために必須の戦略です。

バージョニングが求められる変更例:

破壊的変更 (Breaking Change): フィールド名の変更や削除、必須パラメータの追加など、既存クライアントの動作に影響を与える変更。
非破壊的変更 (Non-Breaking Change): 新しいオプションフィールドの追加など、既存クライアントに影響を与えない変更。

API設計原則では、破壊的変更を行う場合は必ず新しいバージョンとして提供し、古いバージョン（旧契約）を一定期間並行稼働させることが求められます。

主要なバージョニング手法（RESTful API 設計の文脈）:

一般的に、API設計者は、シンプルさ、普及度、キャッシュ効率の観点から、URIバージョニングを選択することが多いのが現状です。

具体例・活用シーン

銀行システムのAPI設計例

リソースモデリングとバージョニングがどのように機能するかを、オンライン銀行システムを例にとって考えてみましょう。

リソースモデリングの適用:

リソースの特定: 顧客（Customers）、口座（Accounts）、取引履歴（Transactions）を主要なリソースと定義します。
URIの設計:
- 顧客リスト: /customers
- 特定の口座: /accounts/{account_id}
- その口座の取引履歴: /accounts/{account_id}/transactions
表現の定義: Accounts リソースのJSON構造を定義します。例えば、account_holder_name, balance, currency などのフィールドを定義します。

バージョニングの適用:

初期バージョン（V1）が公開され、数年が経過したとします。V1では、残高（balance）は整数型（integer）で定義されていました。しかし、国際取引の増加に伴い、小数点以下の精度が必要になり、残高を浮動小数点型（float）に変更する必要が出てきました。これは破壊的変更です。

対応: 既存のV1クライアントを壊さないために、新しいAPIをV2としてリリースします。
- V1 API: /v1/accounts/{id} (残高は整数型を返す)
- V2 API: /v2/accounts/{id} (残高は浮動小数点型を返す)

この期間、銀行はV1とV2の両方を並行して稼働させます。古いモバイルアプリ（V1を使用）はそのまま動作し続け、新しいウェブアプリケーション（V2を使用）は高い精度のデータを利用できるようになります。これにより、API設計原則の一つである「進化可能性」が担保されます。

アナロジー：都市計画と地図の改訂

リソースモデリングとバージョニングの関係は、都市計画とそれに伴う地図の改訂に似ています。

リソースモデリングは、都市の設計図を作成する作業です。どこに道路（URI）を通し、どこに建物（リソース）を建て、それぞれの建物の機能（フィールド）をどうするかを決めます。設計がしっかりしていれば、市民（クライアント）は迷わずに目的地に到達できます。

しかし、都市は発展します。ある日、政府（API提供者）が「主要な交差点（エンドポイント）の名前を変える」「古い地下鉄の駅（フィールド）を廃止する」と決定したとしましょう。これはAPIにおける破壊的変更です。

もし政府が突然、新しい地図（V2）だけを配布し、古い地図（V1）を回収してしまったらどうなるでしょうか？古い地図を使っていた市民は、目的地にたどり着けず混乱します。

バージョニングの役割は、新旧両方の地図を一定期間提供し続けることです。新しい都市計画（V2）がスタートしても、古い地図（V1）を持つ市民のために、しばらくは古い道路標識を残したり、移行期間を設けたりします。これにより、市民は新しい地図に徐々に慣れることができ、都市の進化と市民の利便性が両立するのです。