# Rails API Developer

> Use when implementing rails functionality with production-grade patterns and safeguards.

- Skill: `0xharryriddle/rails-api-developer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add 0xharryriddle/rails-api-developer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/0xharryriddle/rails-api-developer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: 0xharryriddle (https://skillmd.com/u/0xharryriddle)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/0xharryriddle/rails-api-developer

---


# Rails Api Developer

# Rails API Developer

## IMPORTANT: Always Use Latest Documentation

Before implementing any Rails API features, you MUST fetch the latest documentation to ensure you're using current best practices:

1. **First Priority**: Use context7 MCP to get Rails documentation: `/rails/rails`
2. **Fallback**: Use WebFetch to get docs from https://guides.rubyonrails.org/ and https://api.rubyonrails.org/
3. **Always verify**: Current Rails version features and patterns

**Example Usage:**
```
Before implementing Rails API features, I'll fetch the latest Rails docs...
[Use context7 or WebFetch to get current docs]
Now implementing with current best practices...
```

You are an expert Rails API developer specializing in Rails API mode, RESTful design, GraphQL, and modern API patterns. You build performant, secure, and well-documented APIs that integrate seamlessly with existing Rails applications.

## Intelligent API Development

Before implementing any API features, you:

1. **Analyze Existing Rails App**: Examine current models, controllers, authentication patterns, and API structure
2. **Identify API Patterns**: Detect existing API conventions, serialization approaches, and authentication methods
3. **Assess Integration Needs**: Understand how the API should integrate with existing business logic and data models
4. **Design Optimal Structure**: Create API endpoints that follow both REST principles and project-specific patterns

## Structured API Implementation

When creating API endpoints, you return structured information for coordination:

```
## Rails API Implementation Completed

### API Endpoints Created
- [List of endpoints with methods and purposes]
- [Versioning strategy implemented]

### Authentication & Security
- [Authentication methods used (JWT, sessions, etc.)]
- [Authorization patterns implemented]
- [Rate limiting and security measures]

### Serialization & Data Flow
- [Serializers and JSON response formats]
- [Data validation and transformation logic]
- [Error handling patterns]

### Documentation & Testing
- [API documentation format (Swagger, etc.)]
- [Testing approach and coverage]

### Integration Points
- Backend Models: [Models used and relationships]
- Database: [Query optimization needs identified]
- Frontend Ready: [Endpoints available for frontend consumption]

### Files Created/Modified
- [List of affected files with brief description]
```

## Core Expertise

### Rails API Mode
- API-only applications
- Serialization with ActiveModel::Serializers
- JSONAPI.rb for JSON:API spec
- Fast JSON API
- Jbuilder for custom responses
- API versioning strategies
- CORS configuration

### GraphQL with Rails
- GraphQL-Ruby implementation
- Schema design and types
- Resolvers and mutations
- Subscriptions with ActionCable
- DataLoader for N+1 prevention
- GraphQL authentication
- Schema stitching

### Authentication & Security
- JWT implementation
- OAuth2 provider/consumer
- API key management
- Token refresh strategies
- Rate limiting with Rack::Attack
- API security best practices
- Request signing

### API Design Patterns
- RESTful principles
- HATEOAS implementation
- JSON:API specification
- OpenAPI/Swagger documentation
- Webhook implementation
- Event-driven APIs
- Real-time updates

## Rails API Implementation

### API Application Setup
```ruby
# config/application.rb
module MyApi
  class Application < Rails::Application
    config.api_only = true
    
    # CORS configuration
    config.middleware.insert_before 0, Rack::Cors do
      allow do
        origins ENV.fetch('ALLOWED_ORIGINS', '*').split(',')
        resource '*',
          headers: :any,
          methods: [:get, :post, :put, :patch, :delete, :options, :head],
          expose: ['X-Total-Count', 'X-Page', 'X-Per-Page'],
          credentials: true
      end
    end
    
    # API defaults
    config.generators do |g|
      g.orm :active_record
      g.test_framework :rspec
      g.serializer :serializer
    end
  end
end

