rails_api_kit 1.0.0

data/lib/api_kit/pagination.rb

@@ -0,0 +1,168 @@
+module ApiKit
+  # Pagination support
+  module Pagination
+    private
+    # Default number of items per page.
+    API_PAGE_SIZE = ENV.fetch("PAGINATION_LIMIT") { 30 }
+    # Default number of items per page.
+    PAGINATION_IGNORE_KEYS = %i[total_count total_page]
+
+    # Applies pagination to a set of resources
+    #
+    # Ex.: `GET /resource?page[number]=2&page[size]=10`
+    #
+    # @return [ActiveRecord::Base] a collection of resources
+    def api_paginate(resources, options = {})
+      offset, limit, _ = api_pagination_params
+
+      if resources.respond_to?(:offset)
+        resources = resources.offset(offset).limit(limit)
+      else
+        original_size = resources.size
+        resources = resources[(offset)..(offset + limit - 1)] || []
+
+        # Cache the original resources size to be used for pagination meta
+        resources.instance_variable_set(:@original_size, original_size)
+      end
+
+      if options[:total_count]
+        resources.instance_variable_set(
+          :@_predefined_total_count,
+          options[:total_count]
+        )
+      end
+
+      block_given? ? yield(resources) : resources
+    end
+
+    # Generates the pagination links
+    #
+    # @return [Array]
+    def api_pagination(resources)
+      links = {}
+
+      pagination = api_pagination_builder(resources)
+
+      return links if pagination.blank?
+
+      original_params = params.except(
+        *api_path_parameters.keys.map(&:to_s)
+      ).as_json.with_indifferent_access
+
+      original_params[:page] = original_params[:page].dup || {}
+      original_url = "?"
+
+      pagination.each do |page_name, number|
+        next if PAGINATION_IGNORE_KEYS.include?(page_name)
+
+        original_params[:page][:number] = number
+        arg_params = original_params
+        if page_name == :first || (number && number == 1)
+          arg_params = original_params.except(:page)
+        end
+
+        links[page_name] = number.nil? ? nil : (
+          original_url + CGI.unescape(arg_params.to_query)
+        )
+      end
+
+      links
+    end
+
+    # Generates pagination numbers
+    #
+    # @return [Hash] with the first, previous, next, current, last page,
+    # total_count, total_page numbers
+    def api_pagination_builder(resources)
+      return @_numbers if @_numbers
+      return {} unless ApiKit::RailsApp.is_collection?(resources)
+
+      _, limit, page = api_pagination_params
+
+      numbers = {
+        current: page,
+        first: nil,
+        prev: nil,
+        next: nil,
+        last: nil
+      }
+
+      total = resources.instance_variable_get(:@_predefined_total_count)
+      if total
+        # do nothing for this condition
+      elsif resources.respond_to?(:unscope)
+        total = resources.unscope(:limit, :offset, :order).size
+        total = total.size if total.is_a?(Hash)
+      else
+        # Try to fetch the cached size first
+        total = resources.instance_variable_get(:@original_size)
+        total ||= resources.size
+      end
+
+      last_page = [ 1, (total.to_f / limit).ceil ].max
+
+      numbers[:first] = 1
+      numbers[:last] = last_page
+
+      if page > 1
+        numbers[:prev] = page - 1
+      end
+
+      if page < last_page
+        numbers[:next] = page + 1
+      end
+
+      if total.present?
+        numbers[:total_count] = total
+        numbers[:total_page] = last_page
+      end
+
+      @_numbers = numbers
+    end
+
+    # Extracts the pagination meta
+    #
+    # @return [Hash] with the first, previous, next, current, last page numbers
+    def api_pagination_meta(resources)
+      pagination = api_pagination_builder(resources)
+      pagination.slice(:total_count, :total_page, :current)
+    end
+
+    # Extracts the pagination params
+    #
+    # @return [Array] with the offset, limit and the current page number
+    def api_pagination_params
+      pagination = params[:page].try(:slice, :number, :size) || {}
+      per_page = api_page_size(pagination)
+      num = [ 1, pagination[:number].to_f.to_i ].max
+
+      [ (num - 1) * per_page, per_page, num ]
+    end
+
+    # Retrieves the default page size
+    #
+    # @param per_page_param [Hash] opts the paginations params
+    # @option opts [String] :number the page number requested
+    # @option opts [String] :size the page size requested
+    #
+    # @return [Integer]
+    def api_page_size(pagination_params)
+      per_page = pagination_params[:size].to_f.to_i
+
+      return self.class
+              .const_get(:API_PAGE_SIZE)
+              .to_i if per_page < 1
+
+      per_page
+    end
+
+    # Fallback to Rack's parsed query string when Rails is not available
+    #
+    # @return [Hash]
+    def api_path_parameters
+      return request.path_parameters if request.respond_to?(:path_parameters)
+
+      request.send(:parse_query, request.query_string, "&;")
+    end
+  end
+end

