Generate links using route helpers, formalize singletons

* warn when links can not be built
* add option to exclude building resource and relationship links
* add to_s for relationships for prettier warning messages and debugging
* add additional support for singleton resources with id resolution and routing
* fix naming `LinksObjectOperationResult` => `RelationshipOperationResult` and associated methods

Author: lgebhardt

lib/jsonapi/basic_resource.rb

@@ -422,6 +422,8 @@ def inherited(subclass)
         subclass.abstract(false)
         subclass.immutable(false)
         subclass.caching(_caching)
+        subclass.singleton(singleton?, (_singleton_options.dup || {}))
+        subclass.exclude_links(_exclude_links)
         subclass.paginator(_paginator)
         subclass._attributes = (_attributes || {}).dup
         subclass.polymorphic(false)
@@ -628,6 +630,19 @@ def model_hint(model: _model_name, resource: _type)
         _model_hints[model.to_s.gsub('::', '/').underscore] = resource_type.to_s
       end
 
+      def singleton(*attrs)
+        @_singleton = (!!attrs[0] == attrs[0]) ? attrs[0] : true
+        @_singleton_options = attrs.extract_options!
+      end
+
+      def _singleton_options
+        @_singleton_options ||= {}
+      end
+
+      def singleton?
+        @_singleton ||= false
+      end
+
       def filters(*attrs)
         @_allowed_filters.merge!(attrs.inject({}) { |h, attr| h[attr] = {}; h })
       end
@@ -740,6 +755,24 @@ def resource_key_type
         @_resource_key_type ||= JSONAPI.configuration.resource_key_type
       end
 
+      # override to all resolution of masked ids to actual ids. Because singleton routes do not specify the id this
+      # will be needed to allow lookup of singleton resources. Alternately singleton resources can override
+      # `verify_key`
+      def singleton_key(context)
+        if @_singleton_options && @_singleton_options[:singleton_key]
+          strategy = @_singleton_options[:singleton_key]
+          case strategy
+            when Proc
+              key = strategy.call(context)
+            when Symbol, String
+              key = send(strategy, context)
+            else
+              raise "singleton_key must be a proc or function name"
+          end
+        end
+        key
+      end
+
       def verify_key(key, context = nil)
         key_type = resource_key_type
 
@@ -927,6 +960,27 @@ def mutable?
         !@immutable
       end
 
+      def exclude_links(exclude)
+        case exclude
+          when :default, "default"
+            @_exclude_links = [:self]
+          when :none, "none"
+            @_exclude_links = []
+          when Array
+            @_exclude_links = exclude.collect {|link| link.to_sym}
+          else
+            fail "Invalid exclude_links"
+        end
+      end
+
+      def _exclude_links
+        @_exclude_links ||= []
+      end
+
+      def exclude_link?(link)
+        _exclude_links.include?(link.to_sym)
+      end
+
       def caching(val = true)
         @caching = val
       end

lib/jsonapi/configuration.rb

@@ -9,6 +9,7 @@ class Configuration
                 :route_format,
                 :raise_if_parameters_not_allowed,
                 :warn_on_route_setup_issues,
+                :warn_on_missing_routes,
                 :default_allow_include_to_one,
                 :default_allow_include_to_many,
                 :allow_sort,
@@ -57,6 +58,7 @@ def initialize
       self.raise_if_parameters_not_allowed = true
 
       self.warn_on_route_setup_issues = true
+      self.warn_on_missing_routes = true
 
       # :none, :offset, :paged, or a custom paginator name
       self.default_paginator = :none
@@ -261,6 +263,8 @@ def allow_include=(allow_include)
 
     attr_writer :warn_on_route_setup_issues
 
+    attr_writer :warn_on_missing_routes
+
     attr_writer :use_relationship_reflection
 
     attr_writer :resource_cache

lib/jsonapi/link_builder.rb

@@ -2,59 +2,79 @@ module JSONAPI
   class LinkBuilder
     attr_reader :base_url,
                 :primary_resource_klass,
-                :route_formatter,
-                :engine_name
+                :engine,
+                :routes
 
     def initialize(config = {})
       @base_url               = config[:base_url]
       @primary_resource_klass = config[:primary_resource_klass]
-      @route_formatter        = config[:route_formatter]
-      @engine_name            = build_engine_name
+      @engine                 = build_engine
 
-      # Warning: These make LinkBuilder non-thread-safe. That's not a problem with the
-      # request-specific way it's currently used, though.
-      @resources_path_cache   = JSONAPI::NaiveCache.new do |source_klass|
-        formatted_module_path_from_class(source_klass) + format_route(source_klass._type.to_s)
+      if engine?
+        @routes = @engine.routes
+      else
+        @routes = Rails.application.routes
       end
