RailsのAPIモードとは？基本的な使い方について調べてみた

はじめに
- 前提
Ruby on RailsのAPIモードとは
なぜAPIモードが存在するのか
JSON APIにRailsを使う理由
API専用Railsアプリケーションを新規で作成する場合
既存のRailsアプリケーションをAPI専用アプリケーションに変更する方法
RailsでAPIモードと通常のモードを混在する方法
さいごに
参考にしたサイト

はじめに

前提

まず前提として、この記事を書いているのは未経験からプログラミングに挑戦中の者になります。学習はフィヨルドブートキャンプ（以下 FBC）に参加しながら取り組んでいて、現役のエンジニアの方からレビューをもらいながら進めています。

現在の学習状況は以下を随時更新しているので興味ある方はご覧ください。

hirano-vm4.hatenablog.com

フィヨルドブートキャンプは終盤にアジャイル/スクラムでのチーム開発のプラクティスに取り組みます。しかも、これまで自らが使ってきたFBCアプリを開発します。

このFBCアプリはAPIが使われています。

今回はチーム開発に入るにあたって、RailsのAPIモードについてよく知らなかったことをきかけにインプットしました。せっかくのなので、調べたことをまとめてアウトプットしておきたいと思います。

というのも、これまでのプラクティスでRailsをやってきましたが、APIモードが扱ってきませんでした。

しかし、チーム開発で取り組むフィヨルドブートキャンプアプリはAPIモードを使ってフロントとやりとりしている部分があるようなので、概要だけでも理解しておかないと！と思い題材にしました。

現場レベルで使用した意見ではなく、あくまで利用前に調べたことをまとめた記事になりますので、その点はご注意ください。

ということで、ここからが本題になります。

Ruby on RailsのAPIモードとは

Rails におけるAPIモードは、「React.js や Vue.js のような他フロントエンド技術との連携を目的として、MVC アーキテクチャーのフロントエンド領域に相当する V(View) を捨てて、 JSON API としてのみ振る舞うバックエンド領域特化のアプリとして開発するモード」のことです。

後述しますが、完全にViewを捨ててJson APIに専念するだけでなく、Viewをこれまで使いながら一部分をAPIモードとして活用するハイブリットな形式でも用いることも当然できるようです。

なぜAPIモードが存在するのか

RailsはMVC アーキテクチャーによって、フルスタックにアプリ開発を行えるフレームワークであるが、Reactなどフロントエンド技術の進歩により、SPA（Single Page Application）が注目されてきた
React.js や Vue.js のようなモダンなフロントエンド技術は、「フロントエンドに特化したアプリケーションを構築する技術であり、バックエンドは別に用意する」ことを前提としている
それによってRailsはバックエンドに特化する使い方もするようになってきた

このような理由からAPIモードが登場し、使われるようになってきたようだ。

JSON APIにRailsを使う理由

ではなぜ、JSON APIにRailsを使うのか。RailsガイドのRails による API 専用アプリケーションに説明が書いてありました。

例えば「RailsでJSONを出力するのは大げさでは？」、「もっと軽量なフレームワーク（例えばSinatra）でも同じことができるのでは？と疑問に思うかもしれないが以下のようなメリットがRailsを使うことで享受できるとのことです。

開発の迅速化: Railsは「設定より規約」の哲学に基づいており、多くのデフォルト設定がすでに最適化されているため、開発者は細かい設定に時間を費やすことなく、すぐにアプリケーションの開発を開始できる。
豊富な機能: Railsは、開発の各段階で役立つ多くの機能を提供する。これにはミドルウェア層での透過的な再読み込み、開発環境での便利なデフォルト値、テストとログ出力のサポート、セキュリティ対策、パラメータ解析、条件付きGETの処理、HEADリクエストのサポートなどが含まれる。
セキュリティ: RailsはIPスプーフィング攻撃やタイミング攻撃などのセキュリティ脅威を検出し、防御する機能を備えている。これにより、アプリケーションの安全性が高まる。
RESTful APIのサポート: Railsはリソースベースのルーティングをサポートしており、RESTful APIの開発が容易になる。これにより、HTTPの規則に従った明確なURL構造でAPIを構築可能。
便利なツールとプラグイン: Railsには、開発を加速させるための多数のジェネレータ、プラグイン、ライブラリがあります。これらを利用することで、開発者はより高度な機能を簡単に追加でき、開発プロセスをスムーズに進めることができる。
統合環境: Railsはモデル、ビュー、コントローラ（MVC）のフレームワークを採用しており、APIのバックエンドロジック、データベースの操作、フロントエンドとの通信など、アプリケーション開発の全ての側面を統合的に扱うことができる。

要するに、Railsを使用すると、開発者は迅速にアプリケーションを立ち上げることができ、セキュリティ、パフォーマンス、開発の利便性など、多くの面でメリットを享受できるということです。

ビュー層を除外しても、「ほとんどの機能」を引き続き利用できるため、API開発にも非常に適してるというのが理由のようです。

API専用Railsアプリケーションを新規で作成する場合

API専用Railsアプリケーションの生成

API専用Railsアプリケーションを作るには以下のコマンドを使う

$ rails new my_api --api

このコマンドによって以下の設定がされます。

