jpie 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecbe7000fb7dd1053c155ec2f9de3866bd3eb3138e4509dc5e8d226bcdbb054a
-  data.tar.gz: 07e03b20414abbfe7fb849fd5dd99f5390633ff9498bad3d064b5ed3894973a2
+  metadata.gz: 4e425e58d806e51b4cb6ed58345acdc3169079011dca02fa8dfae18b57bbe70c
+  data.tar.gz: e0f9316d7a675048c5c63442e9f897452ffa62358d3ca73d8e8aa288122a623c
 SHA512:
-  metadata.gz: dc63cd8358e5a678bdd69e230f4a5842cf11ff0268006b615d0c5de7570d8da0ec9f83f7da40d2fc8d0758629fae95dfdde13eb34ef2ae384f1b764a6ac99857
-  data.tar.gz: ea527ed50fd384b5cd0e8f21a3cf1d5b23d7121f11b8ad712a5d44cf4adbdd1dfef56e8f2a50da3f34fe42698ef27ff538d59086c5575e70bc0ca9359b261a95
+  metadata.gz: 36c41c6de0027699b5534abe379930f67fc67698aa8016635a294b8ba5624ace0bedaeaebddfbf5708c3ad58696527b1e15f177ac84c36c272581cff123a52ec
+  data.tar.gz: c948938233596ef3345bc7186e8f78575f37c1057d9675850634ddb53c36506de7b26b89f14555fdca8659124ae8ec0b9908da39324f87cff90dd82aa2c8cd8d

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jpie (1.0.2)
+    jpie (1.1.0)
       actionpack (~> 8.0, >= 8.0.0)
       rails (~> 8.0, >= 8.0.0)
 

data/README.md

@@ -14,6 +14,7 @@ A Rails 8+ gem that provides JSON:API compliant routing DSL and generic JSON:API
 - Configurable pagination options
 - Content negotiation with Accept and Content-Type headers
 - Support for polymorphic and STI relationships
+- Namespace support for API versioning and modular organization
 
 ## Installation
 
@@ -679,6 +680,91 @@ This is useful when you need access to features available in `ActionController::
 
 **Note:** The configuration must be set before the gem's controllers are loaded. Set it in a Rails initializer that loads before `json_api` is required.
 
+### Namespace Support
+
+The gem supports namespaced resources, controllers, and models for API versioning or modular organization.
+
+#### Configuration Options
+
+```ruby
+JSONAPI.configure do |config|
+  # Type format in JSON:API responses: :flat (default), :prefixed, or :underscore
+  # :flat       -> "vendors" (namespace inferred from route context)
+  # :prefixed   -> "api/v1/vendors"
+  # :underscore -> "api_v1_vendors"
+  config.namespace_type_format = :flat
+
+  # Model mapping: :same_namespace (default) or :flat
+  # :same_namespace -> API::V1::VendorResource maps to API::V1::Vendor
+  # :flat           -> API::V1::VendorResource maps to Vendor
+  config.namespace_model_mapping = :same_namespace
+
+  # Fallback behavior when namespaced resource not found: true (default) or false
+  # When true, if API::V1::VendorResource not found, try VendorResource
+  config.namespace_fallback = true
+end
+```
+
+#### Namespaced Routes
+
+Use Rails' standard `namespace` or `scope` with `module:` to define namespaced JSON:API resources:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  namespace :api do
+    namespace :v1 do
+      jsonapi_resources :widgets
+    end
+  end
+end
+```
+
+This will:
+
+- Look for `API::V1::WidgetsController` (falls back to `JSONAPI::ResourcesController` if not found)
+- Load `API::V1::WidgetResource` (falls back to `WidgetResource` if `namespace_fallback: true`)
+- Pass `jsonapi_namespace: "api/v1"` to the controller
+
+#### Namespaced Resources
+
+Define resources within namespaces that match your route structure:
+
+```ruby
+# app/resources/api/v1/widget_resource.rb
+module API
+  module V1
+    class WidgetResource < JSONAPI::Resource
+      attributes :name, :description
+    end
+  end
+end
+```
+
+#### Per-Resource Type Format
+
+Override the global `namespace_type_format` for individual resources:
+
+```ruby
+class API::V1::WidgetResource < JSONAPI::Resource
+  self.type_format = :prefixed  # This resource will serialize as "api/v1/widgets"
+
+  attributes :name
+end
+```
+
+#### Explicit Model Class
+
+Override the automatic model class resolution:
+
+```ruby
+class API::V1::WidgetResource < JSONAPI::Resource
+  self.model_class = Widget  # Use flat Widget model regardless of config
+
+  attributes :name
+end
+```
+
 ## Authorization
 
 The gem provides two optional authorization hooks:
