rails_api_kit 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 34e70026279699c8b1e1a1a3b4bcd5fe6e35ebd30114490eabc87db67444d84b
+  data.tar.gz: 1c24f1ad20cddc1340688d39d051caa659cfaaa35ef38e30e2b9c68603847f95
+SHA512:
+  metadata.gz: 742002a691ca1ce8bf656e13be82c495aec57cd6741bf21e3e22293857f83d61a8308904b08a9910e2d76984ba48efedf196d052627d0e8c68300ee0cd474953
+  data.tar.gz: cf6e1acbb07f3e573f80122cad888e2409599b17f691c54933864ca49106357fa3ab3e8e58b862f5af232c13a5c555cbc3ef2be1067b57415913a6cc7af13f75

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Stas Suscov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,313 @@
+# ApiKit
+
+A lightweight Rails toolkit for building standardized, structured API responses with serialization, error handling, filtering, sorting, and pagination.
+
+> Building clean, consistent APIs shouldn't be rocket science. ApiKit provides simple, powerful modules to get you up and running quickly.
+
+## Features
+
+ApiKit offers a collection of lightweight modules that integrate seamlessly with your Rails controllers:
+
+* **Object serialization** - Powered by Active Model Serializers
+* **Error handling** - Standardized error responses for parameters, validation, and generic errors
+* **Fetching** - Support for relationship includes and sparse fieldsets
+* **Filtering & Sorting** - Advanced filtering and sorting powered by Ransack
+* **Pagination** - Built-in pagination support with links and metadata
+
+## Installation
+
+**Requirements:**
+- Ruby 3.3.0 or higher
+- Rails 8.0 or higher
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rails_api_kit"
+```
+
+And then execute:
+
+    $ bundle install
+
+## Quick Start
+
+### 1. Enable Rails Integration
+
+Add this to an initializer:
+
+```ruby
+# config/initializers/rails_api_kit.rb
+require "rails_api_kit"
+
+ApiKit::RailsApp.install!
+```
+
+This registers the media type and renderers.
+
+### 2. Basic Usage
+
+```ruby
+class UsersController < ApplicationController
+  include ApiKit::Filtering
+  include ApiKit::Pagination
+
+  def index
+    allowed_fields = [ :first_name, :last_name, :created_at ]
+
+    api_filter(User.all, allowed_fields) do |filtered|
+      api_paginate(filtered.result) do |paginated|
+        render api_paginate: paginated
+      end
+    end
+  end
+
+  def show
+    user = User.find(params[:id])
+    render api: user
+  end
+end
+```
+
+### 3. Create Serializers
+
+```ruby
+class UserSerializer < ActiveModel::Serializer
+  attributes :id, :first_name, :last_name, :email, :created_at, :updated_at
+
+  has_many :posts
+end
+```
+
+## Core Modules
+
+### ApiKit::Filtering
+
+Provides powerful filtering and sorting using Ransack:
+
+```ruby
+class UsersController < ApplicationController
+  include ApiKit::Filtering
+
+  def index
+    allowed_fields = [ :first_name, :last_name, :email, :posts_title ]
+
+    api_filter(User.all, allowed_fields) do |filtered|
+      render api: filtered.result
+    end
+  end
+end
+```
+
+**Example requests:**
+```bash
+# Filter by first name containing "John"
+GET /users?filter[first_name_cont]=John
+
+# Sort by last name descending, then first name ascending
+GET /users?sort=-last_name,first_name
+
+# Complex filtering with relationships
+GET /users?filter[posts_title_matches_any]=Ruby,Rails&sort=-created_at
+```
+
+#### Sorting with Expressions
+
+Enable aggregation expressions for advanced sorting:
+
+```ruby
+def index
+  allowed_fields = [ :first_name, :posts_count ]
+  options = { sort_with_expressions: true }
+
+  api_filter(User.joins(:posts), allowed_fields, options) do |filtered|
+    render api: filtered.result.group("users.id")
+  end
+end
+```
+
+```bash
+# Sort by post count
+GET /users?sort=-posts_count_sum
+```
+
+### ApiKit::Pagination
+
+Handles pagination with standardized links:
+
+```ruby
+class UsersController < ApplicationController
+  include ApiKit::Pagination
+
+  def index
+    api_paginate(User.all) do |paginated|
+      render api_paginate: paginated
+    end
+  end
+
+  private
+
+  def api_meta(resources)
+    {
+      pagination: api_pagination_meta(resources),
+      total: resources.respond_to?(:count) ? resources.count : resources.size
+    }
+  end
+end
+```
+
+**Example requests:**
+```bash
+# Get page 2 with 20 items per page
+GET /users?page[number]=2&page[size]=20
+```
+
+### ApiKit::Fetching
+
+Supports relationship inclusion and sparse fieldsets:
+
+```ruby
+class UsersController < ApplicationController
+  include ApiKit::Fetching
+
+  def index
+    render api: User.all
+  end
+
+  private
+
+  def api_include
+    # Whitelist allowed includes
+    super & [ "posts", "profile" ]
+  end
+end
+```
+
+**Example requests:**
+```bash
+# Include related posts
+GET /users?include=posts
+
+# Sparse fieldsets
+GET /users?fields[user]=first_name,last_name
+```
+
+### ApiKit::Errors
+
+Standardized error responses for common Rails exceptions:
+
+```ruby
+class UsersController < ApplicationController
+  include ApiKit::Errors
+
+  def create
+    user = User.new(user_params)
+
+    if user.save
+      render api: user, status: :created
+    else
+      render api_errors: user.errors, status: :unprocessable_entity
+    end
+  end
+
+  def update
+    user = User.find(params[:id])
+
+    if user.update(user_params)
+      render api: user
+    else
+      render api_errors: user.errors, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def user_params
+    params.require(:data).require(:attributes).permit(:first_name, :last_name, :email)
+  end
+
+  def render_api_internal_server_error(exception)
+    # Custom exception handling (e.g., error tracking)
+    # Sentry.capture_exception(exception)
+    super(exception)
+  end
+end
+```
+
+**Handled exceptions:**
+- `StandardError` → 500 Internal Server Error
+- `ActiveRecord::RecordNotFound` → 404 Not Found
+- `ActionController::ParameterMissing` → 422 Unprocessable Entity
+
+## Advanced Configuration
+
+### Custom Serializer Resolution
+
+```ruby
+class UsersController < ApplicationController
+  def index
+    render api: User.all, serializer_class: CustomUserSerializer
+  end
+
+  private
+
+  def api_serializer_class(resource, is_collection)
+    ApiKit::RailsApp.serializer_class(resource, is_collection)
+  rescue NameError
+    "#{resource.class.name}Serializer".constantize
+  end
+end
+```
+
+### Custom Page Size
+
+```ruby
+def api_page_size(pagination_params)
+  per_page = pagination_params[:size].to_i
+  return 30 if per_page < 1 || per_page > 100
+  per_page
+end
+```
+
+### Serializer Parameters
+
+```ruby
+def api_serializer_params
+  {
+    current_user: current_user,
+    include_private: params[:include_private].present?
+  }
+end
+```
+
+## Configuration
+
+### Environment Variables
+
+- `PAGINATION_LIMIT` - Default page size (default: 30)
+
+### Dependencies
+
+This gem leverages these excellent libraries:
+- [Active Model Serializers](https://github.com/rails-api/active_model_serializers) - Object serialization
+- [Ransack](https://github.com/activerecord-hackery/ransack) - Advanced filtering and sorting
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/iakbudak/api_kit
+
+This project follows the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## Development
+
+After checking out the repo:
+
+```bash
+bundle install
+bundle exec rspec  # Run tests
+bundle exec rubocop  # Check code style
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/api_kit/error_serializer.rb

