DEV Community: Rodrigo Barreto

Stop Writing Setup READMEs: Add Nix to Your Project in 5 Minutes

Rodrigo Barreto — Sat, 14 Feb 2026 22:54:24 +0000

You have a Laravel API and a React frontend. Add one file and your team never fights dependency versions again.

Note: Ignore the quality of the PHP and React code, this post is focused on Nix and creating a simple environment for your development team.

How This Started

A friend of mine works with Symfony for a local government office. His team is growing fast, they went from 10 to 73 developers in a few months, and onboarding has become a nightmare. Every new hire spends their first day fighting PHP versions, MySQL configs, and missing extensions.

He uses Docker for development and it works fine. But he was curious if there was something lighter for local dev environments, especially for smaller projects or quick onboarding, without having to maintain Dockerfiles and docker-compose configs.

He called me one evening, "do you have 5 minutes?" We caught up, had some good laughs, but at the end of the call I suggested he look at Nix.

Nix is a package manager that guarantees reproducibility. You declare what your project needs in a single file, commit it, and anyone who clones your repo gets the exact same environment, same PHP, same Node, same MySQL, same everything. No containers, no VMs. Just your terminal with the right tools available. And it works with any language or framework, Python, Ruby, Go, you name it.

# Outside nix develop
$ php --version    # whatever your system has (or nothing)

# Inside nix develop
$ php --version    # PHP 8.3.x, exactly what the file says
$ node --version   # v22.x.x
$ mysql --version  # mysql Ver 8.4.x

$ exit             # back to normal, nothing changed

I told him I'd write a post showing exactly how to do it. So here we are. I'm using Laravel for this tutorial, but everything you'll see here applies to any framework.

Installing Nix

Nix runs on macOS, Linux, and WSL2. The recommended installer is from Determinate Systems, it's simpler than the official one and enables Flakes by default:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

Restart your terminal after installing, then verify:

nix --version
# nix (Determinate Nix) 2.33.x

nix flake --help
# Should show flake commands

If nix flake --help fails, add experimental-features = nix-command flakes to ~/.config/nix/nix.conf.

WSL2 users: Keep your projects inside the Linux filesystem (~/projects/), not /mnt/c/. Performance is much better.

That's it. One install, and you're ready for any Nix-managed project, forever.

The Sample Project

For this post I created a simple backend with a product CRUD in Laravel and a React frontend that lists those products. The code was generated with AI, ignore it, our focus is Nix.

You can find the full source code here: github.com/rodrigonbarreto/nix_blog_post

The structure looks like this:

workspace/
├── product-api/          ← Laravel API (PHP + MySQL)
├── product-frontend/     ← React list (Node)

Both projects work fine with my local PHP 8.3, Node, and MySQL. The question is: how do I make sure the next person who clones this doesn't spend half a day setting things up?

The Problem

Your project README probably looks something like this:

## Setup
1. Install PHP 8.3
2. Install Composer
3. Install Node 22
4. Install MySQL
5. Copy .env.example to .env
6. Run composer install
7. Run npm install
8. Create the database
9. Run migrations
10. Pray it works

Every new developer spends half a day on this. Someone has PHP 8.1, someone else has MySQL 5.7, and the intern can't compile the pdo_mysql extension.

Nix replaces all of that with one command: nix develop.

The Solution: One File

We add a single file, flake.nix, next to our projects:

workspace/
├── product-api/
├── product-frontend/
└── flake.nix              ← this is all we add

Here's the file:

{
  description = "Dev environment, PHP, Node, MySQL";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};

        php = pkgs.php83.buildEnv {
          # All extensions Laravel needs out of the box
          extensions = { all, ... }: with all; [
            mbstring
            iconv
            pdo_mysql
            mysqlnd
            openssl
            tokenizer
            xmlwriter
            xmlreader
            ctype
            fileinfo
            bcmath
            curl
            dom
            filter
            pdo
            session
            simplexml
            zip
          ];
        };

      in
      {
        devShells.default = pkgs.mkShell {
          buildInputs = [
            php
            php.packages.composer

            pkgs.nodejs_22
            pkgs.mariadb

            pkgs.git
            pkgs.curl
            pkgs.unzip
          ];

          shellHook = ''
            # Prevent tools like Laravel Herd from hijacking PHP config
            unset PHP_INI_SCAN_DIR
            unset PHPRC

            export MYSQL_HOME="$PWD/.nix-mysql"
            export MYSQL_DATADIR="$MYSQL_HOME/data"
            export MYSQL_UNIX_PORT="$MYSQL_HOME/mysql.sock"
            export MYSQL_TCP_PORT="3307"

            if [ ! -d "$MYSQL_DATADIR" ]; then
              echo "Initializing MySQL..."
              mkdir -p "$MYSQL_HOME"
              mysql_install_db --datadir="$MYSQL_DATADIR" --auth-root-authentication-method=normal > /dev/null 2>&1
            fi

            echo ""
            echo "=========================================="
            echo "  Dev Environment Ready"
            echo "=========================================="
            echo "  PHP:    $(php -r 'echo PHP_VERSION;')"
            echo "  Node:   $(node --version)"
            echo "  MySQL:  port $MYSQL_TCP_PORT"
            echo "=========================================="
            echo ""
            echo "  Start MySQL:"
            echo "    mysqld --datadir=\$MYSQL_DATADIR --socket=\$MYSQL_UNIX_PORT --port=\$MYSQL_TCP_PORT &"
            echo ""
          '';
        };
      }
    );
}

That's it. One file.

What's Happening Here?

flake.nix
│
├── inputs          → where packages come from (pinned to nixos-24.11)
│
└── outputs
    └── devShell
        ├── buildInputs   → packages: PHP, Node, MySQL, etc.
        └── shellHook     → bash that runs on entry (sets up local MySQL)

A few things worth noting:

nixos-24.11 pins the package versions. Everyone with this file gets the same PHP, same Node, same MySQL. Always.
php83.buildEnv builds PHP with the exact extensions your project needs. The base PHP in Nix is minimal, you declare what you need explicitly.
unset PHP_INI_SCAN_DIR prevents tools like Laravel Herd from injecting their own PHP config and overriding the Nix extensions.
mariadb is used instead of MySQL because it's easier to manage locally with Nix and is fully MySQL-compatible. Your Laravel app won't notice the difference.
Port 3307 avoids conflicts if you already have MySQL running on 3306.
shellHook initializes a MySQL data directory inside the project. Nothing touches your system.

Let's Use It

Enter the shell

cd workspace
nix develop

First time takes a few minutes (downloads packages). After that, it's instant.

You'll see:

==========================================
  Dev Environment Ready
==========================================
  PHP:    8.3.11
  Node:   v22.9.0
  MySQL:  port 3307
==========================================

Everything from this point runs inside nix develop.

Start MySQL

mysqld --datadir=$MYSQL_DATADIR --socket=$MYSQL_UNIX_PORT --port=$MYSQL_TCP_PORT &

Wait a couple of seconds, then create the database:

mysql -u root --socket=$MYSQL_UNIX_PORT -e "CREATE DATABASE IF NOT EXISTS product_api;"

Run the backend

Update product-api/.env to use port 3307:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3307
DB_DATABASE=product_api
DB_USERNAME=root
DB_PASSWORD=

Then:

cd product-api
composer install
php artisan migrate
php artisan db:seed
php artisan serve

If you previously ran composer install with a different PHP, delete vendor/ first: rm -rf vendor && composer install.

Run the frontend

Open a new terminal, same directory:

cd workspace
nix develop
cd product-frontend
npm install
npm run dev

Open http://localhost:5173, your product list is running, powered entirely by Nix.

The Day-to-Day

Every time you work on the project:

cd workspace
nix develop

# Start MySQL
mysqld --datadir=$MYSQL_DATADIR --socket=$MYSQL_UNIX_PORT --port=$MYSQL_TCP_PORT &

# Terminal 1: backend
cd product-api && php artisan serve

# Terminal 2 (new terminal, nix develop first): frontend
cd product-frontend && npm run dev

Everything you're used to works normally:

php artisan tinker
php artisan migrate
php artisan make:model
composer require <package>
npm install <package>
mysql -u root --socket=$MYSQL_UNIX_PORT product_api

What to Commit

git add flake.nix flake.lock
git commit -m "Add Nix dev environment"

Add to .gitignore:

.nix-mysql/
.direnv/
result

The flake.lock pins exact versions, treat it like composer.lock.

When a New Developer Joins

Before Nix:

