API Development Patterns

Complete patterns and best practices for building production-grade REST APIs in Rails 7.x/8.x.

RESTful API Conventions

Resource-Oriented Design

Core Principles:

• Resources are nouns (not verbs): /users, /posts, not /get_user
• Use HTTP methods for actions: GET (read), POST (create), PATCH/PUT (update), DELETE (destroy)
• Nest resources for relationships, but limit nesting to 1-2 levels
• Use plural resource names: /users not /user

Standard Resource Routes:

# config/routes.rb
Rails.application.routes.draw do
  namespace :api do
    namespace :v1 do
      resources :posts do
        resources :comments, only: [:index, :create] # Nested but limited
        member do
          post :publish
          post :archive
        end
        collection do
          get :trending
        end
      end

      # Flat route for comments by ID (better than deep nesting)
      resources :comments, only: [:show, :update, :destroy]
    end
  end
end

HTTP Methods & Status Codes

Standard API Actions:

Method	Action	Success Status	Body
GET	Index/List	200 OK	Resource array + pagination
GET	Show	200 OK	Single resource
POST	Create	201 Created	Created resource
PATCH/PUT	Update	200 OK	Updated resource
DELETE	Destroy	204 No Content	Empty

Error Status Codes:

Code	Meaning	When to Use
400	Bad Request	Invalid JSON, malformed request
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource doesn't exist
422	Unprocessable Entity	Validation errors
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error
503	Service Unavailable	Maintenance mode, overloaded

Controller Example:

# app/controllers/api/v1/posts_controller.rb
module Api
  module V1
    class PostsController < Api::BaseController
      before_action :authenticate_api_user!
      before_action :set_post, only: [:show, :update, :destroy]

      def index
        @posts = Post.published
                     .page(params[:page])
                     .per(params[:per_page] || 25)

        render json: PostBlueprint.render(@posts, root: :posts), status: :ok
      end

      def show
        render json: PostBlueprint.render(@post), status: :ok
      end

      def create
        @post = Current.user.posts.build(post_params)

        if @post.save
          render json: PostBlueprint.render(@post), status: :created, location: api_v1_post_url(@post)
        else
          render json: { errors: @post.errors }, status: :unprocessable_entity
        end
      end

      def update
        if @post.update(post_params)
          render json: PostBlueprint.render(@post), status: :ok
        else
          render json: { errors: @post.errors }, status: :unprocessable_entity
        end
      end

      def destroy
        @post.destroy
        head :no_content
      end

      private

      def set_post
        @post = Post.find(params[:id])
      rescue ActiveRecord::RecordNotFound
        render json: { error: "Post not found" }, status: :not_found
      end

      def post_params
        params.require(:post).permit(:title, :body, :published_at, tag_ids: [])
      end
    end
  end
end

---

Serialization Patterns

Blueprinter (Recommended)

Installation:

# Gemfile
gem 'blueprinter'
gem 'oj' # Fast JSON parser

Basic Blueprint:

# app/blueprints/post_blueprint.rb
class PostBlueprint < Blueprinter::Base
  identifier :id

  fields :title, :body, :published_at, :created_at

  field :slug do |post|
    post.title.parameterize
  end

  association :author, blueprint: UserBlueprint, view: :compact

  association :comments, blueprint: CommentBlueprint do |post, options|
    post.comments.limit(options[:comment_limit] || 10)
  end

  view :compact do
    fields :id, :title, :slug
  end

  view :extended do
    include_view :default
    fields :view_count, :like_count
    association :tags, blueprint: TagBlueprint
  end
end

Using Views:

# Compact view for lists
PostBlueprint.render(@posts, view: :compact, root: :posts)

# Extended view for show
PostBlueprint.render(@post, view: :extended)

# Pass options to associations
PostBlueprint.render(@post, comment_limit: 5)

JSONAPI::Serializer (Alternative)

For JSON:API Specification Compliance:

# Gemfile
gem 'jsonapi-serializer'