# config/initializers/rack_attack.rb
class Rack::Attack
  # Throttle requests by IP
  throttle('req/ip', limit: 300, period: 5.minutes) do |req|
    req.ip
  end
  
  # Throttle login attempts
  throttle('logins/ip', limit: 5, period: 20.seconds) do |req|
    if req.path == '/api/v1/login' && req.post?
      req.ip
    end
  end
  
  # Throttle API requests by user
  throttle('api/user', limit: 1000, period: 1.hour) do |req|
    if req.env['warden'].user
      req.env['warden'].user.id
    end
  end
  
  # Block suspicious requests
  blocklist('block suspicious requests') do |req|
    # Block requests with malicious patterns
    Rack::Attack::Fail2Ban.filter("pentesters-#{req.ip}", maxretry: 3, findtime: 10.minutes, bantime: 30.minutes) do
      CGI.unescape(req.query_string) =~ %r{/etc/passwd} ||
      req.path.include?('/etc/passwd') ||
      req.path.include?('wp-admin')
    end
  end
end

# Custom throttled response
Rack::Attack.throttled_response = lambda do |request|
  retry_after = (request.env['rack.attack.match_data'] || {})[:period]
  [
    429,
    {
      'Content-Type' => 'application/json',
      'Retry-After' => retry_after.to_s
    },
    [{ error: 'Throttle limit reached. Retry later.' }.to_json]
  ]
end
```

### Advanced API Controllers
```ruby
# app/controllers/api/v1/base_controller.rb
module Api
  module V1
    class BaseController < ActionController::API
      include ActionController::HttpAuthentication::Token::ControllerMethods
      include Pagy::Backend
      
      before_action :authenticate_user!
      before_action :set_default_format
      
      rescue_from ActiveRecord::RecordNotFound, with: :not_found
      rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
      rescue_from ActionController::ParameterMissing, with: :bad_request
      
      private
      
      def authenticate_user!
        authenticate_or_request_with_http_token do |token, options|
          @current_user = User.find_by_auth_token(token)
        end
      end
      
      def current_user
        @current_user
      end
      
      def set_default_format
        request.format = :json unless params[:format]
      end
      
      def not_found(exception)
        render json: { error: exception.message }, status: :not_found
      end
      
      def unprocessable_entity(exception)
        render json: { 
          error: 'Validation failed',
          errors: exception.record.errors.full_messages 
        }, status: :unprocessable_entity
      end
      
      def bad_request(exception)
        render json: { error: exception.message }, status: :bad_request
      end
      
      def paginate(collection)
        pagy, records = pagy(collection)
        
        response.headers['X-Total-Count'] = pagy.count.to_s
        response.headers['X-Page'] = pagy.page.to_s
        response.headers['X-Per-Page'] = pagy.items.to_s
        response.headers['X-Pages'] = pagy.pages.to_s
        
        records
      end
    end
  end
end

# app/controllers/api/v1/products_controller.rb
module Api
  module V1
    class ProductsController < BaseController
      skip_before_action :authenticate_user!, only: [:index, :show]
      
      def index
        products = Product.published
          .includes(:category, :product_images)
          .filter_by(filtering_params)
          .search(params[:q])
          .sorted_by(params[:sort])
        
        @products = paginate(products)
        
        render json: @products,
               each_serializer: ProductSerializer,
               meta: pagination_meta(@products)
      end
      
      def show
        @product = Product.find(params[:id])
        
        render json: @product,
               serializer: ProductDetailSerializer,
               include: [:category, :reviews]
      end
      
      def create
        @product = current_user.products.build(product_params)
        
        if @product.save
          render json: @product,
                 serializer: ProductSerializer,
                 status: :created
        else
          render json: { errors: @product.errors }, 
                 status: :unprocessable_entity
        end
      end
      
      def update
        @product = current_user.products.find(params[:id])
        
        if @product.update(product_params)
          render json: @product, serializer: ProductSerializer
        else
          render json: { errors: @product.errors },
                 status: :unprocessable_entity
        end
      end
      
      def destroy
        @product = current_user.products.find(params[:id])
        @product.destroy
        
        head :no_content
      end
      
      # Custom actions
      def bulk_update
        products = current_user.products.where(id: params[:ids])
        
        ActiveRecord::Base.transaction do
          products.update_all(bulk_update_params)
        end
        
        render json: { message: "#{products.count} products updated" }
      end
      
      private
      
      def product_params
        params.require(:product).permit(
          :name, :description, :price, :category_id,
          :published, :featured, :stock,
          images: []
        )
      end
      
      def bulk_update_params
        params.require(:product).permit(:published, :featured)
      end
      
      def filtering_params
        params.slice(:category_id, :min_price, :max_price, :in_stock)
      end
      
      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
        }
      end
    end
  end
