• Rails APIモードとは何か知りたい
• 通常のRailsアプリとAPIモードの違いを知りたい
• RailsでJSON APIを作る基本手順を知りたい
• ReactやスマホアプリとつなぐRailsバックエンドを作る時の注意点を知りたい

Rails APIモードを使えば、Ruby on RailsでJSON APIを作れます。通常のRailsアプリのようにHTML画面をサーバー側で描画するのではなく、React、Vue、スマホアプリ、外部サービスなどにJSONを返すことを主な役割にします。まずは小さなCRUD APIを作り、通常Railsとの違い、JSONレスポンス、認証やCORSの注意点を順番に押さえるのが近道です。

Rails公式ガイドでも、API-onlyアプリケーションは rails new my_api --api で作成でき、通常のRailsよりブラウザ向け機能を絞った構成になると説明されています。この記事では、Rails APIモードの概要、通常Railsとの違い、作り方、JSONレスポンスの書き方、実務で注意するポイントまで解説します。

Rails APIモードとは

RailsをJSON APIのバックエンドとして使う構成

Rails APIモードとは、Railsを画面表示用のWebアプリではなく、JSONを返すAPIサーバーとして使うためのモードです。たとえば、フロントエンドをReactで作り、バックエンドをRailsで作る場合、Rails側はユーザー情報や商品一覧などをJSONで返します。

ViewではなくJSONレスポンスを中心にする

通常のRailsでは、ControllerがHTMLテンプレートを呼び出し、ブラウザにHTMLを返す構成がよく使われます。一方、Rails APIモードではControllerがJSONを返す前提になり、View、helper、assetsなどのブラウザ向け機能は初期状態では省かれます。

Railsのバックエンド機能は引き続き使える

APIモードでも、Railsの便利な機能がすべて消えるわけではありません。ルーティング、Controller、Active Record、バリデーション、マイグレーション、ログ、テスト、キャッシュなど、バックエンド開発に必要な機能は引き続き使えます。

Rails APIモードと通常のRailsアプリの違い

初期構成の違いを把握する

Rails APIモードと通常のRailsアプリの大きな違いは、HTML画面を作るための機能を初期状態で持つかどうかです。Rails APIモードでは、APIサーバーに必要な機能を中心に構成されます。

APIモードは通常Railsの上位互換ではない

Rails APIモードは「通常のRailsより必ず優れている」というものではありません。HTML画面をRailsで作るなら通常のRailsアプリが自然です。フロントエンドとバックエンドを分け、RailsをAPIサーバーとして使うならAPIモードが向いています。

Rails APIアプリを作る手順

rails new --apiで新規作成する

新しくRails APIアプリを作る場合は、rails new に --api オプションを付けます。これにより、API向けのControllerやgenerator設定でアプリが作成されます。

rails new my_api --api
cd my_api

scaffoldでCRUDの流れを確認する

リソースを作る場合は、通常のRailsと同じようにscaffoldやmodel/controller generatorを使えます。

bin/rails g scaffold Article title:string body:text
bin/rails db:migrate

生成されたControllerをAPI設計に合わせて整理する

APIモードのscaffoldでは、HTMLテンプレートを作るのではなく、JSONを返すControllerが中心になります。最初はscaffoldで全体像を見てから、自分のAPI設計に合わせてController、serializer、routesを整理すると理解しやすいです。

既存のRailsアプリをAPIモードに近づける方法

config.api_onlyを使う前に影響範囲を見る

既存のRailsアプリをAPI中心にしたい場合は、config.api_only = true と ActionController::API の利用を検討します。ただし、既存アプリでView、session、Cookie、flashを使っている場合、単純に切り替えると画面側の機能が壊れる可能性があります。

# config/application.rb
module MyApp
  class Application < Rails::Application
    config.api_only = true
  end
end

Controllerの継承元を切り替える

# app/controllers/application_controller.rb
class ApplicationController < ActionController::API
end

HTML画面を残すならAPI用Controllerを分ける