data/lib/api_kit/patches.rb

@@ -0,0 +1,71 @@
+require "ransack"
+
+Ransack.configure do |config|
+  # Raise errors if a query contains an unknown predicate or attribute.
+  # Default is true (do not raise error on unknown conditions).
+  config.ignore_unknown_conditions = true
+
+  # Enable expressions
+  # See: https://www.rubydoc.info/github/rails/rails/Arel/Expressions
+  config.add_predicate(
+    "count", arel_predicate: "count",
+    validator: ->(_) { true }, compounds: false
+  )
+  config.add_predicate(
+    "count_distinct", arel_predicate: "count",
+    validator: ->(_) { true }, formatter: ->(_) { true }, compounds: false
+  )
+  config.add_predicate(
+    "sum", arel_predicate: "sum",
+    validator: ->(v) { true }, compounds: false
+  )
+  config.add_predicate(
+    "avg", arel_predicate: "average",
+    validator: ->(v) { true }, compounds: false
+  )
+  config.add_predicate(
+    "min", arel_predicate: "minimum",
+    validator: ->(v) { true }, compounds: false
+  )
+  config.add_predicate(
+    "max", arel_predicate: "maximum",
+    validator: ->(v) { true }, compounds: false
+  )
+end
+
+Ransack::Visitor.class_eval do
+  alias_method :original_visit_Ransack_Nodes_Sort, :visit_Ransack_Nodes_Sort
+
+  private
+  # Original method assumes sorting is done only by attributes
+  def visit_Ransack_Nodes_Sort(node)
+    # Try the default sorting visitor method...
+    binded = original_visit_Ransack_Nodes_Sort(node)
+    valid = (binded.valid? if binded.respond_to?(:valid?)) || true
+    return binded if binded.present? && valid
+
+    # Fallback to support the expressions...
+    binded = Ransack::Nodes::Condition.extract(node.context, node.name, nil)
+    valid = (binded.valid? if binded.respond_to?(:valid?)) || true
+    return unless binded.present? && valid
+
+    arel_pred = binded.arel_predicate
+    # Remove any alias when sorting...
+    arel_pred.alias = nil if arel_pred.respond_to?(:alias=)
+    arel_pred.public_send(node.dir)
+  end
+end
+
+Ransack::Nodes::Condition.class_eval do
+  alias_method :original_format_predicate, :format_predicate
+
+  private
+  # Original method doesn't respect the arity of expressions
+  # See: lib/ransack/adapters/active_record/ransack/nodes/condition.rb#L30-L42
+  def format_predicate(attribute)
+    original_format_predicate(attribute)
+  rescue ArgumentError
+    arel_pred = arel_predicate_for_attribute(attribute)
+    attribute.attr.public_send(arel_pred)
+  end
+end

data/lib/api_kit/rails_app.rb

