api-development-patterns_skill

Overview

This skill is a practical guide for building production-ready REST APIs in Rails, covering routing, serialization, authentication, authorization, versioning, pagination, rate limiting, and testing patterns. It packages opinionated examples and code patterns you can drop into Rails 7/8 projects to speed development and enforce consistency. The focus is on predictable JSON responses, secure authentication, and scalable defaults for enterprise usage.

How this skill works

The skill inspects common API concerns and provides concrete Rails patterns: namespaced routes, controller actions with proper status codes, serializers (Blueprinter / JSONAPI::Serializer / Alba), JWT and API key authentication, Pundit authorization, and Rack::Attack rate limiting. It shows how to wire services (JWT service, API key model), base controller behavior, pagination helpers, and standardized error handling so endpoints behave consistently. Examples include route layouts, controller examples, serializer blueprints, and initializer snippets for middleware.

When to use it

• When building a new REST API in Rails with JSON responses
• When standardizing API behavior across teams or microservices
• When adding authentication (JWT or API keys) and authorization to endpoints
• When introducing versioning, pagination, or rate limits to production APIs
• When you need consistent serializers and error formats for clients

Best practices

• Design resources as nouns and limit nesting to 1–2 levels; use HTTP verbs for actions
• Return correct HTTP status codes (200, 201, 204, 422, 401, 403, 429, 500) and standardized JSON error bodies
• Use a serializer library (Blueprinter recommended) with views for list vs show payloads
• Prefer URL-based versioning for clarity; support header versioning only when necessary
• Centralize auth in Api::BaseController (JWT or API key) and use Pundit for authorization checks
• Protect endpoints with Rack::Attack and expose Retry-After for throttled responses

Example use cases

• Implement a posts API: namespaced routes, PostBlueprint, pagination meta, and Pundit policies
• Add token-based login: JsonWebTokenService, authentication controller, and Current.user wiring
• Protect service endpoints with API keys for machine-to-machine access and last_used_at auditing
• Introduce version v2 routes while keeping v1 intact using URL namespacing and an ApiVersion constraint for header-based switching
• Apply Rack::Attack throttles for login endpoints and per-token request limits with a custom throttled responder