+
+      # ToDo: Use NaiveCache for values. For this we need to not return nils and create composite keys which work
+      # as efficient cache lookups. This could be an array of the [source.identifier, relationship] since the
+      # ResourceIdentity will compare equality correctly
     end
 
     def engine?
-      !!@engine_name
+      !!@engine
     end
 
     def primary_resources_url
-      if engine?
-        engine_primary_resources_url
-      else
-        regular_primary_resources_url
-      end
+      @primary_resources_url_cached ||= "#{ base_url }#{ primary_resources_path }"
+    rescue NoMethodError
+      warn "primary_resources_url for #{@primary_resource_klass} could not be generated" if JSONAPI.configuration.warn_on_missing_routes
     end
 
     def query_link(query_params)
       "#{ primary_resources_url }?#{ query_params.to_query }"
     end
 
     def relationships_related_link(source, relationship, query_params = {})
-      url = "#{ self_link(source) }/#{ route_for_relationship(relationship) }"
+      if relationship.parent_resource.singleton?
+        url_helper_name = singleton_related_url_helper_name(relationship)
+        url = call_url_helper(url_helper_name)
+      else
+        url_helper_name = related_url_helper_name(relationship)
+        url = call_url_helper(url_helper_name, source.id)
+      end
+
+      url = "#{ base_url }#{ url }"
       url = "#{ url }?#{ query_params.to_query }" if query_params.present?
       url
+    rescue NoMethodError
+      warn "related_link for #{relationship} could not be generated" if JSONAPI.configuration.warn_on_missing_routes
     end
 
     def relationships_self_link(source, relationship)
-      "#{ self_link(source) }/relationships/#{ route_for_relationship(relationship) }"
+      if relationship.parent_resource.singleton?
+        url_helper_name = singleton_relationship_self_url_helper_name(relationship)
+        url = call_url_helper(url_helper_name)
+      else
+        url_helper_name = relationship_self_url_helper_name(relationship)
+        url = call_url_helper(url_helper_name, source.id)
+      end
+
+      url = "#{ base_url }#{ url }"
+      url
+    rescue NoMethodError
+      warn "self_link for #{relationship} could not be generated" if JSONAPI.configuration.warn_on_missing_routes
     end
 
     def self_link(source)
-      if engine?
-        engine_resource_url(source)
-      else
-        regular_resource_url(source)
-      end
+      "#{ base_url }#{ resource_path(source) }"
+    rescue NoMethodError
+      warn "self_link for #{source.class} could not be generated" if JSONAPI.configuration.warn_on_missing_routes
     end
 
     private
 
-    def build_engine_name
+    def build_engine
       scopes = module_scopes_from_class(primary_resource_klass)
 
       begin
@@ -68,93 +88,96 @@ def build_engine_name
       end
     end
 
-    def engine_path_from_resource_class(klass)
-      path_name = engine_resources_path_name_from_class(klass)
-      engine_name.routes.url_helpers.public_send(path_name)
+    def call_url_helper(method, *args)
+      routes.url_helpers.public_send(method, args)
+    rescue NoMethodError => e
+      raise e
     end
 
-    def engine_primary_resources_path
-      engine_path_from_resource_class(primary_resource_klass)
+    def path_from_resource_class(klass)
+      url_helper_name = resources_url_helper_name_from_class(klass)
+      call_url_helper(url_helper_name)
     end
 
-    def engine_primary_resources_url
-      "#{ base_url }#{ engine_primary_resources_path }"
+    def resource_path(source)
+      url_helper_name = resource_url_helper_name_from_source(source)
+      if source.class.singleton?
+        call_url_helper(url_helper_name)
+      else
+        call_url_helper(url_helper_name, source.id)
+      end
     end
 
-    def engine_resource_path(source)
-      resource_path_name = engine_resource_path_name_from_source(source)
-      engine_name.routes.url_helpers.public_send(resource_path_name, source.id)
+    def primary_resources_path
+      path_from_resource_class(primary_resource_klass)
     end
 
-    def engine_resource_path_name_from_source(source)
-      scopes         = module_scopes_from_class(source.class)[1..-1]
-      base_path_name = scopes.map { |scope| scope.underscore }.join("_")
-      end_path_name  = source.class._type.to_s.singularize
-      [base_path_name, end_path_name, "path"].reject(&:blank?).join("_")
+    def url_helper_name_from_parts(parts)
+      (parts << "path").reject(&:blank?).join("_")
     end
 
-    def engine_resource_url(source)
-      "#{ base_url }#{ engine_resource_path(source) }"
-    end
+    def resources_path_parts_from_class(klass)
+      if engine?
+        scopes = module_scopes_from_class(klass)[1..-1]
+      else
+        scopes = module_scopes_from_class(klass)
+      end
 
-    def engine_resources_path_name_from_class(klass)
-      scopes         = module_scopes_from_class(klass)[1..-1]
       base_path_name = scopes.map { |scope| scope.underscore }.join("_")
       end_path_name  = klass._type.to_s