# app/serializers/post_serializer.rb
class PostSerializer
  include JSONAPI::Serializer

  attributes :title, :body, :published_at

  belongs_to :author, serializer: UserSerializer
  has_many :comments, serializer: CommentSerializer

  attribute :slug do |post|
    post.title.parameterize
  end

  link :self do |post|
    Rails.application.routes.url_helpers.api_v1_post_url(post)
  end
end

# Usage
PostSerializer.new(@posts, include: [:author, :comments]).serializable_hash

Alba (Lightweight Alternative)

# Gemfile
gem 'alba'

# app/serializers/post_serializer.rb
class PostSerializer
  include Alba::Resource

  attributes :id, :title, :body, :published_at

  one :author, resource: UserSerializer
  many :comments, resource: CommentSerializer

  attribute :slug do |post|
    post.title.parameterize
  end
end

# Usage
PostSerializer.new(@posts).serialize

---

Authentication

JWT (JSON Web Tokens)

Installation:

# Gemfile
gem 'jwt'
gem 'bcrypt' # For password hashing

JWT Service:

# app/services/json_web_token_service.rb
class JsonWebTokenService
  SECRET_KEY = Rails.application.credentials.secret_key_base
  ALGORITHM = 'HS256'

  def self.encode(payload, expiration = 24.hours.from_now)
    payload[:exp] = expiration.to_i
    JWT.encode(payload, SECRET_KEY, ALGORITHM)
  end

  def self.decode(token)
    decoded = JWT.decode(token, SECRET_KEY, true, algorithm: ALGORITHM)[0]
    HashWithIndifferentAccess.new(decoded)
  rescue JWT::DecodeError, JWT::ExpiredSignature => e
    nil
  end
end

Authentication Controller:

# app/controllers/api/v1/authentication_controller.rb
module Api
  module V1
    class AuthenticationController < Api::BaseController
      skip_before_action :authenticate_api_user!, only: [:create]

      def create
        user = User.find_by(email: params[:email])

        if user&.authenticate(params[:password])
          token = JsonWebTokenService.encode(user_id: user.id)
          render json: {
            token: token,
            user: UserBlueprint.render_as_hash(user)
          }, status: :ok
        else
          render json: { error: 'Invalid credentials' }, status: :unauthorized
        end
      end

      def destroy
        # Implement token revocation (requires Redis/database storage)
        head :no_content
      end
    end
  end
end

Base Controller with JWT Authentication:

# app/controllers/api/base_controller.rb
module Api
  class BaseController < ActionController::API
    before_action :authenticate_api_user!

    rescue_from ActiveRecord::RecordNotFound, with: :not_found
    rescue_from ActionController::ParameterMissing, with: :bad_request

    private

    def authenticate_api_user!
      token = request.headers['Authorization']&.split(' ')&.last
      return render_unauthorized unless token

      decoded_token = JsonWebTokenService.decode(token)
      return render_unauthorized unless decoded_token

      @current_user = User.find_by(id: decoded_token[:user_id])
      return render_unauthorized unless @current_user

      # Store in Current for easy access
      Current.user = @current_user
    rescue
      render_unauthorized
    end

    def current_user
      @current_user
    end

    def render_unauthorized
      render json: { error: 'Unauthorized' }, status: :unauthorized
    end

    def not_found
      render json: { error: 'Resource not found' }, status: :not_found
    end

    def bad_request
      render json: { error: 'Bad request' }, status: :bad_request
    end
  end
end

API Keys (Alternative)

For Service-to-Service Authentication:

# Migration
create_table :api_keys do |t|
  t.references :user, null: false, foreign_key: true
  t.string :key, null: false, index: { unique: true }
  t.string :name # e.g., "Production Server", "Mobile App"
  t.datetime :last_used_at
  t.datetime :expires_at
  t.timestamps
end

# app/models/api_key.rb
class ApiKey < ApplicationRecord
  belongs_to :user

  before_create :generate_key

  scope :active, -> { where('expires_at IS NULL OR expires_at > ?', Time.current) }

  def self.authenticate(key)
    active.find_by(key: key)&.tap do |api_key|
      api_key.update_column(:last_used_at, Time.current)
    end
  end

  private

  def generate_key
    self.key = SecureRandom.base58(32)
  end