@@ -0,0 +1,96 @@
+module ApiKit
+  # Serializer for JSON:API error responses
+
+  class ErrorSerializer
+    # The errors to be serialized
+    # @return [Array, ActiveModel::Errors] the errors to be serialized
+    attr_reader :errors
+
+    # Serialization options
+    # @return [Hash] serialization options
+    attr_reader :options
+
+    # Initialize the error serializer
+    #
+    # @param errors [ActiveModel::Errors, Array] errors to serialize
+    # @param options [Hash] serialization options
+    def initialize(errors, options = {})
+      @errors = if errors.is_a?(ActiveModel::Errors)
+                  errors.errors
+      else
+                  Array(errors)
+      end
+      @options = options
+    end
+
+    # Convert errors to JSON format
+    #
+    # @param args [Array] arguments passed to to_json
+    # @return [String] JSON representation of errors
+    def to_json(*args)
+      { errors: serialized_errors }.to_json(*args)
+    end
+
+    private
+
+    # Serialize errors into JSON:API format
+    #
+    # @return [Array<Hash>] array of serialized error objects
+    def serialized_errors
+      errors.map do |error|
+        if error.is_a?(Array) && error.size == 2
+          # Handle [attribute, error_hash] format from rails_app.rb
+          serialize_validation_error(error[0], error[1])
+        elsif error.is_a?(Hash)
+          # Handle direct hash format
+          serialize_hash_error(error)
+        else
+          # Handle generic errors
+          serialize_generic_error(error)
+        end
+      end
+    end
+
+    # Serialize validation error from ActiveModel
+    #
+    # @param attribute [Symbol, String] the attribute with the error
+    # @param error [Hash] the error details
+    # @return [Hash] serialized error object
+    def serialize_validation_error(attribute, error)
+      {
+        status: error[:status] || "422",
+        code: error[:code] || "invalid",
+        title: error[:title] || "Error",
+        detail: error[:message],
+        attribute: attribute
+      }.compact
+    end
+
+    # Serialize hash-formatted error
+    #
+    # @param error [Hash] the error hash
+    # @return [Hash] serialized error object
+    def serialize_hash_error(error)
+      {
+        status: error[:status] || "422",
+        code: error[:code] || "invalid",
+        title: error[:title] || "Error",
+        detail: error[:detail] || error["detail"]
+      }.compact
+    end
+
+    # Serialize generic error object
+    #
+    # @param error [Object] the error object
+    # @return [Hash] serialized error object
+    def serialize_generic_error(error)
+      {
+        status: "422",
+        code: error.type,
+        title: "Error",
+        detail: error.full_message,
+        attribute: error.attribute
+      }
+    end
+  end
+end