-
-      if base_path_name.blank?
-        "#{ end_path_name }_path"
-      else
-        "#{ base_path_name }_#{ end_path_name }_path"
-      end
+      [base_path_name, end_path_name]
     end
 
-    def format_route(route)
-      route_formatter.format(route)
+    def resources_url_helper_name_from_class(klass)
+      url_helper_name_from_parts(resources_path_parts_from_class(klass))
     end
 
-    def formatted_module_path_from_class(klass)
-      scopes = module_scopes_from_class(klass)
-
-      unless scopes.empty?
-        "/#{ scopes.map{ |scope| format_route(scope.to_s.underscore) }.compact.join('/') }/"
+    def resource_path_parts_from_class(klass)
+      if engine?
+        scopes = module_scopes_from_class(klass)[1..-1]
       else
-        "/"
+        scopes = module_scopes_from_class(klass)
       end
-    end
 
-    def module_scopes_from_class(klass)
-      klass.name.to_s.split("::")[0...-1]
+      base_path_name = scopes.map { |scope| scope.underscore }.join("_")
+      end_path_name  = klass._type.to_s.singularize
+      [base_path_name, end_path_name]
     end
 
-    def regular_resources_path(source_klass)
-      @resources_path_cache.get(source_klass)
+    def resource_url_helper_name_from_source(source)
+       url_helper_name_from_parts(resource_path_parts_from_class(source.class))
     end
 
-    def regular_primary_resources_path
-      regular_resources_path(primary_resource_klass)
+    def related_url_helper_name(relationship)
+      relationship_parts = resource_path_parts_from_class(relationship.parent_resource)
+      relationship_parts << relationship.name
+      url_helper_name_from_parts(relationship_parts)
     end
 
-    def regular_primary_resources_url
-      "#{ base_url }#{ regular_primary_resources_path }"
+    def singleton_related_url_helper_name(relationship)
+      relationship_parts = []
+      relationship_parts << relationship.name
+      relationship_parts += resource_path_parts_from_class(relationship.parent_resource)
+      url_helper_name_from_parts(relationship_parts)
     end
 
-    def regular_resource_path(source)
-      if source.is_a?(JSONAPI::CachedResponseFragment)
-        # :nocov:
-        "#{regular_resources_path(source.resource_klass)}/#{source.id}"
-        # :nocov:
-      else
-        "#{regular_resources_path(source.class)}/#{source.id}"
-      end
+    def relationship_self_url_helper_name(relationship)
+      relationship_parts = resource_path_parts_from_class(relationship.parent_resource)
+      relationship_parts << "relationships"
+      relationship_parts << relationship.name
+      url_helper_name_from_parts(relationship_parts)
     end
 
-    def regular_resource_url(source)
-      "#{ base_url }#{ regular_resource_path(source) }"
+    def singleton_relationship_self_url_helper_name(relationship)
+      relationship_parts = []
+      relationship_parts << "relationships"
+      relationship_parts << relationship.name
+      relationship_parts += resource_path_parts_from_class(relationship.parent_resource)
+      url_helper_name_from_parts(relationship_parts)
     end
 
-    def route_for_relationship(relationship)
-      format_route(relationship.name)
+    def module_scopes_from_class(klass)
+      klass.name.to_s.split("::")[0...-1]
     end
   end
 end

lib/jsonapi/operation_result.rb

@@ -100,7 +100,7 @@ def to_hash(serializer = nil)
     end
   end
 
-  class LinksObjectOperationResult < OperationResult
+  class RelationshipOperationResult < OperationResult
     attr_accessor :parent_resource, :relationship, :resource_ids
 
     def initialize(code, parent_resource, relationship, resource_ids, options = {})
@@ -112,7 +112,7 @@ def initialize(code, parent_resource, relationship, resource_ids, options = {})
 
     def to_hash(serializer = nil)
       if serializer
-        serializer.serialize_to_links_hash(parent_resource, relationship, resource_ids)
+        serializer.serialize_to_relationship_hash(parent_resource, relationship, resource_ids)
       else
         # :nocov:
         {}

lib/jsonapi/processor.rb

@@ -130,11 +130,11 @@ def show_relationship
                                                        find_options,
                                                        nil)
 
-      return JSONAPI::LinksObjectOperationResult.new(:ok,
-                                                     parent_resource,
-                                                     resource_klass._relationship(relationship_type),
-                                                     resource_id_tree.fragments.keys,
-                                                     result_options)
+      return JSONAPI::RelationshipOperationResult.new(:ok,
+                                                      parent_resource,
+                                                      resource_klass._relationship(relationship_type),
+                                                      resource_id_tree.fragments.keys,
+                                                      result_options)
     end
 
     def show_related_resource