end

# Authentication in controller
def authenticate_api_key!
  key = request.headers['X-API-Key'] || params[:api_key]
  return render_unauthorized unless key

  @api_key = ApiKey.authenticate(key)
  return render_unauthorized unless @api_key

  @current_user = @api_key.user
  Current.user = @current_user
end

---

Authorization

Pundit for APIs

# Gemfile
gem 'pundit'

# app/controllers/api/base_controller.rb
module Api
  class BaseController < ActionController::API
    include Pundit::Authorization

    rescue_from Pundit::NotAuthorizedError, with: :forbidden

    private

    def forbidden
      render json: { error: 'Forbidden' }, status: :forbidden
    end
  end
end

# app/policies/post_policy.rb
class PostPolicy < ApplicationPolicy
  def index?
    true
  end

  def show?
    record.published? || record.author == user
  end

  def create?
    user.present?
  end

  def update?
    record.author == user
  end

  def destroy?
    record.author == user || user.admin?
  end
end

# In controller
def show
  @post = Post.find(params[:id])
  authorize @post
  render json: PostBlueprint.render(@post)
end

---

Versioning Strategies

URL Versioning (Recommended)

Routes:

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

    namespace :v2 do
      resources :posts
    end
  end
end

Pros: Simple, clear, cache-friendly Cons: URLs change between versions

Header Versioning

# config/routes.rb
namespace :api, defaults: { format: :json } do
  scope module: :v1, constraints: ApiVersion.new('v1', default: true) do
    resources :posts
  end

  scope module: :v2, constraints: ApiVersion.new('v2') do
    resources :posts
  end
end

# lib/api_version.rb
class ApiVersion
  def initialize(version, default = false)
    @version = version
    @default = default
  end

  def matches?(request)
    @default || check_headers(request.headers)
  end

  private

  def check_headers(headers)
    accept = headers['Accept']
    accept&.include?("application/vnd.myapp.#{@version}+json")
  end
end

Usage:

Accept: application/vnd.myapp.v2+json

---

Pagination

Kaminari

# Gemfile
gem 'kaminari'

# Controller
def index
  @posts = Post.published
               .page(params[:page])
               .per(params[:per_page] || 25)

  render json: {
    posts: PostBlueprint.render_as_hash(@posts, view: :compact),
    meta: pagination_meta(@posts)
  }
end

private

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

pagy (Faster Alternative)

# Gemfile
gem 'pagy'

# app/controllers/api/base_controller.rb
include Pagy::Backend

def index
  @pagy, @posts = pagy(Post.published, items: params[:per_page] || 25)

  render json: {
    posts: PostBlueprint.render_as_hash(@posts),
    meta: pagy_metadata(@pagy)
  }
end

private

def pagy_metadata(pagy_object)
  {
    current_page: pagy_object.page,
    next_page: pagy_object.next,
    prev_page: pagy_object.prev,
    total_pages: pagy_object.pages,
    total_count: pagy_object.count,
    per_page: pagy_object.items
  }
end

---

Rate Limiting

Rack::Attack

# Gemfile
gem 'rack-attack'

# config/initializers/rack_attack.rb
class Rack::Attack
  # Throttle all requests by IP
  throttle('req/ip', limit: 300, period: 5.minutes) do |req|
    req.ip if req.path.start_with?('/api/')
  end

  # Throttle API requests by authentication token
  throttle('api/token', limit: 1000, period: 1.hour) do |req|
    req.env['HTTP_AUTHORIZATION']&.split(' ')&.last if req.path.start_with?('/api/')
  end

  # Throttle login attempts
  throttle('logins/email', limit: 5, period: 20.minutes) do |req|
    if req.path == '/api/v1/login' && req.post?
      req.params['email'].to_s.downcase.gsub(/\s+/, "")
    end
  end

  # Block specific IPs
  blocklist('block bad IPs') do |req|
    # Read from Redis or database
    Redis.current.sismember('blocked_ips', req.ip)
  end

  # Custom response for throttled requests
  self.throttled_responder = lambda do |env|
    retry_after = env['rack.attack.match_data'][:period]
    [
      429,
      {
        'Content-Type' => 'application/json',
        'Retry-After' => retry_after.to_s
      },
      [{ error: 'Rate limit exceeded', retry_after: retry_after }.to_json]
    ]
  end
