rails_api_kit 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34e70026279699c8b1e1a1a3b4bcd5fe6e35ebd30114490eabc87db67444d84b
-  data.tar.gz: 1c24f1ad20cddc1340688d39d051caa659cfaaa35ef38e30e2b9c68603847f95
+  metadata.gz: 398056ff21cfe533837881bebaf65d87fff8c5abba87d5cdf8a9c708d55c90ef
+  data.tar.gz: 0b9de9c9f63c4312b898a03d5b8b142a57f82f7a353588f656a0b3cc8da2d290
 SHA512:
-  metadata.gz: 742002a691ca1ce8bf656e13be82c495aec57cd6741bf21e3e22293857f83d61a8308904b08a9910e2d76984ba48efedf196d052627d0e8c68300ee0cd474953
-  data.tar.gz: cf6e1acbb07f3e573f80122cad888e2409599b17f691c54933864ca49106357fa3ab3e8e58b862f5af232c13a5c555cbc3ef2be1067b57415913a6cc7af13f75
+  metadata.gz: d965e94656b77eec9b146898305aed13c67aa744c589e101065f87a828433e1a99e9677145d79285b0e630d7c26d31c0f1e0c63365b281f84007477e235a1afe
+  data.tar.gz: 45b408f991bbf95bc9341396249e2d12900a906cc0359120a6e1877607c4c41f1898fb79862db405fc13a874087ddca3aecafee5014beabf40b6421d841ad079

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019 Stas Suscov
+Copyright (c) 2026 Ismail Akbudak
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,9 +1,7 @@
-# ApiKit
+# RailsApiKit
 
 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:
@@ -294,7 +292,7 @@ This gem leverages these excellent libraries:
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/iakbudak/api_kit
+Bug reports and pull requests are welcome on GitHub at https://github.com/ismailakbudak/rails_api_kit
 
 This project follows the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 

data/lib/api_kit/fetching.rb

@@ -12,9 +12,7 @@ module ApiKit
 
         result = []
 
-        if serializer_class
-          model_name ||= serializer_class.name.demodulize.delete_suffix("Serializer").underscore
-        end
+        model_name ||= ApiKit::RailsApp.serializer_name(serializer_class)
 
         keys = []
         params[:fields].each do |k, v|

data/lib/api_kit/pagination.rb

@@ -49,7 +49,9 @@ module ApiKit
         *api_path_parameters.keys.map(&:to_s)
       ).as_json.with_indifferent_access
 
-      original_params[:page] = original_params[:page].dup || {}
+      # A blank `page=` passed `api_pagination_params` as "no page"; links build a fresh one.
+      page = original_params[:page]
+      original_params[:page] = page.is_a?(Hash) ? page.dup : {}
       original_url = "?"
 
       pagination.each do |page_name, number|
@@ -132,7 +134,16 @@ module ApiKit
     #
     # @return [Array] with the offset, limit and the current page number
     def api_pagination_params
-      pagination = params[:page].try(:slice, :number, :size) || {}
+      page = params[:page]
+      # `page=` names no page: the defaults, like a missing `page`.
+      page = nil if page.is_a?(String) && page.blank?
+      # `page=2` (or a JSON array / number) is not `page[number]=2`: a client error like
+      # `params.expect`, not a 500 from #slice.
+      unless page.nil? || page.is_a?(ActionController::Parameters) || page.is_a?(Hash)
+        raise ActionController::ParameterMissing, :page
+      end
+
+      pagination = page.try(:slice, :number, :size) || {}
       per_page = api_page_size(pagination)
       num = [ 1, pagination[:number].to_f.to_i ].max
 

data/lib/api_kit/rails_app.rb

@@ -75,6 +75,7 @@ module ApiKit
         options[:fields] = api_fields(serializer_class, ApiKit::RailsApp.fetch_name(many, resource))
         options[:adapter] = :attributes
         options[:each_serializer] = serializer_class
+        ApiKit::RailsApp.assign_collection_root!(options, resource, serializer_class) if many
         data = ActiveModelSerializers::SerializableResource.new(resource, options).as_json
         result[:data] = data
         result.to_json
@@ -107,6 +108,7 @@ module ApiKit
         options[:adapter] = :attributes
         options[:each_serializer] = serializer_class
         if many