1. Read the README
2. Install PHP 8.3 (they install 8.1)
3. Install Node (wrong version)
4. Install MySQL (can't connect)
5. Spend 4 hours debugging
6. Finally get it running

After Nix:

# One-time: install Nix
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

# Every time:
git clone https://github.com/rodrigonbarreto/nix_blog_post.git
cd nix_blog_post
nix develop
# Same PHP, same Node, same MySQL. Done.

Customizing

Need Redis? Add it:

buildInputs = with pkgs; [
  # ... existing packages
  redis
];

Need more PHP extensions? Add them to the buildEnv block in flake.nix:

php = pkgs.php83.buildEnv {
  extensions = { all, ... }: with all; [
    # ... existing extensions
    redis
    imagick
    gd
  ];
};

Run nix develop again and the new packages are there.

Troubleshooting

"experimental feature 'flakes' is disabled": Add experimental-features = nix-command flakes to ~/.config/nix/nix.conf.

"The iconv OR mbstring extension is required": Add missing extensions to the buildEnv block in flake.nix, then exit and re-enter nix develop. Also make sure the shellHook includes unset PHP_INI_SCAN_DIR, tools like Laravel Herd can hijack the PHP config and hide Nix extensions.

MySQL won't start: Check if port 3307 is in use. Look at the error output from mysqld.

"command not found" outside the shell: Expected. Everything only exists inside nix develop.

Want auto-activation? Install direnv, create .envrc with use flake, run direnv allow. The environment activates automatically when you cd into the project.

Next Steps

If you found this useful, I'm planning a Part 2 where we set up the entire stack, MySQL, Laravel, and React, to start with a single command. No more opening 3 terminals. Just:

nix develop
start

And everything is running. Drop a comment or a like if you'd want to see that.

In the meantime, some useful links to go deeper:

direnv, auto-activate the environment on cd
devenv.sh, higher-level Nix tool with built-in services
Nix language tutorial, understand what's inside the flake

One file. One command. Every machine. That's Nix.

Source code: github.com/rodrigonbarreto/nix_blog_post

Switching APM providers without the headache

Rodrigo Barreto — Sun, 21 Dec 2025 22:15:18 +0000

The context

Last week a friend called me asking which APM/error tracking tool I use. He had his current provider scattered all over the project and wanted to switch to something different.

I've been using AppSignal or New Relic since 2019 and really like them. In his case, I recommended AppSignal for reasons we can discuss in another post to keep this one short.

But the conversation went further: "What if a year from now I want to switch again? Will I have to find & replace across the entire project?"

I suggested he create an adapter. He said he'd never implemented one in practice.

Well, we built it together that afternoon. And that's exactly what I'm going to share here.

Before: provider coupled throughout the code

His project looked like this:

# app/controllers/orders_controller.rb
class OrdersController < ApplicationController
  def create
    @order = Order.new(order_params)

    if @order.save
      redirect_to @order
    else
      ProviderX.capture_message("Order creation failed", extra: { errors: @order.errors.full_messages })
      render :new
    end
  end
end

# app/services/payment_service.rb
class PaymentService
  def process(order)
    gateway.charge(order.total)
  rescue PaymentError => e
    ProviderX.capture_exception(e, extra: { order_id: order.id })
    raise
  end
end

# app/jobs/sync_inventory_job.rb
class SyncInventoryJob < ApplicationJob
  def perform
    InventorySync.run!
  rescue => e
    ProviderX.capture_exception(e, tags: { job: "inventory_sync" })
    raise
  end
end

The problem is clear: ProviderX scattered across dozens of files. To switch tools, he would have to:

Find all occurrences
Understand the context of each one
Adapt to the new API (which is different)
Hope he didn't miss any

I've been there. It's not fun.

About over-engineering

Before showing the solution, I need to make something clear: I'm not a fan of implementing design patterns for everything. I like to keep things simple.

But this is one of those cases where it makes sense:

It's an external service that can change
The call is spread across dozens of files
Each provider's API is different
The cost of creating the abstraction is low

When these factors align, it's worth the investment.

The solution: Adapter Pattern

The idea is to create a layer between the application and the tracking tool. The application only knows this layer. The layer knows the specific tool.

Structure

app/
└── services/
    └── error_tracking/
        ├── base_adapter.rb
        ├── appsignal_adapter.rb
        ├── null_adapter.rb
        └── tracker.rb

1. Base contract

First, we define the contract that all adapters must follow:

# app/services/error_tracking/base_adapter.rb
# frozen_string_literal: true

module ErrorTracking
  # Abstract base class for error tracking adapters
  # All adapters must implement these methods
  class BaseAdapter
    # Capture and report an exception
    # @param exception [Exception] the exception to capture
    # @param extra [Hash] additional context data
    # @param level [Symbol] severity level (:error, :warning, :info)
    # @param tags [Hash] tags for categorization
    def capture_exception(exception, extra: {}, level: :error, tags: {})
      raise NotImplementedError, "#{self.class} must implement #capture_exception"
    end

    # Capture and report a message
    # @param message [String] the message to capture
    # @param extra [Hash] additional context data
    # @param level [Symbol] severity level (:error, :warning, :info)
    # @param tags [Hash] tags for categorization
    def capture_message(message, extra: {}, level: :info, tags: {})
      raise NotImplementedError, "#{self.class} must implement #capture_message"
    end

    # Set user context for subsequent captures
    # @param user_data [Hash] user information (id, email, username, type, etc.)
    def set_user(user_data)
      raise NotImplementedError, "#{self.class} must implement #set_user"
    end

    # Set request context for subsequent captures
    # @param request_data [Hash] request information (method, path, url, ip, user_agent, params, headers)
    def set_request(request_data)
      raise NotImplementedError, "#{self.class} must implement #set_request"
    end

    # Set custom context data
    # @param context_data [Hash] custom context information
    def set_context(context_data)
      raise NotImplementedError, "#{self.class} must implement #set_context"
    end

    # Add custom context/scope
    # @yield [scope] block to configure scope
    def configure_scope(&)
      raise NotImplementedError, "#{self.class} must implement #configure_scope"
    end

    # Add breadcrumb for debugging trail
    # @param message [String] breadcrumb message
    # @param category [String] category for grouping
    # @param data [Hash] additional data
    def add_breadcrumb(message, category: "custom", data: {})
      raise NotImplementedError, "#{self.class} must implement #add_breadcrumb"
    end

    # Get trace propagation meta for distributed tracing (HTML views)
    # @return [String] HTML meta tags for tracing
    def get_trace_propagation_meta
      raise NotImplementedError, "#{self.class} must implement #get_trace_propagation_meta"
    end

    # Check if the adapter is enabled/configured
    # @return [Boolean]
    def enabled?
      raise NotImplementedError, "#{self.class} must implement #enabled?"
    end
  end
end

2. AppSignal Adapter

The implementation I use in production:

# app/services/error_tracking/appsignal_adapter.rb
# frozen_string_literal: true

module ErrorTracking
  class AppsignalAdapter < BaseAdapter
    def capture_exception(exception, extra: {}, level: :error, tags: {})
      return unless enabled?

      Appsignal.send_error(exception) do |transaction|
        transaction.set_namespace(namespace_from_level(level))
        transaction.set_tags(tags) if tags.any?
        transaction.set_params(extra) if extra.any?
      end
    end

    def capture_message(message, extra: {}, level: :info, tags: {})
      return unless enabled?

      Appsignal.send_error(StandardError.new(message)) do |transaction|
        transaction.set_namespace(namespace_from_level(level))
        transaction.set_tags(tags.merge(type: "message"))
        transaction.set_params(extra) if extra.any?
      end
    end

    def set_user(user_data)
      return unless enabled?

      Appsignal.add_tags(
        user_id: user_data[:id]&.to_s,
        user_email: user_data[:email],
        username: user_data[:username],
        user_type: user_data[:type]
      )
    end

    def set_request(request_data)
      return unless enabled?

      Appsignal.add_tags(
        request_method: request_data[:method],
        request_path: request_data[:path],
        request_url: truncate_value(request_data[:url]),
        request_ip: request_data[:ip],
        request_user_agent: truncate_value(request_data[:user_agent])
      )

      Appsignal.add_params(request_data[:params]) if request_data[:params].present?
      Appsignal.add_headers(sanitize_headers(request_data[:headers])) if request_data[:headers].present?
    end

    def set_context(context_data)
      return unless enabled?

      Appsignal.add_custom_data(context_data)
    end

    def configure_scope
      return unless enabled?

      yield(self) if block_given?
    end

    def add_breadcrumb(message, category: "custom", data: {})
      return unless enabled?

      Appsignal.add_breadcrumb(category, message, "", data)
    end

    def get_trace_propagation_meta
      ""
    end

    def enabled?
      defined?(Appsignal) && Appsignal.config&.active?
    end

    private

    def namespace_from_level(level)
      case level
      when :error then "error"
      when :warning then "warning"
      else "info"
      end
    end

    def truncate_value(value, max_length: 255)
      return nil if value.nil?

      value.to_s[0, max_length]
    end

    def sanitize_headers(headers)
      return {} if headers.nil?

      sensitive_keys = %w[authorization cookie set-cookie x-api-key api-key token]
      headers.transform_values.with_index do |(key, value), _|
        sensitive_keys.any? { |k| key.to_s.downcase.include?(k) } ? "[FILTERED]" : value
      end
    end
  end
end

3. NullAdapter

This is a detail that makes a difference day to day. In development and tests, we don't want to send errors to the real provider. The NullAdapter solves this:

# frozen_string_literal: true

module ErrorTracking
  # Null Object pattern - does nothing, useful for development/test
  class NullAdapter < BaseAdapter
    def capture_exception(exception, extra: {}, level: :error, tags: {}) # rubocop:disable Lint/UnusedMethodArgument
      log_in_development("Exception: #{exception.class} - #{exception.message}", extra, level)
      nil
    end

    def capture_message(message, extra: {}, level: :info, tags: {}) # rubocop:disable Lint/UnusedMethodArgument
      log_in_development("Message: #{message}", extra, level)
      nil
    end

    def set_user(_user_data)
      nil
    end

    def set_request(_request_data)
      nil
    end

    def set_context(_context_data)
      nil
    end

    def configure_scope
      nil
    end

    def add_breadcrumb(_message, _category: "custom", _data: {})
      nil
    end

    def get_trace_propagation_meta
      ""
    end

    def enabled?
      false
    end

    private

    def log_in_development(message, extra, level)
      return unless Rails.env.development?

      Rails.logger.tagged("ErrorTracking") do
        Rails.logger.send(level == :error ? :error : :info, "#{message} | extra: #{extra.inspect}")
      end
    end
  end
end

4. Tracker (facade)

The Tracker centralizes the API and adds some utility methods I use a lot:

# app/services/error_tracking/tracker.rb
# frozen_string_literal: true

module ErrorTracking
  # Main facade for error tracking
  # Usage:
  #   ErrorTracking.capture_exception(e, extra: { user_id: 123 })
  #   ErrorTracking.capture_message("Something happened", level: :warning)
  #
  # Configure in initializer:
  #   ErrorTracking.configure(adapter: ErrorTracking::AppsignalAdapter.new)
  class Tracker
    class << self
      attr_writer :adapter

      def adapter
        @adapter ||= NullAdapter.new
      end

      # Delegate all methods to the adapter
      delegate :capture_exception,
               :capture_message,
               :set_user,
               :set_request,
               :set_context,
               :configure_scope,
               :add_breadcrumb,
               :get_trace_propagation_meta,
               :enabled?,
               to: :adapter

      # Convenience method to capture exception with context and re-raise
      def capture_and_reraise(exception, extra: {}, level: :error, tags: {})
        capture_exception(exception, extra: extra, level: level, tags: tags)
        raise exception
      end

      # Safe capture that never raises (for use in rescue blocks)
      def safe_capture_exception(exception, extra: {}, level: :error, tags: {})
        capture_exception(exception, extra: extra, level: level, tags: tags)
      rescue StandardError => e
        Rails.logger.error("ErrorTracking failed to capture: #{e.message}")
        nil
      end

      # Safe message capture that never raises
      def safe_capture_message(message, extra: {}, level: :info, tags: {})
        capture_message(message, extra: extra, level: level, tags: tags)
      rescue StandardError => e
        Rails.logger.error("ErrorTracking failed to capture message: #{e.message}")
        nil
      end
    end
  end
end

5. Main module

# app/services/error_tracking.rb
# frozen_string_literal: true

module ErrorTracking
  class << self
    delegate :capture_exception,
             :capture_message,
             :set_user,
             :set_request,
             :set_context,
             :configure_scope,
             :add_breadcrumb,
             :get_trace_propagation_meta,
             :enabled?,
             :safe_capture_exception,
             :safe_capture_message,
             :capture_and_reraise,
             to: Tracker

    def configure(adapter:)
      Tracker.adapter = adapter
    end
  end
end

6. Configuration

For those using AppSignal, add the gem:

# Gemfile
gem "appsignal"

# config/initializers/error_tracking.rb
# frozen_string_literal: true

Rails.application.config.after_initialize do
  adapter = if Rails.env.in?(%w[development test])
              ErrorTracking::NullAdapter.new
            else
              ErrorTracking::AppsignalAdapter.new
            end

  ErrorTracking.configure(adapter: adapter)
end

In the future, if you want to migrate to New Relic, Datadog, Bugsnag or any other service, just create a new adapter and change this line.

After: decoupled code

# app/controllers/orders_controller.rb
class OrdersController < ApplicationController
  def create
    @order = Order.new(order_params)

    if @order.save
      redirect_to @order
    else
      ErrorTracking.capture_message(
        "Order creation failed",
        extra: { errors: @order.errors.full_messages },
        level: :warning
      )
      render :new
    end
  end
end

# app/services/payment_service.rb
class PaymentService
  def process(order)
    ErrorTracking.add_breadcrumb("Starting payment", category: "payment")

    gateway.charge(order.total)
  rescue PaymentError => e
    ErrorTracking.capture_and_reraise(e, extra: { order_id: order.id })
  end
end

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  before_action :set_error_tracking_context

  private

  def set_error_tracking_context
    ErrorTracking.set_request(
      method: request.method,
      path: request.path,
      url: request.url,
      ip: request.remote_ip,
      user_agent: request.user_agent
    )

    return unless current_user

    ErrorTracking.set_user(
      id: current_user.id,
      email: current_user.email,
      username: current_user.name,
      type: current_user.class.name
    )
  end
end

What we gained

Before	After
Switching tools = changing dozens of files	Switching tools = create adapter + change 1 line
Tests depend on SDK	Tests use NullAdapter
No logs in development	NullAdapter logs locally
Different API for each tool	Single consistent API

When to use this pattern?

I apply it when:

It's an external service that can change
The call is spread across multiple files
The service API is complex or different between providers

I don't apply it when:

It's used in a single place
The service will probably never change
The complexity doesn't justify it

Conclusion

By the end of that afternoon, my friend's project was ready for the future. If a year from now he wants to go back to the previous provider, switch to Datadog, or anything else, he just needs to create the adapter and change one line.

The code I shared here is a draft of the real code, but the adapters work perfectly in production. The controllers and usage examples are fictional to maintain project integrity.

Trocando de APM sem dor de cabeça

Rodrigo Barreto — Sun, 21 Dec 2025 22:12:54 +0000

O contexto

Semana passada um amigo me ligou perguntando qual ferramenta de APM/error tracking eu usava. Ele estava com o provedor atual espalhado por todo o projeto e queria trocar para algo diferente.

Eu uso AppSignal ou New Relic desde 2017 e gosto bastante. No caso dele aconselhei usar AppSignal por fatores que podemos falar em outro post para não ficar longo.

Mas a conversa foi além: "E se daqui a um ano eu quiser trocar de novo? Vou ter que fazer find & replace no projeto inteiro?"

Sugeri que ele criasse um adapter. Ele disse que nunca tinha implementado isso na prática.

Bom, implementamos juntos naquela tarde. E é exatamente isso que vou compartilhar aqui.

Antes: provedor acoplado em todo o código

O projeto dele estava assim:

# app/controllers/orders_controller.rb
class OrdersController < ApplicationController
  def create
    @order = Order.new(order_params)

    if @order.save
      redirect_to @order
    else
      ProviderX.capture_message("Order creation failed", extra: { errors: @order.errors.full_messages })
      render :new
    end
  end
end

# app/services/payment_service.rb
class PaymentService
  def process(order)
    gateway.charge(order.total)
  rescue PaymentError => e
    ProviderX.capture_exception(e, extra: { order_id: order.id })
    raise
  end
end

# app/jobs/sync_inventory_job.rb
class SyncInventoryJob < ApplicationJob
  def perform
    InventorySync.run!
  rescue => e
    ProviderX.capture_exception(e, tags: { job: "inventory_sync" })
    raise
  end
end

O problema é claro: ProviderX espalhado em dezenas de arquivos. Para trocar de ferramenta, ele teria que:

Buscar todas as ocorrências
Entender o contexto de cada uma
Adaptar para a nova API (que é diferente)
Torcer para não ter esquecido nenhuma

Já passei por isso. Não é divertido.

Sobre over-engineering

Antes de mostrar a solução, preciso deixar algo claro: não sou fã de implementar design patterns para tudo. Gosto de manter as coisas simples.

Mas esse é um daqueles casos onde faz sentido:

É um serviço externo que pode mudar
A chamada está espalhada por dezenas de arquivos
A API de cada provedor é diferente
O custo de criar a abstração é baixo

Quando esses fatores se alinham, vale o investimento.

A solução: Adapter Pattern

A ideia é criar uma camada entre a aplicação e a ferramenta de tracking. A aplicação só conhece essa camada. A camada conhece a ferramenta específica.

Estrutura

app/
└── services/
    └── error_tracking/
        ├── base_adapter.rb
        ├── appsignal_adapter.rb
        ├── null_adapter.rb
        └── tracker.rb

1. Contrato base

Primeiro, definimos o contrato que todos os adapters devem seguir:

# app/services/error_tracking/base_adapter.rb
# frozen_string_literal: true

module ErrorTracking
  # Abstract base class for error tracking adapters
  # All adapters must implement these methods
  class BaseAdapter
    # Capture and report an exception
    # @param exception [Exception] the exception to capture
    # @param extra [Hash] additional context data
    # @param level [Symbol] severity level (:error, :warning, :info)
    # @param tags [Hash] tags for categorization
    def capture_exception(exception, extra: {}, level: :error, tags: {})
      raise NotImplementedError, "#{self.class} must implement #capture_exception"
    end

    # Capture and report a message
    # @param message [String] the message to capture
    # @param extra [Hash] additional context data
    # @param level [Symbol] severity level (:error, :warning, :info)
    # @param tags [Hash] tags for categorization
    def capture_message(message, extra: {}, level: :info, tags: {})
      raise NotImplementedError, "#{self.class} must implement #capture_message"
    end

    # Set user context for subsequent captures
    # @param user_data [Hash] user information (id, email, username, type, etc.)
    def set_user(user_data)
      raise NotImplementedError, "#{self.class} must implement #set_user"
    end

    # Set request context for subsequent captures
    # @param request_data [Hash] request information (method, path, url, ip, user_agent, params, headers)
    def set_request(request_data)
      raise NotImplementedError, "#{self.class} must implement #set_request"
    end

    # Set custom context data
    # @param context_data [Hash] custom context information
    def set_context(context_data)
      raise NotImplementedError, "#{self.class} must implement #set_context"
    end

    # Add custom context/scope
    # @yield [scope] block to configure scope
    def configure_scope(&)
      raise NotImplementedError, "#{self.class} must implement #configure_scope"
    end

    # Add breadcrumb for debugging trail
    # @param message [String] breadcrumb message
    # @param category [String] category for grouping
    # @param data [Hash] additional data
    def add_breadcrumb(message, category: "custom", data: {})
      raise NotImplementedError, "#{self.class} must implement #add_breadcrumb"
    end

    # Get trace propagation meta for distributed tracing (HTML views)
    # @return [String] HTML meta tags for tracing
    def get_trace_propagation_meta
      raise NotImplementedError, "#{self.class} must implement #get_trace_propagation_meta"
    end

    # Check if the adapter is enabled/configured
    # @return [Boolean]
    def enabled?
      raise NotImplementedError, "#{self.class} must implement #enabled?"
    end
  end
end

2. Adapter do AppSignal

A implementação que uso em produção:

# app/services/error_tracking/appsignal_adapter.rb
# frozen_string_literal: true

module ErrorTracking
  class AppsignalAdapter < BaseAdapter
    def capture_exception(exception, extra: {}, level: :error, tags: {})
      return unless enabled?

      Appsignal.send_error(exception) do |transaction|
        transaction.set_namespace(namespace_from_level(level))
        transaction.set_tags(tags) if tags.any?
        transaction.set_params(extra) if extra.any?
      end
    end

    def capture_message(message, extra: {}, level: :info, tags: {})
      return unless enabled?

      Appsignal.send_error(StandardError.new(message)) do |transaction|
        transaction.set_namespace(namespace_from_level(level))
        transaction.set_tags(tags.merge(type: "message"))
        transaction.set_params(extra) if extra.any?
      end
    end

    def set_user(user_data)
      return unless enabled?

      Appsignal.add_tags(
        user_id: user_data[:id]&.to_s,
        user_email: user_data[:email],
        username: user_data[:username],
        user_type: user_data[:type]
      )
    end

    def set_request(request_data)
      return unless enabled?

      Appsignal.add_tags(
        request_method: request_data[:method],
        request_path: request_data[:path],
        request_url: truncate_value(request_data[:url]),
        request_ip: request_data[:ip],
        request_user_agent: truncate_value(request_data[:user_agent])
      )

      Appsignal.add_params(request_data[:params]) if request_data[:params].present?
      Appsignal.add_headers(sanitize_headers(request_data[:headers])) if request_data[:headers].present?
    end

    def set_context(context_data)
      return unless enabled?

      Appsignal.add_custom_data(context_data)
    end

    def configure_scope
      return unless enabled?

      yield(self) if block_given?
    end

    def add_breadcrumb(message, category: "custom", data: {})
      return unless enabled?

      Appsignal.add_breadcrumb(category, message, "", data)
    end

    def get_trace_propagation_meta
      ""
    end

    def enabled?
      defined?(Appsignal) && Appsignal.config&.active?
    end

    private

    def namespace_from_level(level)
      case level
      when :error then "error"
      when :warning then "warning"
      else "info"
      end
    end

    def truncate_value(value, max_length: 255)
      return nil if value.nil?

      value.to_s[0, max_length]
    end

    def sanitize_headers(headers)
      return {} if headers.nil?

      sensitive_keys = %w[authorization cookie set-cookie x-api-key api-key token]
      headers.transform_values.with_index do |(key, value), _|
        sensitive_keys.any? { |k| key.to_s.downcase.include?(k) } ? "[FILTERED]" : value
      end
    end
  end
end

3. NullAdapter

Esse é um detalhe que faz diferença no dia a dia. Em desenvolvimento e testes, não queremos enviar erros para o provedor real. O NullAdapter resolve isso:

# frozen_string_literal: true

module ErrorTracking
  # Null Object pattern - does nothing, useful for development/test
  class NullAdapter < BaseAdapter
    def capture_exception(exception, extra: {}, level: :error, tags: {}) # rubocop:disable Lint/UnusedMethodArgument
      log_in_development("Exception: #{exception.class} - #{exception.message}", extra, level)
      nil
    end

    def capture_message(message, extra: {}, level: :info, tags: {}) # rubocop:disable Lint/UnusedMethodArgument
      log_in_development("Message: #{message}", extra, level)
      nil
    end

    def set_user(_user_data)
      nil
    end

    def set_request(_request_data)
      nil
    end

    def set_context(_context_data)
      nil
    end

    def configure_scope
      nil
    end

    def add_breadcrumb(_message, _category: "custom", _data: {})
      nil
    end

    def get_trace_propagation_meta
      ""
    end

    def enabled?
      false
    end

    private

    def log_in_development(message, extra, level)
      return unless Rails.env.development?

      Rails.logger.tagged("ErrorTracking") do
        Rails.logger.send(level == :error ? :error : :info, "#{message} | extra: #{extra.inspect}")
      end
    end
  end
end

4. Tracker (facade)

O Tracker centraliza a API e adiciona alguns métodos utilitários que uso bastante:

# app/services/error_tracking/tracker.rb
# frozen_string_literal: true

module ErrorTracking
  # Main facade for error tracking
  # Usage:
  #   ErrorTracking.capture_exception(e, extra: { user_id: 123 })
  #   ErrorTracking.capture_message("Something happened", level: :warning)
  #
  # Configure in initializer:
  #   ErrorTracking.configure(adapter: ErrorTracking::AppsignalAdapter.new)
  class Tracker
    class << self
      attr_writer :adapter

      def adapter
        @adapter ||= NullAdapter.new
      end

      # Delegate all methods to the adapter
      delegate :capture_exception,
               :capture_message,
               :set_user,
               :set_request,
               :set_context,
               :configure_scope,
               :add_breadcrumb,
               :get_trace_propagation_meta,
               :enabled?,
               to: :adapter

      # Convenience method to capture exception with context and re-raise
      def capture_and_reraise(exception, extra: {}, level: :error, tags: {})
        capture_exception(exception, extra: extra, level: level, tags: tags)
        raise exception
      end

      # Safe capture that never raises (for use in rescue blocks)
      def safe_capture_exception(exception, extra: {}, level: :error, tags: {})
        capture_exception(exception, extra: extra, level: level, tags: tags)
      rescue StandardError => e
        Rails.logger.error("ErrorTracking failed to capture: #{e.message}")
        nil
      end

      # Safe message capture that never raises
      def safe_capture_message(message, extra: {}, level: :info, tags: {})
        capture_message(message, extra: extra, level: level, tags: tags)
      rescue StandardError => e
        Rails.logger.error("ErrorTracking failed to capture message: #{e.message}")
        nil
      end
    end
  end
end

5. Módulo principal

# app/services/error_tracking.rb
# frozen_string_literal: true

module ErrorTracking
  class << self
    delegate :capture_exception,
             :capture_message,
             :set_user,
             :set_request,
             :set_context,
             :configure_scope,
             :add_breadcrumb,
             :get_trace_propagation_meta,
             :enabled?,
             :safe_capture_exception,
             :safe_capture_message,
             :capture_and_reraise,
             to: Tracker

    def configure(adapter:)
      Tracker.adapter = adapter
    end
  end
end

6. Configuração

Para quem for usar o AppSignal, adicione a gem:

# Gemfile
gem "appsignal"

# config/initializers/error_tracking.rb
# frozen_string_literal: true

# Error Tracking Configuration

Rails.application.config.after_initialize do
  adapter = if Rails.env.in?(%w[development test])
              ErrorTracking::NullAdapter.new
            else
              ErrorTracking::AppsignalAdapter.new
            end

  ErrorTracking.configure(adapter: adapter)
end

No futuro, se quiser migrar para New Relic, Datadog, Bugsnag ou qualquer outro serviço, é só criar um novo adapter e trocar essa linha.

Depois: código desacoplado

# app/controllers/orders_controller.rb
class OrdersController < ApplicationController
  def create
    @order = Order.new(order_params)

    if @order.save
      redirect_to @order
    else
      ErrorTracking.capture_message(
        "Order creation failed",
        extra: { errors: @order.errors.full_messages },
        level: :warning
      )
      render :new
    end
  end
end

# app/services/payment_service.rb
class PaymentService
  def process(order)
    ErrorTracking.add_breadcrumb("Starting payment", category: "payment")

    gateway.charge(order.total)
  rescue PaymentError => e
    ErrorTracking.capture_and_reraise(e, extra: { order_id: order.id })
  end
end

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  before_action :set_error_tracking_context

  private

  def set_error_tracking_context
    ErrorTracking.set_request(
      method: request.method,
      path: request.path,
      url: request.url,
      ip: request.remote_ip,
      user_agent: request.user_agent
    )

    return unless current_user

    ErrorTracking.set_user(
      id: current_user.id,
      email: current_user.email,
      username: current_user.name,
      type: current_user.class.name
    )
  end
end

O que ganhamos

Antes	Depois
Trocar ferramenta = alterar dezenas de arquivos	Trocar ferramenta = criar adapter + mudar 1 linha
Testes dependem do SDK	Testes usam NullAdapter
Sem logs em development	NullAdapter loga localmente
API diferente para cada ferramenta	API única e consistente

Quando usar esse pattern?

Aplico quando:

É um serviço externo que pode mudar
A chamada está espalhada por vários arquivos
A API do serviço é complexa ou diferente entre provedores

Não aplico quando:

É usado em um único lugar
O serviço provavelmente nunca vai mudar
A complexidade não justifica

Conclusão

No final daquela tarde, o projeto do meu amigo estava pronto para o futuro. Se daqui a um ano ele quiser voltar pro provedor anterior, trocar pro Datadog, ou qualquer outra coisa, é só criar o adapter e mudar uma linha.

O código que compartilhei aqui é um rascunho do código real, porém os adapters funcionam tranquilamente em produção. Os controllers e exemplos de uso são fictícios para manter a integridade do projeto.

Importação de Dados em Rails: Do Jeito Menos Indicado ao Otimizado 🚀🇧🇷

Rodrigo Barreto — Sat, 23 Aug 2025 23:11:05 +0000

Este post foi 100% criado com meus exemplos, código e experiências reais, mas formatado com ajuda de AI para melhor organização. A AI pode nos ajudar a formatar e estruturar conteúdo, mas não substitui o conhecimento e experiência prática que nós, desenvolvedores, trazemos!

📦 Código completo disponível no GitHub: https://github.com/rodrigonbarreto/event_reservation_system/tree/blog_post_import_data

Importar dados de arquivos JSON ou Excel é uma tarefa comum no dia a dia de desenvolvimento Rails, mas muita gente ainda faz isso de forma ineficiente. Hoje vou mostrar três abordagens com resultados impressionantes: em um teste local com apenas 10.000 registros, a diferença foi de ~40 segundos para ~5 segundos - uma melhoria de mais de 8x!

O que este post NÃO aborda 📝

Como ler arquivos muito grandes de forma eficiente (isso fica para outro post)
Importações por chunks/batches avançados (para não deixar o post muito extenso)
Estratégias de paralelização com Sidekiq/ActiveJob

💡 Dica de ouro: Para quem usa PostgreSQL, o livro High Performance PostgreSQL for Rails é leitura obrigatória!

Preparando Nosso Cenário 🎬

Primeiro, vamos criar dados mockados para testar nossas implementações:

# file_generator.rb (na raiz do projeto)
require 'json'
require 'faker'

base_users = [
  { name: "John Smith", email: "john@example.com", bio: "Ruby on Rails dev..." },
  { name: "Sarah Johnson", email: "sarah@example.com", bio: "Tech Lead..." },
  { name: "Mike Wilson", email: "mike@example.com", bio: "Full-stack dev..." },
  { name: "Emma Davis", email: "emma@example.com", bio: "DevOps engineer..." },
  { name: "Alex Rodriguez", email: "alex@example.com", bio: "Senior dev..." }
]

base_titles = [
  "Complete Guide to Active Record Queries",
  "Avoiding the N+1 Problem in Rails",
  "TDD with RSpec: From Basic to Advanced"
]

base_contents = [
  "In this article, we explore...",
  "Let's dive deep into...",
  "This tutorial covers..."
]

base_categories = ["Ruby on Rails", "Performance", "Database", "DevOps", "Architecture"]

posts = []

10_000.times do |i|
  user = base_users.sample
  post = {
    title: "#{base_titles.sample} ##{i}",
    content: "#{base_contents.sample} #{Faker::Lorem.paragraph(sentence_count: 5)}",
    published: [true, false].sample,
    user: user,
    categories: base_categories.sample(rand(1..3))
  }
  posts << post
end

File.write("blog_json_data_10k.json", JSON.pretty_generate(posts))

Como executar 🏃‍♂️

Gere o arquivo JSON com dados de teste:

# Na raiz do seu projeto Rails, execute:
ruby file_generator.rb

Isso vai criar um arquivo blog_json_data_10k.json com 10.000 posts mockados.

Para testar as diferentes implementações no Rails console:

# Abra o console Rails
rails console

# Para testar a implementação menos recomendada (prepare o café!)
Importer::BadImporter.import!

# Para testar a implementação razoável
Importer::BlogDataImporter.import!

# Para testar a implementação otimizada (vai voar!)
Importer::BlogDataImporterWithActiveRecordImport.import!

💡 Nota: Você pode alterar 10_000.times para gerar mais ou menos dados. Para começar, 1.000 registros já mostram bem a diferença!

A Classe JsonImporter (Auxiliar) 📄

Você deve ter notado que estamos usando Importer::JsonImporter em todos os exemplos. É uma classe auxiliar simples para ler o arquivo JSON:

# app/services/importer/json_importer.rb
module Importer
  class JsonImporter
    attr_reader :file_name, :file_path

    def initialize(file_name:)
      @file_name = file_name
      @file_path = Rails.root.join(file_name)
    end

    def import!
      unless File.exist?(@file_path)
        raise "File not found: #{@file_path}"
      end

      puts "📁 Reading JSON file: #{@file_name}"
      file_content = File.read(@file_path)
      JSON.parse(file_content)
    rescue JSON::ParserError => e
      raise "Invalid JSON format: #{e.message}"
    rescue StandardError => e
      raise "Error reading file: #{e.message}"
    end
  end
end

Esta é uma implementação básica que carrega todo o arquivo na memória. Existem maneiras MUITO mais performáticas e eficientes de ler arquivos grandes (streaming, chunking, etc.), mas isso fica para outro post! O foco aqui é na importação dos dados para o banco.

Exemplo 1: O Jeito Menos Recomendado ❌

# app/services/importer/bad_importer.rb
module Importer
  class BadImporter
    def self.import!
      start_time = Time.current

      blog_json = Importer::JsonImporter.new(file_name: "blog_json_data_10k.json").import!

      # Processa cada post individualmente
      blog_json.each do |post_data|

        # Cria usuário para cada post (verifica duplicatas toda vez!)
        user = User.find_or_create_by(email: post_data["user"]["email"]) do |u|
          u.name = post_data["user"]["name"]
          u.bio = post_data["user"]["bio"]
        end

        # Cria post
        post = Post.find_or_create_by(title: post_data["title"]) do |p|
          p.content = post_data["content"]
          p.published = post_data["published"]
          p.user = user
        end

        # Cria categorias para cada post (mais verificações!)
        post_data["categories"].each do |category_name|
          category = Category.find_or_create_by(name: category_name)

          # Cria associação
          PostCategory.find_or_create_by(post: post, category: category)
        end
      end

      elapsed_time = Time.current - start_time
      puts "Tempo total: #{elapsed_time.round(2)} segundos"
    end
  end
end

Por que esse código não é o mais recomendável? 🤔

Query explosion: Para cada post, fazemos múltiplas queries (find_or_create_by)
Sem transação: Se algo falhar no meio, você terá dados parciais no banco
Performance sofrível: No meu teste, levou 38.43 segundos para apenas 10.000 registros!
Uso desnecessário de recursos: Verifica duplicatas a cada iteração
Sem proteção contra falhas: Um erro em qualquer linha pode deixar lixo no banco

⚠️ Realidade: Já vi código assim em produção processando muitos de registros. Imagina o tempo!

Exemplo 2: O Jeito Razoável ✅

# app/services/importer/blog_data_importer.rb
module Importer
  class BlogDataImporter
    def self.import!
      start_time = Time.current

      ActiveRecord::Base.transaction do
        blog_json = Importer::JsonImporter.new(file_name: "blog_json_data_10k.json").import!

        # Extrai dados únicos ANTES de inserir
        categories = blog_json.map{ |post| post["categories"] }.flatten.uniq
        users = blog_json.map{ |post| post["user"] }.uniq { |user| user["email"] }

        # Insere categorias e usuários de uma vez só
        Category.insert_all(categories.map { |category| {name: category} })
        User.insert_all(users.map { |user| {name: user["name"], email: user["email"], bio: user["bio"]} })

        # Cria hashes de lookup (OTIMIZAÇÃO CHAVE!)
        categories_hash = Category.all.pluck(:name, :id).to_h
        users_hash = User.all.pluck(:email, :id).to_h

        # Importa posts
        blog_json.map do |post|
          result = {
            title: post["title"],
            content: post["content"],
            published: post["published"],
            user_id: users_hash[post["user"]["email"]]
          }
          post_data = Post.create!(result)

          # Cria associações post-categoria em lote
          PostCategory.insert_all(
            post["categories"].map { |category| 
              {post_id: post_data.id, category_id: categories_hash[category]} 
            }
          )
        end

      rescue ActiveRecord::RecordInvalid, StandardError => e
        error = "Error: #{e.message}"
        puts error
        Rails.logger.error error
      end

      elapsed_time = Time.current - start_time
      puts "Tempo total: #{elapsed_time.round(2)} segundos"
    end
  end
end

Por que este código é bem melhor? 👍

Usa transação: Garante atomicidade - ou importa tudo ou nada
insert_all: Reduz drasticamente o número de queries
Hashes de lookup: Transforma buscas O(n) em O(1) - genial!
Processa duplicatas uma vez só: Muito mais eficiente

A Mágica dos Hashes de Lookup 🎩

categories_hash = Category.all.pluck(:name, :id).to_h
# Resultado: {"Ruby on Rails" => 1, "Performance" => 2, ...}

Ao invés de buscar a categoria no banco para cada post (10.000 buscas!), fazemos uma query só e acessamos via hash. Isso é ouro puro para performance!

Exemplo 3: O Jeito OTIMIZADO com activerecord-import 🚀

Primeiro, adicione ao Gemfile:

gem 'activerecord-import'
# Se estiver usando PostgreSQL (como no exemplo do repositório)
gem 'pg', '~> 1.1'

💡 Nota: Este post funciona com qualquer banco de dados (SQLite, MySQL, PostgreSQL). No código de exemplo que disponibilizei no GitHub, usei PostgreSQL, mas você pode usar o banco que preferir!

Agora veja a mágica acontecer:

# app/services/importer/blog_data_importer_with_active_record_import.rb
module Importer
  class BlogDataImporterWithActiveRecordImport
    def self.import!
      start_time = Time.current

      ActiveRecord::Base.transaction do
        blog_json = Importer::JsonImporter.new(file_name: "blog_json_data_10k.json").import!

        # Prepara dados únicos
        categories = blog_json.map{ |post| post["categories"] }.flatten.uniq
        users = blog_json.map{ |post| post["user"] }.uniq { |user| user["email"] }

        # Importa categorias e usuários em batch
        category_objects = categories.map { |name| Category.new(name: name) }
        Category.import category_objects, on_duplicate_key_ignore: true, validate: false

        user_objects = users.map { |user| 
          User.new(name: user["name"], email: user["email"], bio: user["bio"]) 
        }
        User.import user_objects, on_duplicate_key_ignore: true, validate: false

        # Cria hashes de lookup
        categories_hash = Category.all.pluck(:name, :id).to_h
        users_hash = User.all.pluck(:email, :id).to_h

        # Importa posts em batches para economizar memória
        blog_json.in_groups_of(1000, false) do |post_batch|
          posts_to_import = post_batch.map do |post|
            Post.new(
              title: post["title"],
              content: post["content"],
              published: post["published"],
              user_id: users_hash[post["user"]["email"]]
            )
          end

          # Importa este batch de posts (sem validações para máxima performance!)
          Post.import posts_to_import, validate: false
        end

        # Prepara e importa associações em batches
        Post.where(title: blog_json.map { |p| p["title"] }).find_in_batches(batch_size: 1000) do |post_batch|
          post_categories = []

          post_batch.each do |post|
            post_data = blog_json.find { |p| p["title"] == post.title }
            post_data["categories"].each do |category_name|
              post_categories << PostCategory.new(
                post_id: post.id,
                category_id: categories_hash[category_name]
              )
            end
          end

          # Importa as associações deste batch (sem validações!)
          PostCategory.import post_categories, validate: false if post_categories.any?
        end

      rescue StandardError => e
        error = "Error: #{e.message}"
        puts error
        Rails.logger.error error
      end

      elapsed_time = Time.current - start_time
      puts "Tempo total: #{elapsed_time.round(2)} segundos"
    end
  end
end

Por que activerecord-import é SENSACIONAL? 🎯

SQL otimizado: Gera um único INSERT com múltiplos VALUES
Gestão de memória: Processa em batches de 1000 registros
Flexibilidade total: Validações opcionais, upserts, callbacks
Performance brutal: No meu teste: ~5 segundos!

A gem oferece opções poderosas:

on_duplicate_key_ignore: Ignora duplicatas silenciosamente
on_duplicate_key_update: Atualiza registros existentes
validate: false: Pula validações do Rails (ganho extra de performance!)
batch_size: Controla o uso de memória

Comparação de Performance Real 📊

Teste local com 10.000 registros em um Apple M3 Pro com 18GB RAM:

BadImporter: ~40 segundos 😱
BlogDataImporter: ~15 segundos 😊
BlogDataImporterWithActiveRecordImport: ~5 segundos 🚀

A versão otimizada foi 8x mais rápida que a menos recomendada!

⚠️ Importante sobre os tempos: Estes testes foram feitos em uma máquina potente (M3 Pro, 18GB RAM). Em uma VPS básica (1GB RAM, 1 vCPU), esses tempos podem ser 3-4x maiores - ou seja, o BadImporter poderia levar 2-3 minutos! Mas a proporção de melhoria se mantém: a versão otimizada sempre será muito mais rápida, independente do hardware.

Com volumes maiores (100.000 ou 1.000.000 de registros), você precisaria de estratégias ainda mais avançadas como processamento paralelo, filas, ou ferramentas especializadas - mas mesmo essa versão já é infinitamente melhor que o approach tradicional!

Conclusão e Boas Práticas 🎉

A diferença entre uma importação mal feita e uma otimizada pode significar:

Seu script rodando em segundos ao invés de horas
Menos carga no banco de dados
Menor uso de memória
Rollback automático em caso de erro

Sempre use:

Transações para garantir consistência
Inserções em lote (insert_all ou activerecord-import)
Hashes de lookup para evitar queries desnecessárias
Processamento de dados únicos antes da inserção
Batches para controlar uso de memória

activerecord-import é seu melhor amigo para importações em massa!

Gostou do post? Deixe um ❤️ e compartilhe com outros devs Rails!

Quer mais conteúdo sobre performance e banco de dados?

Comenta aí embaixo o que você gostaria de ver:

Estratégias avançadas com a gem activerecord-import
Migrations e alterações de colunas em bases de dados existentes com milhões de registros
Casos reais com Kafka ou SQS para processamento assíncrono
Outras estratégias de otimização de banco de dados

É só pedir que a gente prepara o conteúdo! 🚀

rails #ruby #performance #database #postgresql #activerecord

Data Import in Rails: From Less Recommended to Optimised 🚀🇬🇧

Rodrigo Barreto — Sat, 23 Aug 2025 23:10:53 +0000

This post was 100% created with my examples, code, and real experiences, but formatted with AI assistance for better organization. AI can help us format and structure content, but it doesn't replace the knowledge and practical experience that we developers bring!

Importing data from JSON or Excel files is a common task in Rails development, but many people still do it inefficiently. Today I'll show you three approaches with impressive results: in a local test with just 10,000 records, the difference was from ~40 seconds to ~5 seconds - an improvement of more than 8x!

What this post does NOT cover 📝

How to efficiently read very large files (that's for another post)
Advanced chunks/batches imports (to keep the post concise)
Parallelization strategies with Sidekiq/ActiveJob

💡 Golden tip: For PostgreSQL users, the book High Performance PostgreSQL for Rails is a must-read!

Setting Up Our Scenario 🎬

First, let's create mock data to test our implementations:

# file_generator.rb (at the root of your project)
require 'json'
require 'faker'

base_users = [
  { name: "John Smith", email: "john@example.com", bio: "Ruby on Rails dev..." },
  { name: "Sarah Johnson", email: "sarah@example.com", bio: "Tech Lead..." },
  { name: "Mike Wilson", email: "mike@example.com", bio: "Full-stack dev..." },
  { name: "Emma Davis", email: "emma@example.com", bio: "DevOps engineer..." },
  { name: "Alex Rodriguez", email: "alex@example.com", bio: "Senior dev..." }
]

base_titles = [
  "Complete Guide to Active Record Queries",
  "Avoiding the N+1 Problem in Rails",
  "TDD with RSpec: From Basic to Advanced"
]

base_contents = [
  "In this article, we explore...",
  "Let's dive deep into...",
  "This tutorial covers..."
]

base_categories = ["Ruby on Rails", "Performance", "Database", "DevOps", "Architecture"]

posts = []

10_000.times do |i|
  user = base_users.sample
  post = {
    title: "#{base_titles.sample} ##{i}",
    content: "#{base_contents.sample} #{Faker::Lorem.paragraph(sentence_count: 5)}",
    published: [true, false].sample,
    user: user,
    categories: base_categories.sample(rand(1..3))
  }
  posts << post
end

File.write("blog_json_data_10k.json", JSON.pretty_generate(posts))

How to run 🏃‍♂️

Generate the JSON file with test data:

# At the root of your Rails project, run:
ruby file_generator.rb

This will create a blog_json_data_10k.json file with 10,000 mock posts.

To test the different implementations in Rails console:

# Open Rails console
rails console

# To test the less recommended implementation (grab some coffee!)
Importer::BadImporter.import!

# To test the reasonable implementation
Importer::BlogDataImporter.import!

# To test the optimized implementation (it will fly!)
Importer::BlogDataImporterWithActiveRecordImport.import!

💡 Note: You can change 10_000.times to generate more or less data. To start, 1,000 records already show the difference well!

The JsonImporter Class (Helper) 📄

You may have noticed we're using Importer::JsonImporter in all examples. It's a simple helper class to read the JSON file:

# app/services/importer/json_importer.rb
module Importer
  class JsonImporter
    attr_reader :file_name, :file_path

    def initialize(file_name:)
      @file_name = file_name
      @file_path = Rails.root.join(file_name)
    end

    def import!
      unless File.exist?(@file_path)
        raise "File not found: #{@file_path}"
      end

      puts "📁 Reading JSON file: #{@file_name}"
      file_content = File.read(@file_path)
      JSON.parse(file_content)
    rescue JSON::ParserError => e
      raise "Invalid JSON format: #{e.message}"
    rescue StandardError => e
      raise "Error reading file: #{e.message}"
    end
  end
end

This is a basic implementation that loads the entire file into memory. There are MUCH more performant and efficient ways to read large files (streaming, chunking, etc.), but that's for another post! The focus here is on importing data to the database.

Example 1: The Less Recommended Way ❌

# app/services/importer/bad_importer.rb
module Importer
  class BadImporter
    def self.import!
      start_time = Time.current

      blog_json = Importer::JsonImporter.new(file_name: "blog_json_data_10k.json").import!

      # Process each post individually
      blog_json.each do |post_data|

        # Create user for every post (checks for duplicates every time!)
        user = User.find_or_create_by(email: post_data["user"]["email"]) do |u|
          u.name = post_data["user"]["name"]
          u.bio = post_data["user"]["bio"]
        end

        # Create post
        post = Post.find_or_create_by(title: post_data["title"]) do |p|
          p.content = post_data["content"]
          p.published = post_data["published"]
          p.user = user
        end

        # Create categories for every post (more checks!)
        post_data["categories"].each do |category_name|
          category = Category.find_or_create_by(name: category_name)

          # Create association
          PostCategory.find_or_create_by(post: post, category: category)
        end
      end

      elapsed_time = Time.current - start_time
      puts "Total time: #{elapsed_time.round(2)} seconds"
    end
  end
end

Why is this code not recommended? 🤔

Query explosion: For each post, we make multiple queries (find_or_create_by)
No transaction: If something fails in the middle, you'll have partial data in the database
Poor performance: In my test, it took ~40 seconds for just 10,000 records!
Unnecessary resource usage: Checks for duplicates on every iteration
No failure protection: An error on any line can leave garbage in the database

⚠️ Reality: I've seen code like this in production processing a lot of records. Imagine the time!

Example 2: The Reasonable Way ✅

# app/services/importer/blog_data_importer.rb
module Importer
  class BlogDataImporter
    def self.import!
      start_time = Time.current

      ActiveRecord::Base.transaction do
        blog_json = Importer::JsonImporter.new(file_name: "blog_json_data_10k.json").import!

        # Extract unique data BEFORE inserting
        categories = blog_json.map{ |post| post["categories"] }.flatten.uniq
        users = blog_json.map{ |post| post["user"] }.uniq { |user| user["email"] }

        # Insert categories and users all at once
        Category.insert_all(categories.map { |category| {name: category} })
        User.insert_all(users.map { |user| {name: user["name"], email: user["email"], bio: user["bio"]} })

        # Create lookup hashes (KEY OPTIMIZATION!)
        categories_hash = Category.all.pluck(:name, :id).to_h
        users_hash = User.all.pluck(:email, :id).to_h

        # Import posts
        blog_json.map do |post|
          result = {
            title: post["title"],
            content: post["content"],
            published: post["published"],
            user_id: users_hash[post["user"]["email"]]
          }
          post_data = Post.create!(result)

          # Create post-category associations in batch
          PostCategory.insert_all(
            post["categories"].map { |category| 
              {post_id: post_data.id, category_id: categories_hash[category]} 
            }
          )
        end

      rescue ActiveRecord::RecordInvalid, StandardError => e
        error = "Error: #{e.message}"
        puts error
        Rails.logger.error error
      end

      elapsed_time = Time.current - start_time
      puts "Total time: #{elapsed_time.round(2)} seconds"
    end
  end
end

Why is this code much better? 👍

Uses transaction: Ensures atomicity - either imports everything or nothing
insert_all: Drastically reduces the number of queries
Lookup hashes: Transforms O(n) searches into O(1) - genius!
Process duplicates only once: Much more efficient

The Magic of Lookup Hashes 🎩

categories_hash = Category.all.pluck(:name, :id).to_h
# Result: {"Ruby on Rails" => 1, "Performance" => 2, ...}

Instead of searching for the category in the database for each post (10,000 searches!), we make one query and access via hash. This is pure gold for performance!

Example 3: The OPTIMIZED Way with activerecord-import 🚀

First, add to your Gemfile:

gem 'activerecord-import'
# If using PostgreSQL (as in the repository example)
gem 'pg', '~> 1.1'

💡 Note: This post works with any database (SQLite, MySQL, PostgreSQL). In the example code I've made available on GitHub, I used PostgreSQL, but you can use whatever database you prefer!

Now watch the magic happen:

# app/services/importer/blog_data_importer_with_active_record_import.rb
module Importer
  class BlogDataImporterWithActiveRecordImport
    def self.import!
      start_time = Time.current

      ActiveRecord::Base.transaction do
        blog_json = Importer::JsonImporter.new(file_name: "blog_json_data_10k.json").import!

        # Prepare unique data
        categories = blog_json.map{ |post| post["categories"] }.flatten.uniq
        users = blog_json.map{ |post| post["user"] }.uniq { |user| user["email"] }

        # Import categories and users in batch
        category_objects = categories.map { |name| Category.new(name: name) }
        Category.import category_objects, on_duplicate_key_ignore: true, validate: false

        user_objects = users.map { |user| 
          User.new(name: user["name"], email: user["email"], bio: user["bio"]) 
        }
        User.import user_objects, on_duplicate_key_ignore: true, validate: false

        # Create lookup hashes
        categories_hash = Category.all.pluck(:name, :id).to_h
        users_hash = User.all.pluck(:email, :id).to_h

        # Import posts in batches to save memory
        blog_json.in_groups_of(1000, false) do |post_batch|
          posts_to_import = post_batch.map do |post|
            Post.new(
              title: post["title"],
              content: post["content"],
              published: post["published"],
              user_id: users_hash[post["user"]["email"]]
            )
          end

          # Import this batch of posts (without validations for maximum performance!)
          Post.import posts_to_import, validate: false
        end

        # Prepare and import associations in batches
        Post.where(title: blog_json.map { |p| p["title"] }).find_in_batches(batch_size: 1000) do |post_batch|
          post_categories = []

          post_batch.each do |post|
            post_data = blog_json.find { |p| p["title"] == post.title }
            post_data["categories"].each do |category_name|
              post_categories << PostCategory.new(
                post_id: post.id,
                category_id: categories_hash[category_name]
              )
            end
          end

          # Import associations for this batch (without validations!)
          PostCategory.import post_categories, validate: false if post_categories.any?
        end

      rescue StandardError => e
        error = "Error: #{e.message}"
        puts error
        Rails.logger.error error
      end

      elapsed_time = Time.current - start_time
      puts "Total time: #{elapsed_time.round(2)} seconds"
    end
  end
end

Why is activerecord-import AMAZING? 🎯

Optimized SQL: Generates a single INSERT with multiple VALUES
Memory management: Processes in batches of 1000 records
Total flexibility: Optional validations, upserts, callbacks
Brutal performance: In my test: ~5 seconds!

The gem offers powerful options:

on_duplicate_key_ignore: Silently ignores duplicates
on_duplicate_key_update: Updates existing records
validate: false: Skips Rails validations (extra performance gain!)
batch_size: Controls memory usage

Real Performance Comparison 📊

Local test with 10,000 records on an Apple M3 Pro with 18GB RAM:

BadImporter: ~40 seconds 😱
BlogDataImporter: ~15 seconds 😊
BlogDataImporterWithActiveRecordImport: ~5 seconds 🚀

The optimized version was 8x faster than the less recommended one!

⚠️ Important about timing: These tests were done on a powerful machine (M3 Pro, 18GB RAM). On a basic VPS (1GB RAM, 1 vCPU), these times could be 3-4x higher - meaning BadImporter could take 2-3 minutes! But the improvement ratio remains: the optimized version will always be much faster, regardless of hardware.

With larger volumes (100,000 or 1,000,000 records), you'd need even more advanced strategies like parallel processing, queues, or specialized tools - but even this version is infinitely better than the traditional approach!

Conclusion and Best Practices 🎉

The difference between a poorly done import and an optimized one can mean:

Your script running in seconds instead of hours
Less database load
Lower memory usage
Automatic rollback in case of error

Always use:

Transactions to ensure consistency
Batch insertions (insert_all or activerecord-import)
Lookup hashes to avoid unnecessary queries
Process unique data before insertion
Batches to control memory usage

activerecord-import is your best friend for bulk imports!

Liked this post? Leave a ❤️ and share with other Rails devs!

Want more content about performance and databases?

Comment below what you'd like to see:

Advanced strategies with the activerecord-import gem
Migrations and column changes in existing databases with millions of records
Real cases with Kafka or SQS for asynchronous processing
Other database optimization strategies

Just ask and we'll prepare the content! 🚀

rails #ruby #performance #database #postgresql #activerecord

Tips and Tricks Ruby on Rails

Rodrigo Barreto — Sun, 27 Jul 2025 14:37:10 +0000

Where This Came From

This content was inspired by:

Drifting Ruby - Ruby on Rails screencasts
Videos de TI - Portuguese course by @jacksonpires
thoughtbot - English courses

Note: Don't let AI do your work, but let it help you! All the content and experience are mine, but it was formatted and organized with AI help for better clarity and structure.

The other day, a friend asked for help with his project. We spent hours catching up and laughing, and he ended up picking up several Rails tips from me - simple stuff that can help Junior and Mid-level developers.

At the end of our chat, he said - "Why don't you create a post about this???"

And I said: "you know what, why not?"

The "Tips and Tricks" title came from Drifting Ruby episode with the same name. They have lots of other examples there, but I literally brought just this one part from there:

Project.find(1).present? 
Project.exists?(id: 1) 
Project.where(id: 1).any?

By the way, I recommend the subscription - they have lots of cool stuff.

Also, if you want to learn Ruby on Rails better, I recommend Videos de TI (only in Portuguese), but I do recommend it - it's from my friend @jacksonpires, he's a great teacher.

And thoughtbot has awesome courses in English.

Let's go, let's build this post!

What's Inside

Project Setup
Console Tips & Navigation
Active Record Basics
Hands-on Console Examples
Wrap Up

Project Setup

First, let's create some simple blog models to test our examples:

📁 Full project available at: github.com/rodrigonbarreto/event_reservation_system

Rails Generate Commands

# Create the models
rails generate model User name:string email:string bio:text
rails generate model Category name:string description: "text"
rails generate model Post title: "string content:text published:boolean user:references"
rails generate model Comment content:text post:references user:references
rails generate model PostCategory post:references category:references

rails db:migrate
rails db:seed

Complete Models

📂 Click to see the complete models

# app/models/user.rb
class User &lt; ApplicationRecord
  has_many :posts, dependent: :destroy
  has_many :comments, dependent: :destroy
  has_many :post_categories, through: :posts
  has_many :categories, through: :post_categories

  validates :name, presence: true
  validates :email, presence: true, uniqueness: true

  def published_posts
    posts.where(published: true)
  end
end

# app/models/category.rb
class Category &lt; ApplicationRecord
  has_many :post_categories, dependent: :destroy
  has_many :posts, through: :post_categories
  has_many :users, through: :posts

  validates :name, presence: true, uniqueness: true

  scope :with_published_posts, -&gt; { joins(:posts).where(posts: { published: true }).distinct }

  def published_posts_count
    posts.where(published: true).count
  end
end

# app/models/post.rb
class Post &lt; ApplicationRecord
  belongs_to :user
  has_many :comments, dependent: :destroy
  has_many :post_categories, dependent: :destroy
  has_many :categories, through: :post_categories

  validates :title, presence: true
  validates :content, presence: true

  scope :published, -&gt; { where(published: true) }
  scope :recent, -&gt; { where('created_at &gt; ?', 1.week.ago) }
  scope :by_user, -&gt;(user) { where(user: user) }

  def comments_count
    comments.count
  end
end

# app/models/comment.rb
class Comment &lt; ApplicationRecord
  belongs_to :post
  belongs_to :user

  validates :content, presence: true

  scope :recent, -&gt; { where('created_at &gt; ?', 1.day.ago) }
  scope :by_user, -&gt;(user) { where(user: user) }

  delegate :title, to: :post, prefix: true
  delegate :name, to: :user, prefix: true
end

# app/models/post_category.rb
class PostCategory &lt; ApplicationRecord
  belongs_to :post
  belongs_to :category

  validates :post_id, uniqueness: { scope: :category_id }

  scope :for_published_posts, -&gt; { joins(:post).where(posts: { published: true }) }
  scope :recent, -&gt; { where('created_at &gt; ?', 1.week.ago) }
end

Console Tips & Navigation

🎯 The Magic Underscore (_)

The underscore always returns the result of the last command you ran in the console. It's a quick way to grab the previous result without running the query again:

Comment.last
# => #<Comment id: 5, content: "Great post!", ...>

# The underscore (_) will always contain the last result
comment = _
# => #<Comment id: 5, content: "Great post!", ...>

# Works with any command
User.where(name: "John").limit(3)
users = _  # Grabs the 3 users without running the query again

🛠️ Helper Methods

# See available helpers
ActionController::Base.helpers

# Use Rails helpers
ActionController::Base.helpers.pluralize(5, 'post')
# => "5 posts"

ActionController::Base.helpers.time_ago_in_words(1.hour.ago)
# => "about 1 hour"

ActionController::Base.helpers.number_to_currency(29.95)
# => "$29.95"

🔄 Reload

# Reload code without leaving the console
reload!

🔍 Inspection Tricks

user = User.first

# Different output formats
user.attributes
# => {"id"=>1, "name"=>"John", ...}

user.attributes.to_json
# => "{\"id\":1,\"name\":\"John\",...}"

JSON.pretty_generate(user.attributes)
# => Nice formatted JSON output

# Pretty print
pp user.attributes

# See just the keys
user.attributes.keys
# => ["id", "name", "email", "bio"]

# Check unsaved changes
user.name = "New Name"
user.changes
# => {"name"=>["John", "New Name"]} (shows old value -> new value)

user.changed_attributes
# => {"name"=>"John"} (just the old values)

# See available methods - great for finding methods you don't know about
user.methods.sort                    # All methods in alphabetical order
user.methods.grep(/name/)           # Only methods that contain "name"
user.public_methods(false)          # Only the class's own methods (no inheritance)

# Inspect - See a readable object representation
user.inspect
# => "#<User id: 1, name: \"John\", email: \"john@example.com\", bio: \"Developer...\">"

# Useful for debugging and logs
puts user.inspect
Rails.logger.info(user.inspect)

Active Record Basics

⚡ Pluck vs Select - Getting IDs Fast

When you only need IDs, there are two main approaches:

# Example: Get all posts from "Ruby on Rails" category

# ❌ Less efficient way - loads complete objects
category_ids = Category.where(name: "Ruby on Rails").map(&:id)
posts = Post.joins(:post_categories).where(post_categories: { category_id: category_ids })

# ✅ PLUCK - Returns array, runs 1 query + 1 query = 2 total queries
ids = Category.where(name: "Ruby on Rails").pluck(:id)
# Category Pluck (0.2ms) SELECT "categories"."id" FROM "categories" WHERE "categories"."name" = 'Ruby on Rails'
posts = Post.joins(:post_categories).where(post_categories: { category_id: ids })
# Post Load (0.4ms) SELECT "posts".* FROM "posts" INNER JOIN "post_categories"...

# ✅ SELECT - Returns ActiveRecord::Relation, runs just 1 optimized query
ids = Category.where(name: "Ruby on Rails").select(:id)
posts = Post.joins(:post_categories).where(post_categories: { category_id: ids })
# Post Load (0.4ms) SELECT "posts".* FROM "posts" INNER JOIN "post_categories" 
# WHERE "post_categories"."category_id" IN (SELECT "categories"."id" FROM "categories" WHERE "categories"."name" = 'Ruby on Rails')

Key differences:

Method	Returns	Queries run	Use when
`pluck(:id)`	`[1, 3, 5]` (Array)	2 queries	Need array of values
`select(:id)`	`ActiveRecord::Relation`	1 optimized query	Using in subqueries or chains

# PLUCK - Runs the query right away and returns Array
ids = Category.where(name: "Ruby on Rails").pluck(:id)
# => [1, 3, 5] (Array of integers)

# SELECT - Returns ActiveRecord::Relation, better for chaining
ids = Category.where(name: "Ruby on Rails").select(:id)
ids.class
# => Category::ActiveRecord_Relation

# When used in the next query, makes an optimized subquery in 1 go:
Post.where(category_id: ids)  # One query with subquery, not two separate ones!

In the image below, you can see the practical difference:

PLUCK (2 queries): When we run the two lines with pluck, Rails makes two separate queries
SELECT (1 query): When we run the two lines with select, Rails optimizes and makes just one query with subquery

🎯 When to Use user_id vs user.id

One of the simplest and most important optimizations - when you only need the ID, use the direct attribute:

comment = Comment.first
# Comment Load (0.3ms) SELECT "comments".* FROM "comments" ORDER BY "comments"."id" ASC LIMIT 1

# ✅ EFFICIENT - Uses the already loaded value
comment.user_id
# => 5
# No extra query!

# ❌ INEFFICIENT - Loads the complete User object
comment.user.id  
# User Load (0.4ms) SELECT "users".* FROM "users" WHERE "users"."id" = 5 LIMIT 1
# => 5

Practical examples:

# ✅ EFFICIENT - Use when you only need the ID
if comment.user_id == current_user.id
  # Just comparing IDs, no need to load user
end

# ❌ INEFFICIENT - Loads the complete User object just for ID
if comment.user.id == current_user.id  
  # This loads the entire user object unnecessarily
end

# ✅ EFFICIENT - Use when you need other user attributes too
name = comment.user.name  # Now we're using the loaded user
id = comment.user.id      # OK to use .id since we already loaded user

Impact on Tests (RSpec):

In a test suite, this difference can be significant. In 1000 tests, this can add 2-3 extra minutes to execution:

# ❌ In a suite of 1000 tests, this can add 2-3 MINUTES
it "checks comment ownership" do
  expect(comment.user.id).to eq(current_user.id)  # Loads user unnecessarily
end

# ✅ Much faster - no extra query
it "checks comment ownership" do
  expect(comment.user_id).to eq(current_user.id)  # Just uses the already loaded ID
end

When to use each:

user_id: For comparisons, validations, foreign keys
user.id: When you're going to use other user attributes later

🚫 N+1 Problem & Includes

The N+1 problem is one of the worst performance killers:

# ❌ N+1 PROBLEM - Runs 1 + N queries
posts = Post.all  # 1 query
posts.each do |post|
  puts post.user.name  # N queries (one for each post)
end

# ✅ SOLUTION - Runs just 2 queries
posts = Post.includes(:user)  # 1 query + 1 query for users
posts.each do |post|
  puts post.user.name  # No extra queries
end

# For more complex relationships
Post.includes(:user, :comments, categories: :posts)

✅ Existence Checks - Performance Matters

# ❌ INEFFICIENT - Loads the complete object in memory
Project.find(1).present?  # SELECT * FROM projects WHERE id = 1

# ✅ EFFICIENT - Just checks if it exists in the database
Project.exists?(id: 1)    # SELECT 1 FROM projects WHERE id = 1 LIMIT 1

# ✅ ALTERNATIVE - For complex queries
Project.where(id: 1, active: true).exists?

# ⚠️ BE CAREFUL - Loads all records
Project.where(id: 1).any?  # SELECT * (can be dangerous with lots of data)

📊 Count vs Size vs Length - Performance Matters

# Scenario: User with many posts
user = User.first

# 1. COUNT - Always runs SQL query
user.posts.count
# => SELECT COUNT(*) FROM posts WHERE user_id = 1

# 2. SIZE - Smart: uses cache if collection was already loaded
user.posts.size
# If posts weren't loaded: SELECT COUNT(*)
# If posts were already loaded: posts.length (no query)

# 3. LENGTH - Forces complete collection loading
user.posts.length
# => SELECT * FROM posts WHERE user_id = 1 (DANGEROUS!)

Rule of thumb:

size: Use by default (99% of cases)
count: Use when you need the exact value from database
length: Avoid, except for small collections already loaded

🔍 Query Explain - Performance Debugging

# Analyze query performance
User.joins(:posts).where(posts: { published: true }).explain

# IRB result:
# User Load (1.2ms)  SELECT "users".* FROM "users" INNER JOIN "posts" ON "posts"."user_id" = "users"."id" WHERE "posts"."published" = ?  [["published", 1]]
# => 
# EXPLAIN for: SELECT "users".* FROM "users" INNER JOIN "posts" ON "posts"."user_id" = "users"."id" WHERE "posts"."published" = ? [["published", 1]]
# 3|0|0|SCAN posts
# 7|0|0|SEARCH users USING INTEGER PRIMARY KEY (rowid=?)

# Look for:
# "SCAN" = Complete table scan (can be slow)
# "SEARCH USING INDEX" = Using index (fast)  
# "USING INTEGER PRIMARY KEY" = Primary key search (awesome)

🔗 Merge - Combining Scopes Nicely

merge lets you combine conditions from different models in a clean way:

# Scenario: Published posts from active users
class User < ApplicationRecord
  scope :active, -> { where(active: true) }
  scope :premium, -> { where(premium: true) }
end

class Post < ApplicationRecord
  scope :published, -> { where(published: true) }
  scope :recent, -> { where('created_at > ?', 1.week.ago) }
end

# ❌ Verbose way
Post.joins(:user)
    .where(published: true)
    .where(users: { active: true, premium: true })

# ✅ Clean way with merge + scopes
Post.published
    .joins(:user)
    .merge(User.active)
    .merge(User.premium)

# ✅ Merge also works with where directly
Post.joins(:user)
    .merge(User.where(active: true))
    .where(published: true)

# ✅ Combining multiple conditions
Post.joins(:user, :comments)
    .merge(User.where('created_at > ?', 1.year.ago))
    .merge(Comment.where('created_at > ?', 1.week.ago))

Hands-on Console Examples

Now that you've populated the data with rails db:seed, try these commands:

# Test basic relationships
user = User.first
user.posts.published

# Test includes
Post.includes(:user, :categories, :comments).first

# Count by category
Category.joins(:posts).group('categories.name').count

# Example of pluck vs select
Category.where(name: "Ruby on Rails").pluck(:id)
Category.where(name: "Ruby on Rails").select(:id)

# Test existence checks
Post.exists?(title: "Complete Guide to Active Record Queries")
Post.where(published: true).any?

# Performance comparison
user.posts.count
user.posts.size

Wrap Up

These simple tips can make a huge difference in your Rails code performance and readability. Remember:

✅ Use pluck when you need specific values and won't continue with other queries
✅ Use select when using in subqueries or continuing the query chain
✅ Use exists? instead of loading objects just to check existence
✅ Always prefer includes to avoid N+1
✅ size is usually the best choice between count/size/length
✅ merge makes your queries more readable and reusable

💡 Tip: If this content helped you, share it with other developers!

Dicas e truques Ruby on Rails

Rodrigo Barreto — Sun, 27 Jul 2025 14:12:36 +0000

Tips and Tricks Ruby on Rails

Inspirações e Conteúdo

Este conteúdo foi inspirado por:

Drifting Ruby - Screencasts de Ruby on Rails
Videos de TI - Curso com conteúdo em português do @jacksonpires
thoughtbot - Cursos com conteúdo em inglês

Observação: Não deixe a AI fazer o seu serviço, mas deixe ela te ajudar! Todo o conteúdo e experiência são meus, mas foi formatado e organizado com ajuda de AI para melhor clareza e estrutura.

Outro dia um amigo me pediu uma ajuda no projeto dele, e perdemos horas dando boas risadas para matar a saudade e ele acabou pegando várias dicas comigo no Ruby on Rails, coisas simples, mas que podem ajudar um Junior e um Medior.

No final da conversa ele até comentou - no caso ele me chama de xará pois o nome dele também é Rodrigo - "porque você não cria um post sobre isso???"

E eu falei: "olha, porque não?"

O título "Tips and Tricks" veio do Drifting Ruby episódio com o mesmo nome. Lá tem muitos outros exemplos, mas literalmente essa única parte eu trouxe de lá:

Project.find(1).present? 
Project.exists?(id: 1) 
Project.where(id: 1).any?

Por sinal, recomendo a assinatura - eles têm muitas coisas legais.

Além disso, se você quiser aprender melhor Ruby on Rails, recomendo o Videos de TI (só tem em português), mas eu recomendo - é do meu amigo @jacksonpires, ele é um ótimo professor.

Já a thoughtbot tem ótimos cursos em inglês.

Bora lá, vamos montar esse post!

Índice

Setup do Projeto
Truques e Navegação no Console
Fundamentos do Active Record
Exemplos Práticos no Console
Conclusão

Setup do Projeto

Primeiro, vamos criar os modelos de um blog simples para testar nossos exemplos:

📁 Projeto completo disponível em: github.com/rodrigonbarreto/event_reservation_system

Comandos Rails Generate

# Gerar os modelos
rails generate model User name:string email:string bio:text
rails generate model Category name:string description: "text"
rails generate model Post title: "string content:text published:boolean user:references"
rails generate model Comment content:text post:references user:references
rails generate model PostCategory post:references category:references

rails db:migrate
rails db:seed

Modelos Completos

📂 Clique para ver os modelos completos

# app/models/user.rb
class User &lt; ApplicationRecord
  has_many :posts, dependent: :destroy
  has_many :comments, dependent: :destroy
  has_many :post_categories, through: :posts
  has_many :categories, through: :post_categories

  validates :name, presence: true
  validates :email, presence: true, uniqueness: true

  def published_posts
    posts.where(published: true)
  end
end

# app/models/category.rb
class Category &lt; ApplicationRecord
  has_many :post_categories, dependent: :destroy
  has_many :posts, through: :post_categories
  has_many :users, through: :posts

  validates :name, presence: true, uniqueness: true

  scope :with_published_posts, -&gt; { joins(:posts).where(posts: { published: true }).distinct }

  def published_posts_count
    posts.where(published: true).count
  end
end

# app/models/post.rb
class Post &lt; ApplicationRecord
  belongs_to :user
  has_many :comments, dependent: :destroy
  has_many :post_categories, dependent: :destroy
  has_many :categories, through: :post_categories

  validates :title, presence: true
  validates :content, presence: true

  scope :published, -&gt; { where(published: true) }
  scope :recent, -&gt; { where('created_at &gt; ?', 1.week.ago) }
  scope :by_user, -&gt;(user) { where(user: user) }

  def comments_count
    comments.count
  end
end

# app/models/comment.rb
class Comment &lt; ApplicationRecord
  belongs_to :post
  belongs_to :user

  validates :content, presence: true

  scope :recent, -&gt; { where('created_at &gt; ?', 1.day.ago) }
  scope :by_user, -&gt;(user) { where(user: user) }

  delegate :title, to: :post, prefix: true
  delegate :name, to: :user, prefix: true
end

# app/models/post_category.rb
class PostCategory &lt; ApplicationRecord
  belongs_to :post
  belongs_to :category

  validates :post_id, uniqueness: { scope: :category_id }

  scope :for_published_posts, -&gt; { joins(:post).where(posts: { published: true }) }
  scope :recent, -&gt; { where('created_at &gt; ?', 1.week.ago) }
end

Truques e Navegação no Console

🎯 Magia do Underscore (_)

O underscore sempre retorna o resultado do último comando executado no console. É uma forma rápida de capturar o resultado anterior sem precisar executar a query novamente:

Comment.last
# => #<Comment id: 5, content: "Great post!", ...>

# O underscore (_) sempre vai conter o último resultado
comment = _
# => #<Comment id: 5, content: "Great post!", ...>

# Funciona com qualquer comando
User.where(name: "John").limit(3)
users = _  # Captura os 3 usuários sem executar a query novamente

🛠️ Métodos Helper

# Ver helpers disponíveis
ActionController::Base.helpers

# Usar helpers do Rails
ActionController::Base.helpers.pluralize(5, 'post')
# => "5 posts"

ActionController::Base.helpers.time_ago_in_words(1.hour.ago)
# => "about 1 hour"

ActionController::Base.helpers.number_to_currency(29.95)
# => "$29.95"

🔄 Reload

# Recarregar código sem sair do console
reload!

🔍 Truques de Inspeção

user = User.first

# Diferentes formatos de saída
user.attributes
# => {"id"=>1, "name"=>"John", ...}

user.attributes.to_json
# => "{\"id\":1,\"name\":\"John\",...}"

JSON.pretty_generate(user.attributes)
# => Saída JSON formatada e legível

# Pretty print
pp user.attributes

# Ver apenas keys
user.attributes.keys
# => ["id", "name", "email", "bio"]

# Inspecionar mudanças não salvas
user.name = "New Name"
user.changes
# => {"name"=>["John", "New Name"]} (mostra valor antigo -> valor novo)

user.changed_attributes
# => {"name"=>"John"} (apenas os valores antigos)

# Ver métodos disponíveis - útil para descobrir métodos que você não conhece
user.methods.sort                    # Todos os métodos em ordem alfabética
user.methods.grep(/name/)           # Apenas métodos que contém "name"
user.public_methods(false)          # Apenas métodos próprios da classe (sem herança)

# Inspect - Ver representação do objeto de forma legível
user.inspect
# => "#<User id: 1, name: \"John\", email: \"john@example.com\", bio: \"Developer...\">"

# Útil para debugging e logs
puts user.inspect
Rails.logger.info(user.inspect)

Fundamentos do Active Record

⚡ Pluck vs Select - Performance na Recuperação de IDs

Quando você precisa apenas de IDs, existem duas abordagens principais:

# Exemplo: Buscar todos os posts da categoria "Ruby on Rails"

# ❌ Forma menos eficiente - carrega objetos completos
category_ids = Category.where(name: "Ruby on Rails").map(&:id)
posts = Post.joins(:post_categories).where(post_categories: { category_id: category_ids })

# ✅ PLUCK - Retorna array, executa 1 query + 1 query = 2 queries totais
ids = Category.where(name: "Ruby on Rails").pluck(:id)
# Category Pluck (0.2ms) SELECT "categories"."id" FROM "categories" WHERE "categories"."name" = 'Ruby on Rails'
posts = Post.joins(:post_categories).where(post_categories: { category_id: ids })
# Post Load (0.4ms) SELECT "posts".* FROM "posts" INNER JOIN "post_categories"...

# ✅ SELECT - Retorna ActiveRecord::Relation, executa apenas 1 query otimizada
ids = Category.where(name: "Ruby on Rails").select(:id)
posts = Post.joins(:post_categories).where(post_categories: { category_id: ids })
# Post Load (0.4ms) SELECT "posts".* FROM "posts" INNER JOIN "post_categories" 
# WHERE "post_categories"."category_id" IN (SELECT "categories"."id" FROM "categories" WHERE "categories"."name" = 'Ruby on Rails')

Diferenças importantes:

Método	Retorno	Queries executadas	Use quando
`pluck(:id)`	`[1, 3, 5]` (Array)	2 queries	Precisar de array de valores
`select(:id)`	`ActiveRecord::Relation`	1 query otimizada	Usar em subqueries ou chains

# PLUCK - Executa a query imediatamente e retorna Array
ids = Category.where(name: "Ruby on Rails").pluck(:id)
# => [1, 3, 5] (Array de integers)

# SELECT - Retorna ActiveRecord::Relation, mais eficiente para chains
ids = Category.where(name: "Ruby on Rails").select(:id)
ids.class
# => Category::ActiveRecord_Relation

# Quando usado na próxima query, faz subquery otimizada em 1 comando só:
Post.where(category_id: ids)  # Uma query com subquery, não duas separadas!

Na imagem abaixo, você pode ver a diferença prática:

PLUCK (2 queries): Quando executamos as duas linhas com pluck, o Rails faz duas queries separadas
SELECT (1 query): Quando executamos as duas linhas com select, o Rails otimiza e faz apenas uma query com subquery

🎯 Quando Usar user_id vs user.id

Uma das otimizações mais simples e importantes - quando você só precisa do ID, use o atributo direto:

comment = Comment.first
# Comment Load (0.3ms) SELECT "comments".* FROM "comments" ORDER BY "comments"."id" ASC LIMIT 1

# ✅ EFICIENTE - Usa o valor já carregado
comment.user_id
# => 5
# Sem query adicional!

# ❌ INEFICIENTE - Carrega o objeto User completo
comment.user.id  
# User Load (0.4ms) SELECT "users".* FROM "users" WHERE "users"."id" = 5 LIMIT 1
# => 5

Exemplos práticos:

# ✅ EFICIENTE - Use quando precisar apenas do ID
if comment.user_id == current_user.id
  # Comparando apenas IDs, sem carregar user
end

# ❌ INEFICIENTE - Carrega o objeto User completo só para pegar o ID
if comment.user.id == current_user.id  
  # Isso carrega o objeto user inteiro desnecessariamente
end

# ✅ EFICIENTE - Use quando for usar outros atributos do user também
name = comment.user.name  # Agora estamos usando o user carregado
id = comment.user.id      # OK usar .id já que carregamos o user

Impacto nos Testes (RSpec):

Em uma suite de testes, essa diferença pode ser significativa. Em 1000 testes, isso pode adicionar 2-3 minutos extras na execução:

# ❌ Em uma suite de 1000 testes, isso pode adicionar 2-3 MINUTOS
it "checks comment ownership" do
  expect(comment.user.id).to eq(current_user.id)  # Carrega user desnecessariamente
end

# ✅ Muito mais rápido - sem query extra
it "checks comment ownership" do
  expect(comment.user_id).to eq(current_user.id)  # Só usa o ID já carregado
end

Quando usar cada um:

user_id: Para comparações, validações, foreign keys
user.id: Quando você já vai usar outros atributos do user depois

🚫 Problema N+1 & Includes

O problema N+1 é um dos mais críticos em performance:

# ❌ PROBLEMA N+1 - Executa 1 + N queries
posts = Post.all  # 1 query
posts.each do |post|
  puts post.user.name  # N queries (uma para cada post)
end

# ✅ SOLUÇÃO - Executa apenas 2 queries
posts = Post.includes(:user)  # 1 query + 1 query para users
posts.each do |post|
  puts post.user.name  # Sem queries adicionais
end

# Para relacionamentos mais complexos
Post.includes(:user, :comments, categories: :posts)

✅ Verificações de Existência - Performance Importa

# ❌ INEFICIENTE - Carrega o objeto completo na memória
Project.find(1).present?  # SELECT * FROM projects WHERE id = 1

# ✅ EFICIENTE - Apenas verifica existência no banco
Project.exists?(id: 1)    # SELECT 1 FROM projects WHERE id = 1 LIMIT 1

# ✅ ALTERNATIVA - Para queries complexas
Project.where(id: 1, active: true).exists?

# ⚠️ CUIDADO - Carrega todos os registros
Project.where(id: 1).any?  # SELECT * (pode ser perigoso com muitos dados)

📊 Count vs Size vs Length - Performance Crítica

# Cenário: User com muitos posts
user = User.first

# 1. COUNT - Sempre executa query SQL
user.posts.count
# => SELECT COUNT(*) FROM posts WHERE user_id = 1

# 2. SIZE - Inteligente: usa cache se collection já foi carregada
user.posts.size
# Se posts não foram carregados: SELECT COUNT(*)
# Se posts já foram carregados: posts.length (sem query)

# 3. LENGTH - Força carregamento completo da collection
user.posts.length
# => SELECT * FROM posts WHERE user_id = 1 (PERIGOSO!)

Regra de ouro:

size: Use por padrão (99% dos casos)
count: Use quando precisar do valor exato do banco
length: Evite, exceto em collections pequenas já carregadas

🔍 Query Explain - Debug de Performance

# Analisar performance de queries
User.joins(:posts).where(posts: { published: true }).explain

# Resultado do IRB:
# User Load (1.2ms)  SELECT "users".* FROM "users" INNER JOIN "posts" ON "posts"."user_id" = "users"."id" WHERE "posts"."published" = ?  [["published", 1]]
# => 
# EXPLAIN for: SELECT "users".* FROM "users" INNER JOIN "posts" ON "posts"."user_id" = "users"."id" WHERE "posts"."published" = ? [["published", 1]]
# 3|0|0|SCAN posts
# 7|0|0|SEARCH users USING INTEGER PRIMARY KEY (rowid=?)

# Procure por:
# "SCAN" = Table scan completo (pode ser lento)
# "SEARCH USING INDEX" = Usando índice (rápido)  
# "USING INTEGER PRIMARY KEY" = Busca por chave primária (ótimo)

🔗 Merge - Combinando Scopes com Elegância

O merge permite combinar condições de diferentes modelos de forma limpa:

# Cenário: Posts publicados de usuários ativos
class User < ApplicationRecord
  scope :active, -> { where(active: true) }
  scope :premium, -> { where(premium: true) }
end

class Post < ApplicationRecord
  scope :published, -> { where(published: true) }
  scope :recent, -> { where('created_at > ?', 1.week.ago) }
end

# ❌ Forma verbosa
Post.joins(:user)
    .where(published: true)
    .where(users: { active: true, premium: true })

# ✅ Forma elegante com merge + scopes
Post.published
    .joins(:user)
    .merge(User.active)
    .merge(User.premium)

# ✅ Merge também funciona com where direto
Post.joins(:user)
    .merge(User.where(active: true))
    .where(published: true)

# ✅ Combinando múltiplas condições
Post.joins(:user, :comments)
    .merge(User.where('created_at > ?', 1.year.ago))
    .merge(Comment.where('created_at > ?', 1.week.ago))

Exemplos Práticos no Console

Agora que você já populou os dados com rails db:seed, teste estes comandos:

# Teste básico de relacionamentos
user = User.first
user.posts.published

# Teste de includes
Post.includes(:user, :categories, :comments).first

# Contagem por categoria
Category.joins(:posts).group('categories.name').count

# Exemplo de pluck vs select
Category.where(name: "Ruby on Rails").pluck(:id)
Category.where(name: "Ruby on Rails").select(:id)

# Teste de existence checks
Post.exists?(title: "Complete Guide to Active Record Queries")
Post.where(published: true).any?

# Performance comparison
user.posts.count
user.posts.size

Conclusão

Essas dicas simples podem fazer uma grande diferença na performance e legibilidade do seu código Rails. Lembre-se:

✅ Use pluck quando precisar apenas de valores específicos e não continuar com outras queries
✅ Use select quando for usar em subqueries ou continuar o chain de queries
✅ Use exists? em vez de carregar objetos só para verificar existência
✅ Sempre prefira includes para evitar N+1
✅ size é geralmente a melhor opção entre count/size/length
✅ merge torna suas queries mais legíveis e reutilizáveis

💡 Dica: Se este conteúdo te ajudou, compartilhe com outros desenvolvedores!

Creating APIs with Grape and Rails: A Complete Journey - Part 3

Rodrigo Barreto — Tue, 22 Apr 2025 22:42:43 +0000

Introduction

Hello, devs! 👋

Welcome to the third part of our series on Grape and Rails! In the previous posts, we explored the basic API configuration and implemented CRUD operations for our events. Today, we'll take a step further and implement authentication for our API.

Security is a crucial aspect of any API, and implementing a robust authentication system is essential to protect your resources. In this post, we'll explore how to implement authentication with JWT (JSON Web Tokens) and how to protect our routes.

Setting Up Authentication with JWT

For our example, we'll use JWT for authentication. If you're not familiar with JWT, it's a standard for creating access tokens that can be validated without the need to query a database. JWT tokens contain information about the user and expire after a certain period.

First, let's add the necessary gems to our project:

gem 'devise'  # For user authentication
gem 'jwt'     # For working with JWT tokens

Run bundle install to install the dependencies.

1. Creating the JWT Service

First, we need to create a service to handle the encoding and decoding of JWT tokens. In app/services/jwt/json_web_token.rb:

# frozen_string_literal: true

module Jwt
  class JsonWebToken
    # SECRET = Rails.application.credentials.secret_key_base
    SECRET = "secret-key" # use some code in secrets or something more secure
    ENCRYPTION = "HS256"

    def self.encode(payload, exp = 120.hours.from_now)
      payload[:exp] = exp.to_i
      JWT.encode(payload, SECRET)
    rescue JWT::EncodeError => e
      Rails.logger.error("JWT Encode Error: #{e.message}")
    end

    def self.decode(token)
      body = JWT.decode(token, SECRET)[0]
      ActiveSupport::HashWithIndifferentAccess.new(body)
    rescue JWT::ExpiredSignature, JWT::DecodeError => e
      Rails.logger.error("JWT Encode Error: #{e.message}")
      nil
    end
  end
end

Note: In a production environment, you should store the secret key in a secure location, such as Rails.application.credentials.secret_key_base or an environment variable.

2. Creating Authentication Helpers

Next, let's create helpers to handle authentication in our endpoints. In app/api/helpers/auth_helpers.rb:

# frozen_string_literal: true

module Helpers
  module AuthHelpers
    extend Grape::API::Helpers

    # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
    def authenticate_request!
      # This example is simplified; in the real project, we only use headers["Authorization"]
      token = headers["Authorization"]&.split&.last || headers["authorization"]&.split&.last
      error!({ error: "Unauthorized", success: false }, 401) unless token

      # Decode the JWT token
      @jwt_result = Jwt::JsonWebToken.decode(token)
      error!({ error: "Invalid Token", success: false }, 401) unless @jwt_result

      # Fetch the current user (or generate an error if not found)
      current_user!
    rescue StandardError => e
      error!({ error: "Authentication Error: #{e.message}" }, 401)
    end
    # rubocop:enable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity

    # This method fetches the current user and generates an error if not found
    def current_user!
      @current_user ||= User.find_by(id: @jwt_result["id"])
      error!({ error: "Invalid Token", success: false }, 401) unless @current_user
      @current_user
    end

    # This method allows using current_user anywhere
    def current_user
      @current_user
    end
  end
end

3. Implementing the Login Endpoint

Now, let's create an endpoint to authenticate users and generate JWT tokens. In app/api/v1/login.rb:

# frozen_string_literal: true

module V1
  class Login < Grape::API
    resource :login do
      desc "Login ", {
        success: Entities::Users::LoginResponse,
        failure: [{ code: 401, message: "Unauthorized" }],
        params: ::Helpers::ContractToParams.generate_params(LoginContract)
      }
      post do
        contract = LoginContract.new
        result = contract.call(params)
        error!({ errors: result.errors.to_h }, 422) if result.failure?

        @user = User.find_by(email: params[:email])
        if @user&.valid_password?(params[:password])
          token = ::Jwt::JsonWebToken.encode({ id: @user.id })
          status 200
          present({ user: @user, token: token }, with: Entities::Users::LoginResponse)
        else
          error!({ error: "Unauthorized" }, 401)
        end
      end
    end
  end
end

Note: This example uses Devise's valid_password?, which is a standard method for verifying passwords.

4. Defining Entities for Login Response

To format the login endpoint responses, let's create some entities:

In app/api/entities/users/user_response.rb:

# frozen_string_literal: true

module Entities
  module Users
    class UserResponse < Grape::Entity
      expose :id, documentation: { type: "Integer", desc: "User id" }
      expose :email, documentation: { type: "String", desc: "User email" }
    end
  end
end

In app/api/entities/users/login_response.rb:

# frozen_string_literal: true

module Entities
  module Users
    class LoginResponse < Grape::Entity
      expose :user, using: Entities::Users::UserResponse,
                   documentation: { type: "Array", desc: "List of users" }
      expose :token, documentation: { type: "String", desc: "JWT token" }
    end
  end
end

5. Updating the Grape API

Now, let's update our app/api/v1/api_grape.rb file to include the authentication helpers and the new login endpoint:

# frozen_string_literal: true

class V1::ApiGrape < Grape::API
  version "v1", using: :path
  format :json
  default_format :json

  use CustomErrorMiddleware

  helpers ::Helpers::AuthHelpers

  mount V1::Events
  mount V1::Login

  add_swagger_documentation(
    api_version: "v1",
    hide_documentation_path: true,
    mount_path: "/swagger_doc",
    hide_format: true,
    info: {
      title: "Events API",
      description: "API for event management",
      contact_name: "Support Team",
      contact_email: "contact@example.com"
    },
    security_definitions: {
      Bearer: {
        type: "apiKey",
        name: "Authorization",
        in: "header",
        description: 'Enter "Bearer" followed by your token. Example: Bearer abc123'
      }
    },
    security: [{ Bearer: [] }]
  )
end

6. Adding Test Data

To facilitate testing, we can create a default user using seeds:

# db/seeds.rb

User.find_or_create_by!(email: "teste@examle.com") do |user|
  user.password = "123456"
  user.password_confirmation = "123456"
end

Run rails db:seed to create the user.

Protecting Endpoints

With our authentication setup in place, we can now protect our endpoints. Let's update our events controller to require authentication:

module V1
  class Events < Grape::API
    before { authenticate_request! }

    # The rest of the code remains the same...
  end
end

Now, all endpoints in the events resource will require a valid JWT token for access.

Implementing Middleware for Error Handling

To further improve our API, let's implement a custom middleware to handle common errors. In app/middleware/custom_error_middleware.rb:

# frozen_string_literal: true

class CustomErrorMiddleware < Grape::Middleware::Base
  def call(env)
    @app.call(env) # Pass the request forward
  rescue Grape::Exceptions::MethodNotAllowed => e
    handle_method_not_allowed(e, env)
  rescue ActiveRecord::RecordNotFound => e
    handle_record_not_found(e)
  rescue StandardError => e
    handle_standard_error(e)
  end

  private

  def handle_record_not_found(error)
    # Could use, for example: Sentry.capture_exception(error, extra: { message: error.message })
    error_response(message: "Couldn't find #{error.model || 'record'} with id: #{error.id}", status: 404)
  end

  def handle_method_not_allowed(error, env)
    request_method = env["REQUEST_METHOD"]
    path = env["PATH_INFO"]

    Rails.logger.error "Method not allowed: #{request_method} for path #{path}"

    allowed_methods = if error.respond_to?(:headers) && error.headers["Allow"]
                        "Allowed methods: #{error.headers['Allow']}"
                      else
                        "Please use the appropriate HTTP methods for this endpoint"
                      end

    error_message = "The #{request_method} method is not allowed for this resource. #{allowed_methods}. please check your parameters"

    unless Rails.env.development?
      # Sentry.capture_exception(error, extra: {
      #                            request_method: request_method,
      #                            path: path,
      #                            message: error_message
      #                          })
    end

    error_response(message: error_message, status: 405)
  end

  def handle_standard_error(error)
    Rails.logger.error(error.message)
    Rails.logger.error(error.backtrace.join("\n"))
    # Sentry.capture_exception(error, extra: { message: error.message }) unless Rails.env.development?
    error_response(message: "Something went wrong", status: 500)
  end

  def error_response(message:, status:)
    throw :error, message: { error: message }, status: status
  end
end

This middleware captures common exceptions and transforms them into appropriate API responses. With it implemented, we can simplify our endpoints:

get ":id" do
  @event = Event.find(params[:id])
  present @event, with: ::Entities::EventResponse
end

The middleware will automatically capture the ActiveRecord::RecordNotFound exception and return an appropriate error response.

Testing Authentication

Now that we've implemented authentication, let's add some tests to ensure everything works correctly:

# spec/api/v1/login_spec.rb

require 'rails_helper'

RSpec.describe V1::Login, type: :request do
  let(:base_url) { "/api/v1/login" }
  let(:email) { "user@example.com" }
  let(:password) { "password123" }

  before do
    @user = create(:user, email: email, password: password)
  end

  describe "POST /api/v1/login" do
    context "with valid credentials" do
      it "returns a JWT token" do
        post base_url, params: { email: email, password: password }

        expect(response).to have_http_status(:success)
        json_response = JSON.parse(response.body)

        expect(json_response["user"]["id"]).to eq(@user.id)
        expect(json_response["user"]["email"]).to eq(@user.email)
        expect(json_response["token"]).not_to be_nil
      end
    end

    context "with invalid credentials" do
      it "returns an error" do
        post base_url, params: { email: email, password: "wrong_password" }

        expect(response).to have_http_status(:unauthorized)
        json_response = JSON.parse(response.body)

        expect(json_response["error"]).to eq("Unauthorized")
      end
    end
  end
end

Updated Swagger Documentation

With the addition of authentication and the login endpoint, our Swagger documentation will now show:

A new /login endpoint for authentication
Security information for all protected endpoints
An "Authorize" button in the Swagger interface to enter the JWT token

Conclusion

In this third part of our series, we implemented a complete authentication system for our Grape API:

Set up JWT to generate and verify tokens
Created helpers for authentication
Implemented a login endpoint
Protected our endpoints with authentication
Added middleware for error handling
Updated our Swagger documentation

Authentication is a crucial component for any API, and Grape makes it relatively simple to implement. By combining JWT with Grape's helpers, we achieved a robust authentication system that protects our resources and provides a pleasant developer experience.

In the next post, we'll explore more advanced Grape features such as pagination, sorting, and filtering to make our API even more powerful and flexible.

Did you like this post? Leave your comments below and don't forget to check out the previous parts of this series!

Example repository: https://github.com/rodrigonbarreto/event_reservation_system/tree/mvp_sample_pt3

References:

My name is Rodrigo Nogueira Barreto. I've been working with Ruby on Rails since 2015.

If you want to follow this journey, please comment and leave your like!

Criando APIs com Grape e Rails: Uma Jornada Completa - Parte 3

Rodrigo Barreto — Fri, 18 Apr 2025 12:47:16 +0000

Introdução

Olá, devs! 👋

Bem-vindos à terceira parte da nossa série sobre Grape e Rails! Nos posts anteriores, exploramos a configuração básica da API e implementamos operações CRUD para nossos eventos. Hoje, vamos dar um passo adiante e implementar autenticação para nossa API.

A segurança é um aspecto crucial de qualquer API, e implementar um sistema de autenticação robusto é essencial para proteger seus recursos. Neste post, vamos explorar como implementar autenticação com JWT (JSON Web Tokens) e como proteger nossas rotas.

Configurando Autenticação com JWT

Para nosso exemplo, vamos utilizar JWT para autenticação. Se você não está familiarizado com JWT, é um padrão para a criação de tokens de acesso que podem ser validados sem a necessidade de consultar um banco de dados. Os tokens JWT contêm informações sobre o usuário e expiram após um determinado período.

Primeiro, vamos adicionar as gems necessárias ao nosso projeto:

gem 'devise'  # Para autenticação de usuários
gem 'jwt'     # Para trabalhar com tokens JWT

Execute bundle install para instalar as dependências.

1. Criando o Serviço de JWT

Primeiro, precisamos criar um serviço para lidar com a codificação e decodificação de tokens JWT. Em app/services/jwt/json_web_token.rb:

# frozen_string_literal: true

module Jwt
  class JsonWebToken
    # SECRET = Rails.application.credentials.secret_key_base
    SECRET = "secret-key" # usar algum código no secrets ou algo mais seguro
    ENCRYPTION = "HS256"

    def self.encode(payload, exp = 120.hours.from_now)
      payload[:exp] = exp.to_i
      JWT.encode(payload, SECRET)
    rescue JWT::EncodeError => e
      Rails.logger.error("JWT Encode Error: #{e.message}")
    end

    def self.decode(token)
      body = JWT.decode(token, SECRET)[0]
      ActiveSupport::HashWithIndifferentAccess.new(body)
    rescue JWT::ExpiredSignature, JWT::DecodeError => e
      Rails.logger.error("JWT Encode Error: #{e.message}")
      nil
    end
  end
end

Observação: No ambiente de produção, você deve armazenar a chave secreta em um local seguro, como Rails.application.credentials.secret_key_base ou uma variável de ambiente.

2. Criando Helpers para Autenticação

Em seguida, vamos criar helpers para lidar com a autenticação em nossos endpoints. Em app/api/helpers/auth_helpers.rb:

# frozen_string_literal: true

module Helpers
  module AuthHelpers
    extend Grape::API::Helpers

    # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
    def authenticate_request!
      # Este exemplo é simplificado; no projeto real, usamos apenas headers["Authorization"]
      token = headers["Authorization"]&.split&.last || headers["authorization"]&.split&.last
      error!({ error: "Unauthorized", success: false }, 401) unless token

      # Decodifica o token JWT
      @jwt_result = Jwt::JsonWebToken.decode(token)
      error!({ error: "Invalid Token", success: false }, 401) unless @jwt_result

      # Busca o usuário atual (ou gera erro se não for encontrado)
      current_user!
    rescue StandardError => e
      error!({ error: "Authentication Error: #{e.message}" }, 401)
    end
    # rubocop:enable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity

    # Este método busca o usuário atual e gera erro se não for encontrado
    def current_user!
      @current_user ||= User.find_by(id: @jwt_result["id"])
      error!({ error: "Invalid Token", success: false }, 401) unless @current_user
      @current_user
    end

    # Este método permite usar o current_user em qualquer lugar
    def current_user
      @current_user
    end
  end
end

3. Implementando o Endpoint de Login

Agora, vamos criar um endpoint para autenticar usuários e gerar tokens JWT. Em app/api/v1/login.rb:

# frozen_string_literal: true

module V1
  class Login < Grape::API
    resource :login do
      desc "Login ", {
        success: Entities::Users::LoginResponse,
        failure: [{ code: 401, message: "Unauthorized" }],
        params: ::Helpers::ContractToParams.generate_params(LoginContract)
      }
      post do
        contract = LoginContract.new
        result = contract.call(params)
        error!({ errors: result.errors.to_h }, 422) if result.failure?

        @user = User.find_by(email: params[:email])
        if @user&.valid_password?(params[:password])
          token = ::Jwt::JsonWebToken.encode({ id: @user.id })
          status 200
          present({ user: @user, token: token }, with: Entities::Users::LoginResponse)
        else
          error!({ error: "Unauthorized" }, 401)
        end
      end
    end
  end
end

Nota: Este exemplo usa valid_password? do Devise, que é um método padrão para verificar senhas.

4. Definindo Entidades para Resposta de Login

Para formatar as respostas do endpoint de login, vamos criar algumas entidades:

Em app/api/entities/users/user_response.rb:

# frozen_string_literal: true

module Entities
  module Users
    class UserResponse < Grape::Entity
      expose :id, documentation: { type: "Integer", desc: "User id" }
      expose :email, documentation: { type: "String", desc: "User email" }
    end
  end
end

Em app/api/entities/users/login_response.rb:

# frozen_string_literal: true

module Entities
  module Users
    class LoginResponse < Grape::Entity
      expose :user, using: Entities::Users::UserResponse,
                   documentation: { type: "Array", desc: "List of users" }
      expose :token, documentation: { type: "String", desc: "JWT token" }
    end
  end
end

5. Atualizando o API Grape

Agora, vamos atualizar nosso arquivo app/api/v1/api_grape.rb para incluir os helpers de autenticação e o novo endpoint de login:

# frozen_string_literal: true

class V1::ApiGrape < Grape::API
  version "v1", using: :path
  format :json
  default_format :json

  use CustomErrorMiddleware

  helpers ::Helpers::AuthHelpers

  mount V1::Events
  mount V1::Login

  add_swagger_documentation(
    api_version: "v1",
    hide_documentation_path: true,
    mount_path: "/swagger_doc",
    hide_format: true,
    info: {
      title: "Events API",
      description: "API for event management",
      contact_name: "Support Team",
      contact_email: "contact@example.com"
    },
    security_definitions: {
      Bearer: {
        type: "apiKey",
        name: "Authorization",
        in: "header",
        description: 'Enter "Bearer" followed by your token. Example: Bearer abc123'
      }
    },
    security: [{ Bearer: [] }]
  )
end

6. Adicionando Dados de Teste

Para facilitar os testes, podemos criar um usuário padrão usando seeds:

# db/seeds.rb

User.find_or_create_by!(email: "teste@examle.com") do |user|
  user.password = "123456"
  user.password_confirmation = "123456"
end

Execute rails db:seed para criar o usuário.

Protegendo Endpoints

Com nossa configuração de autenticação em vigor, agora podemos proteger nossos endpoints. Vamos atualizar nosso controlador de eventos para exigir autenticação:

module V1
  class Events < Grape::API
    before { authenticate_request! }

    # Resto do código permanece o mesmo...
  end
end

Agora, todos os endpoints no recurso events exigirão um token JWT válido para acesso.

Implementando Middleware para Tratamento de Erros

Para melhorar ainda mais nossa API, vamos implementar um middleware personalizado para tratar erros comuns. Em app/middleware/custom_error_middleware.rb:

# frozen_string_literal: true

class CustomErrorMiddleware < Grape::Middleware::Base
  def call(env)
    @app.call(env) # Passa a requisição adiante
  rescue Grape::Exceptions::MethodNotAllowed => e
    handle_method_not_allowed(e, env)
  rescue ActiveRecord::RecordNotFound => e
    handle_record_not_found(e)
  rescue StandardError => e
    handle_standard_error(e)
  end

  private

  def handle_record_not_found(error)
    # Poderia usar, por exemplo: Sentry.capture_exception(error, extra: { message: error.message })
    error_response(message: "Couldn't find #{error.model || 'record'} with id: #{error.id}", status: 404)
  end

  def handle_method_not_allowed(error, env)
    request_method = env["REQUEST_METHOD"]
    path = env["PATH_INFO"]

    Rails.logger.error "Method not allowed: #{request_method} for path #{path}"

    allowed_methods = if error.respond_to?(:headers) && error.headers["Allow"]
                        "Allowed methods: #{error.headers['Allow']}"
                      else
                        "Please use the appropriate HTTP methods for this endpoint"
                      end

    error_message = "The
    #{request_method} method is not allowed for this resource.
   #{allowed_methods}. please check your parameters"

    unless Rails.env.development?
      # Sentry.capture_exception(error, extra: {
      #                            request_method: request_method,
      #                            path: path,
      #                            message: error_message
      #                          })
    end

    error_response(message: error_message, status: 405)
  end

  def handle_standard_error(error)
    Rails.logger.error(error.message)
    Rails.logger.error(error.backtrace.join("\n"))
    # Sentry.capture_exception(error, extra: { message: error.message }) unless Rails.env.development?
    error_response(message: "Something went wrong", status: 500)
  end

  def error_response(message:, status:)
    throw :error, message: { error: message }, status: status
  end
end

Este middleware captura exceções comuns e as transforma em respostas de API adequadas. Com ele implementado, podemos simplificar nossos endpoints:

get ":id" do
  @event = Event.find(params[:id])
  present @event, with: ::Entities::EventResponse
end

O middleware capturará automaticamente a exceção ActiveRecord::RecordNotFound e retornará uma resposta de erro apropriada.

Testando a Autenticação

Agora que implementamos a autenticação, vamos adicionar alguns testes para garantir que tudo funcione corretamente:

# spec/api/v1/login_spec.rb

require 'rails_helper'

RSpec.describe V1::Login, type: :request do
  let(:base_url) { "/api/v1/login" }
  let(:email) { "user@example.com" }
  let(:password) { "password123" }

  before do
    @user = create(:user, email: email, password: password)
  end

  describe "POST /api/v1/login" do
    context "with valid credentials" do
      it "returns a JWT token" do
        post base_url, params: { email: email, password: password }

        expect(response).to have_http_status(:success)
        json_response = JSON.parse(response.body)

        expect(json_response["user"]["id"]).to eq(@user.id)
        expect(json_response["user"]["email"]).to eq(@user.email)
        expect(json_response["token"]).not_to be_nil
      end
    end

    context "with invalid credentials" do
      it "returns an error" do
        post base_url, params: { email: email, password: "wrong_password" }

        expect(response).to have_http_status(:unauthorized)
        json_response = JSON.parse(response.body)

        expect(json_response["error"]).to eq("Unauthorized")
      end
    end
  end
end

Documentação Swagger Atualizada

Com a adição da autenticação e do endpoint de login, nossa documentação Swagger agora mostrará:

Um novo endpoint /login para autenticação
Informações de segurança para todos os endpoints protegidos
Um botão "Authorize" na interface Swagger para inserir o token JWT

Conclusão

Nesta terceira parte da nossa série, implementamos um sistema de autenticação completo para nossa API Grape:

Configuramos JWT para gerar e verificar tokens
Criamos helpers para autenticação
Implementamos um endpoint de login
Protegemos nossos endpoints com autenticação
Adicionamos middleware para tratamento de erros
Atualizamos nossa documentação Swagger

A autenticação é um componente crucial para qualquer API, e o Grape torna relativamente simples implementá-la. Ao combinar JWT com os helpers do Grape, conseguimos um sistema de autenticação robusto que protege nossos recursos e proporciona uma experiência de desenvolvedor agradável.

No próximo post, exploraremos recursos mais avançados do Grape, como paginação, ordenação e filtragem, para tornar nossa API ainda mais poderosa e flexível.

Gostou deste post? Deixe seus comentários abaixo e não se esqueça de conferir as partes anteriores desta série!

Repositório do exemplo: https://github.com/rodrigonbarreto/event_reservation_system/tree/mvp_sample_pt3

Referências:

Me chamo Rodrigo Nogueira Barreto. Trabalho com Ruby on Rails desde 2015.

Caso queiram acompanhar essa jornada, por favor comentem e deixem seu like!

Creating APIs with Grape and Rails: A Complete Journey - Part 2

Rodrigo Barreto — Sun, 13 Apr 2025 15:56:45 +0000

Introduction

Hello, devs! 👋

Welcome to the second part of our journey creating APIs with Grape and Rails. In Part 1, we covered the basics of setting up a Grape API and how to write effective tests. Today, we'll elevate our API by implementing two powerful gems that can significantly improve your development workflow:

dry-validation - For robust parameter validation
interactor - For clean, organized business logic

I'll also share a custom helper I created to simplify working with dry-validation in Grape APIs. It's something I developed quickly for an MVP, but it worked perfectly for our needs.

Setting Up Our Project

Let's add the necessary gems to our Gemfile:

gem 'grape'
gem 'grape-swagger'
gem 'grape-entity'
gem 'grape-swagger-entity'
gem 'rswag-ui'
gem 'rack-cors'

# Add these new gems
gem 'dry-validation', '~> 1.10'
gem 'interactor', '~> 3.1'

Run bundle install to install the dependencies.

The Power of Contracts with dry-validation

Instead of relying solely on Grape's built-in parameter validation, we can use dry-validation contracts to create more robust validation rules. Let's create two contracts for our event resource:

# app/contracts/events_create_contract.rb
# frozen_string_literal: true

class EventsCreateContract < Dry::Validation::Contract
  params do
    # @title = Event title, at least 3 characters long
    required(:title).filled(:string, min_size?: 3)

    # @description = Detailed description of the event
    optional(:description).maybe(:string)

    # @event_type = Type of event (business or birthday)
    required(:event_type).filled(:string, included_in?: %w[business birthday])

    # @number_of_people = Expected number of attendees
    optional(:number_of_people).maybe(:integer, gt?: 0)

    # @special_requests = Any special requirements for the event
    optional(:special_requests).maybe(:string)
  end

  rule(:number_of_people) do
    key.failure("must be provided for business events") if values[:event_type] == "business" && value.nil?
  end
end

Notice how we're using comments with a special format (# @parameter_name = description) - this is important for the custom helper we'll discuss later.

For update operations, we create a separate contract:

# app/contracts/events_update_contract.rb
# frozen_string_literal: true

class EventsUpdateContract < Dry::Validation::Contract
  params do
    # @id = Event ID
    required(:id).filled(:integer)

    # @title = Event title, at least 3 characters long
    required(:title).filled(:string, min_size?: 3)

    # @description = Detailed description of the event
    optional(:description).maybe(:string)

    # @event_type = Type of event (business or birthday)
    required(:event_type).filled(:string, included_in?: %w[business birthday])

    # @number_of_people = Expected number of attendees
    optional(:number_of_people).maybe(:integer, gt?: 0)

    # @special_requests = Any special requirements for the event
    optional(:special_requests).maybe(:string)
  end
end

You might be wondering why I created two separate contracts that look very similar. While it's tempting to follow the DRY principle and reuse the same contract, in practice, I've found that having separate contracts for different operations (create vs update) provides more flexibility. It's a pattern derived from the concept of DTOs (Data Transfer Objects), and we'll dive deeper into this in a future post!

The ContractToParams Helper: A Bridge Between dry-validation and Grape

One of the challenges when using dry-validation with Grape is that you end up defining parameters twice: once in the contract and once in the Grape endpoint. To solve this, I created a helper that automatically generates Grape parameter definitions from dry-validation contracts:

# app/api/helpers/contract_to_params.rb
# frozen_string_literal: true

module Helpers
  module ContractToParams
    extend Grape::API::Helpers

    def self.generate_params(contract_class, options = {})
      annotations = extract_annotations(contract_class)
      contract = contract_class.new
      param_type = options[:param_type] || 'body'

      contract.schema.rules.each_with_object({}) do |(name, rule), params_hash|
        type = extract_type(rule)
        required = !optional_field?(rule)
        description = annotations[name] || name.to_s.humanize

        params_hash[name] = {
          type: type,
          desc: description,
          required: required,
          documentation: { param_type: param_type }
        }
      end
    end

    def self.extract_annotations(contract_class)
      # Read the source file content using the class path
      file_path = contract_class.name.underscore
      paths_to_try = [
        Rails.root.join("app/contracts/", "#{file_path}.rb"),
        Rails.root.join("app/api/contracts/", "#{file_path}.rb"),
        Rails.root.join("app/models/#{file_path}.rb")
      ]

      source_path = paths_to_try.find { |path| File.exist?(path) }
      return {} unless source_path

      source_lines = File.readlines(source_path)
      annotations = {}
      field_pattern = /\s*(optional|required)\(:([\w_]+)\)/

      source_lines.each_with_index do |line, index|
        next unless line.match?(field_pattern)

        field_name = line.match(field_pattern)[2]

        previous_line = source_lines[index - 1]
        if previous_line&.match?(/^\s*#\s*@#{field_name}\s*=\s*(.+)/)
          annotations[field_name.to_sym] = previous_line.match(/^\s*#\s*@#{field_name}\s*=\s*(.+)/)[1].strip
        end
      end

      annotations
    end

    def self.extract_type(rule)
      predicates = extract_all_predicates(rule)

      return [TrueClass, FalseClass] if predicates.include?(:bool?)
      return Integer if predicates.include?(:int?) || predicates.include?(:integer?)
      return Float if predicates.include?(:float?)
      return Array if predicates.include?(:array?)
      return Hash if predicates.include?(:hash?)
      return Date if predicates.include?(:date?)
      return Time if predicates.include?(:time?)

      String
    end

    def self.extract_all_predicates(rule)
      predicates = []

      case rule
      when Dry::Logic::Operations::And, Dry::Logic::Operations::Or
        rule.rules.each do |sub_rule|
          predicates.concat(extract_all_predicates(sub_rule))
        end
      when Dry::Logic::Operations::Key
        predicates.concat(extract_all_predicates(rule.rules.first))
      when Dry::Logic::Operations::Implication
        predicates << :optional
        rule.rules.each do |sub_rule|
          predicates.concat(extract_all_predicates(sub_rule))
        end
      when Dry::Logic::Rule::Predicate
        predicates << rule.predicate.name if rule.predicate&.name
      end

      predicates.uniq
    end

    def self.optional_field?(rule)
      return true if rule.is_a?(Dry::Logic::Operations::Implication)

      if rule.is_a?(Dry::Logic::Operations::And)
        rule.rules.any? do |sub_rule|
          sub_rule.is_a?(Dry::Logic::Operations::Implication)
        end
      else
        false
      end
    end
  end
end

This helper was created in a hurry and I work on improving it whenever I can, but currently it meets 99% of our project's needs.

As you can see in the images, our helper improves our documentation as shown below:

Organizing Business Logic with Interactors

If you speak Portuguese, I highly recommend taking Jackson Pires' course at https://videosdeti.com.br/ - he teaches how to use the Interactors gem effectively, among other things.

The interactor gem helps us divide business logic into small, focused classes. Let's see how we implemented this for our events resource:

# app/services/events/interactors/create_event.rb
# frozen_string_literal: true

module Events
  module Interactors
    class CreateEvent
      include Interactor

      delegate :params, to: :context
      def call
        event = Event.new(context.params)

        if event.save
          context.event = event
        else
          context.fail!(errors: event.errors)
        end
      end
    end
  end
end

This interactor has a single responsibility: creating an event in the database.

Next, we create an interactor to send a notification after the event is created:

# app/services/events/interactors/send_notification.rb
# frozen_string_literal: true

module Events
  module Interactors
    class SendNotification
      include Interactor

      delegate :event, to: :context
      def call
        Rails.logger.info("Event '#{event.title}' was created successfully!")

        # Here you could send an actual notification via email, SMS, etc.
        # For demonstration purposes, we're just logging a message
      end
    end
  end
end

Finally, we create an organizer to coordinate these interactors:

# app/services/events/organizers/register.rb
# frozen_string_literal: true

module Events
  module Organizers
    class Register
      include Interactor::Organizer

      organize ::Events::Interactors::CreateEvent,
               ::Events::Interactors::SendNotification

      around do |interactor|
        ActiveRecord::Base.transaction do
          interactor.call
          raise ActiveRecord::Rollback if context.failure?
        end
      end
    end
  end
end

The organizer does two important things:

Defines the order of execution for the interactors using organize
Wraps the execution in a transaction, ensuring that if any interactor fails, all database changes are rolled back

What's amazing about this pattern is how it makes business logic easy to understand, test, and maintain.

Integrating With Our Grape API

Now, let's put everything together and see how our Grape API looks with these improvements:

# app/api/v1/events.rb
# frozen_string_literal: true

module V1
  class Events < Grape::API
    # this is just an example for this post, I recommend better planning and creating something like
    # FormatErrorHelpers and calling
    # helpers ::Helpers::FormatErrorHelpers
    helpers do
      def format_errors(errors)
        case errors
        when ActiveModel::Errors
          errors.messages.transform_values { |messages| messages.join(", ") }
        when Hash
          errors
        else
          { base: errors.to_s }
        end
      end
    end

    resource :events do
      desc "Get all events", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" }
        ],
        tags: ["events"]
      }
      get do
        @events = Event.all
        present @events, with: ::Entities::EventResponse
      end

      desc "Get a specific event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" }
        ],
        params: {
          id: { type: Integer, desc: "Event ID" }
        },
        tags: ["events"]
      }
      get ":id" do
        @event = Event.find(params[:id])
        present @event, with: ::Entities::EventResponse
      rescue ActiveRecord::RecordNotFound
        error!({ error: "Event not found" }, 404)
      end

      desc "Create a new event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 422, message: "Unprocessable Entity" }
        ],
        params: ::Helpers::ContractToParams.generate_params(EventsCreateContract)
      }
      post do
        contract = EventsCreateContract.new
        result = contract.call(params)
        error!({ errors: result.errors.to_h }, 422) if result.failure?

        service_result = ::Events::Organizers::Register.call(params: result.to_h)

        if service_result.success?
          present service_result.event, with: ::Entities::EventResponse, status: :created
        else
          error!({ errors: format_errors(service_result.errors) }, 422)
        end
      end

      desc "Update an existing event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" },
          { code: 422, message: "Unprocessable Entity" }
        ],
        params: ::Helpers::ContractToParams.generate_params(EventsUpdateContract),
        # Even though the fields are practically the same, we know that details make all the difference!
        # I recommend using EventsUpdateContract - repeating the fields from EventsCreateContract, not everything needs to be 100% DRY (Don't Repeat Yourself).
        # And this applies to DTOs (yes, our contracts too!).
        # But feel free to use inheritance or modules to avoid repeating fields; the important thing is that you and your team agree and have fun.
        #
        # And if you're curious about why I don't use abstraction in DTOs... maybe we'll discuss that in a future post!
        tags: ["events"]
      }
      put ":id" do
        contract = EventsUpdateContract.new
        result = contract.call(params)
        error!({ errors: result.errors.to_h }, 422) if result.failure?

        @event = ::Event.find(params[:id])
        @event.assign_attributes(result.to_h)

        if @event.save
          present @event, with: ::Entities::EventResponse
        else
          error!({ errors: format_errors(@event.errors) }, 422)
        end
      rescue ActiveRecord::RecordNotFound
        error!({ error: "Event not found" }, 404)
      end

      desc "Delete an event", {
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" }
        ],
        params: {
          id: { type: Integer, desc: "Event ID" }
        },
        tags: ["events"]
      }
      delete ":id" do
        @event = Event.find(params[:id])

        if @event.destroy
          { success: true, message: "Event successfully deleted" }
        else
          error!({ errors: format_errors(@event.errors) }, 422)
        end
      rescue ActiveRecord::RecordNotFound
        error!({ error: "Event not found" }, 404)
      end
    end
  end
