先生と生徒の会話形式で理解しよう

生徒

「RailsでAPIを作るとき、どうやってルーティングを設計すればいいんですか？」

先生

「とても大事なポイントですね。APIのルーティングでは、バージョン管理や名前空間の使い方が重要なんですよ。」

生徒

「バージョン管理って、アプリのバージョンですか？」

先生

「そうです！Web APIでは将来の変更に備えて、v1、v2のようにversioningするのが一般的なんですよ。それでは、RailsでのAPIルーティング設計を一緒に見ていきましょう！」

1. RailsでのAPIルーティングとは？

Railsでは、Web API（ウェブエーピーアイ）を作るときに、どのURLにどの処理を対応させるかをルーティングで決めます。たとえば「商品一覧を取得するAPI」なら、/api/productsのようなURLを用意します。

APIはWebブラウザからではなく、スマホアプリやJavaScriptなど他のシステムからアクセスされるため、HTMLではなくJSON形式のデータを返すのが一般的です。

2. JSON形式に限定したAPIにするには？

Railsでは、ルーティングの段階でdefaultsオプションを使えば、全てのレスポンスをJSONに限定することができます。これは「このAPIはJSON専用です」と明確にするための大事な設定です。


Rails.application.routes.draw do
  namespace :api, defaults: { format: :json } do
    resources :products
  end
end

namespace（ネームスペース）とは、フォルダのようにAPI用の機能を分けて整理するための仕組みです。ここではapiという名前空間を使っており、URLは/api/productsのようになります。

APIは一度作ったらずっと同じというわけではなく、あとで仕様を変えることもあります。そのために最初からv1、v2といったバージョン番号をURLに含めておくのが定石です。


Rails.application.routes.draw do
  namespace :api, defaults: { format: :json } do
    namespace :v1 do
      resources :products
    end
  end
end

このように書くことで、URLは/api/v1/productsになります。次のバージョンを作るときにはv2フォルダを用意し、影響のない形で新しい仕様に切り替えることができます。

ルーティングでnamespaceを使うと、コントローラの場所も分けて管理する必要があります。たとえばapi/v1/products_controller.rbのような形でファイルを作成し、Api::V1::ProductsControllerというクラス名にします。


class Api::V1::ProductsController < ApplicationController
  def index
    render json: Product.all
  end
end

このようにすることで、API専用のロジックと通常のWeb画面用のロジックを完全に分離することができ、保守性が高まります。

constraints（コンストレインツ）を使うと、特定の条件に当てはまるリクエストだけをルーティングに通すことができます。たとえば、ドメイン名やリクエストヘッダーなどで制御できます。

以下は、Acceptヘッダーがapplication/jsonのリクエストだけをAPIとして受け付ける例です。


constraints(lambda { |req| req.format == :json }) do
  namespace :api do
    namespace :v1 do
      resources :products
    end
  end
end

このようなconstraintsを使うと、誤ったアクセスを防ぎ、セキュリティと安全性を高めることができます。

実はRailsでは最初から「APIモード」でアプリを作成することも可能です。--apiオプションを付けてプロジェクトを作ると、ビュー（画面）機能を省いたJSON専用アプリになります。


rails new my_api_app --api

このようにしておけば、軽量で高速なAPI専用アプリケーションをすぐに作ることができます。

たとえば/api/v1/productsというURLを分解すると、以下のような意味になります：

このようにURLに意味を持たせることで、APIの設計が分かりやすく保守しやすいものになります。