aigroup-workflow 2.2.1 → 2.2.3

package/skills/ruby/rails-expert/references/api-development.md

@@ -1,401 +1,401 @@
-# API Development
-
-## API-Only Rails Application
-
-```ruby
-# Generate API-only app
-rails new myapp --api
-
-# config/application.rb
-module MyApp
-  class Application < Rails::Application
-    config.api_only = true
-    config.load_defaults 7.1
-  end
-end
-
-# app/controllers/application_controller.rb
-class ApplicationController < ActionController::API
-  include ActionController::HttpAuthentication::Token::ControllerMethods
-
-  before_action :authenticate
-
-  rescue_from ActiveRecord::RecordNotFound, with: :not_found
-  rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
-
-  private
-
-  def authenticate
-    authenticate_token || render_unauthorized
-  end
-
-  def authenticate_token
-    authenticate_with_http_token do |token, options|
-      @current_user = User.find_by(api_token: token)
-    end
-  end
-
-  def render_unauthorized
-    render json: { error: 'Unauthorized' }, status: :unauthorized
-  end
-
-  def not_found
-    render json: { error: 'Not found' }, status: :not_found
-  end
-
-  def unprocessable_entity(exception)
-    render json: { errors: exception.record.errors }, status: :unprocessable_entity
-  end
-end
-```
-
-## RESTful API Controller
-
-```ruby
-# app/controllers/api/v1/posts_controller.rb
-module Api
-  module V1
-    class PostsController < ApplicationController
-      before_action :set_post, only: [:show, :update, :destroy]
-
-      # GET /api/v1/posts
-      def index
-        @posts = Post.includes(:user)
-                    .page(params[:page])
-                    .per(params[:per_page] || 20)
-
-        render json: @posts, meta: pagination_meta(@posts)
-      end
-
-      # GET /api/v1/posts/:id
-      def show
-        render json: @post, include: [:user, :comments]
-      end
-
-      # POST /api/v1/posts
-      def create
-        @post = current_user.posts.build(post_params)
-
-        if @post.save
-          render json: @post, status: :created, location: api_v1_post_url(@post)
-        else
-          render json: { errors: @post.errors }, status: :unprocessable_entity
-        end
-      end
-
-      # PATCH/PUT /api/v1/posts/:id
-      def update
-        if @post.update(post_params)
-          render json: @post
-        else
-          render json: { errors: @post.errors }, status: :unprocessable_entity
-        end
-      end
-
-      # DELETE /api/v1/posts/:id
-      def destroy
-        @post.destroy
-        head :no_content
-      end
-
-      private
-
-      def set_post
-        @post = Post.find(params[:id])
-      end
-
-      def post_params
-        params.require(:post).permit(:title, :body, :published)
-      end
-
-      def pagination_meta(collection)
-        {
-          current_page: collection.current_page,
-          total_pages: collection.total_pages,
-          total_count: collection.total_count
-        }
-      end
-    end
-  end
-end
-```
-
-## Serialization with ActiveModel::Serializers
-
-```ruby
-# Gemfile
-gem 'active_model_serializers'
-
-# app/serializers/post_serializer.rb
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body, :published, :created_at
-
-  belongs_to :user
-  has_many :comments
-
-  # Conditional attributes
-  attribute :draft_content, if: :current_user_is_author?
-
-  # Custom attributes
-  def published_date
-    object.created_at.strftime("%Y-%m-%d")
-  end
-
-  private
-
-  def current_user_is_author?
-    current_user == object.user
-  end
-end
-
-# app/serializers/user_serializer.rb
-class UserSerializer < ActiveModel::Serializer
-  attributes :id, :username, :email
-
-  # Exclude sensitive data
-  def email
-    return nil unless current_user&.admin?
-    object.email
-  end
-end
-```
-
-## JWT Authentication
-
-```ruby
-# Gemfile
-gem 'jwt'
-
-# app/lib/json_web_token.rb
-class JsonWebToken
-  SECRET_KEY = Rails.application.credentials.secret_key_base
-
-  def self.encode(payload, exp = 24.hours.from_now)
-    payload[:exp] = exp.to_i
-    JWT.encode(payload, SECRET_KEY)
-  end
-
-  def self.decode(token)
-    decoded = JWT.decode(token, SECRET_KEY)[0]
-    HashWithIndifferentAccess.new(decoded)
-  rescue JWT::DecodeError
-    nil
-  end
-end
-
-# app/controllers/api/v1/authentication_controller.rb
-module Api
-  module V1
-    class AuthenticationController < ApplicationController
-      skip_before_action :authenticate, only: [:create]
-
-      # POST /api/v1/auth/login
-      def create
-        user = User.find_by(email: params[:email])
-
-        if user&.authenticate(params[:password])
-          token = JsonWebToken.encode(user_id: user.id)
-          render json: { token: token, user: UserSerializer.new(user) }
-        else
-          render json: { error: 'Invalid credentials' }, status: :unauthorized
-        end
-      end
-    end
-  end
-end
-
-# app/controllers/application_controller.rb
-class ApplicationController < ActionController::API
-  before_action :authenticate_request
-
-  attr_reader :current_user
-
-  private
-
-  def authenticate_request
-    header = request.headers['Authorization']
-    token = header.split(' ').last if header
-
-    decoded = JsonWebToken.decode(token)
-    @current_user = User.find(decoded[:user_id]) if decoded
-
-    render json: { error: 'Unauthorized' }, status: :unauthorized unless @current_user
-  rescue ActiveRecord::RecordNotFound
-    render json: { error: 'Unauthorized' }, status: :unauthorized
-  end
-end
-```
-
-## API Versioning
-
-```ruby
-# config/routes.rb
-Rails.application.routes.draw do
-  namespace :api do
-    namespace :v1 do
-      resources :posts
-      resources :users
-
-      post '/auth/login', to: 'authentication#create'
-    end
-
-    namespace :v2 do
-      resources :posts
-    end
-  end
-end
-
-# app/controllers/api/v1/base_controller.rb
-module Api
-  module V1
-    class BaseController < ApplicationController
-      # V1 specific logic
-    end
-  end
-end
-```
-
-## Rate Limiting
-
-```ruby
-# Gemfile
-gem 'rack-attack'
-
-# config/initializers/rack_attack.rb
-class Rack::Attack
-  # Throttle all requests by IP
-  throttle('req/ip', limit: 300, period: 5.minutes) do |req|
-    req.ip
-  end
-
-  # Throttle login attempts by email
-  throttle('logins/email', limit: 5, period: 20.seconds) do |req|
-    if req.path == '/api/v1/auth/login' && req.post?
-      req.params['email'].to_s.downcase.gsub(/\s+/, "")
-    end
-  end
-
-  # Block suspicious requests
-  blocklist('block bad IPs') do |req|
-    # Requests are blocked if the return value is truthy
-    BadIpList.include?(req.ip)
-  end
-end
-
-# config/application.rb
-config.middleware.use Rack::Attack
-```
-
-## CORS Configuration
-
-```ruby
-# Gemfile
-gem 'rack-cors'
-
-# config/initializers/cors.rb
-Rails.application.config.middleware.insert_before 0, Rack::Cors do
-  allow do
-    origins 'localhost:3000', 'example.com'
-
-    resource '*',
-      headers: :any,
-      methods: [:get, :post, :put, :patch, :delete, :options, :head],
-      credentials: true
-  end
-end
-```
-
-## API Documentation with RSwag
-
-```ruby
-# Gemfile
-gem 'rswag'
-
-# spec/requests/api/v1/posts_spec.rb
-require 'swagger_helper'
-
-RSpec.describe 'Posts API', type: :request do
-  path '/api/v1/posts' do
-    get 'Retrieves posts' do
-      tags 'Posts'
-      produces 'application/json'
-      parameter name: :page, in: :query, type: :integer, required: false
-
-      response '200', 'posts found' do
-        schema type: :array,
-          items: {
-            type: :object,
-            properties: {
-              id: { type: :integer },
-              title: { type: :string },
-              body: { type: :string }
-            }
-          }
-
-        run_test!
-      end
-    end
-
-    post 'Creates a post' do
-      tags 'Posts'
-      consumes 'application/json'
-      parameter name: :post, in: :body, schema: {
-        type: :object,
-        properties: {
-          title: { type: :string },
-          body: { type: :string }
-        },
-        required: ['title', 'body']
-      }
-
-      response '201', 'post created' do
-        let(:post) { { title: 'Test', body: 'Content' } }
-        run_test!
-      end
-    end
-  end
-end
-```
-
-## Error Handling
-
-```ruby
-# app/controllers/concerns/error_handler.rb
-module ErrorHandler
-  extend ActiveSupport::Concern
-
-  included do
-    rescue_from ActiveRecord::RecordNotFound, with: :not_found
-    rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
-    rescue_from ActionController::ParameterMissing, with: :bad_request
-  end
-
-  private
-
-  def not_found(exception)
-    render json: { error: exception.message }, status: :not_found
-  end
-
-  def unprocessable_entity(exception)
-    render json: { errors: exception.record.errors.full_messages },
-           status: :unprocessable_entity
-  end
-
-  def bad_request(exception)
-    render json: { error: exception.message }, status: :bad_request
-  end
-end
-```
-
-## Best Practices
-
-- Use semantic versioning for API versions
-- Return proper HTTP status codes
-- Include pagination for list endpoints
-- Use JSON:API or similar standard format
-- Document API with OpenAPI/Swagger
-- Implement rate limiting and throttling
-- Use HTTPS in production
-- Validate and sanitize all inputs
-- Include API versioning in URL or headers
-- Provide helpful error messages
+# API Development
+
+## API-Only Rails Application
+
+```ruby
+# Generate API-only app
+rails new myapp --api
+
+# config/application.rb
+module MyApp
+  class Application < Rails::Application
+    config.api_only = true
+    config.load_defaults 7.1
+  end
+end
+
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::API
+  include ActionController::HttpAuthentication::Token::ControllerMethods
+
+  before_action :authenticate
+
+  rescue_from ActiveRecord::RecordNotFound, with: :not_found
+  rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
+
+  private
+
+  def authenticate
+    authenticate_token || render_unauthorized
+  end
+
+  def authenticate_token
+    authenticate_with_http_token do |token, options|
+      @current_user = User.find_by(api_token: token)
+    end
+  end
+
+  def render_unauthorized
+    render json: { error: 'Unauthorized' }, status: :unauthorized
+  end
+
+  def not_found
+    render json: { error: 'Not found' }, status: :not_found
+  end
+
+  def unprocessable_entity(exception)
+    render json: { errors: exception.record.errors }, status: :unprocessable_entity
+  end
+end
+```
+
+## RESTful API Controller
+
+```ruby
+# app/controllers/api/v1/posts_controller.rb
+module Api
+  module V1
+    class PostsController < ApplicationController
+      before_action :set_post, only: [:show, :update, :destroy]
+
+      # GET /api/v1/posts
+      def index
+        @posts = Post.includes(:user)
+                    .page(params[:page])
+                    .per(params[:per_page] || 20)
+
+        render json: @posts, meta: pagination_meta(@posts)
+      end
+
+      # GET /api/v1/posts/:id
+      def show
+        render json: @post, include: [:user, :comments]
+      end
+
+      # POST /api/v1/posts
+      def create
+        @post = current_user.posts.build(post_params)
+
+        if @post.save
+          render json: @post, status: :created, location: api_v1_post_url(@post)
+        else
+          render json: { errors: @post.errors }, status: :unprocessable_entity
+        end
+      end
+
+      # PATCH/PUT /api/v1/posts/:id
+      def update
+        if @post.update(post_params)
+          render json: @post
+        else
+          render json: { errors: @post.errors }, status: :unprocessable_entity
+        end
+      end
+
+      # DELETE /api/v1/posts/:id
+      def destroy
+        @post.destroy
+        head :no_content
+      end
+
+      private
+
+      def set_post
+        @post = Post.find(params[:id])
+      end
+
+      def post_params
+        params.require(:post).permit(:title, :body, :published)
+      end
+
+      def pagination_meta(collection)
+        {
+          current_page: collection.current_page,
+          total_pages: collection.total_pages,
+          total_count: collection.total_count
+        }
+      end
+    end
+  end
+end
+```
+
+## Serialization with ActiveModel::Serializers
+
+```ruby
+# Gemfile
+gem 'active_model_serializers'
+
+# app/serializers/post_serializer.rb
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body, :published, :created_at
+
+  belongs_to :user
+  has_many :comments
+
+  # Conditional attributes
+  attribute :draft_content, if: :current_user_is_author?
+
+  # Custom attributes
+  def published_date
+    object.created_at.strftime("%Y-%m-%d")
+  end
+
+  private
+
+  def current_user_is_author?
+    current_user == object.user
+  end
+end
+
+# app/serializers/user_serializer.rb
+class UserSerializer < ActiveModel::Serializer
+  attributes :id, :username, :email
+
+  # Exclude sensitive data
+  def email
+    return nil unless current_user&.admin?
+    object.email
+  end
+end
+```
+
+## JWT Authentication
+
+```ruby
+# Gemfile
+gem 'jwt'
+
+# app/lib/json_web_token.rb
+class JsonWebToken
+  SECRET_KEY = Rails.application.credentials.secret_key_base
+
+  def self.encode(payload, exp = 24.hours.from_now)
+    payload[:exp] = exp.to_i
+    JWT.encode(payload, SECRET_KEY)
+  end
+
+  def self.decode(token)
+    decoded = JWT.decode(token, SECRET_KEY)[0]
+    HashWithIndifferentAccess.new(decoded)
+  rescue JWT::DecodeError
+    nil
+  end
+end
+
+# app/controllers/api/v1/authentication_controller.rb
+module Api
+  module V1
+    class AuthenticationController < ApplicationController
+      skip_before_action :authenticate, only: [:create]
+
+      # POST /api/v1/auth/login
+      def create
+        user = User.find_by(email: params[:email])
+
+        if user&.authenticate(params[:password])
+          token = JsonWebToken.encode(user_id: user.id)
+          render json: { token: token, user: UserSerializer.new(user) }
+        else
+          render json: { error: 'Invalid credentials' }, status: :unauthorized
+        end
+      end
+    end
+  end
+end
+
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::API
+  before_action :authenticate_request
+
+  attr_reader :current_user
+
+  private
+
+  def authenticate_request
+    header = request.headers['Authorization']
+    token = header.split(' ').last if header
+
+    decoded = JsonWebToken.decode(token)
+    @current_user = User.find(decoded[:user_id]) if decoded
+
+    render json: { error: 'Unauthorized' }, status: :unauthorized unless @current_user
+  rescue ActiveRecord::RecordNotFound
+    render json: { error: 'Unauthorized' }, status: :unauthorized
+  end
+end
+```
+
+## API Versioning
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  namespace :api do
+    namespace :v1 do
+      resources :posts
+      resources :users
+
+      post '/auth/login', to: 'authentication#create'
+    end
+
+    namespace :v2 do
+      resources :posts
+    end
+  end
+end
+
+# app/controllers/api/v1/base_controller.rb
+module Api
+  module V1
+    class BaseController < ApplicationController
+      # V1 specific logic
+    end
+  end
+end
+```
+
+## Rate Limiting
+
+```ruby
+# Gemfile
+gem 'rack-attack'
+
+# config/initializers/rack_attack.rb
+class Rack::Attack
+  # Throttle all requests by IP
+  throttle('req/ip', limit: 300, period: 5.minutes) do |req|
+    req.ip
+  end
+
+  # Throttle login attempts by email
+  throttle('logins/email', limit: 5, period: 20.seconds) do |req|
+    if req.path == '/api/v1/auth/login' && req.post?
+      req.params['email'].to_s.downcase.gsub(/\s+/, "")
+    end
+  end
+
+  # Block suspicious requests
+  blocklist('block bad IPs') do |req|
+    # Requests are blocked if the return value is truthy
+    BadIpList.include?(req.ip)
+  end
+end
+
+# config/application.rb
+config.middleware.use Rack::Attack
+```
+
+## CORS Configuration
+
+```ruby
+# Gemfile
+gem 'rack-cors'
+
+# config/initializers/cors.rb
+Rails.application.config.middleware.insert_before 0, Rack::Cors do
+  allow do
+    origins 'localhost:3000', 'example.com'
+
+    resource '*',
+      headers: :any,
+      methods: [:get, :post, :put, :patch, :delete, :options, :head],
+      credentials: true
+  end
+end
+```
+
+## API Documentation with RSwag
+
+```ruby
+# Gemfile
+gem 'rswag'
+
+# spec/requests/api/v1/posts_spec.rb
+require 'swagger_helper'
+
+RSpec.describe 'Posts API', type: :request do
+  path '/api/v1/posts' do
+    get 'Retrieves posts' do
+      tags 'Posts'
+      produces 'application/json'
+      parameter name: :page, in: :query, type: :integer, required: false
+
+      response '200', 'posts found' do
+        schema type: :array,
+          items: {
+            type: :object,
+            properties: {
+              id: { type: :integer },
+              title: { type: :string },
+              body: { type: :string }
+            }
+          }
+
+        run_test!
+      end
+    end
+
+    post 'Creates a post' do
+      tags 'Posts'
+      consumes 'application/json'
+      parameter name: :post, in: :body, schema: {
+        type: :object,
+        properties: {
+          title: { type: :string },
+          body: { type: :string }
+        },
+        required: ['title', 'body']
+      }
+
+      response '201', 'post created' do
+        let(:post) { { title: 'Test', body: 'Content' } }
+        run_test!
+      end
+    end
+  end
+end
+```
+
+## Error Handling
+
+```ruby
+# app/controllers/concerns/error_handler.rb
+module ErrorHandler
+  extend ActiveSupport::Concern
+
+  included do
+    rescue_from ActiveRecord::RecordNotFound, with: :not_found
+    rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
+    rescue_from ActionController::ParameterMissing, with: :bad_request
+  end
+
+  private
+
+  def not_found(exception)
+    render json: { error: exception.message }, status: :not_found
+  end
+
+  def unprocessable_entity(exception)
+    render json: { errors: exception.record.errors.full_messages },
+           status: :unprocessable_entity
+  end
+
+  def bad_request(exception)
+    render json: { error: exception.message }, status: :bad_request
+  end
+end
+```
+
+## Best Practices
+
+- Use semantic versioning for API versions
+- Return proper HTTP status codes
+- Include pagination for list endpoints
+- Use JSON:API or similar standard format
+- Document API with OpenAPI/Swagger
+- Implement rate limiting and throttling
+- Use HTTPS in production
+- Validate and sanitize all inputs
+- Include API versioning in URL or headers
+- Provide helpful error messages