end

Notice how our API is cleaner and more organized:

We use ::Helpers::ContractToParams.generate_params(EventsCreateContract) to automatically generate parameter documentation.
We validate parameters with dry-validation contracts.
We delegate business logic to interactors.

And here's our main Grape API configuration:

# app/api/v1/api_grape.rb
# frozen_string_literal: true

class V1::ApiGrape < Grape::API
  version "v1", using: :path
  format :json
  default_format :json

  mount V1::Events

  add_swagger_documentation(
    api_version: "v1",
    hide_documentation_path: true,
    mount_path: "/swagger_doc",
    hide_format: true,
    info: {
      title: "Events API",
      description: "API for event management",
      contact_name: "Support Team",
      contact_email: "contact@example.com"
    },
    security_definitions: {
      Bearer: {
        type: "apiKey",
        name: "Authorization",
        in: "header",
        description: 'Enter "Bearer" followed by your token. Example: Bearer abc123'
      }
    },
    security: [{ Bearer: [] }]
  )
end

Benefits of This Approach

We use contracts (a kind of DTO) for business validation in the request rather than in the model. We use models only to represent database rules (in the project my friend and I are working on, even with validation in the models, we also have validation rules in the database itself so the project isn't dependent on a framework).

After implementing these patterns in our project, we noticed several benefits:

Using dry-validation Contracts

Separation of concerns: Validation is completely separate from the API and models.
More powerful validations: We can express complex business rules clearly.
Reusability: Contracts can be used in different contexts, not just in the API.
Automatic documentation: With our custom helper, documentation is generated automatically.

Using Interactors

Modular code: Each interactor has a single responsibility.
Easy to test: Interactors can be tested in isolation.
Transaction control: The organizer takes care of wrapping everything in a transaction.
Readability: It's easy to understand the business flow by looking at the organizer.

One thing I'd like to highlight is my decision to use separate contracts for creation and updating. Although they contain similar fields, I believe that keeping our Contracts (a kind of DTO) separate is a good practice. Validation needs for creation and updating often diverge over time, and having separate contracts gives us flexibility to evolve.

Conclusion

In this post, we explored how to elevate our Grape API using dry-validation for parameter validation and interactors for organizing business logic. I also shared a custom helper I developed to facilitate integration between dry-validation and Grape.

Although some of these solutions were developed quickly for an MVP, they demonstrate how we can create more robust and maintainable APIs with relatively little effort.

In the next post, we'll talk about Policies and Authorization with login using JWT tokens. Stay tuned!

Have you used dry-validation or interactors in your Rails projects? What was your experience? Leave a comment below!

Repository: https://github.com/rodrigonbarreto/event_reservation_system/tree/mvp_sample_pt2

References:

Rodrigo Nogueira Ruby on Rails Developer since 2015
Postgraduate in Software Engineering (PUC-RJ) & passionate about technology since 2011.

Criando APIs com Grape e Rails: Uma Jornada Completa - Parte 2

Rodrigo Barreto — Sun, 13 Apr 2025 15:40:17 +0000

Introdução

Olá, devs! 👋

Bem-vindos à segunda parte da nossa jornada criando APIs com Grape e Rails. Na Parte 1, abordamos o básico da configuração de uma API Grape e como escrever testes eficazes. Hoje, vamos elevar o nível da nossa API implementando duas gems poderosas que podem melhorar significativamente seu fluxo de desenvolvimento:

dry-validation - Para validação robusta de parâmetros
interactor - Para uma lógica de negócios limpa e organizada

Também vou compartilhar um helper personalizado que criei para simplificar o trabalho com dry-validation em APIs Grape. Foi algo que desenvolvi rapidamente para um MVP, mas funcionou perfeitamente para nossas necessidades.

Configurando Nosso Projeto

Vamos adicionar as gems necessárias ao nosso Gemfile:

gem 'grape'
gem 'grape-swagger'
gem 'grape-entity'
gem 'grape-swagger-entity'
gem 'rswag-ui'
gem 'rack-cors'

# Adicione essas novas gems
gem 'dry-validation', '~> 1.10'
gem 'interactor', '~> 3.1'

Execute bundle install para instalar as dependências.

O Poder dos Contratos com dry-validation

Em vez de depender apenas da validação de parâmetros integrada do Grape, podemos usar contratos do dry-validation para criar regras de validação mais robustas. Vamos criar dois contratos para nosso recurso de eventos:

# app/contracts/events_create_contract.rb
# frozen_string_literal: true

class EventsCreateContract < Dry::Validation::Contract
  params do
    # @title = Título do evento, com no mínimo 3 caracteres
    required(:title).filled(:string, min_size?: 3)

    # @description = Descrição detalhada do evento
    optional(:description).maybe(:string)

    # @event_type = Tipo de evento (business ou birthday)
    required(:event_type).filled(:string, included_in?: %w[business birthday])

    # @number_of_people = Número esperado de participantes
    optional(:number_of_people).maybe(:integer, gt?: 0)

    # @special_requests = Quaisquer requisitos especiais para o evento
    optional(:special_requests).maybe(:string)
  end

  rule(:number_of_people) do
    key.failure("must be provided for business events") if values[:event_type] == "business" && value.nil?
  end
end

Observe como estamos usando comentários com um formato especial (# @nome_do_parametro = descrição) - isso é importante para o helper personalizado que discutiremos mais adiante.

Para operações de atualização, criamos um contrato separado:

# app/contracts/events_update_contract.rb
# frozen_string_literal: true

class EventsUpdateContract < Dry::Validation::Contract
  params do
    # @id = ID do evento
    required(:id).filled(:integer)

    # @title = Título do evento, com no mínimo 3 caracteres
    required(:title).filled(:string, min_size?: 3)

    # @description = Descrição detalhada do evento
    optional(:description).maybe(:string)

    # @event_type = Tipo de evento (business ou birthday)
    required(:event_type).filled(:string, included_in?: %w[business birthday])

    # @number_of_people = Número esperado de participantes
    optional(:number_of_people).maybe(:integer, gt?: 0)

    # @special_requests = Quaisquer requisitos especiais para o evento
    optional(:special_requests).maybe(:string)
  end
end

Você pode estar se perguntando por que criei dois contratos separados que parecem muito semelhantes. Embora seja tentador seguir o princípio DRY e reutilizar o mesmo contrato, na prática, descobri que ter contratos separados para diferentes operações (criar vs atualizar) oferece mais flexibilidade. É um padrão derivado do conceito de DTOs (Data Transfer Objects), e vamos nos aprofundar nisso em um post futuro!

O Helper ContractToParams: Uma Ponte Entre dry-validation e Grape

Um dos desafios ao usar dry-validation com Grape é que você acaba definindo parâmetros duas vezes: uma vez no contrato e outra vez no endpoint do Grape. Para resolver isso, eu criei um helper que gera automaticamente definições de parâmetros do Grape a partir de contratos do dry-validation:

# app/api/helpers/contract_to_params.rb
# frozen_string_literal: true

module Helpers
  module ContractToParams
    extend Grape::API::Helpers

    def self.generate_params(contract_class, options = {})
      annotations = extract_annotations(contract_class)
      contract = contract_class.new
      param_type = options[:param_type] || 'body'

      contract.schema.rules.each_with_object({}) do |(name, rule), params_hash|
        type = extract_type(rule)
        required = !optional_field?(rule)
        description = annotations[name] || name.to_s.humanize

        params_hash[name] = {
          type: type,
          desc: description,
          required: required,
          documentation: { param_type: param_type }
        }
      end
    end

    def self.extract_annotations(contract_class)
      # Lê o conteúdo do arquivo fonte usando o path da classe
      file_path = contract_class.name.underscore
      paths_to_try = [
        Rails.root.join("app/contracts/", "#{file_path}.rb"),
        Rails.root.join("app/api/contracts/", "#{file_path}.rb"),
        Rails.root.join("app/models/#{file_path}.rb")
      ]

      source_path = paths_to_try.find { |path| File.exist?(path) }
      return {} unless source_path

      source_lines = File.readlines(source_path)
      annotations = {}
      field_pattern = /\s*(optional|required)\(:([\w_]+)\)/

      source_lines.each_with_index do |line, index|
        next unless line.match?(field_pattern)

        field_name = line.match(field_pattern)[2]

        previous_line = source_lines[index - 1]
        if previous_line&.match?(/^\s*#\s*@#{field_name}\s*=\s*(.+)/)
          annotations[field_name.to_sym] = previous_line.match(/^\s*#\s*@#{field_name}\s*=\s*(.+)/)[1].strip
        end
      end

      annotations
    end

    def self.extract_type(rule)
      predicates = extract_all_predicates(rule)

      return [TrueClass, FalseClass] if predicates.include?(:bool?)
      return Integer if predicates.include?(:int?) || predicates.include?(:integer?)
      return Float if predicates.include?(:float?)
      return Array if predicates.include?(:array?)
      return Hash if predicates.include?(:hash?)
      return Date if predicates.include?(:date?)
      return Time if predicates.include?(:time?)

      String
    end

    def self.extract_all_predicates(rule)
      predicates = []

      case rule
      when Dry::Logic::Operations::And, Dry::Logic::Operations::Or
        rule.rules.each do |sub_rule|
          predicates.concat(extract_all_predicates(sub_rule))
        end
      when Dry::Logic::Operations::Key
        predicates.concat(extract_all_predicates(rule.rules.first))
      when Dry::Logic::Operations::Implication
        predicates << :optional
        rule.rules.each do |sub_rule|
          predicates.concat(extract_all_predicates(sub_rule))
        end
      when Dry::Logic::Rule::Predicate
        predicates << rule.predicate.name if rule.predicate&.name
      end

      predicates.uniq
    end

    def self.optional_field?(rule)
      return true if rule.is_a?(Dry::Logic::Operations::Implication)

      if rule.is_a?(Dry::Logic::Operations::And)
        rule.rules.any? do |sub_rule|
          sub_rule.is_a?(Dry::Logic::Operations::Implication)
        end
      else
        false
      end
    end
  end
end

Este helper foi feito às pressas e sempre que posso trabalho em melhorias nele, mas atualmente supre 99% a necessidade do nosso projeto.

Como você vê nas fotos, o nosso helper ajuda a melhorar nossa documentação seguem as fotos abaixo

Organizando a Lógica de Negócios com Interactors

Se você fala português super recomendo fazer o curso do Jackson Pires no site https://videosdeti.com.br/ ele ensina a usar bem a gem Interactors entre outras coisas.

A gem interactor nos ajuda a dividir a lógica de negócios em pequenas classes focadas. Vamos ver como implementamos isso para nosso recurso de eventos:

# app/services/events/interactors/create_event.rb
# frozen_string_literal: true

module Events
  module Interactors
    class CreateEvent
      include Interactor

      delegate :params, to: :context
      def call
        event = Event.new(context.params)

        if event.save
          context.event = event
        else
          context.fail!(errors: event.errors)
        end
      end
    end
  end
end

Este interactor tem uma única responsabilidade: criar um evento no banco de dados.

Em seguida, criamos um interactor para enviar uma notificação após a criação do evento:

# app/services/events/interactors/send_notification.rb
# frozen_string_literal: true

module Events
  module Interactors
    class SendNotification
      include Interactor

      delegate :event, to: :context
      def call
        Rails.logger.info("Event '#{event.title}' was created successfully!")

        # Aqui você poderia enviar uma notificação real via email, SMS, etc.
        # Para fins de demonstração, estamos apenas registrando uma mensagem
      end
    end
  end
end

Finalmente, criamos um organizador para coordenar esses interactors:

# app/services/events/organizers/register.rb
# frozen_string_literal: true

module Events
  module Organizers
    class Register
      include Interactor::Organizer

      organize ::Events::Interactors::CreateEvent,
               ::Events::Interactors::SendNotification

      around do |interactor|
        ActiveRecord::Base.transaction do
          interactor.call
          raise ActiveRecord::Rollback if context.failure?
        end
      end
    end
  end
end

O organizador faz duas coisas importantes:

Define a ordem de execução dos interactors usando organize
Envolve a execução em uma transação, garantindo que, se qualquer interactor falhar, todas as mudanças no banco de dados sejam revertidas

O que é incrível sobre esse padrão é como ele torna a lógica de negócios fácil de entender, testar e manter.

Integrando Com Nossa API Grape

Agora, vamos juntar tudo e ver como nossa API Grape fica com essas melhorias:

# app/api/v1/events.rb
# frozen_string_literal: true

module V1
  class Events < Grape::API
    # este é um exemplo apenas pro post, recomendo planejar melhor e criar algo como
    # FormatErrorHelpers e chamando
    # helpers ::Helpers::FormatErrorHelpers
    helpers do
      def format_errors(errors)
        case errors
        when ActiveModel::Errors
          errors.messages.transform_values { |messages| messages.join(", ") }
        when Hash
          errors
        else
          { base: errors.to_s }
        end
      end
    end

    resource :events do
      desc "Get all events", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" }
        ],
        tags: ["events"]
      }
      get do
        @events = Event.all
        present @events, with: ::Entities::EventResponse
      end

      desc "Get a specific event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" }
        ],
        params: {
          id: { type: Integer, desc: "Event ID" }
        },
        tags: ["events"]
      }
      get ":id" do
        @event = Event.find(params[:id])
        present @event, with: ::Entities::EventResponse
      rescue ActiveRecord::RecordNotFound
        error!({ error: "Event not found" }, 404)
      end

      desc "Create a new event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 422, message: "Unprocessable Entity" }
        ],
        params: ::Helpers::ContractToParams.generate_params(EventsCreateContract)
      }
      post do
        contract = EventsCreateContract.new
        result = contract.call(params)
        error!({ errors: result.errors.to_h }, 422) if result.failure?

        service_result = ::Events::Organizers::Register.call(params: result.to_h)

        if service_result.success?
          present service_result.event, with: ::Entities::EventResponse, status: :created
        else
          error!({ errors: format_errors(service_result.errors) }, 422)
        end
      end

      desc "Update an existing event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" },
          { code: 422, message: "Unprocessable Entity" }
        ],
        params: ::Helpers::ContractToParams.generate_params(EventsUpdateContract),
        # Mesmo que os campos sejam praticamente os mesmos, a gente sabe que os detalhes fazem toda a diferença!
        # Recomendo usar o EventsUpdateContract – repetindo os campos do EventsCreateContract, nem tudo precisa ser 100% DRY (Don't Repeat Yourself).
        # E isso vale para os DTOs (sim, nossos contracts também!).
        # Mas fique à vontade para usar herança ou módulos para evitar repetir os campos; o importante é que você e sua equipe entrem em acordo e se divirtam.
        #
        # Ah, e se vocês tiverem curiosidade sobre por que eu não uso abstração em DTOs... quem sabe a gente discute isso num próximo post!
        tags: ["events"]
      }
      put ":id" do
        contract = EventsUpdateContract.new
        result = contract.call(params)
        error!({ errors: result.errors.to_h }, 422) if result.failure?

        @event = ::Event.find(params[:id])
        @event.assign_attributes(result.to_h)

        if @event.save
          present @event, with: ::Entities::EventResponse
        else
          error!({ errors: format_errors(@event.errors) }, 422)
        end
      rescue ActiveRecord::RecordNotFound
        error!({ error: "Event not found" }, 404)
      end

      desc "Delete an event", {
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" }
        ],
        params: {
          id: { type: Integer, desc: "Event ID" }
        },
        tags: ["events"]
      }
      delete ":id" do
        @event = Event.find(params[:id])

        if @event.destroy
          { success: true, message: "Event successfully deleted" }
        else
          error!({ errors: format_errors(@event.errors) }, 422)
        end
      rescue ActiveRecord::RecordNotFound
        error!({ error: "Event not found" }, 404)
      end
    end
  end
