rails_api_kit 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34e70026279699c8b1e1a1a3b4bcd5fe6e35ebd30114490eabc87db67444d84b
-  data.tar.gz: 1c24f1ad20cddc1340688d39d051caa659cfaaa35ef38e30e2b9c68603847f95
+  metadata.gz: 3c6f2c6b595530d2b1c63ad4a4e582c83e2555e04bc26c4d5e5c0e31e879fd34
+  data.tar.gz: 4c1700476844577653e7311cf315c1eaeca1c7eb82b1a33cd0dedd646e330311
 SHA512:
-  metadata.gz: 742002a691ca1ce8bf656e13be82c495aec57cd6741bf21e3e22293857f83d61a8308904b08a9910e2d76984ba48efedf196d052627d0e8c68300ee0cd474953
-  data.tar.gz: cf6e1acbb07f3e573f80122cad888e2409599b17f691c54933864ca49106357fa3ab3e8e58b862f5af232c13a5c555cbc3ef2be1067b57415913a6cc7af13f75
+  metadata.gz: 1c998192b4f161fb2cb4cd7f87253f94feb9a83e05b1e30e0f70a9e533130e2f0864da68205f9babbac0c8c8b26319606ef3567008ca25499e00b51f40566c0f
+  data.tar.gz: 05c8ffa12577ce6980e98750ff4e6050276c6b4cd5d4a7aaef2e2a24c693f470e39263106b0c96b28541fdd6dfe8959a15454553f61dd5a54a6088ff427efb70

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:

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/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.1"
 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/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.1
 platform: ruby
 authors:
 - Ismail Akbudak
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-06 00:00:00.000000000 Z
+date: 2026-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ransack
@@ -244,6 +244,7 @@ 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