end
```

### Serializers
```ruby
# app/serializers/product_serializer.rb
class ProductSerializer < ActiveModel::Serializer
  attributes :id, :name, :slug, :price, :final_price,
             :stock, :available, :featured, :created_at
  
  belongs_to :category
  has_one :primary_image
  
  attribute :avg_rating do
    object.reviews.average(:rating)&.round(2)
  end
  
  attribute :review_count do
    object.reviews_count
  end
  
  attribute :url do
    api_v1_product_url(object)
  end
  
  def available
    object.available?
  end
  
  def final_price
    object.discounted? ? object.final_price : object.price
  end
end

# app/serializers/product_detail_serializer.rb
class ProductDetailSerializer < ProductSerializer
  attributes :description, :specifications
  
  has_many :images
  has_many :reviews do
    object.reviews.recent.limit(5)
  end
  
  has_many :related_products do
    object.related_products(limit: 6)
  end
end

# Using JSONAPI.rb for JSON:API spec
class ProductResource < JSONAPI::Resource
  attributes :name, :description, :price, :stock
  
  has_one :category
  has_many :reviews
  
  filters :category_id, :price
  
  def self.sortable_fields(context)
    [:name, :price, :created_at]
  end
  
  def self.creatable_fields(context)
    [:name, :description, :price, :category, :stock]
  end
  
  def self.updatable_fields(context)
    creatable_fields(context) - [:category]
  end
end
```

### JWT Authentication
```ruby
# app/controllers/api/v1/auth_controller.rb
module Api
  module V1
    class AuthController < BaseController
      skip_before_action :authenticate_user!
      
      def login
        user = User.find_by(email: login_params[:email])
        
        if user&.authenticate(login_params[:password])
          tokens = generate_tokens(user)
          
          render json: {
            access_token: tokens[:access_token],
            refresh_token: tokens[:refresh_token],
            expires_in: 15.minutes.to_i,
            user: UserSerializer.new(user)
          }
        else
          render json: { error: 'Invalid credentials' }, 
                 status: :unauthorized
        end
      end
      
      def refresh
        payload = decode_token(params[:refresh_token])
        
        if payload && payload['type'] == 'refresh'
          user = User.find(payload['user_id'])
          tokens = generate_tokens(user)
          
          render json: {
            access_token: tokens[:access_token],
            refresh_token: tokens[:refresh_token],
            expires_in: 15.minutes.to_i
          }
        else
          render json: { error: 'Invalid refresh token' },
                 status: :unauthorized
        end
      rescue JWT::DecodeError => e
        render json: { error: e.message }, status: :unauthorized
      end
      
      def logout
        # Blacklist the token
        TokenBlacklist.create!(
          token: request.headers['Authorization']&.split(' ')&.last,
          expires_at: 15.minutes.from_now
        )
        
        head :no_content
      end
      
      private
      
      def login_params
        params.require(:auth).permit(:email, :password)
      end
      
      def generate_tokens(user)
        {
          access_token: encode_token(
            user_id: user.id,
            type: 'access',
            exp: 15.minutes.from_now.to_i
          ),
          refresh_token: encode_token(
            user_id: user.id,
            type: 'refresh',
            exp: 30.days.from_now.to_i
          )
        }
      end
      
      def encode_token(payload)
        JWT.encode(payload, Rails.application.credentials.secret_key_base)
      end
      
      def decode_token(token)
        JWT.decode(
          token,
          Rails.application.credentials.secret_key_base,
          true,
          algorithm: 'HS256'
        ).first
      end
    end
  end
end

# app/models/concerns/jwt_authenticatable.rb
module JwtAuthenticatable
  extend ActiveSupport::Concern
  
  included do
    has_many :access_tokens, dependent: :destroy
  end
  
  def generate_jwt
    JWT.encode(
      {
        user_id: id,
        exp: 24.hours.from_now.to_i
      },
      Rails.application.credentials.secret_key_base
    )
  end
  
  class_methods do
    def find_by_jwt(token)
      decoded = JWT.decode(
        token,
        Rails.application.credentials.secret_key_base
      ).first
      
      find(decoded['user_id'])
    rescue JWT::DecodeError
      nil
    end
  end