end

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

---

Error Handling

Standardized Error Format

# app/controllers/api/base_controller.rb
module Api
  class BaseController < ActionController::API
    rescue_from StandardError, with: :internal_server_error
    rescue_from ActiveRecord::RecordNotFound, with: :not_found
    rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
    rescue_from ActionController::ParameterMissing, with: :bad_request
    rescue_from Pundit::NotAuthorizedError, with: :forbidden

    private

    def render_error(message, status, details = {})
      render json: {
        error: {
          message: message,
          status: status,
          **details
        }
      }, status: status
    end

    def bad_request(exception)
      render_error('Bad request', :bad_request, details: exception.message)
    end

    def unauthorized
      render_error('Unauthorized', :unauthorized)
    end

    def forbidden(exception)
      render_error('Forbidden', :forbidden, details: exception.message)
    end

    def not_found(exception)
      render_error('Resource not found', :not_found, resource: exception.model)
    end

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

    def internal_server_error(exception)
      Rails.logger.error(exception.message)
      Rails.logger.error(exception.backtrace.join("\n"))

      # Report to error tracking service (Sentry, Rollbar, etc.)
      ErrorTrackingService.report(exception) if defined?(ErrorTrackingService)

      render_error('Internal server error', :internal_server_error)
    end
  end
end

Validation Errors Format

# app/models/post.rb
class Post < ApplicationRecord
  validates :title, presence: true, length: { minimum: 5, maximum: 100 }
  validates :body, presence: true
end

# Response for validation errors (422):
{
  "error": {
    "message": "Validation failed",
    "status": 422,
    "errors": {
      "title": ["can't be blank", "is too short (minimum is 5 characters)"],
      "body": ["can't be blank"]
    }
  }
}

---

CORS Configuration

# Gemfile
gem 'rack-cors'

# config/initializers/cors.rb
Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins 'https://example.com', 'https://app.example.com'

    resource '/api/*',
      headers: :any,
      methods: [:get, :post, :put, :patch, :delete, :options, :head],
      credentials: true,
      max_age: 86400
  end

  # Development
  if Rails.env.development?
    allow do
      origins 'http://localhost:3000', 'http://localhost:3001'
      resource '*', headers: :any, methods: :any
    end
  end
end

---

API Documentation

rswag (OpenAPI/Swagger)

Installation:

# Gemfile
gem 'rswag'

# Run installer
rails g rswag:install

Request Spec:

# spec/requests/api/v1/posts_spec.rb
require 'swagger_helper'

RSpec.describe 'API V1 Posts', type: :request do
  path '/api/v1/posts' do
    get 'Retrieves posts' do
      tags 'Posts'
      produces 'application/json'
      parameter name: :page, in: :query, type: :integer, required: false
      parameter name: :per_page, in: :query, type: :integer, required: false

      response '200', 'posts found' do
        schema type: :object,
          properties: {
            posts: {
              type: :array,
              items: {
                type: :object,
                properties: {
                  id: { type: :integer },
                  title: { type: :string },
                  body: { type: :string },
                  published_at: { type: :string, format: 'date-time' }
                },
                required: ['id', 'title']
              }
            },
            meta: {
              type: :object,
              properties: {
                current_page: { type: :integer },
                total_pages: { type: :integer },
                total_count: { type: :integer }
              }
            }
          }

        run_test!
      end
    end

    post 'Creates a post' do
      tags 'Posts'
      consumes 'application/json'
      produces 'application/json'
      parameter name: :post, in: :body, schema: {
        type: :object,
        properties: {
          title: { type: :string },
          body: { type: :string }
        },
        required: ['title', 'body']
      }

      response '201', 'post created' do
        let(:post) { { title: 'Test Post', body: 'Test body' } }
        run_test!
      end

      response '422', 'invalid request' do
        let(:post) { { title: '' } }
        run_test!
      end
    end
  end
