Ruby on Rails has come a long way since its inception, and one of the coolest things you can do with it now is build API-only applications. These are perfect for mobile apps or projects where the frontend is doing most of the heavy lifting. Let’s dive into how to create one of these bad boys.

First things first, when you’re setting up a new Rails project for API-only mode, you’ll want to use the —api flag. It’s as simple as running:

rails new my_api --api

This neat little trick sets up your Rails app with a slimmed-down configuration, ditching all the view-related stuff you won’t need. It’s like putting your app on a diet, but in a good way.

Now, let’s talk about controllers. In an API-only app, your controllers will inherit from ActionController::API instead of ActionController::Base. This gives you a leaner controller with just the essentials for API development. Here’s what a typical controller might look like:

class UsersController < ApplicationController
  def index
    users = User.all
    render json: users
  end

  def show
    user = User.find(params[:id])
    render json: user
  end
end

Notice how we’re using render json: to send back our responses? That’s the bread and butter of API development in Rails.

But wait, there’s more! You’ll want to version your API to make future updates easier. A common way to do this is by namespace:

# config/routes.rb
Rails.application.routes.draw do
  namespace :api do
    namespace :v1 do
      resources :users
    end
  end
end

This setup allows you to have multiple versions of your API coexisting peacefully. Trust me, your future self will thank you for this.

Now, let’s talk about authentication. You can’t just let anyone access your API willy-nilly, right? JWT (JSON Web Tokens) is a popular choice for API authentication. Here’s a basic setup using the jwt gem:

# Gemfile
gem 'jwt'

# app/controllers/application_controller.rb
class ApplicationController < ActionController::API
  def encode_token(payload)
    JWT.encode(payload, 'my_secret')
  end

  def auth_header
    request.headers['Authorization']
  end

  def decoded_token
    if auth_header
      token = auth_header.split(' ')[1]
      begin
        JWT.decode(token, 'my_secret', true, algorithm: 'HS256')
      rescue JWT::DecodeError
        nil
      end
    end
  end

  def current_user
    if decoded_token
      user_id = decoded_token[0]['user_id']
      @user = User.find_by(id: user_id)
    end
  end

  def logged_in?
    !!current_user
  end

  def authorize
    render json: { message: 'Please log in' }, status: :unauthorized unless logged_in?
  end
end

This gives you a solid foundation for handling user authentication in your API. You can then use the authorize method as a before_action in controllers where you need to restrict access.

Speaking of restricting access, let’s talk about rate limiting. You don’t want someone hammering your API with requests, right? The rack-attack gem is great for this:

# Gemfile
gem 'rack-attack'

# config/application.rb
config.middleware.use Rack::Attack

# config/initializers/rack_attack.rb
class Rack::Attack
  Rack::Attack.cache.store = ActiveSupport::Cache::MemoryStore.new

  throttle('req/ip', limit: 300, period: 5.minutes) do |req|
    req.ip
  end
end

This setup will limit each IP to 300 requests every 5 minutes. Adjust as needed for your app’s requirements.

Now, let’s talk about serialization. When you’re building an API, you often want to customize how your data is presented. The active_model_serializers gem is fantastic for this:

# Gemfile
gem 'active_model_serializers'

# app/serializers/user_serializer.rb
class UserSerializer < ActiveModel::Serializer
  attributes :id, :name, :email
  has_many :posts
end

This allows you to control exactly what data gets sent back in your API responses. It’s like being a data DJ, mixing and matching just the right attributes.

Error handling is another crucial aspect of API development. You want to provide clear, consistent error messages. Here’s a simple way to set this up:

# app/controllers/application_controller.rb
class ApplicationController < ActionController::API
  rescue_from ActiveRecord::RecordNotFound, with: :render_not_found_response
  rescue_from ActiveRecord::RecordInvalid, with: :render_unprocessable_entity_response

  def render_not_found_response(exception)
    render json: { error: exception.message }, status: :not_found
  end

  def render_unprocessable_entity_response(exception)
    render json: { errors: exception.record.errors.full_messages }, status: :unprocessable_entity
  end
