Skip to content
Learni
View all tutorials
Backend

How to Build a RESTful API with Ruby on Rails in 2026

18 minINTERMEDIATE
APIRubyRails
Lire en français

Introduction

Ruby on Rails remains a leading framework in 2026 for building fast and maintainable RESTful APIs. Its convention over configuration approach lets you deliver features in hours instead of days. This intermediate tutorial guides you through creating an articles management API with token authentication, validations, and JSON serialization. You'll learn how to structure a Rails API-only project, use Active Model Serializers, and write robust tests with RSpec. Each step includes complete, executable code.

Prerequisites

  • Ruby 3.3+ and Rails 8.0+
  • Basic knowledge of Ruby and REST
  • PostgreSQL installed
  • API testing tool (Postman or curl)

Initialize the API Project

terminal
rails new blog_api --api -d postgresql
cd blog_api
bundle install
rails db:create

The --api flag generates a lightweight structure without views. PostgreSQL is used for production. The db:create command prepares the database immediately.

API Configuration

We will now add Active Model Serializers and configure CORS to allow requests from the frontend.

Add Required Gems

Gemfile
gem 'active_model_serializers', '~> 0.10.14'
gem 'rack-cors'
gem 'bcrypt'
group :development, :test do
  gem 'rspec-rails'
end

Active Model Serializers handles clean JSON serialization. rack-cors enables cross-origin requests. bcrypt is required for token hashing.

Create the Article Model

app/models/article.rb
class Article < ApplicationRecord
  validates :title, :content, presence: true
  validates :title, length: { minimum: 3, maximum: 100 }
end

The model includes strict validations. These rules are automatically applied before any database save.

Generate the API Controller

app/controllers/api/v1/articles_controller.rb
module Api
  module V1
    class ArticlesController < ApplicationController
      def index
        articles = Article.all
        render json: articles, each_serializer: ArticleSerializer
      end

      def create
        article = Article.new(article_params)
        if article.save
          render json: article, serializer: ArticleSerializer, status: :created
        else
          render json: { errors: article.errors }, status: :unprocessable_entity
        end
      end

      private

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

The controller follows REST conventions. Validation errors are returned with the correct HTTP 422 status code.

Define API Routes

config/routes.rb
Rails.application.routes.draw do
  namespace :api do
    namespace :v1 do
      resources :articles, only: [:index, :create, :show]
    end
  end
end

The v1 namespace enables clean API versioning. Only the necessary actions are exposed.

Create the Serializer

app/serializers/article_serializer.rb
class ArticleSerializer < ActiveModel::Serializer
  attributes :id, :title, :content, :created_at
end

The serializer controls exactly which fields are exposed and prevents sensitive data leaks.

Best Practices

  • Always version your API using namespaces
  • Use serializers to control exposed data
  • Validate parameters with strong parameters
  • Write RSpec tests for every endpoint
  • Enable request logging in production

Common Errors

  • Forgetting to configure CORS (cross-origin errors)
  • Exposing all model attributes without a serializer
  • Not handling validation errors on the client side
  • Using unversioned routes

Going Further

Explore our advanced Ruby on Rails courses at example.com to master JWT authentication, Sidekiq jobs, and Kubernetes deployments.