end

Observe como nossa API está mais limpa e organizada:

Usamos ::Helpers::ContractToParams.generate_params(EventsCreateContract) para gerar automaticamente a documentação de parâmetros.
Validamos os parâmetros com os contratos do dry-validation.
Delegamos a lógica de negócios a interactors.

E aqui está nossa configuração principal da API Grape:

# app/api/v1/api_grape.rb
# frozen_string_literal: true

class V1::ApiGrape < Grape::API
  version "v1", using: :path
  format :json
  default_format :json

  mount V1::Events

  add_swagger_documentation(
    api_version: "v1",
    hide_documentation_path: true,
    mount_path: "/swagger_doc",
    hide_format: true,
    info: {
      title: "Events API",
      description: "API for event management",
      contact_name: "Support Team",
      contact_email: "contact@example.com"
    },
    security_definitions: {
      Bearer: {
        type: "apiKey",
        name: "Authorization",
        in: "header",
        description: 'Enter "Bearer" followed by your token. Example: Bearer abc123'
      }
    },
    security: [{ Bearer: [] }]
  )
end

Benefícios Desta Abordagem

Usamos os contracts (uma espécie de DTO) para as validações de negócio no request e não no modelo, usamos os modelos apenas para representar as regras do banco de dados (no nosso projeto que eu e meu amigo estamos trabalhando, mesmo com validação nos modelos também temos as regras de validação no próprio banco de dados para o projeto não ser refém de um framework).