+          ApiKit::RailsApp.assign_collection_root!(options, resource, serializer_class)
           data = ActiveModelSerializers::SerializableResource.new(resource, options).as_json
         else
           data = ActiveModelSerializers::SerializableResource.new([ resource ], options).as_json[0]
@@ -137,21 +139,79 @@ module ApiKit
       "#{klass.name}Serializer".constantize
     end
 
-    # Resolves the singular model name for sparse fieldsets
+    # Resolves the model name used as the sparse-fieldset type key
+    #
+    # Mirrors `ActiveModel::Serializer#json_key`, which AMS uses to look a
+    # type up in the fieldset: `object.class.model_name.to_s.underscore`.
+    # NOT `model_name.singular` — that tr()s the namespace separator to an
+    # underscore (`manufacturing_work_order`), so for a namespaced model the
+    # key never matched, the primary type went unconstrained, and AMS fell
+    # through to the pluralised collection key whose value is an empty list:
+    # every attribute of the primary resource was silently dropped.
     #
     # @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
+    # @return [String, nil] 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
+      record = many ? collection_model(resource) : resource
+      model_name = record&.model_name
+      model_name && model_name.to_s.underscore
+    end
+
+    # Root key for a collection AMS cannot infer one for
+    #
+    # `AMS::CollectionSerializer#json_key` reads the root from its first
+    # element, or from a named collection (`ActiveRecord::Relation` answers
+    # `#name` through its klass). An EMPTY plain Array offers neither, so it
+    # raises `CannotInferRootKeyError` the moment sparse fieldsets are
+    # requested. Aggregation endpoints that render POROs hit exactly that.
+    #
+    # Returns nil whenever AMS can infer the key itself, so a collection that
+    # already works keeps its own root and item serializers keep their
+    # `json_key`.
+    #
+    # @param resource [Object] the collection being serialized
+    # @param serializer_class [Class, NilClass] serializer for its members
+    # @return [String, nil] pluralised root key, or nil to leave it to AMS
+    def self.collection_root(resource, serializer_class)
+      return nil unless resource.respond_to?(:empty?) && resource.empty?
+      return nil if resource.respond_to?(:name)
+
+      name = serializer_name(serializer_class)
+      name && name.pluralize
+    end
+
+    # Sets the collection root only when AMS could not work one out
+    #
+    # @param options [Hash] render options, mutated in place
+    # @param resource [Object] the collection being serialized
+    # @param serializer_class [Class, NilClass] serializer for its members
+    # @return [NilClass]
+    def self.assign_collection_root!(options, resource, serializer_class)
+      return if options[:root]
+
+      root = collection_root(resource, serializer_class)
+      options[:root] = root if root
+      nil
+    end
+
+    # Resolves the type name a serializer class stands for
+    #
+    # @param serializer_class [Class, NilClass] e.g. `V1::UserSerializer`
+    # @return [String, nil] e.g. `"user"`
+    def self.serializer_name(serializer_class)
+      name = serializer_class && serializer_class.name
+      name && name.demodulize.delete_suffix("Serializer").underscore
+    end
+
+    # Resolves the record a collection's model name should come from
+    #
+    # @param resource [Object] the collection
+    # @return [Object, NilClass] a record responding to `model_name`
+    def self.collection_model(resource)
+      return resource if resource.is_a?(ActiveRecord::Relation)
+
+      resource.respond_to?(:first) ? resource.first : nil
     end
   end
 end

data/lib/api_kit/version.rb

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

data/spec/dummy.rb

@@ -28,6 +28,12 @@ ActiveRecord::Schema.define do
     t.integer :quantity
     t.timestamps
   end
+
+  create_table :inventory_items, force: true do |t|
+    t.string :name
+    t.integer :quantity
+    t.timestamps
+  end
 end
 
 
@@ -94,6 +100,32 @@ class UserSerializer < ActiveModel::Serializer
   end
 end
 
+# Namespaced model — `model_name.to_s.underscore` is slash-separated
+# (`inventory/item`) while `model_name.singular` is not
+# (`inventory_item`). The sparse-fieldset type key is the former.
+module Inventory
+  class Item < ApplicationRecord
+    self.table_name = 'inventory_items'
+  end
+
+  class ItemSerializer < ActiveModel::Serializer
+    attributes :id, :name, :quantity
+  end
+end
+
+# A row of an aggregation endpoint: a PORO, not an AR record, rendered as
+# a plain Array. An empty one gives AMS nothing to infer a root key from.
+class ReportRow
+  include ActiveModel::Model
+  include ActiveModel::Serialization
+
+  attr_accessor :label, :total
+end
+
+class ReportRowSerializer < ActiveModel::Serializer
+  attributes :label, :total
+end
+
 class MyUserSerializer < UserSerializer
   attribute :full_name
 
