ag0os/rails-api-patterns
skills/rails-api-patterns/SKILL.md
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.
$ install --global
skillsauthnpx skillsauth add ag0os/rails-dev-plugin rails-api-patternsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 22, 2026, 3:47 AM132.8s2 files scanned
SKILL.md
- name:
- rails-api-patterns
- description:
- 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.
- allowed-tools:
- Read, Grep, Glob
Rails API Patterns
Analyze and recommend best practices for Rails API design including controllers, serialization, authentication, versioning, and error handling.
Applies on the api delivery axis (Axis B, rails-stack-profiles) — including an /api namespace inside an otherwise html app. For server-rendered HTML use rails-views-patterns and hotwire-patterns.
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
- Response envelope always -- every response wraps in
{ data:, meta:, errors: }, never bare objects/arrays - URL versioning from day one --
/api/v1/namespace even for first version; header-based versioning adds complexity without benefit for most apps - Blueprinter over AMS -- ActiveModel::Serializer is unmaintained; prefer Blueprinter for views-based serialization, or Jbuilder for complex one-offs
- Cap per_page at 100 -- enforce
[params[:per_page].to_i, 100].minto prevent clients from requesting unbounded results - Authenticate in base, skip explicitly --
before_action :authenticateinApi::BaseController, useskip_before_actionfor public endpoints - Dual rate limits -- per-token (100/min) for authenticated, per-IP (20/min) for unauthenticated; return
Retry-Afterheader
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
Related Skills
ag0os/refactoring-guidance
development
VerifiedTrustedCommunity
WHAT: Language-agnostic corrective guidance for the refactoring phase. WHEN: Agent is restructuring code, fixing code smells, reducing complexity, or improving maintainability. NOT FOR: Writing new features, debugging runtime errors, performance tuning, or object design decisions.
4SKILL.mdUpdated May 22, 2026
ag0os/rails-views-patterns
tools
VerifiedTrustedCommunity
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.
4SKILL.mdUpdated Mar 31, 2026
ag0os/rails-testing-patterns
testing
VerifiedTrustedCommunity
Analyzes Rails test suites and recommends testing best practices for RSpec and Minitest. Use when writing new tests, reviewing test coverage, fixing flaky tests, improving test performance, choosing between test types (unit, integration, system, request), or setting up factories and fixtures. NOT for production monitoring, deployment verification, or load/stress testing infrastructure.
4SKILL.mdUpdated Mar 31, 2026
ag0os/rails-stack-profiles
development
VerifiedTrustedCommunity
Detects a Rails project's architecture axes — logic placement (native vs extracted) and delivery (html vs api) — so other skills load profile-appropriate guidance without inline conditionals. Use when planning architecture or when a recommendation depends on where business logic lives or whether the app renders HTML or serves JSON. NOT for test framework, job backend, cache store, or auth library choices — those are orthogonal facts detected by project-conventions.
4SKILL.mdUpdated Mar 31, 2026