ミドルウェアの絞り込み:
- Railsアプリケーションは、リクエストの処理にさまざまなミドルウェアを使用する。APIモードでは、ブラウザからのアクセスに必要なミドルウェア（例えば、クッキーのサポート）を除外し、APIサーバーとしての機能に特化させたミドルウェアスタックを使用する。
ApplicationControllerの変更:
- 標準のActionController::Baseではなく、ActionController::APIを継承したApplicationControllerが生成される。これにより、ビューをレンダリングするための機能など、APIサーバーには不要な機能が除外される。
ビュー、ヘルパー、アセットの生成の無効化:
- API専用アプリケーションでは、HTMLビュー、ビューヘルパー、アセットファイル（CSSやJavaScript）は必要なくなる。そのため、これらのファイルを生成するジェネレーターがデフォルトで無効に設定される。

新しいリソースの作成

例としてグループのデータを管理するためのGroupというリソースを作成する。 Railsでは$ bin/rails g scaffoldコマンドを使って、リソースに関するモデル・ビュー・コントローラー・マイグレーションファイルを一度に生成できる。

$ bin/rails g scaffold Group name:string

このコマンドは、Groupという名前のモデルと、それに紐づくname(型はstring)を「持つテーブルを作成します。

データベースのマイグレーション

生成したマイグレーションファイルを使ってデータベーススキーマを更新する。これにより、groupsテーブルがデータベースに作られます。

$ bin/rails db:migrate

コントローラーの確認と修正

scaffoldコマンドで生成されたGroupsControllerはデフォルトでJSON形式でデータを返すように設定されています。

※API専用Railsアプリケーションの生成した場合ですのでご注意ください

$ rails new my_api --api

これにより、APIとして機能します。例えばindex アクションでは全てのグループを取得してJSON形式で返します。

そのほか、show、create、update、destroyアクションでは、それぞれ特定のグループの詳細を表示、新しいグループを作成、グループの情報を更新、グループを削除する処理を行います。

データを確認する

サーバーを起動して、ブラウザからhttp://localhost:3000/groups.json:titleにアクセスすると、データをJSON形式で確認することができます。

既存のRailsアプリケーションをAPI専用アプリケーションに変更する方法

ここからは、既存のRailsアプリをAPIモードに変更する方法になります。

APIモードの設定

まず、アプリケションをAPI専用モードに変更します。

config/application.rbファイルを開き、Applicationクラスの定義の冒頭に以下を追加します。

module YourApp
  class Application < Rails::Application
    config.api_only = true
  end
end

これにより、アプリケーションがAPIモードで動作するようになる。

開発モードでのエラー表示の設定

開発中にエラーが発生した時のレスポンス形式を設定する。これにより、エラーが発生した際にどのような情報を表示するのかを制御できる。

HTML形式でのエラー表示 config/environments/development.rbファイルにconfig.debug_exception_response_format = :defaultを設定すると、エラーが発生した際にHTMLページでデバッグ情報が表示される。これは、従来のWebアプリケーション開発時に親しみやすい形式。
API形式でのエラー表示 同じファイルにconfig.debug_exception_response_format = :apiを設定すると、エラーが発生した際にAPI形式（通常はJSON）でデバッグ情報が返さる。これは、API専用アプリケーションを開発している場合に適している。

APIモードであれば、config.debug_exception_response_formatはデフォルトで:apiに設定されている。

ApplicationControllerの継承先の変更

アプリケーション全体でAPI関連の機能を使用するために、ApplicationControllerの継承元をActionCntroller::BaseからActionController::APIに変更する。

これによりビューをレンタリングするためのメソッドなどAPIに不要な機能が削除される。

変更前

class ApplicationController < ActionController::Base
end

変更後

class ApplicationController < ActionController::API
end

この変更を行うことでアプリケーションはAPI専用モードで動作するようになり、バックエンドからフロントエンドにデータを送信する際にJSONなどの形式を利用するようになる。

これにより、フロントエンドとバックエンドを分離したモダンなWebアプリケーションの開発が容易になるとのこと。

RailsでAPIモードと通常のモードを混在する方法

API専用のコントローラーの作成

API 機能を提供する部分については、ActionController::APIを継承したコントローラーで作成する。これにより、APIに必要な昨日のみを持った継承なコントローラーが作成できる。

class Api::V1::ExampleController < ActionController::API
  def index
    # API用のアクションをここに記述
  end
end

通常のコントローラー

従来のRailsアプリケーションとしてビューを提供する部分には、これまでのように通常通りActionController::Baseを継承したコントローラを使用する

class PagesController < ActionController::Base
  def show
    # ビューを提供するアクションをここに記述
  end
end

ルーティングの設定

APIとビューを提供する部分のルーティングを適切に設定する。

API用のルーティングは、通常namespaceを使ってグループ化し、URLに/api/v1/などを含めることが一般的。

例

Rails.application.routes.draw do
  namespace :api do
    namespace :v1 do
      resources :examples, only: [:index]
    end
  end

  get 'pages/show'
end

フロントエンドとの統合

ReactなどのフロントエンドフレームワークをRailsと統合して利用する。

WebpackerやRails 7以降で導入されたjsbundling-railsなどのツールを使用して、フロントエンドのビルドシステムをRailsと組み合わせることができる。

さいごに

以上、RailsのAPIモードについて予習まとめでした。

今後、実践していく中で追記したほうがよさそうなことがあれば、リライトしていきたいと思います。

チーム開発が終わったらいよいよ自作サービスの作成に入るので気合をいれて学習に取り組んでいきたいと思います💪

参考にしたサイト

Rails による API 専用アプリケーション - Railsガイド

「Rails API とは？普通の Rails と何が違うの？」と思った人がまず読む記事

Code Journey

30代未経験からプログラミング挑戦中(追うものは追われる者に勝る)