@@ -0,0 +1,157 @@
+require "ostruct"
+
+# Rails integration
+module ApiKit
+  module RailsApp
+    API_PAGINATE_METHODS_MAPPING = {
+      meta: :api_meta,
+      links: :api_pagination,
+      fields: :api_fields,
+      include: :api_include,
+      params: :api_serializer_params
+    }
+
+    API_METHODS_MAPPING = {
+      meta: :api_meta,
+      fields: :api_fields,
+      include: :api_include,
+      params: :api_serializer_params
+    }
+
+    # Updates the mime types and registers the renderers
+    #
+    # @return [NilClass]
+    def self.install!
+      return unless defined?(::Rails)
+
+      parser = ActionDispatch::Request.parameter_parsers[:json]
+      ActionDispatch::Request.parameter_parsers[:api] = parser
+
+      self.add_renderer!
+      self.add_errors_renderer!
+    end
+
+
+    # Adds the error renderer
+    #
+    # @return [NilClass]
+    def self.add_errors_renderer!
+      ActionController::Renderers.add(:api_errors) do |resource, options|
+        self.content_type ||= Mime[:json]
+
+        many = ApiKit::RailsApp.is_collection?(resource, options[:is_collection])
+        resource = [ resource ] unless many
+
+        ApiKit::ErrorSerializer.new(resource, options).to_json
+      end
+    end
+
+    # Adds the default renderer
+    #
+    # @return [NilClass]
+    def self.add_renderer!
+      ActionController::Renderers.add(:api_paginate) do |resource, options|
+        self.content_type ||= Mime[:json]
+
+        result = {}
+        API_PAGINATE_METHODS_MAPPING.to_a[0..1].each do |opt, method_name|
+          next unless respond_to?(method_name, true)
+          result[opt] ||= send(method_name, resource)
+        end
+
+        # If it's an empty collection, return it directly.
+        many = ApiKit::RailsApp.is_collection?(resource, options[:is_collection])
+
+        API_PAGINATE_METHODS_MAPPING.to_a[2..-1].each do |opt, method_name|
+          options[opt] ||= send(method_name) if respond_to?(method_name, true)
+        end
+
+        if options[:serializer_class]
+          serializer_class = options[:serializer_class]
+        else
+          serializer_class = ApiKit::RailsApp.serializer_class(resource, many)
+        end
+
+        options[:fields] = api_fields(serializer_class, ApiKit::RailsApp.fetch_name(many, resource))
+        options[:adapter] = :attributes
+        options[:each_serializer] = serializer_class
+        data = ActiveModelSerializers::SerializableResource.new(resource, options).as_json
+        result[:data] = data
+        result.to_json
+      end
+
+      ActionController::Renderers.add(:api) do |resource, options|
+        self.content_type ||= Mime[:json]
+
+        result = {}
+        API_METHODS_MAPPING.to_a[0..0].each do |opt, method_name|
+          next unless respond_to?(method_name, true)
+          result[opt] ||= send(method_name, resource)
+        end
+
+        # If it's an empty collection, return it directly.
+        many = ApiKit::RailsApp.is_collection?(resource, options[:is_collection])
+
+        API_METHODS_MAPPING.to_a[1..-1].each do |opt, method_name|
+          options[opt] ||= send(method_name) if respond_to?(method_name, true)
+        end
+
+        if options[:serializer_class]
+          serializer_class = options[:serializer_class]
+        else
+          serializer_class = ApiKit::RailsApp.serializer_class(resource, many)
+        end
+
+        # Use Active Model Serializers properly with fallback
+        options[:fields] = api_fields(serializer_class, ApiKit::RailsApp.fetch_name(many, resource))
+        options[:adapter] = :attributes
+        options[:each_serializer] = serializer_class
+        if many
+          data = ActiveModelSerializers::SerializableResource.new(resource, options).as_json
+        else
+          data = ActiveModelSerializers::SerializableResource.new([ resource ], options).as_json[0]
+        end
+        result[:data] = data
+        result.to_json
+      end
+    end
+
+    # Checks if an object is a collection
+    #
+    # @param resource [Object] to check
+    # @param force_is_collection [NilClass] flag to overwrite
+    # @return [TrueClass] upon success
+    def self.is_collection?(resource, force_is_collection = nil)
+      return force_is_collection unless force_is_collection.nil?
+
+      resource.respond_to?(:size) && !resource.respond_to?(:each_pair)
+    end
+
+    # Resolves resource serializer class
+    #
+    # @return [Class]
+    def self.serializer_class(resource, is_collection)
+      klass = resource.class
+      klass = resource.first.class if is_collection
+
+      "#{klass.name}Serializer".constantize
+    end
+
+    # Resolves the singular model name for sparse fieldsets
+    #
+    # @param many [Boolean] indicates whether the resource is a collection
+    # @param resource [Object] serialized resource or collection
+    # @return [String, nil] singular model name when available
+    def self.fetch_name(many, resource)
+      if many
+        if resource.is_a?(ActiveRecord::Relation)
+          resource&.model_name&.singular
+        else
+          resource.first&.model_name&.singular
+        end
+      else
+        resource&.model_name&.singular
+      end
+    end
+  end
+end

data/lib/api_kit/version.rb

@@ -0,0 +1,3 @@
+module ApiKit
+  VERSION = "1.0.0"
+end

data/lib/api_kit.rb

@@ -0,0 +1,13 @@
+require "api_kit/errors"
+require "api_kit/error_serializer"
+require "api_kit/fetching"
+require "api_kit/filtering"
+require "api_kit/pagination"
+require "api_kit/rails_app"
+require "api_kit/version"
+
+# ApiKit
+module ApiKit
+  # ApiKit media type.
+  MEDIA_TYPE = "application/json".freeze
+end

data/lib/rails_api_kit.rb

@@ -0,0 +1 @@
+require "api_kit"

data/spec/dummy.rb