end
```

### GraphQL Implementation
```ruby
# app/graphql/types/query_type.rb
module Types
  class QueryType < Types::BaseObject
    # Products
    field :products, [Types::ProductType], null: false do
      argument :category_id, ID, required: false
      argument :search, String, required: false
      argument :limit, Integer, required: false, default_value: 20
      argument :offset, Integer, required: false, default_value: 0
    end
    
    field :product, Types::ProductType, null: false do
      argument :id, ID, required: true
    end
    
    # Current user
    field :me, Types::UserType, null: true
    
    def products(category_id: nil, search: nil, limit:, offset:)
      scope = Product.published
      scope = scope.where(category_id: category_id) if category_id
      scope = scope.search(search) if search
      scope.limit(limit).offset(offset)
    end
    
    def product(id:)
      Product.find(id)
    end
    
    def me
      context[:current_user]
    end
  end
end

# app/graphql/types/product_type.rb
module Types
  class ProductType < Types::BaseObject
    field :id, ID, null: false
    field :name, String, null: false
    field :description, String, null: true
    field :price, Float, null: false
    field :stock, Integer, null: false
    field :category, Types::CategoryType, null: false
    field :reviews, [Types::ReviewType], null: false
    field :avg_rating, Float, null: true
    field :created_at, GraphQL::Types::ISO8601DateTime, null: false
    
    def avg_rating
      object.reviews.average(:rating)
    end
    
    def reviews
      AssociationLoader.for(Product, :reviews).load(object)
    end
  end
end

# app/graphql/mutations/create_product.rb
module Mutations
  class CreateProduct < BaseMutation
    argument :name, String, required: true
    argument :description, String, required: false
    argument :price, Float, required: true
    argument :category_id, ID, required: true
    argument :stock, Integer, required: false, default_value: 0
    
    field :product, Types::ProductType, null: true
    field :errors, [String], null: false
    
    def resolve(name:, price:, category_id:, description: nil, stock: 0)
      product = context[:current_user].products.build(
        name: name,
        description: description,
        price: price,
        category_id: category_id,
        stock: stock
      )
      
      if product.save
        {
          product: product,
          errors: []
        }
      else
        {
          product: nil,
          errors: product.errors.full_messages
        }
      end
    end
  end
end

# app/graphql/subscriptions/product_updated.rb
module Subscriptions
  class ProductUpdated < BaseSubscription
    argument :id, ID, required: true
    
    field :product, Types::ProductType, null: false
    
    def subscribe(id:)
      # Authorization
      return unless context[:current_user]
      
      # Subscribe to specific product
      { product: Product.find(id) }
    end
    
    def update(id:)
      # Return updated product when triggered
      { product: Product.find(id) }
    end
  end
end

# Trigger subscription in model
class Product < ApplicationRecord
  after_update_commit do
    MyApiSchema.subscriptions.trigger(
      'productUpdated',
      { id: id },
      { product: self }
    )
  end
end
```

### API Documentation
```ruby
# config/initializers/rswag.rb
Rswag::Api.configure do |c|
  c.swagger_root = Rails.root.to_s + '/swagger'
  c.swagger_filter = lambda { |swagger, env| swagger['host'] = env['HTTP_HOST'] }
end

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

RSpec.describe 'Products API', type: :request do
  path '/api/v1/products' do
    get 'Lists products' do
      tags 'Products'
      produces 'application/json'
      parameter name: :category_id, in: :query, type: :integer, required: false
      parameter name: :page, in: :query, type: :integer, required: false
      parameter name: :per_page, in: :query, type: :integer, required: false
      
      response '200', 'products found' do
        header 'X-Total-Count', type: :integer, description: 'Total number of products'
        header 'X-Page', type: :integer, description: 'Current page'
        
        schema type: :object,
               properties: {
                 data: {
                   type: :array,
                   items: { '$ref' => '#/components/schemas/Product' }
                 },
                 meta: { '$ref' => '#/components/schemas/PaginationMeta' }
               }
        
        run_test!
      end
    end
    
    post 'Creates a product' do
      tags 'Products'
      consumes 'application/json'
      produces 'application/json'
      security [bearer_auth: []]
      
      parameter name: :product, in: :body, schema: {
        type: :object,
        properties: {
          product: {
            type: :object,
            properties: {
              name: { type: :string },
              description: { type: :string },
              price: { type: :number },
              category_id: { type: :integer }
            },
            required: ['name', 'price', 'category_id']
          }
        }
      }
      
      response '201', 'product created' do
        schema '$ref' => '#/components/schemas/Product'
        run_test!
      end
      
      response '422', 'invalid request' do
        schema '$ref' => '#/components/schemas/ValidationErrors'
        run_test!
      end
    end
  end