end

Generate Swagger Docs:

rake rswag:specs:swaggerize

Access at: http://localhost:3000/api-docs

---

Performance Optimization

Caching

# Controller with caching
def index
  @posts = Rails.cache.fetch(['posts', 'index', params[:page]], expires_in: 5.minutes) do
    Post.published
        .includes(:author, :tags)
        .page(params[:page])
        .per(25)
        .to_a
  end

  render json: PostBlueprint.render(@posts)
end

# ETags for conditional requests
def show
  @post = Post.find(params[:id])

  if stale?(@post)
    render json: PostBlueprint.render(@post)
  end
end

N+1 Query Prevention

# Always use includes/eager_load for associations
def index
  @posts = Post.published
               .includes(:author, :tags, comments: :user)
               .page(params[:page])

  render json: PostBlueprint.render(@posts)
end

Bullet Gem (Development)

# Gemfile
group :development do
  gem 'bullet'
end

# config/environments/development.rb
config.after_initialize do
  Bullet.enable = true
  Bullet.alert = true
  Bullet.bullet_logger = true
  Bullet.console = true
  Bullet.rails_logger = true
  Bullet.add_footer = false # API doesn't need HTML footer
end

---

Testing

Request Specs

# spec/requests/api/v1/posts_spec.rb
require 'rails_helper'

RSpec.describe 'API V1 Posts', type: :request do
  let(:user) { create(:user) }
  let(:token) { JsonWebTokenService.encode(user_id: user.id) }
  let(:auth_headers) { { 'Authorization' => "Bearer #{token}" } }

  describe 'GET /api/v1/posts' do
    before do
      create_list(:post, 3, :published)
      create(:post, :draft) # Should not be included
    end

    it 'returns published posts' do
      get '/api/v1/posts', headers: auth_headers

      expect(response).to have_http_status(:ok)
      json = JSON.parse(response.body)
      expect(json['posts'].size).to eq(3)
    end

    it 'paginates results' do
      create_list(:post, 30, :published)

      get '/api/v1/posts', params: { page: 2, per_page: 10 }, headers: auth_headers

      json = JSON.parse(response.body)
      expect(json['posts'].size).to eq(10)
      expect(json['meta']['current_page']).to eq(2)
    end

    it 'returns 401 without authentication' do
      get '/api/v1/posts'
      expect(response).to have_http_status(:unauthorized)
    end
  end

  describe 'POST /api/v1/posts' do
    let(:valid_params) do
      { post: { title: 'Test Post', body: 'Test body' } }
    end

    it 'creates a post' do
      expect {
        post '/api/v1/posts', params: valid_params, headers: auth_headers
      }.to change(Post, :count).by(1)

      expect(response).to have_http_status(:created)
      json = JSON.parse(response.body)
      expect(json['title']).to eq('Test Post')
      expect(response.headers['Location']).to be_present
    end

    it 'returns validation errors' do
      post '/api/v1/posts', params: { post: { title: '' } }, headers: auth_headers

      expect(response).to have_http_status(:unprocessable_entity)
      json = JSON.parse(response.body)
      expect(json['error']['errors']).to have_key('title')
    end
  end

  describe 'PATCH /api/v1/posts/:id' do
    let(:post_record) { create(:post, author: user) }

    it 'updates the post' do
      patch "/api/v1/posts/#{post_record.id}",
        params: { post: { title: 'Updated' } },
        headers: auth_headers

      expect(response).to have_http_status(:ok)
      expect(post_record.reload.title).to eq('Updated')
    end

    it 'returns 403 for unauthorized update' do
      other_post = create(:post)

      patch "/api/v1/posts/#{other_post.id}",
        params: { post: { title: 'Hacked' } },
        headers: auth_headers

      expect(response).to have_http_status(:forbidden)
    end
  end