既存アプリをAPI化する時は、まず「HTML画面を今後もRailsで返すのか」「JSON APIだけに寄せるのか」を決めましょう。管理画面やログイン画面をRailsで持ち続けるなら、通常RailsのままAPI用Controllerだけを切り出す選択肢もあります。

コントローラでJSONを返す書き方

一覧・詳細ではrender json:を明示する

Rails APIのControllerでは、render json: を使ってJSONレスポンスを返します。APIモードではテンプレートが自動で描画される前提ではないため、各actionで何を返すかを明示することが大切です。

class ArticlesController < ApplicationController
  def index
    articles = Article.order(created_at: :desc)
    render json: articles
  end

  def show
    article = Article.find(params[:id])
    render json: article
  end
end

作成・更新ではHTTPステータスも返す

作成・更新・削除では、HTTPステータスも一緒に返すと、フロントエンド側が成功・失敗を判断しやすくなります。

class ArticlesController < ApplicationController
  def create
    article = Article.new(article_params)

    if article.save
      render json: article, status: :created
    else
      render json: { errors: article.errors }, status: :unprocessable_entity
    end
  end

  def destroy
    article = Article.find(params[:id])
    article.destroy
    head :no_content
  end

  private

  def article_params
    params.require(:article).permit(:title, :body)
  end
end

代表的なステータスコードを揃える

ルーティング・params・Strong Parametersの考え方

RESTfulなroutesで入口を整理する

Rails APIでも、RESTfulなルーティングとStrong Parametersを使って入力値を安全に扱います。APIだからといって、受け取ったJSONをそのままModelへ渡すのは避けましょう。

# config/routes.rb
Rails.application.routes.draw do
  resources :articles, only: %i[index show create update destroy]
end

JSONリクエストはparamsで受け取る

フロントエンドから次のようなJSONを送る場合、Rails側では params から値を取得できます。

{
  "article": {
    "title": "Rails API入門",
    "body": "RailsでJSON APIを作る"
  }
}

Strong Parametersで許可項目を明示する

実務では、許可する項目をStrong Parametersで明示します。RubyのHashやparamsの扱いに慣れておくと、APIで受け取るデータ構造を読みやすくなります。

def article_params
  params.require(:article).permit(:title, :body)
end

認証・CORS・serializerで注意すること

Rails APIを実務で使う時は、Controllerの書き方だけでなく、認証、CORS、レスポンス形式を先に設計しましょう。APIはフロントエンドや外部サービスから呼ばれるため、画面表示中心のRailsとはつまずきやすいポイントが変わります。

認証方式はフロントエンド構成に合わせる

APIでは、session cookie、token、JWT、OAuthなど、構成に応じて認証方式を選びます。SPAやスマホアプリから呼ぶ場合は、どこに認証情報を持たせるか、ログアウトやtoken更新をどう扱うかまで決める必要があります。

CORSは開発初期に確認する

ReactやVueなど別ドメインのフロントエンドからRails APIを呼ぶ場合、CORS設定が必要になることがあります。ローカル開発では動いても、本番ドメインでブロックされることがあるため、許可するorigin、method、headerを早めに確認しましょう。

レスポンスの形はserializerで整理する

render json: article は最初の学習には分かりやすいですが、実務ではそのまま全カラムを返すと不要な情報まで含まれることがあります。返す項目、ネスト、日付形式、エラー形式を統一するために、serializerや専用のJSON整形クラスを使う設計も検討しましょう。

Rails APIモードを使うべきケース

Rails APIモードは、RailsをバックエンドAPIとして使い、画面側を別の技術で作る場合に向いています。特に、次のような構成ではAPIモードを検討しやすいです。

• React、Vue、Next.jsなどのフロントエンドと分けて開発する
• スマホアプリ向けのAPIをRailsで作る
• 外部サービスや社内システム向けのREST APIを作る
• 管理画面よりもAPIレスポンスの設計が中心になる
• 将来的に複数のクライアントから同じバックエンドを使いたい