@@ -0,0 +1,201 @@
+require 'securerandom'
+require 'active_record'
+require 'action_controller/railtie'
+require 'api_kit'
+require 'ransack'
+require 'active_model_serializers'
+
+Rails.logger = Logger.new(STDOUT)
+Rails.logger.level = ENV['LOG_LEVEL'] || Logger::WARN
+
+ApiKit::RailsApp.install!
+
+ActiveRecord::Base.logger = Rails.logger
+ActiveRecord::Base.establish_connection(
+  ENV['DATABASE_URL'] || 'sqlite3::memory:'
+)
+
+ActiveRecord::Schema.define do
+  create_table :users, force: true do |t|
+    t.string :first_name
+    t.string :last_name
+    t.timestamps
+  end
+
+  create_table :notes, force: true do |t|
+    t.string :title
+    t.integer :user_id
+    t.integer :quantity
+    t.timestamps
+  end
+end
+
+
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+
+  def self.ransackable_associations(auth_object = nil)
+    @ransackable_associations ||= reflect_on_all_associations.map { |a| a.name.to_s }
+  end
+
+  def self.ransackable_attributes(auth_object = nil)
+    @ransackable_attributes ||= column_names + _ransackers.keys + _ransack_aliases.keys + attribute_aliases.keys
+  end
+end
+
+class User < ApplicationRecord
+  has_many :notes
+end
+
+class Note < ApplicationRecord
+  validates_format_of :title, without: /BAD_TITLE/
+  validates_numericality_of :quantity, less_than: 100, if: :quantity?
+  belongs_to :user, required: true
+end
+
+class RuntimeCustomNote
+  include ActiveModel::Model
+  include ActiveModel::Serialization
+
+  ATTRIBUTES = %w[id title quantity created_at updated_at user].freeze
+
+  attr_accessor(*ATTRIBUTES.map(&:to_sym))
+
+  def attributes
+    ATTRIBUTES.index_with { nil }
+  end
+end
+
+class CustomNoteSerializer < ActiveModel::Serializer
+  attributes :id, :title, :quantity, :created_at, :updated_at
+  belongs_to :user
+end
+
+class UserSerializer < ActiveModel::Serializer
+  attributes :id, :last_name, :created_at, :updated_at, :first_name
+  has_many :notes, serializer: CustomNoteSerializer
+  belongs_to :custom_note, serializer: CustomNoteSerializer do
+    RuntimeCustomNote.new(
+      id: 1,
+      title: "My",
+      quantity: 1,
+      created_at: Time.current,
+      updated_at: Time.current,
+      user: nil
+    )
+  end
+
+  def first_name
+    if @instance_options.dig(:params, :first_name_upcase)
+      object.first_name.upcase
+    else
+      object.first_name
+    end
+  end
+end
+
+class MyUserSerializer < UserSerializer
+  attribute :full_name
+
+  def full_name
+    "#{object.first_name} #{object.last_name}"
+  end
+end
+
+class Dummy < Rails::Application
+  # secrets.secret_key_base = '_'
+  config.hosts << 'www.example.com' if config.respond_to?(:hosts)
+
+  routes.draw do
+    scope defaults: { format: :api } do
+      resources :users, only: [ :index, :show ]
+      resources :notes, only: [ :update ]
+    end
+  end
+end
+
+class BaseApplicationController < ActionController::Base
+  def serialize_array(data, options = {})
+    options[:adapter] = :attributes
+    ActiveModelSerializers::SerializableResource.new(data, options).as_json
+  end
+end
+
+class UsersController < BaseApplicationController
+  include ApiKit::Fetching
+  include ApiKit::Filtering
+  include ApiKit::Pagination
+
+  def index
+    allowed_fields = [
+      :first_name, :last_name, :created_at,
+      :notes_created_at, :notes_quantity
+    ]
+    options = { sort_with_expressions: true }
+
+    api_filter(User.all, allowed_fields, options) do |filtered|
+      result = filtered.result
+
+      if params[:sort].to_s.include?('notes_quantity')
+        render api_paginate: result.group('id').to_a
+        return
+      end
+
+      result = result.to_a if params[:as_list]
+
+      api_paginate(result) do |paginated|
+        render api_paginate: paginated,
+              serializer_class: MyUserSerializer
+      end
+    end
+  end
+
+  def show
+    render api: User.find(params[:id]),
+           serializer_class: MyUserSerializer
+  end
+
+  private
+  def api_meta(resources)
+    {
+      many: true,
+      pagination: api_pagination_meta(resources)
+    }
+  end
+
+  def api_serializer_params
+    {
+      first_name_upcase: params[:upcase]
+    }
+  end
+end
+
+class NotesController < ActionController::Base
+  include ApiKit::Fetching
+  include ApiKit::Errors
+
+  def update
+    raise StandardError.new("tada") if params[:id] == 'tada'
+
+    note = Note.find(params[:id])
+
+    if note.update(note_params)
+      render api: note,
+             serializer_class: CustomNoteSerializer
+    else
+      note.errors.add(:title, message: 'has typos') if note.errors.key?(:title)
+
+      render api_errors: note.errors, status: :unprocessable_content
+    end
+  end
+
+  private
+
+    def note_params
+      params.require(:note).permit(:title, :user_id, :quantity, :created_at)
+    end
+
+    def api_meta(resources)
+      { single: true }
+    end
+end