rails-api-design

Rails API Design

Build a JSON API that ages well. AI agents generate Rails APIs by reflex: respond_to :json, to_json, no versioning, no rate limiting, no consistent error shape. This skill encodes the choices senior Rails API authors make when the API has to live for years.

Why this matters

A REST API is a contract. Once clients depend on it, every change is a coordination cost. Get the foundations right at the start — versioning strategy, serialization layer, pagination, error format — or pay for it later in deprecation pain.

The opinion

URL versioning (/api/v1). jsonapi-serializer for JSON:API; alba for plain JSON. pagy for pagination (faster than kaminari). JWT for stateless third-party / mobile clients; session cookies for first-party SPAs on the same domain. rack-attack for rate limiting + brute-force. Structured errors per RFC 9457 (problem-details) or JSON:API errors. rswag for OpenAPI generation from request specs.

Counter-positions:

• GraphQL over REST: legitimate for highly-relational read APIs with many client variants. We default to REST because the tooling is broader and the operational burden is lower. If you have GraphQL needs, use graphql-ruby.
• Accept-header versioning (Accept: application/vnd.myapp+json; version=2): cleaner in theory; in practice harder to debug, caches awkwardly, and devs hate it. URL versioning wins on operational ergonomics.
• active_model_serializers (AMS): widely used historically. We default to jsonapi-serializer (formerly Fast JSONAPI) or alba because both are 10–50× faster.

Core patterns

Pattern 1: URL versioning

Route structure:

# config/routes.rb
Rails.application.routes.draw do
  namespace :api do
    namespace :v1 do
      resources :posts, only: %i[index show create update destroy] do
        resources :comments, only: %i[index create]
      end
      resource :session, only: %i[create destroy]
    end
  end
end

Controller structure:

# app/controllers/api/v1/base_controller.rb
class Api::V1::BaseController < ActionController::API
  include ActionController::HttpAuthentication::Token::ControllerMethods

  before_action :authenticate_user!
  rescue_from ActiveRecord::RecordNotFound, with: :not_found
  rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
  rescue_from Pundit::NotAuthorizedError, with: :forbidden

  private

  def authenticate_user!
    authenticate_or_request_with_http_token do |token, _options|
      @current_user = User.find_by(api_token: token)
    end
  end

  def current_user
    @current_user
  end

  def not_found(error)
    render json: { errors: [{ status: "404", title: "Not Found", detail: error.message }] },
      status: :not_found
  end

  def unprocessable_entity(error)
    render json: { errors: error.record.errors.map { |e| { status: "422", title: "Validation Failed", detail: "#{e.attribute} #{e.message}", source: { pointer: "/data/attributes/#{e.attribute}" } } } },
      status: :unprocessable_entity
  end

  def forbidden(_error)
    render json: { errors: [{ status: "403", title: "Forbidden" }] }, status: :forbidden
  end
end

class Api::V1::PostsController < Api::V1::BaseController
  def index
    posts = policy_scope(Post).includes(:author).order(created_at: :desc)
    pagy_obj, paginated = pagy(posts, limit: 25)
    render json: PostSerializer.new(paginated, meta: pagination_meta(pagy_obj)).serializable_hash
  end
end