@@ -110,6 +142,8 @@ class Dummy < Rails::Application
     scope defaults: { format: :api } do
       resources :users, only: [ :index, :show ]
       resources :notes, only: [ :update ]
+      resources :inventory_items, only: [ :index ]
+      resources :reports, only: [ :index ]
     end
   end
 end
@@ -170,6 +204,29 @@ class UsersController < BaseApplicationController
   end
 end
 
+class InventoryItemsController < BaseApplicationController
+  include ApiKit::Fetching
+
+  def index
+    render api: Inventory::Item.all, serializer_class: Inventory::ItemSerializer
+  end
+end
+
+class ReportsController < BaseApplicationController
+  include ApiKit::Fetching
+
+  def index
+    rows =
+      if params[:empty]
+        []
+      else
+        [ ReportRow.new(label: 'first', total: 1) ]
+      end
+
+    render api: rows, serializer_class: ReportRowSerializer
+  end
+end
+
 class NotesController < ActionController::Base
   include ApiKit::Fetching
   include ApiKit::Errors

data/spec/filtering_spec.rb

@@ -40,11 +40,18 @@ RSpec.describe UsersController, type: :request do
       let(:user) { users.last }
 
       context 'returns filtered users' do
+        # FFaker names are random, so filter on a token that no other user
+        # can match by accident
+        let(:name_prefix) { 'Filterable' }
+        let(:filterable_name) { "#{name_prefix}#{third_user.id}" }
+
         let(:params) do
+          third_user.update(first_name: filterable_name)
+
           {
             filter: {
               last_name_or_first_name_cont_any: (
-                "#{third_user.first_name[0..5]}%,#{self.class.name}"
+                "#{name_prefix},#{self.class.name}"
               )
             }
           }
@@ -56,6 +63,27 @@ RSpec.describe UsersController, type: :request do
           expect(response_json['data'][0]['id']).to eql(third_user.id)
         end
 
+        # `cont` escapes LIKE wildcards, `matches` passes them through
+        context 'with a wildcard' do
+          let(:params) do
+            third_user.update(first_name: filterable_name)
+
+            {
+              filter: {
+                last_name_or_first_name_matches_any: (
+                  "#{name_prefix}%,#{self.class.name}"
+                )
+              }
+            }
+          end
+
+          it do
+            expect(response).to have_http_status(:ok)
+            expect(response_json['data'].size).to eq(1)
+            expect(response_json['data'][0]['id']).to eql(third_user.id)
+          end
+        end
+
         context 'with a comma' do
           let(:params) do
             third_user.update(first_name: third_user.first_name + ',')

data/spec/pagination_spec.rb

@@ -332,4 +332,50 @@ RSpec.describe UsersController, type: :request do
       end
     end
   end
+
+  describe 'GET /users with a scalar page' do
+    # `page=2` is not `page[number]=2`: ParameterMissing, a client error, not a 500 from
+    # String#slice. This controller has no ApiKit::Errors, so Rails answers 400; with it, 422.
+    [ 'page=2', 'page[]=2' ].each do |query|
+      it "answers #{query} with a client error" do
+        get("#{users_path}?#{query}", headers: api_headers)
+
+        expect(response).to have_http_status(:bad_request)
+      end
+    end
+  end
+
+  describe 'GET /users with a blank page' do
+    # `page=` names no page: the defaults, like a missing `page`.
+    [ 'page=', 'page=%20' ].each do |query|
+      it "answers #{query} with the first page" do
+        get("#{users_path}?#{query}", headers: api_headers)
+
+        expect(response).to have_http_status(:ok)
+        expect(response_json.dig('meta', 'pagination', 'current')).to eq(1)
+      end
+    end
+  end
+
+  describe '#api_pagination_params with a typed non-hash page' do
+    # A JSON body reaches it typed: an array or a number is malformed too, never a #slice error.
+    let(:controller_class) do
+      Class.new do
+        include ApiKit::Pagination
+
+        attr_reader :params
+
+        def initialize(params)
+          @params = ActionController::Parameters.new(params)
+        end
+      end
+    end
+
+    [ [], 2 ].each do |page|
+      it "raises ParameterMissing for #{page.inspect}" do
+        expect { controller_class.new(page: page).send(:api_pagination_params) }
+          .to raise_error(ActionController::ParameterMissing)
+      end
+    end
+  end
 end