data/lib/api_kit/errors.rb

@@ -0,0 +1,75 @@
+require "rack/utils"
+
+module ApiKit
+  # Helpers to handle some error responses
+  #
+  # Most of the exceptions are handled in Rails by [ActionDispatch] middleware
+  # See: https://api.rubyonrails.org/classes/ActionDispatch/ExceptionWrapper.html
+  module Errors
+    # Callback will register the error handlers
+    #
+    # @return [Module]
+    def self.included(base)
+      base.class_eval do
+        rescue_from(
+          StandardError,
+          with: :render_api_internal_server_error
+        )
+
+        rescue_from(
+          ActiveRecord::RecordNotFound,
+          with: :render_api_not_found
+        )
+
+        rescue_from(
+          ActionController::ParameterMissing,
+          with: :render_api_unprocessable_entity
+        )
+      end
+    end
+
+    private
+      # Generic error handler callback
+      #
+      # @param exception [Exception] instance to handle
+      # @return [String] error response
+      def render_api_internal_server_error(exception)
+        error = {
+          status: "500",
+          code: "internal_server_error",
+          title: Rack::Utils::HTTP_STATUS_CODES[500],
+          detail: exception.message
+        }
+        render api_errors: [ error ], status: :internal_server_error
+      end
+
+      # Not found (404) error handler callback
+      #
+      # @param exception [Exception] instance to handle
+      # @return [String] error response
+      def render_api_not_found(exception)
+        error = {
+          status: "404",
+          code: "not_found",
+          title: Rack::Utils::HTTP_STATUS_CODES[404],
+          detail: "Resource not found"
+        }
+        render api_errors: [ error ], status: :not_found
+      end
+
+      # Unprocessable entity (422) error handler callback
+      #
+      # @param exception [Exception] instance to handle
+      # @return [String] error response
+      def render_api_unprocessable_entity(exception)
+        error = {
+          status: "422",
+          code: "unprocessable_entity",
+          title: Rack::Utils::HTTP_STATUS_CODES[422],
+          detail: "Required parameter missing or invalid"
+        }
+
+        render api_errors: [ error ], status: :unprocessable_content
+      end
+  end
+end

data/lib/api_kit/fetching.rb

@@ -0,0 +1,42 @@
+module ApiKit
+  # Inclusion and sparse fields support
+  module Fetching
+    private
+      # Extracts and formats sparse fieldsets for Active Model Serializers
+      #
+      # Ex.: `GET /resource?fields[relationship]=id,created_at`
+      #
+      # @return [Hash] in Active Model Serializers format
+      def api_fields(serializer_class = nil, model_name = nil)
+        return unless params[:fields].respond_to?(:each_pair)
+
+        result = []
+
+        if serializer_class
+          model_name ||= serializer_class.name.demodulize.delete_suffix("Serializer").underscore
+        end
+
+        keys = []
+        params[:fields].each do |k, v|
+          field_names = v.to_s.split(",").map(&:strip).compact.map(&:to_sym)
+          result << { k.to_sym => field_names }
+          keys << k
+        end
+
+        if model_name && serializer_class && !keys.include?(model_name)
+          result << { model_name.to_sym => serializer_class._attributes }
+        end
+
+        result
+      end
+
+      # Extracts and whitelists allowed includes
+      #
+      # Ex.: `GET /resource?include=relationship,relationship.subrelationship`
+      #
+      # @return [Array]
+      def api_include
+        params["include"].to_s.split(",").map(&:strip).compact
+      end
+  end
+end

