【ITニュース解説】Don't Let Your Database Schema Become Your API Contract

多くのWebアプリケーションでは、データはデータベースに保存され、そのデータをWebブラウザやスマートフォンアプリなどの「クライアント」に提供するために「API（Application Programming Interface）」が使われる。APIは、クライアントからのリクエストに応じて、データベースからデータを取得し、整形して返す役割を担っている。

しかし、この仕組みには落とし穴がある。開発者がデータベースの構造、例えばテーブルのフィールド名（列名）を少し変更しただけで、アプリケーション全体が動かなくなるという緊急事態が発生することがあるのだ。記事の例では、ユーザーの誕生日を管理するデータベースのフィールド名をbirth_dayからbirthdayに修正しただけで、ユーザープロフィールページが壊れたり、モバイルアプリがクラッシュしたり、友人との誕生日がシステム上で管理できなくなったりする、という深刻な問題が紹介されている。これは、APIがデータベースのフィールド名をそのままクライアントに返してしまい、クライアント側が変更前のbirth_dayという名前を期待していたために起こる現象だ。

このような問題が起きると、「バックエンド（APIを提供するサーバー側）を先にデプロイし、その後にフロントエンド（クライアント側）をデプロイする」といった運用上の調整が考えられる。しかし、この方法でも、バックエンドが新しいデータベース構造で稼働し、フロントエンドがまだ古い構造を期待している間は、一時的にシステムが正常に動作しない「神経をすり減らす時間」が発生してしまう。また、birth_dayというフィールド名に依存するテストコードの更新を忘れてしまい、デプロイが失敗するといったリスクも伴う。さらに、深夜や早朝のオフピーク時間にデプロイ作業を行うことで、開発者の負担が増大するという問題もある。

このような事態を避けるためには、APIの設計を見直す必要がある。その鍵となるのが「APIコントラクト」という考え方だ。APIコントラクトとは、APIがクライアントにどのような形式のデータを返すかという「約束事」を明確に定義することである。データベースのスキーマ（構造）とAPIのレスポンス（返すデータ）を直接結びつけるのではなく、その間に「変換層」を設けることで、この問題は解決できる。

具体的には、APIがデータベースからデータを受け取った後、それをクライアントに返す前に、手動でフィールドをマッピング（紐付け）する処理を加える。記事の例では、以前はbirth_dayというフィールド名でデータを返していたAPIが、データベース側のフィールド名がbirthdayに変わっても、クライアントには引き続きbirth_dayとしてデータを返すように、変換層で調整する。

Copy
1// :: データベース変更前
2// APIのミドルウェア（変換層）の例
3const myMiddleware = (...) => {
4  // ... その他の処理
5  return {
6    first_name: user.first_name,
7    last_name: user.last_name,
8    phone_number: user.phone_number,
9    birth_day: user.birth_day // データベースのbirth_dayフィールドを、APIレスポンスのbirth_dayにマッピング
10  }
11}
12
13// :: データベース変更後：birth_day -> birthday
14// APIのミドルウェア（変換層）の例
15const myMiddleware = (...) => {
16  // ... その他の処理
17  return {
18    first_name: user.first_name,
19    last_name: user.last_name,
20    phone_number: user.phone_number,
21    birth_day: user.birthday // データベースのbirthdayフィールドを、APIレスポンスのbirth_dayにマッピング
22  }
23}

このコード例では、データベースのフィールド名がbirthdayに変わっても、APIがクライアントに返すデータは常にbirth_dayという名前を維持している。これにより、フロントエンドはデータベースの変更に影響されずに済み、システム全体の後方互換性が保たれる。これは、データベースのスキーマとAPIコントラクトを「分離」し、APIが提供するデータの形を「明示的に定義する」という重要な考え方に基づいている。

このパターンは、DTO（Data Transfer Object）やシリアライザ（Serializer）と呼ばれる既存の設計パターンと非常に似ている。これらは、データがアプリケーション内の異なる層を移動する際に、その形式を変換するために用いられる。

また、「ハイブリッドアプローチ」も考えられる。これは、ほとんどのフィールドはデータベースからAPIへ自動的にマッピングされるようにしつつ、特に変更が加えられたフィールドや、後方互換性を保ちたいフィールドだけを手動でマッピングするという方法だ。例えば、データベースのbirthdayフィールドの内容を、APIレスポンスでbirth_dayという古いフィールド名とbirthdayという新しいフィールド名の両方で提供することで、フロントエンド開発チームが新しいフィールド名にコードを更新する猶予期間を設けることができる。

このような設計パターンは、Express.jsだけでなく、Djangoのシリアライザ、LaravelのAPIリソース、NestJSのDTO、Ruby on Railsのシリアライザなど、多くのWebフレームワークで実現可能だ。重要なのは、フィールド名がAPIの「公開契約」の一部であり、一度公開したら恒久的な約束として扱うべきだという認識である。

ただし、このパターンを常に適用する必要はない。もし構築しているのがチーム内でのみ使用される内部APIであったり、プロジェクトがまだ初期段階でデータモデルが頻繁に変わるMVP（Minimum Viable Product）フェーズにある場合は、この追加のオーバーヘッド（手間）をスキップしても良いだろう。しかし、APIが成長し、利用するクライアントやエンドポイントが増えてくるにつれて、このパターンを導入する価値は高まる。新しいプロジェクトでは、最初はシンプルに始め、システムが成熟するにつれて再検討するのが賢明である。

さらに、APIコントラクトをより強固にするためには、OpenAPIスペック（旧Swagger）のようなツールを活用することが推奨される。OpenAPIスペックは、APIがどのようなエンドポイントを持ち、どのようなリクエストを受け付け、どのようなレスポンスを返すかを記述するための標準的な方法を提供する。これにより、「APIがbirth_dayというフィールドを常に返す」という約束を文書化し、開発者全員が参照できる「唯一の真実」とすることができる。データベースの構造がどのように変化しようとも、APIコントラクトは安定したものとして維持できるのだ。

GraphQLやgRPCといった技術には、もともとスキーマ定義が組み込まれているため、このような問題は発生しにくい。しかし、これはREST APIが劣っているという意味ではない。プロジェクトの規模、チームの構成、長期的な目標によって最適な技術は異なる。もし大規模なRESTプロジェクトで後方互換性の問題に直面しているなら、すぐにGraphQLなどへの全面的な移行を考えるのではなく、既存のREST APIを強化することに注力すべきである。OpenAPIスペック、JSON Schema、Pydantic、Zodといったツールを活用することで、REST APIにもスキーマ駆動の安全性と信頼性をもたらすことができる。

結論として、APIコントラクトはデータベースのスキーマと切り離して考えるべきであり、これらをデカップリング（分離）することが極めて重要である。適切な設計パターンとツールを用いることで、深夜の緊急デプロイや大規模なシステム改修といった事態を避け、より安定した運用と効率的な開発を実現できる。