data/spec/sparse_fields_type_key_spec.rb

@@ -0,0 +1,87 @@
+require 'spec_helper'
+
+# The sparse-fieldset type key AMS looks a serializer up by is
+# `model_name.to_s.underscore`. api_kit has to derive the same string when it
+# injects the fallback "everything for the primary type" entry, or AMS falls
+# through to the pluralised collection key — whose value is an empty list.
+RSpec.describe 'sparse fieldsets', type: :request do
+  describe 'GET /inventory_items' do
+    let!(:item) { Inventory::Item.create!(name: 'Bolt', quantity: 7) }
+
+    before { get(inventory_items_path, params: params, headers: api_headers) }
+
+    context 'when fields are sent for the primary type' do
+      let(:params) { { fields: { 'inventory/item' => 'id,name' } } }
+
+      it 'trims the primary type to the requested attributes' do
+        expect(response).to have_http_status(:ok)
+        expect(response_json['data'].first.keys).to contain_exactly('id', 'name')
+      end
+    end
+
+    context 'when fields are sent only for another type' do
+      let(:params) { { fields: { user: 'id' } } }
+
+      it 'leaves the namespaced primary type fully populated' do
+        expect(response).to have_http_status(:ok)
+        expect(response_json['data'].first.keys)
+          .to contain_exactly('id', 'name', 'quantity')
+      end
+    end
+
+    context 'without any fields param' do
+      let(:params) { {} }
+
+      it 'returns every attribute' do
+        expect(response).to have_http_status(:ok)
+        expect(response_json['data'].first.keys)
+          .to contain_exactly('id', 'name', 'quantity')
+      end
+    end
+  end
+
+  # `AMS::CollectionSerializer#json_key` infers the root from the first element,
+  # or from a collection that answers `#name` (an `ActiveRecord::Relation` does,
+  # through its klass). An empty plain Array answers neither, and raises
+  # `CannotInferRootKeyError` as soon as a fieldset has to be built.
+  describe 'GET /reports' do
+    before { get(reports_path, params: params, headers: api_headers) }
+
+    context 'with rows and a fields param' do
+      let(:params) { { fields: { report_row: 'label' } } }
+
+      it 'trims the PORO row to the requested attributes' do
+        expect(response).to have_http_status(:ok)
+        expect(response_json['data'].first.keys).to contain_exactly('label')
+      end
+    end
+
+    context 'with rows and no fields param' do
+      let(:params) { {} }
+
+      it 'returns every attribute' do
+        expect(response).to have_http_status(:ok)
+        expect(response_json['data'].first.keys)
+          .to contain_exactly('label', 'total')
+      end
+    end
+
+    context 'with no rows and a fields param' do
+      let(:params) { { empty: true, fields: { report_row: 'label' } } }
+
+      it 'renders an empty collection instead of failing to infer a root' do
+        expect(response).to have_http_status(:ok)
+        expect(response_json['data']).to eq([])
+      end
+    end
+
+    context 'with no rows and no fields param' do
+      let(:params) { { empty: true } }
+
+      it 'renders an empty collection' do
+        expect(response).to have_http_status(:ok)
+        expect(response_json['data']).to eq([])
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_api_kit
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Ismail Akbudak
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-06 00:00:00.000000000 Z
+date: 2026-11-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ransack
@@ -244,9 +244,10 @@ files:
 - spec/fetching_spec.rb
 - spec/filtering_spec.rb
 - spec/pagination_spec.rb
+- spec/sparse_fields_type_key_spec.rb
 - spec/spec_helper.rb
 - spec/support/api_kit_rspec.rb
-homepage: https://github.com/iakbudak/api_kit
+homepage: https://github.com/ismailakbudak/rails_api_kit
 licenses:
 - MIT
 metadata: {}
@@ -265,7 +266,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: A lightweight toolkit for building JSON:API compliant APIs with Rails.