API Development Patterns

What it does

Describes patterns and best practices for building production-grade REST APIs in Rails 7.x/8.x, covering routing conventions, HTTP methods and status codes, serialization strategies, authentication (JWT and API keys), authorization, versioning, pagination, rate limiting, and standardized error handling.

How it works

• Establishes RESTful conventions: resource-oriented routes, nested resources with limits, and specific member/collection actions.
• Specifies standard HTTP actions and their success/error statuses, plus corresponding response bodies (e.g., 201 Created for create, 204 No Content for destroy).
• Provides concrete controller examples (index, show, create, update, destroy) and a before_action for authentication, with a rescue strategy for not found errors.
• Details multiple serialization options: Blueprinter (with views and associations), JSONAPI::Serializer, and Alba, including installation steps and usage.
• Outlines authentication approaches:
  • JWT-based tokens with a JsonWebTokenService for encode/decode, a base API controller for authentication, and an authentication controller for login/logout.
  • API Keys as an alternative with a model, migration, and a controller filter for key-based auth.
• Describes authorization using Pundit policies and how to apply authorize in controllers.
• Describes versioning strategies: URL versioning and header-based versioning, with code sketches for routes and a simple ApiVersion matcher.
• Details pagination options: Kaminari and Pagy with example controller code and metadata extraction.
• Explains rate limiting using Rack::Attack with multiple throttles (by IP, token, login attempts) and a custom throttled response.
• Provides standardized error handling in a base controller, with methods to render structured error responses for various exceptions, and examples of the error payload structure.

When to use it

• When implementing a Rails-based REST API and you want a comprehensive, production-ready blueprint covering routing, serialization, auth, versioning, rate limiting, and error handling.
• When you need concrete code samples for controllers, serializers, policies, and middleware configuration.

What it can touch

• Routes: Ruby code in config/routes.rb for API namespaces and versioning setups.
• Controllers: Api::V1::..., Api::BaseController, Api::AuthenticationController, PostController, etc.
• Serializers/Blueprints: Blueprinter, JSONAPI::Serializer, Alba usage files under app/blueprints or app/serializers.
• Authentication: app/services/json_web_token_service.rb, app/controllers/api/v1/authentication_controller.rb, app/controllers/api/base_controller.rb, and related modules.
• Authorization: app/policies/post_policy.rb and policy usage in controllers.
• Versioning: lib/api_version.rb and config/routes.rb patterns for v1/v2.
• Pagination: examples using Kaminari and Pagy in controllers.
• Rate limiting: config/initializers/rack_attack.rb and Gemfile entry for rack-attack.
• Error handling: app/controllers/api/base_controller.rb with render_error utilities.

Caveats

• Only factual patterns and code examples as stated; no speculative outcomes.
• Licensing is MIT for the skill; no implementation guarantees beyond described usage.
• Examples assume Rails 7.x/8.x and common gem ecosystems; exact compatibility should be verified in the target project.