end

This setup will catch common errors and format them nicely for your API consumers.

Testing is super important when building APIs. RSpec is a popular choice in the Rails community. Here’s a basic spec for our Users controller:

# spec/controllers/api/v1/users_controller_spec.rb
require 'rails_helper'

RSpec.describe Api::V1::UsersController, type: :controller do
  describe "GET #index" do
    it "returns a success response" do
      get :index
      expect(response).to be_successful
    end
  end

  describe "GET #show" do
    it "returns a success response" do
      user = User.create!(name: "John Doe", email: "[email protected]")
      get :show, params: { id: user.to_param }
      expect(response).to be_successful
    end
  end
end

Remember, thorough testing is your friend. It’ll save you headaches down the road, trust me.

Now, let’s talk about documentation. Your API is only as good as its documentation. The rswag gem is great for generating Swagger documentation:

# Gemfile
gem 'rswag'

# spec/swagger_helper.rb
RSpec.configure do |config|
  config.swagger_root = Rails.root.join('swagger').to_s
  config.swagger_docs = {
    'v1/swagger.yaml' => {
      openapi: '3.0.1',
      info: {
        title: 'API V1',
        version: 'v1'
      },
      paths: {},
      servers: [
        {
          url: 'https://{defaultHost}',
          variables: {
            defaultHost: {
              default: 'www.example.com'
            }
          }
        }
      ]
    }
  }
end

With this setup, you can generate beautiful, interactive API documentation that your users will love.

Performance is key in API development. N+1 queries can be a real pain, but Rails makes it easy to avoid them with includes:

class UsersController < ApplicationController
  def index
    users = User.includes(:posts).all
    render json: users
  end
end

This simple change can dramatically improve your API’s performance when dealing with associations.

Speaking of performance, caching is another great way to speed things up. Rails makes it super easy with fragment caching:

class UsersController < ApplicationController
  def index
    users = User.all
    render json: Rails.cache.fetch("users", expires_in: 12.hours) do
      UserSerializer.new(users).serializable_hash
    end
  end
end

This will cache your user data for 12 hours, reducing database hits and speeding up responses.

Now, let’s talk about handling file uploads in your API. Active Storage makes this a breeze:

# app/models/user.rb
class User < ApplicationRecord
  has_one_attached :avatar
end

# app/controllers/api/v1/users_controller.rb
class Api::V1::UsersController < ApplicationController
  def update
    user = User.find(params[:id])
    user.avatar.attach(params[:avatar])
    render json: user
  end
end

This setup allows you to easily handle file uploads through your API.

Pagination is crucial when dealing with large datasets. The kaminari gem makes this super easy:

# Gemfile
gem 'kaminari'

# app/controllers/api/v1/users_controller.rb
class Api::V1::UsersController < ApplicationController
  def index
    users = User.page(params[:page]).per(20)
    render json: users
  end
end

This will paginate your users, returning 20 per page.

Finally, let’s talk about background jobs. When you’re building an API, you often want to offload time-consuming tasks to the background. Sidekiq is great for this:

# Gemfile
gem 'sidekiq'

# app/jobs/heavy_lifting_job.rb
class HeavyLiftingJob < ApplicationJob
  queue_as :default

  def perform(*args)
    # Do something time consuming here
  end
end

# app/controllers/api/v1/users_controller.rb
class Api::V1::UsersController < ApplicationController
  def create
    user = User.new(user_params)
    if user.save
      HeavyLiftingJob.perform_later(user.id)
      render json: user, status: :created
    else
      render json: user.errors, status: :unprocessable_entity
    end
  end
end

This setup allows you to respond quickly to API requests while handling time-consuming tasks in the background.

Building API-only Rails applications opens up a world of possibilities. Whether you’re supporting a mobile app or a JavaScript-heavy frontend, Rails has got you covered. With these tools and techniques, you’ll be building robust, performant APIs in no time. Remember, the key is to keep things simple, test thoroughly, and always be thinking about your API consumers. Happy coding!