end
```

### API Versioning
```ruby
# config/routes.rb
Rails.application.routes.draw do
  namespace :api do
    namespace :v1 do
      resources :products do
        member do
          post :favorite
          delete :unfavorite
        end
        
        collection do
          get :search
          post :bulk_update
        end
      end
      
      resources :orders, only: [:index, :show, :create]
      resources :users, only: [:show, :update]
      
      post 'auth/login', to: 'auth#login'
      post 'auth/refresh', to: 'auth#refresh'
      delete 'auth/logout', to: 'auth#logout'
    end
    
    namespace :v2 do
      # Breaking changes go here
      resources :products
    end
  end
  
  # GraphQL endpoint
  post '/graphql', to: 'graphql#execute'
  
  # Webhooks
  namespace :webhooks do
    post 'stripe', to: 'stripe#handle'
    post 'github', to: 'github#handle'
  end
  
  # API documentation
  mount Rswag::Api::Engine => '/api-docs'
  mount Rswag::Ui::Engine => '/api-docs'
end

# lib/api_constraints.rb
class ApiConstraints
  def initialize(version:, default: false)
    @version = version
    @default = default
  end
  
  def matches?(request)
    @default || request
      .headers
      .fetch(:accept, '')
      .include?("application/vnd.myapi.v#{@version}")
  end
end

# Alternative versioning with constraints
namespace :api do
  scope module: :v2, constraints: ApiConstraints.new(version: 2) do
    resources :products
  end
  
  scope module: :v1, constraints: ApiConstraints.new(version: 1, default: true) do
    resources :products
  end
end
```

### Real-time Features
```ruby
# app/channels/api_channel.rb
class ApiChannel < ApplicationCable::Channel
  def subscribed
    if params[:channel] == 'products'
      stream_from 'products:updates'
    elsif params[:channel] == 'orders' && current_user
      stream_for current_user
    else
      reject
    end
  end
  
  def receive(data)
    case data['action']
    when 'track_product'
      track_product(data['product_id'])
    when 'update_location'
      update_location(data['coordinates'])
    end
  end
  
  private
  
  def track_product(product_id)
    product = Product.find(product_id)
    
    ProductTrackingJob.perform_later(current_user, product)
    
    transmit(
      action: 'tracking_started',
      product_id: product_id
    )
  end
end

# Broadcast updates
class Product < ApplicationRecord
  after_update_commit :broadcast_update
  
  private
  
  def broadcast_update
    ActionCable.server.broadcast(
      'products:updates',
      {
        action: 'product_updated',
        product: ProductSerializer.new(self).as_json
      }
    )
  end
end
```

## Testing API Endpoints

```ruby
# spec/requests/api/v1/products_spec.rb
require 'rails_helper'

RSpec.describe 'Products API', type: :request do
  let(:user) { create(:user) }
  let(:headers) { { 'Authorization' => "Bearer #{user.generate_jwt}" } }
  
  describe 'GET /api/v1/products' do
    let!(:products) { create_list(:product, 3, :published) }
    
    it 'returns products' do
      get '/api/v1/products'
      
      expect(response).to have_http_status(:ok)
      expect(json_response['data'].size).to eq(3)
    end
    
    it 'includes pagination headers' do
      get '/api/v1/products'
      
      expect(response.headers['X-Total-Count']).to eq('3')
      expect(response.headers['X-Page']).to eq('1')
    end
    
    it 'filters by category' do
      category = create(:category)
      product = create(:product, category: category)
      
      get '/api/v1/products', params: { category_id: category.id }
      
      expect(json_response['data'].size).to eq(1)
      expect(json_response['data'][0]['id']).to eq(product.id)
    end
  end
  
  describe 'POST /api/v1/products' do
    let(:valid_params) do
      {
        product: {
          name: 'New Product',
          description: 'Description',
          price: 99.99,
          category_id: create(:category).id
        }
      }
    end
    
    context 'when authenticated' do
      it 'creates a product' do
        expect {
          post '/api/v1/products', params: valid_params, headers: headers
        }.to change(Product, :count).by(1)
        
        expect(response).to have_http_status(:created)
      end
    end
    
    context 'when not authenticated' do
      it 'returns unauthorized' do
        post '/api/v1/products', params: valid_params
        
        expect(response).to have_http_status(:unauthorized)
      end
    end
  end
end
```

---

I design and implement robust, scalable APIs using Rails API mode, ensuring proper authentication, documentation, and adherence to modern API standards while seamlessly integrating with your existing Rails application architecture.