3 Ways to build a Rails API

Updated: 

In this tutorial, we cover three different ways of building an API with Ruby on Rails - a new API-only app, an API inside a normal Rails app and converting a Rails app to an API.

This lesson is from Full Stack Rails Mastery.

Buy Now
1. A brand new API-only Rails app
If you're building a Ruby on Rails app that's mainly going to be used as an API by other clients (for example, with mobile apps and a SPA web app), you can directly start by creating a new Rails app in API-only mode by running:

$ rails new api-app --api

This creates a Rails application with a limited subset of features, leaving out anything you'd typically need in the browser (for example, support for cookies and any view, helper and asset files).
Then you can add any specific things you need on top (for example, authentication).

2. An API inside a normal Rails app
This is a very common situation as it turns out that you don’t need a separate Rails application for your API.
Instead, you can manage both the REST API and the regular Rails application within a single app by using namespaced controllers and routes.
You need to define API routes in a namespace to keep them separate from your web routes.

#config/routes.rb:

Rails.application.routes.draw do
  # Web routes
  ...

  # API routes
  namespace :api, defaults: { format: :json } do
    namespace :v1 do
      resources :products, only: [:index, :show, :create, :update, :destroy] do
        # API-specific actions can be added here if needed
        post "buy", on: :member
      end
    end
  end
end

Then create API-Specific controllers in a dedicated namespace.

# app/api/v1/products_controller.rb:

module Api
  module V1
    class ProductsController < ApplicationController
      # GET /api/v1/products
      def index
        @products = Product.all
        render json: @products
      end

      # GET /api/v1/products/:id
      def show
        render json: @product
      end
    end
  end
end

This approach allows you to share models, helpers, and validations between your API and web interfaces, reducing redundancy.

3. Convert an existing Rails app into an API-only app
If you have an existing normal Rails app, but don't intend to use the view layer any more you can conver it to an API-only app.

This also happens often as a product matures and an organisaiton grows. While you may have started as a majestic monolith, over time you may decide to break up your Rails app into a backend API which serves a separate frontend React, Angular or Vue app.

Instead of keeping the old unused views and middleware lying around, you can clean up your codebase and remove dead code. See the Rails guide for the list of middleware you need.

Remove gems related to non-API functionality that you no longer need.
You'll need to make a few configuration changes.
Enable API mode in config/application.rb:
config.api_only = true

Make ApplicationController inherit from ActionController::API instead of ActionController::Base.

class ApplicationController < ActionController::API
end

It's crucial that your Rails app has good tests with high coverage before you make the switch.