end

Factory for API Testing

# spec/factories/users.rb
FactoryBot.define do
  factory :user do
    email { Faker::Internet.email }
    password { 'password123' }
    password_confirmation { 'password123' }
  end
end

# spec/factories/posts.rb
FactoryBot.define do
  factory :post do
    title { Faker::Lorem.sentence }
    body { Faker::Lorem.paragraphs(number: 3).join("\n") }
    association :author, factory: :user

    trait :published do
      published_at { 1.day.ago }
    end

    trait :draft do
      published_at { nil }
    end
  end
end

Shared Examples for API Responses

# spec/support/shared_examples/api_responses.rb
RSpec.shared_examples 'requires authentication' do
  it 'returns 401 without token' do
    make_request(headers: {})
    expect(response).to have_http_status(:unauthorized)
  end

  it 'returns 401 with invalid token' do
    make_request(headers: { 'Authorization' => 'Bearer invalid' })
    expect(response).to have_http_status(:unauthorized)
  end
end

RSpec.shared_examples 'paginates results' do
  it 'includes pagination metadata' do
    make_request

    json = JSON.parse(response.body)
    expect(json['meta']).to include(
      'current_page',
      'total_pages',
      'total_count'
    )
  end
end

# Usage in specs
describe 'GET /api/v1/posts' do
  def make_request(headers: auth_headers)
    get '/api/v1/posts', headers: headers
  end

  it_behaves_like 'requires authentication'
  it_behaves_like 'paginates results'
end

---

Security Best Practices

Input Sanitization

# Always use strong parameters
def post_params
  params.require(:post).permit(:title, :body, :published_at, tag_ids: [])
end

SQL Injection Prevention

# BAD - vulnerable to SQL injection
Post.where("title = '#{params[:title]}'")

# GOOD - use parameterized queries
Post.where("title = ?", params[:title])
Post.where(title: params[:title])

Mass Assignment Protection

# Models automatically protected with strong parameters
# Never use:
Post.new(params[:post]) # BAD
Post.create(params[:post]) # BAD

# Always use:
Post.new(post_params) # GOOD
Post.create(post_params) # GOOD

Sensitive Data Filtering

# config/initializers/filter_parameter_logging.rb
Rails.application.config.filter_parameters += [
  :password,
  :password_confirmation,
  :token,
  :api_key,
  :secret,
  :credit_card
]

---

Anti-Patterns to Avoid

❌ Don't Return ActiveRecord Objects Directly

# BAD
def index
  render json: Post.all # Exposes all attributes
end

# GOOD
def index
  render json: PostBlueprint.render(Post.all)
end

❌ Don't Use Sessions/Cookies in APIs

# APIs should be stateless
# Use JWT or API keys, not session-based authentication

❌ Don't Skip Authorization

# BAD
def destroy
  @post = Post.find(params[:id])
  @post.destroy
end

# GOOD
def destroy
  @post = Post.find(params[:id])
  authorize @post # Pundit
  @post.destroy
end

❌ Don't Ignore Rate Limiting

# Always implement rate limiting for public APIs
# Use Rack::Attack or similar

❌ Don't Return 200 for All Responses

# Use appropriate status codes
# 200 OK, 201 Created, 204 No Content, 400 Bad Request, etc.

---

Summary Checklist

When building a new API endpoint:

• Use RESTful resource naming and HTTP methods
• Implement proper authentication (JWT/API keys)
• Add authorization checks (Pundit)
• Use serializers (Blueprinter) - never expose raw models
• Return appropriate HTTP status codes
• Implement pagination for list endpoints
• Add rate limiting (Rack::Attack)
• Configure CORS properly
• Handle errors consistently
• Write comprehensive request specs
• Document with rswag/OpenAPI
• Optimize queries (includes, caching)
• Version your API (URL or header)
• Filter sensitive parameters in logs
• Use strong parameters for mass assignment protection

This skill provides the foundation for building production-ready REST APIs in Rails!