@@ -1182,8 +1268,7 @@ Content-Type: application/vnd.api+json
       "filename": "avatar.jpg",
       "content_type": "image/jpeg",
       "byte_size": 102400,
-      "checksum": "abc123...",
-      "url": "/rails/active_storage/blobs/.../avatar.jpg"
+      "checksum": "abc123..."
     },
     "links": {
       "self": "/active_storage_blobs/1",
@@ -1193,7 +1278,7 @@ Content-Type: application/vnd.api+json
 }
 ```
 
-The built-in `JSONAPI::ActiveStorageBlobResource` provides `filename`, `content_type`, `byte_size`, `checksum`, and `url` attributes, plus a download link.
+The built-in `JSONAPI::ActiveStorageBlobResource` provides `filename`, `content_type`, `byte_size`, and `checksum` attributes. The download URL is available via the `links.download` property.
 
 ### Attaching Files
 

data/lib/json_api/configuration.rb

@@ -3,7 +3,8 @@
 module JSONAPI
   class Configuration
     attr_accessor :default_page_size, :max_page_size, :jsonapi_meta, :authorization_handler,
-                  :authorization_scope, :document_meta_resolver
+                  :authorization_scope, :document_meta_resolver,
+                  :namespace_type_format, :namespace_model_mapping, :namespace_fallback
 
     def initialize
       @default_page_size = 25
@@ -13,6 +14,9 @@ module JSONAPI
       @authorization_scope = nil
       @document_meta_resolver = ->(controller:) { {} } # rubocop:disable Lint/UnusedBlockArgument
       @base_controller_class = "ActionController::API"
+      @namespace_type_format = :flat
+      @namespace_model_mapping = :same_namespace
+      @namespace_fallback = true
     end
 
     def base_controller_class=(value)

data/lib/json_api/controllers/concerns/controller_helpers/resource_setup.rb

@@ -6,7 +6,7 @@ module JSONAPI
       extend ActiveSupport::Concern
 
       included do
-        attr_reader :resource_class, :model_class
+        attr_reader :resource_class, :model_class, :jsonapi_namespace
       end
 
       protected
@@ -15,8 +15,13 @@ module JSONAPI
         @resource_name = params[:resource_type].to_s.singularize
       end
 
+      def set_jsonapi_namespace
+        @jsonapi_namespace = params[:jsonapi_namespace].presence
+      end
+
       def set_resource_class
-        @resource_class = JSONAPI::ResourceLoader.find(params[:resource_type])
+        namespace = params[:jsonapi_namespace].presence
+        @resource_class = JSONAPI::ResourceLoader.find(params[:resource_type], namespace:)
         @model_class = @resource_class.model_class
       rescue JSONAPI::ResourceLoader::MissingResourceClass => e
         render_resource_not_found_error(e.message)

data/lib/json_api/controllers/concerns/resource_actions/resource_loading.rb

@@ -9,7 +9,8 @@ module JSONAPI
 
       def load_jsonapi_resource
         @resource_name = params[:resource_type]&.singularize
-        @resource_class = JSONAPI::ResourceLoader.find(@resource_name) if @resource_name
+        @jsonapi_namespace = params[:jsonapi_namespace].presence
+        @resource_class = JSONAPI::ResourceLoader.find(@resource_name, namespace: @jsonapi_namespace) if @resource_name
         @model_class = @resource_class.model_class if @resource_class
         @resource = @model_class.find(params[:id]) if params[:id] && @model_class
       rescue JSONAPI::ResourceLoader::MissingResourceClass

data/lib/json_api/resources/concerns/model_class_helpers.rb

@@ -5,23 +5,42 @@ module JSONAPI
     module ModelClassHelpers
       extend ActiveSupport::Concern
 
+      module NamespaceResolution
+        def resolve_model_class_name
+          resource_name = name.sub(/Resource$/, "")
+          flat_namespace_mapping? ? resource_name.demodulize : resource_name
+        end
+
+        def flat_namespace_mapping?
+          JSONAPI.configuration.namespace_model_mapping == :flat
+        end
+
+        def resource_namespace
+          name.deconstantize.presence&.underscore
+        end
+      end
+
       class_methods do
+        include NamespaceResolution
+
+        attr_writer :model_class
+
         def resource_for_model(model_class)
-          resource_const = "#{model_class.name}Resource"
-          resource_const.safe_constantize if resource_const.respond_to?(:safe_constantize) || defined?(ActiveSupport)
+          "#{model_class.name}Resource".safe_constantize
         rescue NameError
           nil
         end
 
         def model_class
-          name.sub(/Resource$/, "").classify.constantize
+          return @model_class if defined?(@model_class) && @model_class
+
+          resolve_model_class_name.constantize
         end
 
         def safe_model_class
-          return nil unless respond_to?(:name) && name
-          return nil unless defined?(ActiveSupport)
+          return nil unless respond_to?(:name) && name && defined?(ActiveSupport)
 
-          name.sub(/Resource$/, "").classify.safe_constantize
+          resolve_model_class_name&.safe_constantize
         rescue NoMethodError
           nil
         end

data/lib/json_api/resources/resource.rb

@@ -16,6 +16,15 @@ module JSONAPI
     include Resources::MetaDsl
     include Resources::ModelClassHelpers
 
+    class << self
+      attr_accessor :type_format
+
+      def inherited(subclass)
+        super
+        subclass.type_format = type_format
+      end
+    end
+
     def initialize(record = nil, context = {})
       @record = record
       @context = context

data/lib/json_api/resources/resource_loader.rb

@@ -3,33 +3,82 @@
 module JSONAPI
   class ResourceLoader
     class MissingResourceClass < JSONAPI::Error
-      def initialize(resource_type)
-        super("Resource class for '#{resource_type}' not found. Define #{resource_type.singularize.classify}Resource < JSONAPI::Resource")
+      def initialize(resource_type, namespace: nil)
+        class_hint = build_class_hint(resource_type, namespace)
+        super("Resource class for '#{resource_type}' not found. Define #{class_hint} < JSONAPI::Resource")
+      end
+
+      private
+
+      def build_class_hint(resource_type, namespace)
+        base = "#{resource_type.singularize.classify}Resource"
+        namespace.present? ? "#{namespace.to_s.camelize}::#{base}" : base
       end
     end
 
-    def self.find(resource_type)
-      resource_class_name = "#{resource_type.singularize.classify}Resource"
-      resource_class_name.constantize
+    def self.find(resource_type, namespace: nil)
+      return find_namespaced(resource_type, namespace) if namespace.present?
+
+      find_flat(resource_type, namespace)
+    end
+
+    def self.find_namespaced(resource_type, namespace)
+      namespaced_class = build_resource_class_name(resource_type, namespace)
+      namespaced_class.constantize
     rescue NameError
-      raise MissingResourceClass, resource_type
+      raise MissingResourceClass.new(resource_type, namespace:) unless JSONAPI.configuration.namespace_fallback
+
+      find_flat(resource_type, namespace)
     end
 
-    def self.find_for_model(model_class)
-      # Handle ActiveStorage::Blob specially
-      return ActiveStorageBlobResource if defined?(::ActiveStorage) && model_class == ::ActiveStorage::Blob
+    def self.find_flat(resource_type, namespace)
+      flat_class = build_resource_class_name(resource_type, nil)
+      flat_class.constantize
+    rescue NameError
+      raise MissingResourceClass.new(resource_type, namespace:)
+    end
 
-      # For STI subclasses, try the specific subclass resource first
-      resource_type = model_class.name.underscore.pluralize
-      begin
-        find(resource_type)
-      rescue MissingResourceClass
-        # For STI subclasses, fall back to base class resource
-        raise unless model_class.respond_to?(:base_class) && model_class.base_class != model_class
+    def self.build_resource_class_name(resource_type, namespace)
+      base = "#{resource_type.singularize.classify}Resource"
+      return base unless namespace.present?
 
-        base_resource_type = model_class.base_class.name.underscore.pluralize
-        find(base_resource_type)
-      end
+      "#{namespace.to_s.camelize}::#{base}"
+    end
+
+    def self.find_for_model(model_class, namespace: nil)
+      return ActiveStorageBlobResource if active_storage_blob?(model_class)
+
+      find_resource_for_model(model_class, namespace)
+    end
+
+    def self.find_resource_for_model(model_class, namespace)
+      effective_namespace = namespace || extract_namespace_from_model(model_class)
+      resource_type = model_class.name.demodulize.underscore.pluralize
+
+      find(resource_type, namespace: effective_namespace)
+    rescue MissingResourceClass
+      find_base_class_resource(model_class, effective_namespace)
+    end
+
+    def self.find_base_class_resource(model_class, effective_namespace)
+      raise MissingResourceClass, model_class.name unless sti_subclass?(model_class)
+
+      base_resource_type = model_class.base_class.name.demodulize.underscore.pluralize
+      base_namespace = extract_namespace_from_model(model_class.base_class) || effective_namespace
+      find(base_resource_type, namespace: base_namespace)
+    end
+
+    def self.active_storage_blob?(model_class)
+      defined?(::ActiveStorage) && model_class == ::ActiveStorage::Blob
+    end
+
+    def self.sti_subclass?(model_class)
+      model_class.respond_to?(:base_class) && model_class.base_class != model_class
+    end
+
+    def self.extract_namespace_from_model(model_class)
+      parts = model_class.name.deconstantize
+      parts.presence&.underscore
     end
   end
 end

data/lib/json_api/routing.rb

@@ -4,32 +4,39 @@ module JSONAPI
   module Routing
     def jsonapi_resources(resource, controller: nil, defaults: {}, sti: false, **options, &)
       resource_name = resource.to_s
-      controller = detect_controller(resource_name) if controller.nil?
-
-      JSONAPI::ResourceLoader.find(resource_name)
-      defaults = defaults.merge(format: :jsonapi, resource_type: resource_name)
+      namespace = extract_namespace_from_scope
+      controller ||= detect_controller(resource_name, namespace)
+      defaults = build_jsonapi_defaults(defaults, resource_name, namespace)
       options[:only] = :index if sti
 
+      JSONAPI::ResourceLoader.find(resource_name, namespace:)
       define_resource_routes(resource, controller, defaults, options, &)
-      define_sti_routes(resource, resource_name, defaults, sti)
+      define_sti_routes(resource, resource_name, defaults, sti, namespace)
+    end
+
+    def build_jsonapi_defaults(defaults, resource_name, namespace)
+      defaults.merge(format: :jsonapi, resource_type: resource_name, jsonapi_namespace: namespace)
     end
 
     private
 
-    def detect_controller(resource_name)
-      potential_controller_name = build_controller_name(resource_name)
+    def extract_namespace_from_scope
+      @scope[:module]&.to_s.presence
+    end
+
+    def detect_controller(resource_name, namespace = nil)
+      potential_controller_name = build_controller_name(resource_name, namespace)
       potential_controller_name.constantize
       nil
     rescue NameError
       "json_api/resources"
     end
 
-    def build_controller_name(resource_name)
-      scoped_module = @scope[:module]
+    def build_controller_name(resource_name, namespace = nil)
       base_name = "#{resource_name.pluralize.camelize}Controller"
-      return base_name unless scoped_module
+      return base_name unless namespace
 
-      "#{scoped_module.to_s.camelize}::#{base_name}"
+      "#{namespace.to_s.camelize}::#{base_name}"
     end
 
     def define_resource_routes(resource, controller, defaults, options, &block)
@@ -47,15 +54,13 @@ module JSONAPI
       end
     end
 
-    def define_sti_routes(resource, resource_name, defaults, sti)
+    def define_sti_routes(resource, resource_name, defaults, sti, namespace = nil)
       return unless sti
 
       if sti.is_a?(Array)
-        define_explicit_sti_routes(sti,
-                                   defaults,)
+        define_explicit_sti_routes(sti, defaults)
       else
-        define_auto_sti_routes(resource, resource_name,
-                               defaults,)
+        define_auto_sti_routes(resource, resource_name, defaults, namespace)
       end
     end
 
@@ -63,13 +68,13 @@ module JSONAPI
       sti_resources.each { |sub_resource_name| jsonapi_resources(sub_resource_name, defaults:) }
     end
 
-    def define_auto_sti_routes(resource, resource_name, defaults)
-      resource_class = JSONAPI::ResourceLoader.find(resource_name)
+    def define_auto_sti_routes(resource, resource_name, defaults, namespace = nil)
+      resource_class = JSONAPI::ResourceLoader.find(resource_name, namespace:)
       model_class = resource_class.model_class
       return unless model_class.respond_to?(:descendants)
 
       model_class.descendants.each do |subclass|
-        sub_resource_name = subclass.name.underscore.pluralize.to_sym
+        sub_resource_name = subclass.name.demodulize.underscore.pluralize.to_sym
         next if sub_resource_name == resource.to_sym
 
         jsonapi_resources(sub_resource_name, defaults:)

data/lib/json_api/support/resource_identifier.rb

@@ -27,18 +27,35 @@ module JSONAPI
       raise ArgumentError, "Missing type or id in relationship data" unless type && id
 
       is_polymorphic = polymorphic_association?(definition, relationship_name)
-      validate_relationship_type!(type, association) unless is_polymorphic
+      validate_relationship_type!(type, association, definition) unless is_polymorphic
 
       find_related_record(type, id, association, is_polymorphic)
     end
 
-    def validate_relationship_type!(type, association)
-      expected_type = TypeConversion.model_type_name(association.klass)
-      return if type == expected_type
+    def validate_relationship_type!(type, association, definition = nil)
+      # Get expected type using the same format as the incoming type
+      format = resolve_type_format_from_incoming(type, definition)
+      expected_type = TypeConversion.model_type_name(association.klass, format:)
+
+      # Also check flat type for backwards compatibility
+      expected_flat = TypeConversion.model_type_name(association.klass, format: :flat)
+
+      return if type == expected_type || type == expected_flat
 
       raise ArgumentError, "Invalid relationship type: expected #{expected_type}, got #{type}"
     end
 
+    def resolve_type_format_from_incoming(type, definition)
+      # Detect format from incoming type string
+      if type.include?("/")
+        :prefixed
+      elsif definition.respond_to?(:type_format) && definition.type_format
+        definition.type_format
+      else
+        JSONAPI.configuration.namespace_type_format
+      end
+    end
+
     def find_related_record(type, id, association, is_polymorphic)
       related_model_class = resolve_related_model_class(type, association, is_polymorphic)
       related_model_class.find(id)

data/lib/json_api/support/type_conversion.rb

@@ -4,18 +4,52 @@ module JSONAPI
   module TypeConversion
     module_function
 
-    def type_to_class_name(type)
-      type.to_s.singularize.classify
+    def type_to_class_name(type, namespace: nil)
+      type_str = type.to_s
+      return prefixed_type_to_class(type_str) if type_str.include?("/")
+      return "#{namespace.to_s.camelize}::#{type_str.singularize.classify}" if namespace.present?
+
+      type_str.singularize.classify
+    end
+
+    def prefixed_type_to_class(type_str)
+      parts = type_str.split("/")
+      "#{parts[0..-2].join("/").camelize}::#{parts.last.singularize.classify}"
+    end
+
+    def model_type_name(model_class, format: nil)
+      format ||= JSONAPI.configuration.namespace_type_format
+
+      full_name = model_class.name.underscore.pluralize
+
+      format_type_name(full_name, format)
+    end
+
+    def resource_type_name(definition_class, format: nil)
+      format ||= resolve_type_format(definition_class)
+
+      full_name = definition_class.name.sub(/Resource$/, "").underscore.pluralize
+
+      format_type_name(full_name, format)
     end
 
-    def model_type_name(model_class)
-      model_class.name.underscore.pluralize
+    def format_type_name(full_name, format)
+      case format
+      when :prefixed
+        full_name
+      when :underscore
+        full_name.tr("/", "_")
+      else # :flat
+        full_name.split("/").last
+      end
     end
 
-    def resource_type_name(definition_class)
-      type_name = definition_class.name.sub(/Resource$/, "").underscore.pluralize
-      # Remove namespace prefix if present (e.g., "json_api/active_storage_blobs" -> "active_storage_blobs")
-      type_name.split("/").last
+    def resolve_type_format(definition_class)
+      if definition_class.respond_to?(:type_format) && definition_class.type_format
+        definition_class.type_format
+      else
+        JSONAPI.configuration.namespace_type_format
+      end
     end
   end
 end

data/lib/json_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONAPI
-  VERSION = "1.0.2"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Emil Kampp