ruby rails api rest json serialization

RESTful API design with Rails

Sarah Mitchell Feb 2026

4 tabs

module Api
  module V1
    class UsersController < ApplicationController
      before_action :authenticate_user!, except: [:index, :show]
      before_action :set_user, only: [:show, :update, :destroy]

      # GET /api/v1/users
      def index
        @users = User.page(params[:page]).per(params[:per_page] || 20)

        render json: {
          users: @users.map { |user| UserSerializer.new(user).as_json },
          meta: pagination_meta(@users)
        }
      end

      # GET /api/v1/users/:id
      def show
        render json: UserSerializer.new(@user), status: :ok
      end

      # POST /api/v1/users
      def create
        @user = User.new(user_params)

        if @user.save
          render json: UserSerializer.new(@user), status: :created
        else
          render json: { errors: @user.errors.full_messages }, status: :unprocessable_entity
        end
      end

      # PATCH/PUT /api/v1/users/:id
      def update
        if @user.update(user_params)
          render json: UserSerializer.new(@user), status: :ok
        else
          render json: { errors: @user.errors.full_messages }, status: :unprocessable_entity
        end
      end

      # DELETE /api/v1/users/:id
      def destroy
        @user.destroy
        head :no_content
      end

      private

      def set_user
        @user = User.find(params[:id])
      rescue ActiveRecord::RecordNotFound
        render json: { error: 'User not found' }, status: :not_found
      end

      def user_params
        params.require(:user).permit(:name, :email, :bio)
      end

      def pagination_meta(collection)
        {
          current_page: collection.current_page,
          total_pages: collection.total_pages,
          total_count: collection.total_count,
          per_page: collection.limit_value
        }
      end
    end
  end
end

# app/serializers/user_serializer.rb
class UserSerializer
  def initialize(user)
    @user = user
  end

  def as_json
    {
      id: @user.id,
      name: @user.name,
      email: @user.email,
      bio: @user.bio,
      avatar_url: @user.avatar.url,
      created_at: @user.created_at.iso8601,
      links: {
        self: "/api/v1/users/#{@user.id}",
        posts: "/api/v1/users/#{@user.id}/posts"
      }
    }
  end
end

# With Active Model Serializers gem
class UserSerializer < ActiveModel::Serializer
  attributes :id, :name, :email, :bio, :created_at

  has_many :posts
  belongs_to :company

  def created_at
    object.created_at.iso8601
  end

  # Conditional attributes
  attribute :email, if: :show_email?

  def show_email?
    scope.admin? || scope == object
  end
end

# Using Jbuilder
# app/views/api/v1/users/show.json.jbuilder
json.user do
  json.id @user.id
  json.name @user.name
  json.email @user.email

  json.posts @user.posts do |post|
    json.id post.id
    json.title post.title
    json.url api_v1_post_url(post)
  end
end

# app/controllers/concerns/api/error_handling.rb
module Api::ErrorHandling
  extend ActiveSupport::Concern

  included do
    rescue_from ActiveRecord::RecordNotFound, with: :not_found
    rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
    rescue_from ActionController::ParameterMissing, with: :bad_request
    rescue_from StandardError, with: :internal_server_error
  end

  private

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

  def unprocessable_entity(exception)
    render json: {
      error: 'Validation failed',
      details: exception.record.errors.full_messages
    }, status: :unprocessable_entity
  end

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

  def internal_server_error(exception)
    Rails.logger.error(exception.full_message)

    render json: {
      error: 'Internal server error'
    }, status: :internal_server_error
  end
end

# app/controllers/concerns/api/filterable.rb
module Api::Filterable
  extend ActiveSupport::Concern

  def apply_filters(scope)
    filter_params.each do |key, value|
      scope = scope.public_send(key, value) if value.present?
    end
    scope
  end

  def filter_params
    params.slice(:status, :created_after, :created_before, :search)
  end
end

# Usage in controller
class Api::V1::PostsController < Api::V1::BaseController
  include Api::ErrorHandling
  include Api::Filterable

  def index
    @posts = apply_filters(Post.all)
    render json: @posts
  end
end

Rails.application.routes.draw do
  namespace :api do
    namespace :v1 do
      resources :users do
        resources :posts, only: [:index, :create]
        member do
          post :follow
          delete :unfollow
        end
        collection do
          get :search
        end
      end

      resources :posts do
        resources :comments, only: [:index, :create, :destroy]
        member do
          post :publish
          post :like
        end
      end

      # Custom routes
      post 'auth/login', to: 'authentication#create'
      delete 'auth/logout', to: 'authentication#destroy'
      get 'me', to: 'users#current'

      # Health check
      get 'health', to: 'health#show'
    end

    # API v2
    namespace :v2 do
      resources :users, only: [:index, :show]
    end
  end

  # Default to API v1
  namespace :api, defaults: { format: :json } do
    # routes
  end
end

4 files · ruby Explain with highlit

Rails conventions support RESTful API development. I use resourceful routing for standard CRUD operations. Controllers inherit from ActionController::API for API-only apps. JSON serialization with Jbuilder or Active Model Serializers structures responses. Versioning uses namespaces—/api/v1/users. Authentication with JWT tokens or OAuth. Pagination with kaminari or pagy gems. Rate limiting protects endpoints. CORS configuration allows cross-origin requests. Error handling returns appropriate HTTP status codes. API documentation with rswag or Swagger. Filtering, sorting, and searching enhance usability. Proper REST design creates intuitive, maintainable APIs. Following conventions reduces decisions and improves consistency.