data/lib/api_kit/filtering.rb

@@ -0,0 +1,103 @@
+require "ransack/predicate"
+require_relative "patches"
+
+# Filtering and sorting support
+module ApiKit
+  module Filtering
+    # Parses and returns the attribute and the predicate of a ransack field
+    #
+    # @param requested_field [String] the field to parse
+    # @return [Array] with the fields and the predicate
+    def self.extract_attributes_and_predicates(requested_field)
+      predicates = []
+      field_name = requested_field.to_s.dup
+
+      while Ransack::Predicate.detect_from_string(field_name).present? do
+        predicate = Ransack::Predicate
+          .detect_and_strip_from_string!(field_name)
+        predicates << Ransack::Predicate.named(predicate)
+      end
+
+      [ field_name.split(/_and_|_or_/), predicates.reverse ]
+    end
+
+    private
+    # Applies filtering and sorting to a set of resources if requested
+    #
+    # The fields follow [Ransack] specifications.
+    # See: https://github.com/activerecord-hackery/ransack#search-matchers
+    #
+    # Ex.: `GET /resource?filter[region_matches_any]=Lisb%&sort=-created_at,id`
+    #
+    # @param allowed_fields [Array] a list of allowed fields to be filtered
+    # @param options [Hash] extra flags to enable/disable features
+    # @return [ActiveRecord::Base] a collection of resources
+    def api_filter(resources, allowed_fields, options = {})
+      allowed_fields = allowed_fields.map(&:to_s)
+      extracted_params = api_filter_params(allowed_fields)
+      extracted_params[:sorts] = api_sort_params(allowed_fields, options)
+      resources = resources.ransack(extracted_params)
+      block_given? ? yield(resources) : resources
+    end
+
+    # Extracts and whitelists allowed fields to be filtered
+    #
+    # The fields follow [Ransack] specifications.
+    # See: https://github.com/activerecord-hackery/ransack#search-matchers
+    #
+    # @param allowed_fields [Array] a list of allowed fields to be filtered
+    # @return [Hash] to be passed to [ActiveRecord::Base#order]
+    def api_filter_params(allowed_fields)
+      filtered = {}
+      requested = params[:filter] || {}
+      allowed_fields = allowed_fields.map(&:to_s)
+
+      requested.each_pair do |requested_field, to_filter|
+        field_names, predicates = ApiKit::Filtering
+          .extract_attributes_and_predicates(requested_field)
+
+        wants_array = predicates.any? && predicates.map(&:wants_array).any?
+
+        if to_filter.is_a?(String) && wants_array
+          to_filter = to_filter.split(",")
+        end
+
+        if predicates.any? && (field_names - allowed_fields).empty?
+          filtered[requested_field] = to_filter
+        end
+      end
+
+      filtered
+    end
+
+    # Extracts and whitelists allowed fields (or expressions) to be sorted
+    #
+    # @param allowed_fields [Array] a list of allowed fields to be sorted
+    # @param options [Hash] extra options to enable/disable features
+    # @return [Hash] to be passed to [ActiveRecord::Base#order]
+    def api_sort_params(allowed_fields, options = {})
+      filtered = []
+      requested = params[:sort].to_s.split(",")
+
+      requested.each do |requested_field|
+        if requested_field.to_s.start_with?("-")
+          dir = "desc"
+          requested_field = requested_field[1..-1]
+        else
+          dir = "asc"
+        end
+
+        field_names, predicates = ApiKit::Filtering
+          .extract_attributes_and_predicates(requested_field)
+
+        next unless (field_names - allowed_fields).empty?
+        next if !options[:sort_with_expressions] && predicates.any?
+
+        # Convert to strings instead of hashes to allow joined table columns.
+        filtered << [ requested_field, dir ].join(" ")
+      end
+
+      filtered
+    end
+  end
+end