Depois de implementar esses padrões em nosso projeto, percebemos vários benefícios:

Usando Contratos dry-validation

Separação de responsabilidades: A validação está completamente separada da API e dos modelos.
Validações mais poderosas: Podemos expressar regras de negócios complexas de maneira clara.
Reutilização: Os contratos podem ser usados em diferentes contextos, não apenas na API.
Documentação automática: Com nosso helper personalizado, a documentação é gerada automaticamente.

Usando Interactors

Código modular: Cada interactor tem uma única responsabilidade.
Fácil de testar: Interactors podem ser testados isoladamente.
Controle transacional: O organizador cuida de envolver tudo em uma transação.
Legibilidade: É fácil entender o fluxo de negócios olhando para o organizador.

Uma coisa que eu gostaria de destacar é minha decisão de usar contratos separados para criação e atualização. Embora eles contenham campos semelhantes, eu acredito que manter os nossos Contracts (uma espécie de DTO) separados é uma boa prática. As necessidades de validação para criação e atualização muitas vezes divergem com o tempo, e ter contratos separados nos dá flexibilidade para evoluir.

Conclusão

Neste post, exploramos como elevar o nível da nossa API Grape usando dry-validation para validação de parâmetros e interactors para organizar a lógica de negócios. Também compartilhei um helper personalizado que desenvolvi para facilitar a integração entre dry-validation e Grape.

