既存モノリスをAPI化する前に決めるべきこと
「フロントをReactに切り替えたい」「モバイルアプリも作りたい」「取引先とデータ連携したい」——こうした話が出るたびに、既存のRailsモノリスを「とりあえずAPI化しよう」という結論に飛びつく相談をよく受けます。しかし実際に着手してみると、どこまでをAPIにするか、既存の画面をどう維持するかで手が止まり、中途半端な状態のまま数ヶ月が過ぎているケースが少なくありません。
サーバーサイドレンダリング（ビューがHTMLを直接返す構成）のモノリスをAPI化するのは、単なる技術選定の問題ではなく、「今動いている画面を壊さずに、新しいクライアントを迎え入れる」という制約付きの設計判断です。この記事では、着手前に決めておくべき論点を、発注者が判断できる粒度で整理します。
なぜ「全部API化」が失敗しやすいのか
API化のプロジェクトが停滞する典型パターンは、最初から「全画面・全機能をAPI経由に統一する」というゴールを掲げてしまうことです。
- 既存のHaml/ERBビューは動いている。それを一旦壊してAPI+フロントに作り直すには、UIの全画面を再実装する工数がかかる
- 業務ロジックがコントローラやビューに直接書かれている場合、API化にはロジックの抽出（リファクタリング）が先に必要になる
- 「全部やる」計画は完了までリリースできないため、途中で予算が尽きると中途半端な二重管理状態が固定化する
実務で機能するのは、「新しく必要になった導線だけを先にAPI化し、既存画面は動くまま残す」という段階的なアプローチです。全面リプレイスは、リスクとコストが釣り合わないことがほとんどです。
最初に決めるべきは「なぜAPI化するか」
API化の目的によって、設計の優先順位がまったく変わります。着手前に以下を言語化しておく必要があります。
- フロント分離（React/Next.jsへの段階移行）が目的なら、まず画面単位でAPIを切り出し、既存のHaml/ERBと並走させられる構成にする
- モバイルアプリが目的なら、Web画面とは異なる認証方式（トークンベース）やレスポンス設計が必要になり、Web用のセッション認証とは別の仕組みを用意する必要がある
- 外部連携（取引先・パートナー企業とのデータ連携）が目的なら、社内利用のAPIより厳格なバージョニングとレート制限、アクセス権限の設計が要る
目的を曖昧にしたまま「汎用的なAPI」を作ろうとすると、結局どの用途にも中途半端な設計になりがちです。最初のユースケースを1つに絞り、そこに最適化してから汎用化する順番のほうが手戻りが少なくなります。
API境界の引き方
モノリスのどこにAPIの境界線を引くかは、既存のドメイン構造に大きく左右されます。
- 既存のモデル・コントローラの責務がある程度整理されているなら、ドメイン（ユーザー管理・注文・在庫など）単位で境界を引くのが基本
- ビジネスロジックがコントローラやビューに散らばっている場合は、API化の前にサービスクラスやフォームオブジェクトへロジックを抽出する下準備が必要になることが多い
- 既存のActive Recordモデルをそのままシリアライズして返すと、DBスキーマの変更がAPIレスポンスの破壊的変更に直結してしまう。DB構造とAPIレスポンスの間に1枚シリアライザ層を挟む判断は早い段階でしておくべき
境界設計に時間をかけすぎるのも禁物です。最初のユースケース（1〜2画面分）が動く最小構成を決め、実際に運用しながら境界を調整していくほうが、机上の設計より精度が上がります。
段階的な切り出しの進め方
いきなり全体をAPI化するのではなく、次のような順序で進めるのが現実的です。
- 1つの画面・1つの機能だけを対象に、API+新フロント（またはモバイル）の疎通を通す
- 並行して既存のHaml/ERB画面はそのまま残し、新旧が同時に動く期間を許容する
- 新しいAPI経由の導線が安定したら、次の画面へ範囲を広げる
- 最後まで移行しない画面（利用頻度が低い管理画面など）は、無理にAPI化せず残す判断もあり得る
「全部揃うまでリリースしない」計画は途中で止まりやすい一方、この進め方であれば各ステップごとに動くものが増え、進捗が発注者にも見える形になります。
後方互換をどう守るか
API化の途中で最も事故が起きやすいのが、既存の画面が知らないうちに壊れるパターンです。
- 既存のコントローラが依存しているモデルのメソッドやコールバックを、API用の変更で不用意に書き換えない
- APIレスポンスの形式を途中で変えると、先に作ったモバイルアプリや外部連携先が壊れる。バージョニング（
/api/v1/のようなパス、またはヘッダーでのバージョン指定）は最初から入れておく - DBのスキーマ変更を伴う場合は、既存画面・新API双方から見て問題ないマイグレーション手順（カラム追加→両対応→旧参照の除去、の順）を踏む
「動いているものを壊さない」という制約は、API化の全工程を通じて最優先です。新しい仕組みを追加する速度より、既存導線を壊さない慎重さのほうが、結果的にプロジェクト全体の信頼を守ります。
認証をどう設計するか
既存のRailsモノリスがDeviseなどでセッションベースの認証をしている場合、API化にあたって認証方式の選定が必要になります。
- Web画面からのAPI呼び出し（同一オリジンのフロント分離）であれば、既存のセッション認証をそのまま流用できる場合が多い
- モバイルアプリや外部連携のように別オリジン・別クライアントからのアクセスが前提なら、トークンベース認証（APIキーやJWTなど）を別途用意する必要がある
- 「とりあえず両方使えるように」と認証方式を複数同時に作り込むと、権限管理が複雑化しセキュリティホールの温床になりやすい。最初のユースケースに必要な認証方式だけに絞るのが安全
認証は後から差し替えるコストが高い部分です。目的（フロント分離かモバイルか外部連携か）が先に決まっていれば、認証方式も自然に絞り込めます。
いきなり全部やらないための優先順位
以上を踏まえると、着手の順番は次のようになります。
- API化の目的を1つに絞る（フロント分離／モバイル／外部連携のどれを最初にやるか）
- その目的に必要な1〜2画面分だけを対象に境界を決める
- 既存画面と並走できる構成（新旧共存）で最小構成を動かす
- 後方互換とバージョニングの方針を最初に決めてから、対象範囲を広げていく
この順番を守ると、途中で予算やスケジュールの制約が来ても「中途半端で使えない状態」ではなく「一部は完成している状態」で止まれます。
torcheees では Ruby on Rails を中心とした既存モノリスのAPI化やフロント分離を、既存画面を壊さない段階移行の形で数多く手がけており、モダナイゼーションのサービスとして提供しています。
関連記事
API化はモノリス改善の一部です。全体像や関連する論点は以下も参考にしてください。
まとめ
- 「全部API化」を最初のゴールにすると停滞しやすい。目的（フロント分離／モバイル／外部連携）を1つに絞り、対象範囲を段階的に広げるのが現実的
- API境界の設計は、既存のドメイン構造とロジックの散らばり具合に左右される。DB構造とAPIレスポンスの間にシリアライザ層を挟む判断は早めにしておく
- 後方互換（バージョニング、既存画面を壊さない移行手順）と認証方式は、途中で差し替えるコストが高いため最初に方針を決めておく
「既存のモノリスをAPI化したいが、どこから手をつければいいか分からない」という段階でも、torcheees はご相談を受け付けています。まずは1〜4週間の「要件整理・開発診断」で、現状のコードとAPI境界の設計案を一通り確認し、優先順位と概算費用をご提示します。お問い合わせフォームからお気軽にご連絡ください。