Agent skill

rails-api-patterns

Analyzes Rails API controllers, serializers, and endpoint design for best practices. Use when building RESTful API endpoints, implementing JWT authentication, designing JSON response structures, adding API versioning, writing serializers, setting up error handling, or adding pagination and rate limiting. NOT for HTML views, Turbo/Stimulus interactions, or GraphQL schemas.

View SKILL.md on GitHub Repository
Stars 4
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/ag0os/rails-dev-plugin/tree/main/skills/rails-api-patterns

SKILL.md

Rails API Patterns

Analyze and recommend best practices for Rails API design including controllers, serialization, authentication, versioning, and error handling.

Follow standard Rails API controller conventions (ActionController::API, strong parameters, rescue_from). See patterns.md for opinionated decisions and configuration.

Quick Reference

Area Decision Key File
Base controller ActionController::API + shared concerns app/controllers/api/base_controller.rb
Versioning URL namespace (/api/v1/) -- NOT header-based config/routes.rb
Auth JWT bearer token via JwtService app/controllers/concerns/authenticatable.rb
Serialization Blueprinter preferred (views for complexity) app/blueprints/
Response format { data:, meta:, errors: } envelope always All API responses
Pagination Pagy or Kaminari + max_per_page: 100 cap app/controllers/concerns/paginatable.rb
Rate limiting Rack::Attack: 100/min per token, 20/min per IP config/initializers/rack_attack.rb
CORS rack-cors gem, env-driven origins config/initializers/cors.rb

Core Decisions

  1. Response envelope always -- every response wraps in { data:, meta:, errors: }, never bare objects/arrays
  2. URL versioning from day one -- /api/v1/ namespace even for first version; header-based versioning adds complexity without benefit for most apps
  3. Blueprinter over AMS -- ActiveModel::Serializer is unmaintained; prefer Blueprinter for views-based serialization, or Jbuilder for complex one-offs
  4. Cap per_page at 100 -- enforce [params[:per_page].to_i, 100].min to prevent clients from requesting unbounded results
  5. Authenticate in base, skip explicitly -- before_action :authenticate in Api::BaseController, use skip_before_action for public endpoints
  6. Dual rate limits -- per-token (100/min) for authenticated, per-IP (20/min) for unauthenticated; return Retry-After header

Anti-Patterns

Bad Good Why
Render ActiveRecord objects directly Use serializers/blueprints Controls exposed fields, prevents leaking columns
No pagination on index Always paginate with max cap Memory + performance, prevents client abuse
Version in header only URL versioning (/api/v1/) Simpler routing, cacheable, easier debugging
N+1 queries in serializers includes() in controller Serializers should not trigger queries
Bare error strings Structured { error:, errors: } envelope Clients need machine-parseable error format
CORS origins "*" in production Env-driven origin allowlist Security; wildcard disables credential sharing

Output Format

When reporting on API design, use:

## API Analysis: [controller_or_endpoint]

**Issues:**
- [severity] description

**Recommendations:**
1. actionable recommendation

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

ag0os/rails-dev-plugin

rails-caching-patterns

Caching patterns for Rails applications including fragment caching, low-level caching, HTTP caching, Russian doll caching, and cache invalidation strategies. Automatically invoked when working with Rails.cache, cache stores, stale?/fresh_when, fragment caching, cache keys, or performance optimization through caching. Triggers on "cache", "caching", "Rails.cache", "fragment cache", "Russian doll", "stale?", "fresh_when", "cache key", "cache store", "Redis cache", "Solid Cache", "memcached", "ETag", "cache invalidation", "cache bust". NOT for CDN configuration (use rails-devops-patterns) or database query optimization (use rails-model-patterns).

4 0
Explore
ag0os/rails-dev-plugin

rails-graphql-patterns

Analyzes and recommends GraphQL patterns for Rails using graphql-ruby including schema design, types, resolvers, mutations, subscriptions, DataLoader, and query complexity. Use when building GraphQL APIs, defining types, writing mutations, optimizing N+1 queries, or structuring app/graphql. NOT for REST API controllers, ActiveRecord queries outside GraphQL, or Turbo Stream responses.

4 0
Explore
ag0os/rails-dev-plugin

ruby-object-design

Automatically invoked when making decisions about Ruby code structure and organization. Triggers on "class or module", "should this be a class", "struct vs class", "PORO", "data object", "design pattern", "class vs module", "when to use class", "module vs class", "stateless class", "value object", "data container", "object factory", "extend self", "singleton class". Provides guidance on choosing the right Ruby construct (class, module, Struct, Data, Hash). NOT for code smell identification or refactoring (use ruby-refactoring) or Rails-specific framework patterns.

4 0
Explore
ag0os/rails-dev-plugin

rails-views-patterns

Analyzes Rails view templates, partials, layouts, helpers, and form patterns for best practices. Use when reviewing ERB templates, improving view performance with fragment caching, fixing form helpers, organizing partials, adding accessibility attributes, or evaluating collection rendering. NOT for Stimulus/Turbo logic (use hotwire-patterns), controller concerns, or API-only responses.

4 0
Explore
ag0os/rails-dev-plugin

rails-architecture-patterns

Provides architectural planning, design decisions, and coordination guidance for Rails applications. Use when planning new features, choosing between design approaches (STI vs polymorphic, service vs concern, monolith vs engine), evaluating system architecture, or deciding which domain skill or agent to delegate to. NOT for implementation details within a single domain (use the domain-specific skill instead).

4 0
Explore
ag0os/rails-dev-plugin

rails-mailer-patterns

Action Mailer patterns for Rails applications. Automatically invoked when working with email delivery, mailer classes, email templates, mailer previews, interceptors, or delivery configuration. Triggers on "mailer", "email", "ActionMailer", "deliver_later", "deliver_now", "mail template", "email preview", "SMTP", "SendGrid", "Postmark", "notification email". NOT for push notifications, SMS, or in-app messaging.

4 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results