Embora algumas dessas soluções tenham sido desenvolvidas rapidamente para um MVP, elas demonstram como podemos criar APIs mais robustas e manuteníveis com relativamente pouco esforço.

No próximo post vamos falar de Middleware,Policies e Authorization com login usando JWT tokens, com isso o projeto vai ficar mais robusto ainda. Fique ligado!

Você já usou dry-validation ou interactors em seus projetos Rails? Qual foi sua experiência? Deixe um comentário abaixo!

Repositório: https://github.com/rodrigonbarreto/event_reservation_system/tree/mvp_sample_pt2

Referências:

Me chamo Rodrigo Nogueira - Desenvolvedor Ruby on Rails desde 2015
Pós em Engenharia de Software (PUC-RJ) e trabalho com tecnologia desde 2011.
Se você quiser acompanhar esta jornada, por favor, comente e deixe seu like!

Creating APIs with Grape and Rails: A Complete Journey - Part 1

Rodrigo Barreto — Sat, 12 Apr 2025 13:23:46 +0000

Introduction

Hello, devs! 👋

Last year, I embarked on a project with a friend where we decided to create an application using Ruby on Rails for the backend API and React for the frontend. As many of you know, creating a robust and well-documented API can be a challenging task, especially when you want to focus more on development than documentation.

