API Development
API-Only Rails Application
# Generate API-only app
rails new myapp --api
# config/application.rb
module MyApp
class Application < Rails::Application
config.api_only = true
config.load_defaults 7.1
end
end
# app/controllers/application_controller.rb
class ApplicationController < ActionController::API
include ActionController::HttpAuthentication::Token::ControllerMethods
before_action :authenticate
rescue_from ActiveRecord::RecordNotFound, with: :not_found
rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
private
def authenticate
authenticate_token || render_unauthorized
end
def authenticate_token
authenticate_with_http_token do |token, options|
@current_user = User.find_by(api_token: token)
end
end
def render_unauthorized
render json: { error: 'Unauthorized' }, status: :unauthorized
end
def not_found
render json: { error: 'Not found' }, status: :not_found
end
def unprocessable_entity(exception)
render json: { errors: exception.record.errors }, status: :unprocessable_entity
end
end
RESTful API Controller
# app/controllers/api/v1/posts_controller.rb
module Api
module V1
class PostsController < ApplicationController
before_action :set_post, only: [:show, :update, :destroy]
# GET /api/v1/posts
def index
@posts = Post.includes(:user)
.page(params[:page])
.per(params[:per_page] || 20)
render json: @posts, meta: pagination_meta(@posts)
end
# GET /api/v1/posts/:id
def show
render json: @post, include: [:user, :comments]
end
# POST /api/v1/posts
def create
@post = current_user.posts.build(post_params)
if @post.save
render json: @post, status: :created, location: api_v1_post_url(@post)
else
render json: { errors: @post.errors }, status: :unprocessable_entity
end
end
# PATCH/PUT /api/v1/posts/:id
def update
if @post.update(post_params)
render json: @post
else
render json: { errors: @post.errors }, status: :unprocessable_entity
end
end
# DELETE /api/v1/posts/:id
def destroy
@post.destroy
head :no_content
end
private
def set_post
@post = Post.find(params[:id])
end
def post_params
params.require(:post).permit(:title, :body, :published)
end
def pagination_meta(collection)
{
current_page: collection.current_page,
total_pages: collection.total_pages,
total_count: collection.total_count
}
end
end
end
end
Serialization with ActiveModel::Serializers
# Gemfile
gem 'active_model_serializers'
# app/serializers/post_serializer.rb
class PostSerializer < ActiveModel::Serializer
attributes :id, :title, :body, :published, :created_at
belongs_to :user
has_many :comments
# Conditional attributes
attribute :draft_content, if: :current_user_is_author?
# Custom attributes
def published_date
object.created_at.strftime("%Y-%m-%d")
end
private
def current_user_is_author?
current_user == object.user
end
end
# app/serializers/user_serializer.rb
class UserSerializer < ActiveModel::Serializer
attributes :id, :username, :email
# Exclude sensitive data
def email
return nil unless current_user&.admin?
object.email
end
end
JWT Authentication
# Gemfile
gem 'jwt'
# app/lib/json_web_token.rb
class JsonWebToken
SECRET_KEY = Rails.application.credentials.secret_key_base
def self.encode(payload, exp = 24.hours.from_now)
payload[:exp] = exp.to_i
JWT.encode(payload, SECRET_KEY)
end
def self.decode(token)
decoded = JWT.decode(token, SECRET_KEY)[0]
HashWithIndifferentAccess.new(decoded)
rescue JWT::DecodeError
nil
end
end
# app/controllers/api/v1/authentication_controller.rb
module Api
module V1
class AuthenticationController < ApplicationController
skip_before_action :authenticate, only: [:create]
# POST /api/v1/auth/login
def create
user = User.find_by(email: params[:email])
if user&.authenticate(params[:password])
token = JsonWebToken.encode(user_id: user.id)
render json: { token: token, user: UserSerializer.new(user) }
else
render json: { error: 'Invalid credentials' }, status: :unauthorized
end
end
end
end
end
# app/controllers/application_controller.rb
class ApplicationController < ActionController::API
before_action :authenticate_request
attr_reader :current_user
private
def authenticate_request
header = request.headers['Authorization']
token = header.split(' ').last if header
decoded = JsonWebToken.decode(token)
@current_user = User.find(decoded[:user_id]) if decoded
render json: { error: 'Unauthorized' }, status: :unauthorized unless @current_user
rescue ActiveRecord::RecordNotFound
render json: { error: 'Unauthorized' }, status: :unauthorized
end
end
API Versioning
# config/routes.rb
Rails.application.routes.draw do
namespace :api do
namespace :v1 do
resources :posts
resources :users
post '/auth/login', to: 'authentication#create'
end
namespace :v2 do
resources :posts
end
end
end
# app/controllers/api/v1/base_controller.rb
module Api
module V1
class BaseController < ApplicationController
# V1 specific logic
end
end
end
Rate Limiting
# 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
end
# Throttle login attempts by email
throttle('logins/email', limit: 5, period: 20.seconds) do |req|
if req.path == '/api/v1/auth/login' && req.post?
req.params['email'].to_s.downcase.gsub(/\s+/, "")
end
end
# Block suspicious requests
blocklist('block bad IPs') do |req|
# Requests are blocked if the return value is truthy
BadIpList.include?(req.ip)
end
end
# config/application.rb
config.middleware.use Rack::Attack
CORS Configuration
# Gemfile
gem 'rack-cors'
# config/initializers/cors.rb
Rails.application.config.middleware.insert_before 0, Rack::Cors do
allow do
origins 'localhost:3000', 'example.com'
resource '*',
headers: :any,
methods: [:get, :post, :put, :patch, :delete, :options, :head],
credentials: true
end
end
API Documentation with RSwag
# Gemfile
gem 'rswag'
# spec/requests/api/v1/posts_spec.rb
require 'swagger_helper'
RSpec.describe 'Posts API', 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
response '200', 'posts found' do
schema type: :array,
items: {
type: :object,
properties: {
id: { type: :integer },
title: { type: :string },
body: { type: :string }
}
}
run_test!
end
end
post 'Creates a post' do
tags 'Posts'
consumes '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', body: 'Content' } }
run_test!
end
end
end
end
Error Handling
# app/controllers/concerns/error_handler.rb
module ErrorHandler
extend ActiveSupport::Concern
included do
rescue_from ActiveRecord::RecordNotFound, with: :not_found
rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
rescue_from ActionController::ParameterMissing, with: :bad_request
end
private
def not_found(exception)
render json: { error: exception.message }, status: :not_found
end
def unprocessable_entity(exception)
render json: { errors: exception.record.errors.full_messages },
status: :unprocessable_entity
end
def bad_request(exception)
render json: { error: exception.message }, status: :bad_request
end
end
Best Practices
- Use semantic versioning for API versions
- Return proper HTTP status codes
- Include pagination for list endpoints
- Use JSON:API or similar standard format
- Document API with OpenAPI/Swagger
- Implement rate limiting and throttling
- Use HTTPS in production
- Validate and sanitize all inputs
- Include API versioning in URL or headers
- Provide helpful error messages
tools-only