一方で、ブログ、管理画面、社内ツールのようにRailsでHTML画面まで作る方が速い場合は、通常のRailsアプリの方が合うこともあります。APIモードは「モダンだから使う」ではなく、アプリの構成に合わせて選びましょう。

Rails APIの実務で見られるスキル

JSONを返すだけでなくAPI設計まで見られる

Rails APIの実務では、JSONを返すコードだけでなく、API設計、DB設計、認証、テスト、運用まで見られます。Rails APIモードを学ぶなら、CRUDを作った後に、実務で必要になる周辺スキルまで広げると案件で説明しやすくなります。

募集要件から次に学ぶ範囲を逆算する

Rails APIのスキルを実務でどう使うか知りたい方は、Ruby on Rails案件一覧で、API開発、バックエンド開発、認証、DB設計、テストなどがどのように募集要件に入っているか確認しておくと、学習する範囲を決めやすくなります。

Rails APIを学ぶ順番

小さなCRUD APIから始める

Rails APIを初めて学ぶなら、小さなCRUD APIから始めるのが一番分かりやすいです。いきなり認証や複雑なserializerを入れるより、まずはRailsがJSONを返す流れを体験しましょう。

1. rails new my_api --api でAPIアプリを作る
2. resources でRESTfulなroutesを書く
3. render json: で一覧・詳細を返す
4. POST / PATCH で作成・更新を作る
5. Strong Parametersで入力値を制限する
6. エラー時のJSONとHTTPステータスを整える
7. request specでAPIの挙動を確認する
8. 認証、CORS、serializerを追加する

Ruby文法もAPIレスポンス整形で使う

Rubyの配列変換や整形に不安がある場合は、Rubyのmapメソッドのような基礎文法も合わせて確認しておくと、APIレスポンスの加工が理解しやすくなります。

よくある質問

Rails APIモードではViewを使えないですか？

初期状態ではViewやhelperなどの生成が省かれますが、必要な機能を追加して使うことはできます。ただし、HTML画面をRailsで多く作るなら、最初から通常のRailsアプリとして作る方が自然な場合があります。

Rails APIモードでもActive Recordは使えますか？

使えます。APIモードはView周りを軽くする構成であり、Active Record、マイグレーション、バリデーションなどのDB関連機能はRailsのバックエンド機能として利用できます。

Rails APIではDeviseを使えますか？

使えますが、通常の画面ログインとは設計が変わることがあります。SPAやスマホアプリと接続する場合は、session cookieで扱うのか、tokenやJWTを使うのか、フロントエンド側の保存方法まで合わせて決める必要があります。

Rails APIとGraphQLはどちらがよいですか？

まずREST APIで十分かを考えましょう。Rails APIモードはREST APIを作りやすい構成です。クライアントごとに取得項目を細かく変えたい、複雑なデータ取得を1回のリクエストで扱いたい場合はGraphQLも候補になります。

Rails APIモードは初心者にもおすすめですか？

RailsのMVCやHTTPの基礎を学びながらならおすすめです。ただし、APIモードでは画面が自動で表示されないため、JSONレスポンス、HTTPステータス、フロントエンドとの接続を意識する必要があります。最初は小さなCRUD APIから始めましょう。

まとめ

Rails APIモードは、RailsをJSON APIのバックエンドとして使うための構成です。rails new my_api --api で作成でき、通常のRailsアプリよりView、helper、assetsなどのブラウザ向け機能を絞った状態で始められます。

Rails APIを理解するには、通常Railsとの違い、ActionController::API、render json:、RESTful routing、Strong Parameters、HTTPステータスを順番に押さえることが大切です。実務ではさらに、認証、CORS、serializer、request spec、ログや監視まで求められます。

まずは小さなCRUD APIを作り、JSONの返し方とエラー時のレスポンスを整理しましょう。そのうえで、Ruby on Rails案件一覧を確認すると、Rails APIのスキルが実務でどのように評価されるか把握しやすくなります。

参考: Rails公式ガイド「Using Rails for API-only Applications」、Rails APIドキュメント「ActionController::API」