This journey began when I realized I was tired of writing RSpec tests just to generate documentation with Rswag. So we made a decision: we will write tests, but to validate our code as it should be done, not to generate API documentation.

That's when we decided to use Grape. At first, I confess there was some resistance and distrust from my friend. But today, with our stack 100% ready, I can confidently say it was one of the best decisions I convinced him to make. He also trusted and gave 100% support in these types of decisions.

In this series of posts, I'll share our complete journey, from basic configuration to more advanced features. In today's post, I'll show you how to set up an API using Grape with Rails and write effective tests for it.

What is Grape?

Grape is a framework for building REST-like APIs in Ruby. It's designed to work with frameworks like Rails and Sinatra, or even standalone. Some of the features that made us choose Grape include:

Clear and expressive syntax for defining endpoints and routes
Integrated parameter validation
Flexible response formatting
Automatic documentation with Swagger
Simplified API versioning

Installation and Initial Setup

To get started, we need to add the necessary gems to our project. Add these gems to your Gemfile:

gem 'grape'
gem 'grape-swagger'
gem 'grape-entity'
gem 'grape-swagger-entity'
gem 'rswag-ui'
gem 'rack-cors'

Run bundle install to install the dependencies.

Setting Up the Project

Let's start with a simple model for our events:

class Event < ApplicationRecord
  enum event_type: { business: 'business', birthday: 'birthday' }
