Full Rails versus API-only Rails

Direct Answer

A full Rails application includes the controller, view, browser-session, asset, and middleware features needed to render HTML. An API-only application starts with ActionController::API, a smaller default middleware set, and generators aimed at JSON services, while still allowing omitted Rails features to be added deliberately.

Deep Dive & Architecture

The --api generator sets config.api_only = true. The generated ApplicationController inherits from ActionController::API, whose smaller module set focuses on request parameters, headers, rendering, redirects, status codes, and other API controller needs. Full applications inherit from ActionController::Base, which builds on the API controller foundation with browser-facing modules and Action View integration.

The middleware stack also starts smaller. Browser sessions and cookies are not assumed in the same way, and generators avoid views, helpers, and assets for ordinary resources. This reduces unused surface area, but it does not create a non-Rails microframework. The router still dispatches requests, Active Record still maps models when included, Active Job still runs work, and render json: still uses Rails rendering support.

Representation remains an action-level decision. Returning a Ruby object from a method does not by itself define an HTTP JSON response. The controller chooses a status, headers, and body, commonly with render json: or head. Validation errors need a stable error shape; created resources should use an appropriate success status and may include a Location header; a 204 response must not carry a body.

Features can be restored deliberately. A browser-based API using cookie authentication may add cookie and session middleware plus the relevant controller modules, then handle CSRF according to its credential model. An endpoint that also serves an HTML administration view may be better in a full app or separated behind a clear controller boundary. The important point is to understand every added feature's request and security behaviour.

The mode decision therefore follows clients and ownership. If Rails renders the document and handles form navigation, full mode offers coherent defaults. If independent clients own presentation and Rails supplies representations of resources, API-only mode avoids unused browser machinery. Teams should verify with bin/rails middleware, the controller ancestors, and generated files rather than relying on the label alone.

Choose the application mode from the delivered clients and operational needs, not from the word API in a project name. A service that renders no pages may still need cookies or browser protections, while a full-stack application can expose a small, well-designed JSON namespace.

Code Example

class ApplicationController < ActionController::API
end

class Api::OrdersController < ApplicationController
  def show
    order = Order.find(params[:id])
    render json: { id: order.id, state: order.state }, status: :ok
  end
end

ActionController::API provides a focused controller stack, while the action still chooses JSON and its status explicitly.

Common Mistakes & Pitfalls

Claiming --api makes every action return JSON automatically or makes cookies impossible.