end

File Structure

To keep our code organized, we created the following directory structure:

app/
├── api/
│   ├── entities/
│   │   └── event_response.rb
│   └── v1/
│       ├── api_grape.rb
│       └── events.rb
└── models/
    └── event.rb

Route Configuration

In the config/routes.rb file, we mount our API and Swagger documentation:

Rails.application.routes.draw do
  mount Rswag::Ui::Engine => "/api-docs"

  mount V1::ApiGrape => "api", as: :v1_api

  # The code below is commented out, as we're now using Grape instead of Rails' default routes
  # namespace :api do
  #   namespace :v1 do
  #     resources :events
  #   end
  # end
end

Swagger UI Configuration

To improve the API documentation viewing experience, let's configure Rswag UI to point to our Swagger documentation generated by Grape. In config/initializers/rswag_ui.rb:

Rswag::Ui.configure do |c|
  # This is the URL generated by grape-swagger and our configuration file app/api/v1/api_grape.rb
  c.swagger_endpoint "/api/v1/swagger_doc.json", "Events V1 Docs"

  # Add Basic Auth in case your API is private
  # c.basic_auth_enabled = true
  # c.basic_auth_credentials 'username', 'password'
end

It's important to highlight that the endpoint /api/v1/swagger_doc.json generates documentation in OpenAPI 2.0 format. I'm using mount Rswag::Ui::Engine to make the documentation view more pleasant, although I've already started working on a gem to generate OpenAPI 3.0 documentation (a topic for a future post). Even so, this configuration has worked perfectly for the working scenario between me and my friend.

Defining the API

The main API configuration is in the app/api/v1/api_grape.rb file:

# frozen_string_literal: true

class V1::ApiGrape < Grape::API
  version "v1", using: :path
  format :json
  default_format :json

  # Mount your endpoints here
  mount V1::Events

  add_swagger_documentation(
    api_version: "v1",
    hide_documentation_path: true,
    mount_path: "/swagger_doc",
    hide_format: true,
    info: {
      title: "Events API",
      description: "API for event management",
      contact_name: "Support Team",
      contact_email: "contact@example.com"
    },
    security_definitions: {
      Bearer: {
        type: "apiKey",
        name: "Authorization",
        in: "header",
        description: 'Enter "Bearer" followed by your token. Example: Bearer abc123'
      }
    },
    security: [{ Bearer: [] }]
  )
end

Implementing the Endpoints

In the app/api/v1/events.rb file, we implement the complete CRUD for our events:

# frozen_string_literal: true

module V1
  class Events < Grape::API
    helpers do
      def event_params
        ActionController::Parameters.new(params).permit(
          :title,
          :description,
          :event_type,
          :number_of_people,
          :special_requests
        )
      end

      def find_event
        @event = Event.find(params[:id])
      rescue ActiveRecord::RecordNotFound
        error!({ error: "Event not found" }, 404)
      end
    end

    resource :events do
      desc "Get all events", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" }
        ],
        tags: ["events"]
      }
      get do
        @events = Event.all
        present @events, with: ::Entities::EventResponse
      end

      desc "Get a specific event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" }
        ],
        tags: ["events"]
      }
      params do
        requires :id, type: Integer, desc: "Event ID"
      end
      get ":id" do
        find_event
        present @event, with: ::Entities::EventResponse
      end

      desc "Create a new event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 422, message: "Unprocessable Entity" }
        ],
        tags: ["events"]
      }
      params do
        requires :title, type: String, desc: "Event title"
        requires :event_type, type: String, values: %w[business birthday], desc: "Event type"
        optional :description, type: String, desc: "Event description"
        optional :number_of_people, type: Integer, desc: "Number of attendees"
        optional :special_requests, type: String, desc: "Special requests"
      end
      post do
        @event = Event.new(event_params)
        if @event.save
          present @event, with: ::Entities::EventResponse
        else
          error!({ errors: @event.errors.full_messages }, 422)
        end
      end

      desc "Update an existing event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" },
          { code: 422, message: "Unprocessable Entity" }
        ],
        tags: ["events"]
      }
      params do
        requires :id, type: Integer, desc: "Event ID"
        optional :title, type: String, desc: "Event title"
        optional :event_type, type: String, values: %w[business birthday], desc: "Event type"
        optional :description, type: String, desc: "Event description"
        optional :number_of_people, type: Integer, desc: "Number of attendees"
        optional :special_requests, type: String, desc: "Special requests"
      end
      put ":id" do
        find_event
        if @event.update(event_params)
          present @event, with: ::Entities::EventResponse
        else
          error!({ errors: @event.errors.full_messages }, 422)
        end
      end

      desc "Delete an event", {
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" }
        ],
        tags: ["events"]
      }
      params do
        requires :id, type: Integer, desc: "Event ID"
      end
      delete ":id" do
        find_event
        if @event.destroy
          { success: true, message: "Event successfully deleted" }
        else
          error!({ errors: @event.errors.full_messages }, 422)
        end
      end
    end
  end
end

Defining Entities for Data Representation

To format our API responses, we use Grape entities in app/api/entities/event_response.rb:

# frozen_string_literal: true

module Entities
  class EventResponse < Grape::Entity
    expose :id, documentation: { type: "Integer", desc: "Event ID" }
    expose :title, documentation: { type: "String", desc: "Event Title" }
    expose :description, documentation: { type: "String", desc: "Event Description" }
    expose :event_type, documentation: { type: "String", desc: "Event Type" }
    expose :number_of_people, documentation: { type: "Integer", desc: "Number of People" }
    expose :special_requests, documentation: { type: "String", desc: "Special Requests" }
  end
end

Testing the API with RSpec

One of the great advantages of Grape is that we can write direct and efficient tests for our API without needing to generate documentation through them. Let's see how this works:

Setting Up Tests

First, add the necessary gems to your Gemfile:

group :development, :test do
  gem 'rspec-rails'
  gem 'factory_bot_rails'
end

Run bundle install and configure RSpec with rails generate rspec:install.

Creating Factory for Tests

In spec/factories/events.rb:

# frozen_string_literal: true

FactoryBot.define do
  factory :event do
    title { "Event Title" }
    description { "Event Description" }
    event_type { "business" }
    number_of_people { 5 }
    special_requests { "Event Special Requests" }

    trait :business do
      event_type { "business" }
    end

    trait :birthday do
      event_type { "birthday" }
    end
  end
end

Testing the Endpoints

In spec/api/v1/events_spec.rb:

# frozen_string_literal: true

require "rails_helper"

RSpec.describe V1::Events, type: :request do
  let(:base_url) { "/api/v1/events" }
  let(:event_type) { "business" }
  let(:title) { "Meeting with clients" }
  let(:description) { "Quarterly planning meeting" }
  let(:number_of_people) { 10 }
  let(:special_requests) { "Need projector and coffee" }

  let(:valid_event_params) do
    {
      title: title,
      description: description,
      event_type: event_type,
      number_of_people: number_of_people,
      special_requests: special_requests
    }
  end

  let(:invalid_event_params) do
    {
      title: "",
      event_type: "invalid_type"
    }
  end

  describe "GET /api/v1/events" do
    context "when there are events" do
      before do
        create(:event, title: "First event", event_type: "business")
        create(:event, title: "Second event", event_type: "birthday")
      end

      it "returns all events" do
        get base_url
        expect(response).to have_http_status(:success)
        json_response = JSON.parse(response.body)
        expect(json_response.size).to eq(2)
        expect(json_response.first["title"]).to eq("First event")
        expect(json_response.second["title"]).to eq("Second event")
      end
    end

    context "when there are no events" do
      it "returns an empty array" do
        get base_url

        expect(response).to have_http_status(:success)
        json_response = JSON.parse(response.body)

        expect(json_response).to be_empty
      end
    end
  end

  describe "GET /api/v1/events/:id" do
    context "when the event exists" do
      let(:event) { create(:event, valid_event_params) }

      it "returns the event" do
        get "#{base_url}/#{event.id}"

        expect(response).to have_http_status(:success)
        json_response = JSON.parse(response.body)

        expect(json_response["id"]).to eq(event.id)
        expect(json_response["title"]).to eq(event.title)
        expect(json_response["description"]).to eq(event.description)
        expect(json_response["event_type"]).to eq(event.event_type)
        expect(json_response["number_of_people"]).to eq(event.number_of_people)
        expect(json_response["special_requests"]).to eq(event.special_requests)
      end
    end

    context "when the event does not exist" do
      it "returns a 404 error" do
        get "#{base_url}/999"

        expect(response).to have_http_status(:not_found)
        json_response = JSON.parse(response.body)

        expect(json_response["error"]).to eq("Event not found")
      end
    end
  end

  describe "POST /api/v1/events" do
    context "with valid parameters" do
      it "creates a new event" do
        expect do
          post base_url, params: valid_event_params
        end.to change(Event, :count).by(1)

        expect(response).to have_http_status(:created)
        json_response = JSON.parse(response.body)

        expect(json_response["title"]).to eq(title)
        expect(json_response["description"]).to eq(description)
        expect(json_response["event_type"]).to eq(event_type)
        expect(json_response["number_of_people"]).to eq(number_of_people)
        expect(json_response["special_requests"]).to eq(special_requests)
      end
    end

    context "with invalid parameters" do
      it "does not create an event and returns errors" do
        expect do
          post base_url, params: invalid_event_params
        end.not_to change(Event, :count)

        expect(response).to have_http_status(:bad_request)
        json_response = JSON.parse(response.body)
        expect(json_response).to have_key("error")
        expect(json_response["error"]).to eq("event_type does not have a valid value")
      end
    end
  end

  describe "PUT /api/v1/events/:id" do
    let!(:event) { create(:event, valid_event_params) }
    let(:new_title) { "Updated Event Title" }
    let(:update_params) { { title: new_title } }

    context "when the event exists" do
      it "updates the event" do
        put "#{base_url}/#{event.id}", params: update_params

        expect(response).to have_http_status(:success)
        json_response = JSON.parse(response.body)

        expect(json_response["id"]).to eq(event.id)
        expect(json_response["title"]).to eq(new_title)
        expect(event.reload.title).to eq(new_title)
      end
    end

    context "when the event does not exist" do
      it "returns a 404 error" do
        put "#{base_url}/999", params: update_params

        expect(response).to have_http_status(:not_found)
        json_response = JSON.parse(response.body)

        expect(json_response["error"]).to eq("Event not found")
      end
    end

    context "with invalid parameters" do
      it "does not update the event and returns errors" do
        put "#{base_url}/#{event.id}", params: invalid_event_params

        expect(response).to have_http_status(:bad_request)
        JSON.parse(response.body)
      end
    end
  end

  describe "DELETE /api/v1/events/:id" do
    let!(:event) { create(:event, valid_event_params) }

    context "when the event exists" do
      it "deletes the event" do
        expect do
          delete "#{base_url}/#{event.id}"
        end.to change(Event, :count).by(-1)

        expect(response).to have_http_status(:success)
        json_response = JSON.parse(response.body)

        expect(json_response["success"]).to be true
        expect(json_response["message"]).to eq("Event successfully deleted")
      end
    end

    context "when the event does not exist" do
      it "returns a 404 error" do
        delete "#{base_url}/999"

        expect(response).to have_http_status(:not_found)
        json_response = JSON.parse(response.body)

        expect(json_response["error"]).to eq("Event not found")
      end
    end
  end
end

Important Details About Testing

During the development of the tests, we discovered some peculiarities of Grape that are worth sharing:

Two-Layer Validation: Grape has two layers of validation:
- Parameter Validation: Happens before the endpoint code is executed and returns status 400 (Bad Request)
- Model Validation: Happens within the endpoint code and returns status 422 (Unprocessable Entity)
Behavior with Invalid Parameters: When we use values: %w[business birthday] in the parameter definition, Grape automatically rejects invalid values with a 400 error before even executing the endpoint code. Our tests reflect this expected behavior by expecting status 400 when we send an invalid event_type.
Specific Error Messages: Grape provides specific error messages, such as "event_type does not have a valid value", which are useful both for debugging and for properly informing API users.

Running the tests:

bundle exec rspec spec/api/v1/events_spec.rb

# Result:
# Finished in 0.04411 seconds (files took 1.16 seconds to load)
# 11 examples, 0 failures

Benefits of Using Grape

After implementing our API with Grape, we noticed several benefits:

Cleaner and more organized code: Grape's structure helps us keep the code organized and easy to understand.
Automatic documentation: Grape automatically generates Swagger documentation without the need for specific tests for this purpose.
Robust parameter validation: Integrated parameter validation happens before code execution, avoiding unnecessary processing.
More direct tests: Tests focus on verifying the actual behavior of the API, not on generating documentation.
Clear error messages: Grape provides specific and well-formatted error messages.
Now, when I specify the response format:
present @event, with: ::Entities::EventResponse
I just need to define the expected response type in the endpoint:
success: ::Entities::EventResponse

Many times we change the serializer and fix the test where we changed the data, but we forget about other points where the same serializer is used. If the test is not 100% well covered, our API starts to become inconsistent in Swagger documentation or with a high maintenance cost.

How to Test Manually

After setting up your API, you can test it using tools like Postman, curl, or the automatically generated Swagger interface:

Start your Rails server: rails s
Access the Swagger documentation: http://localhost:3000/api-docs
Try out the available endpoints

Next Steps

In this post, we saw how to set up a basic API with Grape and Rails and how to test it efficiently. In the next posts in the series, I'll cover more advanced topics, such as:

Using the contracts gem for validation
Organizing code with the Interactor gem and controlling actions with organizers and interactors
Creating custom helpers
Adding middlewares for error handling
Authentication and authorization with Pundit
Pagination of resources
And much more!

Conclusion

Using Grape with Rails to create APIs has been an extremely positive experience. The combination of an expressive API with direct and efficient tests has allowed us to focus on what really matters: building a robust and well-documented API without the overhead of tests aimed solely at documentation.

If you're tired of writing tests just to generate documentation and want a more direct and efficient solution for your APIs, I definitely recommend trying Grape.

See you in the next post, where we'll delve into more advanced Grape features!

Have you used Grape in your Rails projects? What were your experiences? Leave your comments below!

Example repository: https://github.com/rodrigonbarreto/event_reservation_system/tree/mvp_sample

References:

Rodrigo Nogueira • Ruby on Rails Developer since 2015
Postgraduate in Software Engineering (PUC-RJ) & passionate about technology since 2011.

If you want to follow this journey, please comment and leave your like!