jsonapi-resources 0.7.1.beta2 → 0.8.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dceb946bf28d998cd1db3e5fbf7b16756cf8de1a
-  data.tar.gz: 5b5da11044442fc0afd60f0cac50e655692535d9
+  metadata.gz: d825825bdf720bb3b498b9975b9455c52df1ed92
+  data.tar.gz: fad2b60d570a85cadb6fc44a073cd316d0ed3650
 SHA512:
-  metadata.gz: 72b316a3c84777e316599dd3dafc51da115ea7cd7af2ee4cbad8d391fe594543eb81b7efa7834e57f6540f6b7ccfcc137e6d5c38eaa0f59373af6605c3051894
-  data.tar.gz: f9a961dfe2c6472e37f82c31e6764df600628841b0c05e1f02e3451c2872be068f78fffef1e4ee25406a54d6699b7d2161ccac334de888b56a85ca1b27de56cc
+  metadata.gz: 4f10510695282091866599ec8ca994d25ba348e98a12b8cc9501ab9e0a1b6f0f054e43ceb0091078cac26d05b43c6971db22a73350662186b6126d4ce888520d
+  data.tar.gz: 9aaa540340d1426f24269dc2bf3813931256b3dfb1e9e0c667967ee103262033ad8834be14a564e1fe817820392e6e80d4001fda3763a8155e0fa4686c4efe74

data/README.md

@@ -2,6 +2,13 @@
 
 [![Join the chat at https://gitter.im/cerebris/jsonapi-resources](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/cerebris/jsonapi-resources?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
+**NOTE:** This README is the documentation for `JSONAPI::Resources`. If you are viewing this at the
+[project page on Github](https://github.com/cerebris/jsonapi-resources) you are viewing the documentation for the `master`
+branch. This may contain information that is not relevant to the release you are using. Please see the README for the
+[version](https://github.com/cerebris/jsonapi-resources/releases) you are using.
+
+ ---
+
 `JSONAPI::Resources`, or "JR", provides a framework for developing a server that complies with the
 [JSON API](http://jsonapi.org/) specification.
 
@@ -43,6 +50,7 @@ backed by ActiveRecord models or by custom objects.
     * [Key Format] (#key-format)
   * [Routing] (#routing)
     * [Nested Routes] (#nested-routes)
+  * [Authorization](#authorization)
 * [Configuration] (#configuration)
 * [Contributing] (#contributing)
 * [License] (#license)
@@ -91,7 +99,7 @@ class ContactResource < JSONAPI::Resource
 end
 ```
 
-A jsonapi-resource generator is avaliable
+A jsonapi-resource generator is available
 ```
 rails generate jsonapi:resource contact
 ```
@@ -333,6 +341,21 @@ The request will look something like:
 GET /books?include=author&sort=author.name
 ```
 
+###### Default sorting
+
+By default JR sorts ascending on the `id` of the primary resource, unless the request specifies an alternate sort order.
+To override this you may override the `self.default_sort` on a `resource`. `default_sort` should return an array of
+`sort_param` hashes. A `sort_param` hash contains a `field` and a `direction`, with `direction` being either `:asc` or
+`:desc`.
+
+For example:
+
+```ruby
+  def self.default_sort
+    [{field: 'name_last', direction: :desc}, {field: 'name_first', direction: :desc}]
+  end
+```
+
 ##### Attribute Formatting
 
 Attributes can have a `Format`. By default all attributes use the default formatter. If an attribute has the `format`
@@ -526,10 +549,14 @@ The relationship methods (`relationship`, `has_one`, and `has_many`) support the
  * `polymorphic` - set to true to identify relationships that are polymorphic.
  * `relation_name` - the name of the relation to use on the model. A lambda may be provided which allows conditional selection of the relation based on the context.
  * `always_include_linkage_data` - if set to true, the relationship includes linkage data. Defaults to false if not set.
+ * `eager_load_on_include` - if set to false, will not include this relationship in join SQL when requested via an include. You usually want to leave this on, but it will break 'relationships' which are not active record, for example if you want to expose a tree using the `ancestry` gem or similar, or the SQL query becomes too large to handle. Defaults to true if not set.
 
 `to_one` relationships support the additional option:
  * `foreign_key_on` - defaults to `:self`. To indicate that the foreign key is on the related resource specify `:related`.
 
+`to_many` relationships support the additional option:
+ * `reflect` - defaults to `true`. To indicate that updates to the relationship are performed on the related resource, if relationship reflection is turned on. See [Configuration] (#configuration)
+
 Examples:
 
 ```ruby
@@ -1118,6 +1145,13 @@ Callbacks can be defined for the following `JSONAPI::Resource` events:
 - `:remove_to_one_link`
 - `:replace_fields`
 
+###### Relationship Reflection
+
+By default updates to relationships only invoke callbacks on the primary
+Resource. By setting the `use_relationship_reflection` [Configuration] (#configuration) option
+updates to `has_many` relationships will occur on the related resource, triggering
+callbacks on both resources.
+
 ##### `JSONAPI::Processor` Callbacks
 
 Callbacks can also be defined for `JSONAPI::Processor` events:
@@ -1174,7 +1208,7 @@ rails generate jsonapi:controller contact
 ###### ResourceControllerMetal
 
 `JSONAPI::Resources` also provides an alternative class to `ResourceController` called `ResourceControllerMetal`.
-In order to provide a lighter weight controller option this strips the controller down to just the classes needed 
+In order to provide a lighter weight controller option this strips the controller down to just the classes needed
 to work with `JSONAPI::Resources`.
 
 For example:
@@ -1186,7 +1220,7 @@ end
 ```
 
 Note: This may not provide all of the expected controller capabilities if you are using additional gems such as DoorKeeper.
- 
+
 ###### Serialization Options
 
 Additional options can be passed to the serializer using the `serialization_options` method.
@@ -1222,7 +1256,7 @@ JSONAPI::Resources supports namespacing of controllers and resources. With names
 
 If you namespace your controller it will require a namespaced resource.
 
-In the following example we have a `resource` that isn't namespaced, and one the has now been namespaced. There are
+In the following example we have a `resource` that isn't namespaced, and one that has now been namespaced. There are
 slight differences between the two resources, as might be seen in a new version of an API:
 
 ```ruby
@@ -1862,6 +1896,15 @@ phone_number_contact GET    /phone-numbers/:phone_number_id/contact(.:format) co
 
 ```
 
+### Authorization
+
+Currently `json-api-resources` doesn't come with built-in primitives for authorization. However multiple users of the framework have come up with different approaches, check out:
+
+- [jsonapi-authorization](https://github.com/venuu/jsonapi-authorization)
+- [pundit-resources](https://github.com/togglepro/pundit-resources)
+
+Refer to the comments/discussion [here](https://github.com/cerebris/jsonapi-resources/issues/16#issuecomment-222438975) for the differences between approaches
+
 ## Configuration
 
 JR has a few configuration options. Some have already been mentioned above. To set configuration options create an
@@ -1928,6 +1971,19 @@ JSONAPI.configure do |config|
   # Controls the serialization of resource linkage for non compound documents
   # NOTE: always_include_to_many_linkage_data is not currently implemented
   config.always_include_to_one_linkage_data = false
+
+  # Relationship reflection invokes the related resource when updates
+  # are made to a has_many relationship. By default relationship_reflection
+  # is turned off because it imposes a small performance penalty.
+  config.use_relationship_reflection = false
+
+  # Allows transactions for creating and updating records
+  # Set this to false if your backend does not support transactions (e.g. Mongodb)
+  config.allow_transactions = true
+
+  # Formatter Caching
+  # Set to false to disable caching of string operations on keys and links.
+  config.cache_formatters = true
 end
 ```
 

data/lib/jsonapi/configuration.rb

@@ -21,10 +21,12 @@ module JSONAPI
                 :top_level_meta_record_count_key,
                 :top_level_meta_include_page_count,
                 :top_level_meta_page_count_key,
+                :allow_transactions,
                 :exception_class_whitelist,
                 :always_include_to_one_linkage_data,
                 :always_include_to_many_linkage_data,
-                :cache_formatters
+                :cache_formatters,
+                :use_relationship_reflection
 
     def initialize
       #:underscored_key, :camelized_key, :dasherized_key, or custom
@@ -80,9 +82,18 @@ module JSONAPI
       # for a Resource.
       self.default_processor_klass = JSONAPI::Processor
 
+      # Allows transactions for creating and updating records
+      # Set this to false if your backend does not support transactions (e.g. Mongodb)
+      self.allow_transactions = true
+
       # Formatter Caching
       # Set to false to disable caching of string operations on keys and links.
       self.cache_formatters = true
+
+      # Relationship reflection invokes the related resource when updates
+      # are made to a has_many relationship. By default relationship_reflection
+      # is turned off because it imposes a small performance penalty.
+      self.use_relationship_reflection = false
     end
 
     def cache_formatters=(bool)
@@ -172,6 +183,8 @@ module JSONAPI
 
     attr_writer :top_level_meta_page_count_key
 
+    attr_writer :allow_transactions
+
     attr_writer :exception_class_whitelist
 
     attr_writer :always_include_to_one_linkage_data
@@ -179,6 +192,8 @@ module JSONAPI
     attr_writer :always_include_to_many_linkage_data
 
     attr_writer :raise_if_parameters_not_allowed
+
+    attr_writer :use_relationship_reflection
   end
 
   class << self

data/lib/jsonapi/include_directives.rb

@@ -19,7 +19,9 @@ module JSONAPI
     #   }
     # }
 
-    def initialize(includes_array)
+    def initialize(resource_klass, includes_array, force_eager_load: false)
+      @resource_klass = resource_klass
+      @force_eager_load = force_eager_load
       @include_directives_hash = { include_related: {} }
       includes_array.each do |include|
         parse_include(include)
@@ -38,16 +40,27 @@ module JSONAPI
 
     def get_related(current_path)
       current = @include_directives_hash
+      current_resource_klass = @resource_klass
       current_path.split('.').each do |fragment|
         fragment = fragment.to_sym
-        current[:include_related][fragment] ||= { include: false, include_related: {} }
+
+        if current_resource_klass
+          current_relationship = current_resource_klass._relationships[fragment]
+          current_resource_klass = current_relationship.try(:resource_klass)
+        else
+          warn "[RELATIONSHIP NOT FOUND] Relationship could not be found for #{current_path}."
+        end
+
+        include_in_join = @force_eager_load || !current_relationship || current_relationship.eager_load_on_include
+
+        current[:include_related][fragment] ||= { include: false, include_related: {}, include_in_join: include_in_join }
         current = current[:include_related][fragment]
       end
       current
     end
 
     def get_includes(directive)
-      directive[:include_related].map do |name, directive|
+      directive[:include_related].select { |k,v| v[:include_in_join] }.map do |name, directive|
         sub = get_includes(directive)
         sub.any? ? { name => sub } : name
       end

data/lib/jsonapi/operation_dispatcher.rb

@@ -16,9 +16,10 @@ module JSONAPI
       # Use transactions if more than one operation and if one of the operations can be transactional
       # Even if transactional transactions won't be used unless the derived OperationsProcessor supports them.
       transactional = false
+
       operations.each do |operation|
         transactional |= operation.transactional?
-      end
+      end if JSONAPI.configuration.allow_transactions
 
       transaction(transactional) do
         # Links and meta data global to the set of operations

data/lib/jsonapi/relationship.rb

@@ -2,7 +2,7 @@ module JSONAPI
   class Relationship
     attr_reader :acts_as_set, :foreign_key, :options, :name,
                 :class_name, :polymorphic, :always_include_linkage_data,
-                :parent_resource
+                :parent_resource, :eager_load_on_include
 
     def initialize(name, options = {})
       @name = name.to_s
@@ -13,6 +13,7 @@ module JSONAPI
       @relation_name = options.fetch(:relation_name, @name)
       @polymorphic = options.fetch(:polymorphic, false) == true
       @always_include_linkage_data = options.fetch(:always_include_linkage_data, false) == true
+      @eager_load_on_include = options.fetch(:eager_load_on_include, true) == true
     end
 
     alias_method :polymorphic?, :polymorphic
@@ -74,15 +75,19 @@ module JSONAPI
       end
 
       def polymorphic_type
-        "#{type.to_s.singularize}_type" if polymorphic?
+        "#{name}_type" if polymorphic?
       end
     end
 
     class ToMany < Relationship
+      attr_reader :reflect, :inverse_relationship
+
       def initialize(name, options = {})
         super
         @class_name = options.fetch(:class_name, name.to_s.camelize.singularize)
         @foreign_key ||= "#{name.to_s.singularize}_ids".to_sym
+        @reflect = options.fetch(:reflect, true) == true
+        @inverse_relationship = options.fetch(:inverse_relationship, parent_resource._type.to_s.singularize.to_sym) if parent_resource
       end
     end
   end

data/lib/jsonapi/relationship_builder.rb

@@ -0,0 +1,157 @@
+module JSONAPI
+  class RelationshipBuilder
+    attr_reader :model_class, :options, :relationship_class
+    delegate :register_relationship, to: :@resource_class
+
+    def initialize(relationship_class, model_class, options)
+      @relationship_class = relationship_class
+      @model_class        = model_class
+      @resource_class     = options[:parent_resource]
+      @options            = options
+    end
+
+    def define_relationship_methods(relationship_name)
+      # Initialize from an ActiveRecord model's properties
+      if model_class && model_class.ancestors.collect{|ancestor| ancestor.name}.include?('ActiveRecord::Base')
+        model_association = model_class.reflect_on_association(relationship_name)
+        if model_association
+          options[:class_name] ||= model_association.class_name
+        end
+      end
+
+      relationship = register_relationship(
+        relationship_name,
+        relationship_class.new(relationship_name, options)
+      )
+
+      foreign_key = define_foreign_key_setter(relationship.foreign_key)
+
+      case relationship
+      when JSONAPI::Relationship::ToOne
+        associated = define_resource_relationship_accessor(:one, relationship_name)
+        args = [relationship, foreign_key, associated, relationship_name]
+
+        relationship.belongs_to? ? build_belongs_to(*args) : build_has_one(*args)
+      when JSONAPI::Relationship::ToMany
+        associated = define_resource_relationship_accessor(:many, relationship_name)
+
+        build_to_many(relationship, foreign_key, associated, relationship_name)
+      end
+    end
+
+    def define_foreign_key_setter(foreign_key)
+      define_on_resource "#{foreign_key}=" do |value|
+        @model.method("#{foreign_key}=").call(value)
+      end
+      foreign_key
+    end
+
+    def define_resource_relationship_accessor(type, relationship_name)
+      associated_records_method_name = {
+        one:  "record_for_#{relationship_name}",
+        many: "records_for_#{relationship_name}"
+      }
+      .fetch(type)
+
+      define_on_resource associated_records_method_name do
+        relationship = self.class._relationships[relationship_name]
+        relation_name = relationship.relation_name(context: @context)
+        records_for(relation_name)
+      end
+
+      associated_records_method_name
+    end
+
+    def build_belongs_to(relationship, foreign_key, associated_records_method_name, relationship_name)
+      # Calls method matching foreign key name on model instance
+      define_on_resource foreign_key do
+        @model.method(foreign_key).call
+      end
+
+      # Returns instantiated related resource object or nil
+      define_on_resource relationship_name do |options = {}|
+        relationship = self.class._relationships[relationship_name]
+
+        if relationship.polymorphic?
+          associated_model = public_send(associated_records_method_name)
+          resource_klass = self.class.resource_for_model(associated_model) if associated_model
+          return resource_klass.new(associated_model, @context) if resource_klass
+        else
+          resource_klass = relationship.resource_klass
+          if resource_klass
+            associated_model = public_send(associated_records_method_name)
+            return associated_model ? resource_klass.new(associated_model, @context) : nil
+          end
+        end
+      end
+    end
+
+    def build_has_one(relationship, foreign_key, associated_records_method_name, relationship_name)
+      # Returns primary key name of related resource class
+      define_on_resource foreign_key do
+        relationship = self.class._relationships[relationship_name]
+
+        record = public_send(associated_records_method_name)
+        return nil if record.nil?
+        record.public_send(relationship.resource_klass._primary_key)
+      end
+
+      # Returns instantiated related resource object or nil
+      define_on_resource relationship_name do |options = {}|
+        relationship = self.class._relationships[relationship_name]
+
+        resource_klass = relationship.resource_klass
+        if resource_klass
+          associated_model = public_send(associated_records_method_name)
+          return associated_model ? resource_klass.new(associated_model, @context) : nil
+        end
+      end
+    end
+
+    def build_to_many(relationship, foreign_key, associated_records_method_name, relationship_name)
+      # Returns array of primary keys of related resource classes
+      define_on_resource foreign_key do
+        records = public_send(associated_records_method_name)
+        return records.collect do |record|
+          record.public_send(relationship.resource_klass._primary_key)
+        end
+      end
+
+      # Returns array of instantiated related resource objects
+      define_on_resource relationship_name do |options = {}|
+        relationship = self.class._relationships[relationship_name]
+
+        resource_klass = relationship.resource_klass
+        records = public_send(associated_records_method_name)
+
+        filters = options.fetch(:filters, {})
+        unless filters.nil? || filters.empty?
+          records = resource_klass.apply_filters(records, filters, options)
+        end
+
+        sort_criteria =  options.fetch(:sort_criteria, {})
+        unless sort_criteria.nil? || sort_criteria.empty?
+          order_options = relationship.resource_klass.construct_order_options(sort_criteria)
+          records = resource_klass.apply_sort(records, order_options, @context)
+        end
+
+        paginator = options[:paginator]
+        if paginator
+          records = resource_klass.apply_pagination(records, paginator, order_options)
+        end
+
+        return records.collect do |record|
+          if relationship.polymorphic?
+            resource_klass = self.class.resource_for_model(record)
+          end
+          resource_klass.new(record, @context)
+        end
+      end
+    end
+
+    def define_on_resource(method_name, &block)
+      return if @resource_class.method_defined?(method_name)
+      @resource_class.inject_method_definition(method_name, block)
+    end
+  end
+end

data/lib/jsonapi/request_parser.rb

@@ -16,7 +16,7 @@ module JSONAPI
       @operations = []
       @fields = {}
       @filters = {}
-      @sort_criteria = [{ field: 'id', direction: :asc }]
+      @sort_criteria = nil
       @source_klass = nil
       @source_id = nil
       @include_directives = nil
@@ -225,7 +225,7 @@ module JSONAPI
         include.push(unformat_key(included_resource).to_s)
       end
 
-      @include_directives = JSONAPI::IncludeDirectives.new(include)
+      @include_directives = JSONAPI::IncludeDirectives.new(@resource_klass, include)
     end
 
     def parse_filters(filters)
@@ -326,7 +326,8 @@ module JSONAPI
         relationship_type: relationship_type,
         source_klass: @source_klass,
         source_id: @source_id,
-        fields: @fields
+        fields: @fields,
+        include_directives: @include_directives
       )
     end
 
@@ -340,7 +341,8 @@ module JSONAPI
         filters: @source_klass.verify_filters(@filters, @context),
         sort_criteria: @sort_criteria,
         paginator: @paginator,
-        fields: @fields
+        fields: @fields,
+        include_directives: @include_directives
       )
     end
 
@@ -364,7 +366,8 @@ module JSONAPI
           @resource_klass,
           context: @context,
           data: data,
-          fields: @fields
+          fields: @fields,
+          include_directives: @include_directives
         )
       end
     rescue JSONAPI::Exceptions::Error => e
@@ -632,7 +635,8 @@ module JSONAPI
         context: @context,
         resource_id: key,
         data: parse_params(data, updatable_fields),
-        fields: @fields
+        fields: @fields,
+        include_directives: @include_directives
       )
     end
 

data/lib/jsonapi/resource.rb

@@ -1,4 +1,5 @@
 require 'jsonapi/callbacks'
+require 'jsonapi/relationship_builder'
 
 module JSONAPI
   class Resource
@@ -22,6 +23,9 @@ module JSONAPI
     def initialize(model, context)
       @model = model
       @context = context
+      @reload_needed = false
+      @changing = false
+      @save_needed = false
     end
 
     def _model
@@ -63,39 +67,39 @@ module JSONAPI
       end
     end
 
-    def create_to_many_links(relationship_type, relationship_key_values)
+    def create_to_many_links(relationship_type, relationship_key_values, options = {})
       change :create_to_many_link do
-        _create_to_many_links(relationship_type, relationship_key_values)
+        _create_to_many_links(relationship_type, relationship_key_values, options)
       end
     end
 
-    def replace_to_many_links(relationship_type, relationship_key_values)
+    def replace_to_many_links(relationship_type, relationship_key_values, options = {})
       change :replace_to_many_links do
-        _replace_to_many_links(relationship_type, relationship_key_values)
+        _replace_to_many_links(relationship_type, relationship_key_values, options)
       end
     end
 
-    def replace_to_one_link(relationship_type, relationship_key_value)
+    def replace_to_one_link(relationship_type, relationship_key_value, options = {})
       change :replace_to_one_link do
-        _replace_to_one_link(relationship_type, relationship_key_value)
+        _replace_to_one_link(relationship_type, relationship_key_value, options)
       end
     end
 
-    def replace_polymorphic_to_one_link(relationship_type, relationship_key_value, relationship_key_type)
+    def replace_polymorphic_to_one_link(relationship_type, relationship_key_value, relationship_key_type, options = {})
       change :replace_polymorphic_to_one_link do
-        _replace_polymorphic_to_one_link(relationship_type, relationship_key_value, relationship_key_type)
+        _replace_polymorphic_to_one_link(relationship_type, relationship_key_value, relationship_key_type, options)
       end
     end
 
-    def remove_to_many_link(relationship_type, key)
+    def remove_to_many_link(relationship_type, key, options = {})
       change :remove_to_many_link do
-        _remove_to_many_link(relationship_type, key)
+        _remove_to_many_link(relationship_type, key, options)
       end
     end
 
-    def remove_to_one_link(relationship_type)
+    def remove_to_one_link(relationship_type, options = {})
       change :remove_to_one_link do
-        _remove_to_one_link(relationship_type)
+        _remove_to_one_link(relationship_type, options)
       end
     end
 
@@ -189,6 +193,7 @@ module JSONAPI
 
       if defined? @model.save
         saved = @model.save(validate: false)
+
         unless saved
           if @model.errors.present?
             fail JSONAPI::Exceptions::ValidationErrors.new(self)
@@ -199,6 +204,8 @@ module JSONAPI
       else
         saved = true
       end
+      @model.reload if @reload_needed
+      @reload_needed = false
 
       @save_needed = !saved
 
@@ -215,34 +222,87 @@ module JSONAPI
       fail JSONAPI::Exceptions::RecordLocked.new(e.message)
     end
 
-    def _create_to_many_links(relationship_type, relationship_key_values)
+    def reflect_relationship?(relationship, options)
+      return false if !relationship.reflect ||
+        (!JSONAPI.configuration.use_relationship_reflection || options[:reflected_source])
+
+      inverse_relationship = relationship.resource_klass._relationships[relationship.inverse_relationship]
+      if inverse_relationship.nil?
+        warn "Inverse relationship could not be found for #{self.class.name}.#{relationship.name}. Relationship reflection disabled."
+        return false
+      end
+      true
+    end
+
+    def _create_to_many_links(relationship_type, relationship_key_values, options)
       relationship = self.class._relationships[relationship_type]
 
-      relationship_key_values.each do |relationship_key_value|
-        related_resource = relationship.resource_klass.find_by_key(relationship_key_value, context: @context)
+      # check if relationship_key_values are already members of this relationship
+      relation_name = relationship.relation_name(context: @context)
+      existing_relations = @model.public_send(relation_name).where(relationship.primary_key => relationship_key_values)
+      if existing_relations.count > 0
+        # todo: obscure id so not to leak info
+        fail JSONAPI::Exceptions::HasManyRelationExists.new(existing_relations.first.id)
+      end
 
-        relation_name = relationship.relation_name(context: @context)
-        # TODO: Add option to skip relations that already exist instead of returning an error?
-        relation = @model.public_send(relation_name).where(relationship.primary_key => relationship_key_value).first
-        if relation.nil?
-          @model.public_send(relation_name) << related_resource._model
+      if options[:reflected_source]
+        @model.public_send(relation_name) << options[:reflected_source]._model
+        return :completed
+      end
+
+      # load requested related resources
+      # make sure they all exist (also based on context) and add them to relationship
+
+      related_resources = relationship.resource_klass.find_by_keys(relationship_key_values, context: @context)
+
+      if related_resources.count != relationship_key_values.count
+        # todo: obscure id so not to leak info
+        fail JSONAPI::Exceptions::RecordNotFound.new('unspecified')
+      end
+
+      reflect = reflect_relationship?(relationship, options)
+
+      related_resources.each do |related_resource|
+        if reflect
+          if related_resource.class._relationships[relationship.inverse_relationship].is_a?(JSONAPI::Relationship::ToMany)
+            related_resource.create_to_many_links(relationship.inverse_relationship, [id], reflected_source: self)
+          else
+            related_resource.replace_to_one_link(relationship.inverse_relationship, id, reflected_source: self)
+          end
+          @reload_needed = true
         else
-          fail JSONAPI::Exceptions::HasManyRelationExists.new(relationship_key_value)
+          @model.public_send(relation_name) << related_resource._model
         end
       end
 
       :completed
     end
 
-    def _replace_to_many_links(relationship_type, relationship_key_values)
+    def _replace_to_many_links(relationship_type, relationship_key_values, options)
       relationship = self.class._relationships[relationship_type]
-      send("#{relationship.foreign_key}=", relationship_key_values)
-      @save_needed = true
+
+      reflect = reflect_relationship?(relationship, options)
+
+      if reflect
+        existing = send("#{relationship.foreign_key}")
+        to_delete = existing - (relationship_key_values & existing)
+        to_delete.each do |key|
+          _remove_to_many_link(relationship_type, key, reflected_source: self)
+        end
+
+        to_add = relationship_key_values - (relationship_key_values & existing)
+        _create_to_many_links(relationship_type, to_add, {})
+
+        @reload_needed = true
+      else
+        send("#{relationship.foreign_key}=", relationship_key_values)
+        @save_needed = true
+      end
 
       :completed
     end
 
-    def _replace_to_one_link(relationship_type, relationship_key_value)
+    def _replace_to_one_link(relationship_type, relationship_key_value, options)
       relationship = self.class._relationships[relationship_type]
 
       send("#{relationship.foreign_key}=", relationship_key_value)
@@ -251,7 +311,7 @@ module JSONAPI
       :completed
     end
 
-    def _replace_polymorphic_to_one_link(relationship_type, key_value, key_type)
+    def _replace_polymorphic_to_one_link(relationship_type, key_value, key_type, options)
       relationship = self.class._relationships[relationship_type.to_sym]
 
       _model.public_send("#{relationship.foreign_key}=", key_value)
@@ -262,10 +322,29 @@ module JSONAPI
       :completed
     end
 
-    def _remove_to_many_link(relationship_type, key)
-      relation_name = self.class._relationships[relationship_type].relation_name(context: @context)
+    def _remove_to_many_link(relationship_type, key, options)
+      relationship = self.class._relationships[relationship_type]
+
+      reflect = reflect_relationship?(relationship, options)
+
+      if reflect
+
+        related_resource = relationship.resource_klass.find_by_key(key, context: @context)
+
+        if related_resource.nil?
+          fail JSONAPI::Exceptions::RecordNotFound.new(key)
+        else
+          if related_resource.class._relationships[relationship.inverse_relationship].is_a?(JSONAPI::Relationship::ToMany)
+            related_resource.remove_to_many_link(relationship.inverse_relationship, id, reflected_source: self)
+          else
+            related_resource.remove_to_one_link(relationship.inverse_relationship, reflected_source: self)
+          end
+        end
 
-      @model.public_send(relation_name).delete(key)
+        @reload_needed = true
+      else
+        @model.public_send(relationship.relation_name(context: @context)).delete(key)
+      end
 
       :completed
 
@@ -275,7 +354,7 @@ module JSONAPI
       fail JSONAPI::Exceptions::RecordNotFound.new(key)
     end
 
-    def _remove_to_one_link(relationship_type)
+    def _remove_to_one_link(relationship_type, options)
       relationship = self.class._relationships[relationship_type]
 
       send("#{relationship.foreign_key}=", nil)
@@ -404,6 +483,8 @@ module JSONAPI
           ActiveSupport::Deprecation.warn('Id without format is no longer supported. Please remove ids from attributes, or specify a format.')
         end
 
+        check_duplicate_attribute_name(attr) if options[:format].nil?
+
         @_attributes ||= {}
         @_attributes[attr] = options
         define_method attr do
@@ -438,6 +519,15 @@ module JSONAPI
         _add_relationship(Relationship::ToOne, *attrs)
       end
 
+      def belongs_to(*attrs)
+        ActiveSupport::Deprecation.warn "In #{name} you exposed a `has_one` relationship "\
+                                        " using the `belongs_to` class method. We think `has_one`" \
+                                        " is more appropriate. If you know what you're doing," \
+                                        " and don't want to see this warning again, override the" \
+                                        " `belongs_to` class method on your resource."
+        _add_relationship(Relationship::ToOne, *attrs)
+      end
+
       def has_many(*attrs)
         _add_relationship(Relationship::ToMany, *attrs)
       end
@@ -613,7 +703,7 @@ module JSONAPI
         end
 
         if required_includes.any?
-          records = apply_includes(records, options.merge(include_directives: IncludeDirectives.new(required_includes)))
+          records = apply_includes(records, options.merge(include_directives: IncludeDirectives.new(self, required_includes, force_eager_load: true)))
         end
 
         records
@@ -653,14 +743,20 @@ module JSONAPI
       end
 
       def resources_for(records, context)
-        resources = []
-        resource_classes = {}
-        records.each do |model|
-          resource_class = resource_classes[model.class] ||= self.resource_for_model(model)
-          resources.push resource_class.new(model, context)
+        records.collect do |model|
+          resource_class = self.resource_for_model(model)
+          resource_class.new(model, context)
         end
+      end
 
-        resources
+      def find_by_keys(keys, options = {})
+        context = options[:context]
+        records = records(options)
+        records = apply_includes(records, options)
+        models = records.where({_primary_key => keys})
+        models.collect do |model|
+          self.resource_for_model(model).new(model, context)
+        end
       end
 
       def find_by_key(key, options = {})
@@ -852,11 +948,17 @@ module JSONAPI
         end
       end
 
+      def default_sort
+        [{field: 'id', direction: :asc}]
+      end
+
       def construct_order_options(sort_params)
+        sort_params ||= default_sort
+
         return {} unless sort_params
 
         sort_params.each_with_object({}) do |sort, order_hash|
-          field = sort[:field] == 'id' ? _primary_key : sort[:field]
+          field = sort[:field].to_s == 'id' ? _primary_key : sort[:field].to_s
           order_hash[field] = sort[:direction]
         end
       end
@@ -865,117 +967,22 @@ module JSONAPI
         options = attrs.extract_options!
         options[:parent_resource] = self
 
-        attrs.each do |attr|
-          relationship_name = attr.to_sym
-
+        attrs.each do |relationship_name|
           check_reserved_relationship_name(relationship_name)
+          check_duplicate_relationship_name(relationship_name)
 
-          # Initialize from an ActiveRecord model's properties
-          if _model_class && _model_class.ancestors.collect{|ancestor| ancestor.name}.include?('ActiveRecord::Base')
-            model_association = _model_class.reflect_on_association(relationship_name)
-            if model_association
-              options[:class_name] ||= model_association.class_name
-            end
-          end
-
-          @_relationships[relationship_name] = relationship = klass.new(relationship_name, options)
-
-          associated_records_method_name = case relationship
-                                           when JSONAPI::Relationship::ToOne then "record_for_#{relationship_name}"
-                                           when JSONAPI::Relationship::ToMany then "records_for_#{relationship_name}"
-                                           end
-
-          foreign_key = relationship.foreign_key
-
-          define_method "#{foreign_key}=" do |value|
-            @model.method("#{foreign_key}=").call(value)
-          end unless method_defined?("#{foreign_key}=")
-
-          define_method associated_records_method_name do
-            relationship = self.class._relationships[relationship_name]
-            relation_name = relationship.relation_name(context: @context)
-            records_for(relation_name)
-          end unless method_defined?(associated_records_method_name)
-
-          if relationship.is_a?(JSONAPI::Relationship::ToOne)
-            if relationship.belongs_to?
-              define_method foreign_key do
-                @model.method(foreign_key).call
-              end unless method_defined?(foreign_key)
-
-              define_method relationship_name do |options = {}|
-                relationship = self.class._relationships[relationship_name]
-
-                if relationship.polymorphic?
-                  associated_model = public_send(associated_records_method_name)
-                  resource_klass = self.class.resource_for_model(associated_model) if associated_model
-                  return resource_klass.new(associated_model, @context) if resource_klass
-                else
-                  resource_klass = relationship.resource_klass
-                  if resource_klass
-                    associated_model = public_send(associated_records_method_name)
-                    return associated_model ? resource_klass.new(associated_model, @context) : nil
-                  end
-                end
-              end unless method_defined?(relationship_name)
-            else
-              define_method foreign_key do
-                relationship = self.class._relationships[relationship_name]
-
-                record = public_send(associated_records_method_name)
-                return nil if record.nil?
-                record.public_send(relationship.resource_klass._primary_key)
-              end unless method_defined?(foreign_key)
-
-              define_method relationship_name do |options = {}|
-                relationship = self.class._relationships[relationship_name]
-
-                resource_klass = relationship.resource_klass
-                if resource_klass
-                  associated_model = public_send(associated_records_method_name)
-                  return associated_model ? resource_klass.new(associated_model, @context) : nil
-                end
-              end unless method_defined?(relationship_name)
-            end
-          elsif relationship.is_a?(JSONAPI::Relationship::ToMany)
-            define_method foreign_key do
-              records = public_send(associated_records_method_name)
-              return records.collect do |record|
-                record.public_send(relationship.resource_klass._primary_key)
-              end
-            end unless method_defined?(foreign_key)
-
-            define_method relationship_name do |options = {}|
-              relationship = self.class._relationships[relationship_name]
-
-              resource_klass = relationship.resource_klass
-              records = public_send(associated_records_method_name)
-
-              filters = options.fetch(:filters, {})
-              unless filters.nil? || filters.empty?
-                records = resource_klass.apply_filters(records, filters, options)
-              end
-
-              sort_criteria =  options.fetch(:sort_criteria, {})
-              unless sort_criteria.nil? || sort_criteria.empty?
-                order_options = relationship.resource_klass.construct_order_options(sort_criteria)
-                records = resource_klass.apply_sort(records, order_options, @context)
-              end
+          JSONAPI::RelationshipBuilder.new(klass, _model_class, options)
+            .define_relationship_methods(relationship_name.to_sym)
+        end
+      end
 
-              paginator = options[:paginator]
-              if paginator
-                records = resource_klass.apply_pagination(records, paginator, order_options)
-              end
+      # Allows JSONAPI::RelationshipBuilder to access metaprogramming hooks
+      def inject_method_definition(name, body)
+        define_method(name, body)
+      end
 
-              return records.collect do |record|
-                if relationship.polymorphic?
-                  resource_klass = self.class.resource_for_model(record)
-                end
-                resource_klass.new(record, @context)
-              end
-            end unless method_defined?(relationship_name)
-          end
-        end
+      def register_relationship(name, relationship_object)
+        @_relationships[name] = relationship_object
       end
 
       private
@@ -1000,6 +1007,18 @@ module JSONAPI
           warn "[NAME COLLISION] `#{name}` is a reserved relationship name in #{_resource_name_from_type(_type)}."
         end
       end
+
+      def check_duplicate_relationship_name(name)
+        if _relationships.include?(name.to_sym)
+          warn "[DUPLICATE RELATIONSHIP] `#{name}` has already been defined in #{_resource_name_from_type(_type)}."
+        end
+      end
+
+      def check_duplicate_attribute_name(name)
+        if _attributes.include?(name.to_sym)
+          warn "[DUPLICATE ATTRIBUTE] `#{name}` has already been defined in #{_resource_name_from_type(_type)}."
+        end
+      end
     end
   end
 end

data/lib/jsonapi/resource_serializer.rb

@@ -16,13 +16,14 @@ module JSONAPI
     # serializer_options: additional options that will be passed to resource meta and links lambdas
 
     def initialize(primary_resource_klass, options = {})
-      @primary_class_name = primary_resource_klass._type
-      @fields             = options.fetch(:fields, {})
-      @include            = options.fetch(:include, [])
-      @include_directives = options[:include_directives]
-      @key_formatter      = options.fetch(:key_formatter, JSONAPI.configuration.key_formatter)
-      @id_formatter       = ValueFormatter.value_formatter_for(:id)
-      @link_builder       = generate_link_builder(primary_resource_klass, options)
+      @primary_resource_klass = primary_resource_klass
+      @primary_class_name     = primary_resource_klass._type
+      @fields                 = options.fetch(:fields, {})
+      @include                = options.fetch(:include, [])
+      @include_directives     = options[:include_directives]
+      @key_formatter          = options.fetch(:key_formatter, JSONAPI.configuration.key_formatter)
+      @id_formatter           = ValueFormatter.value_formatter_for(:id)
+      @link_builder           = generate_link_builder(primary_resource_klass, options)
       @always_include_to_one_linkage_data = options.fetch(:always_include_to_one_linkage_data,
                                                           JSONAPI.configuration.always_include_to_one_linkage_data)
       @always_include_to_many_linkage_data = options.fetch(:always_include_to_many_linkage_data,
@@ -41,7 +42,7 @@ module JSONAPI
       is_resource_collection = source.respond_to?(:to_ary)
 
       @included_objects = {}
-      @include_directives ||= JSONAPI::IncludeDirectives.new(@include)
+      @include_directives ||= JSONAPI::IncludeDirectives.new(@primary_resource_klass, @include)
 
       process_primary(source, @include_directives.include_directives)
 
@@ -219,7 +220,8 @@ module JSONAPI
             resources.each do |resource|
               next if self_referential_and_already_in_source(resource)
               id = resource.id
-              relationships_only = already_serialized?(relationship.type, id)
+              type = resource.class.resource_for_model(resource._model)
+              relationships_only = already_serialized?(type, id)
               if include_linkage && !relationships_only
                 add_included_object(id, object_hash(resource, ia))
               elsif include_linked_children || relationships_only
@@ -297,9 +299,18 @@ module JSONAPI
 
     # Extracts the foreign key value for a to_one relationship.
     def foreign_key_value(source, relationship)
-      foreign_key = relationship.foreign_key
-      value = source.public_send(foreign_key)
-      @id_formatter.format(value)
+      # If you have direct access to the underlying id, you don't have to load the relationship
+      # which can save quite a lot of time when loading a lot of data.
+      # This does not apply to e.g. has_one :through relationships.
+      if source._model.respond_to?("#{relationship.name}_id")
+        related_resource_id = source._model.public_send("#{relationship.name}_id")
+        return nil unless related_resource_id
+        @id_formatter.format(related_resource_id)
+      else
+        related_resource = source.public_send(relationship.name)
+        return nil unless related_resource
+        @id_formatter.format(related_resource.id)
+      end
     end
 
     def foreign_key_types_and_values(source, relationship)
@@ -317,8 +328,8 @@ module JSONAPI
             end
           end
         else
-          source.public_send(relationship.foreign_key).map do |value|
-            [relationship.type, @id_formatter.format(value)]
+          source.public_send(relationship.name).map do |value|
+            [relationship.type, @id_formatter.format(value.id)]
           end
         end
       end

data/lib/jsonapi/resources/version.rb

@@ -1,5 +1,5 @@
 module JSONAPI
   module Resources
-    VERSION = '0.7.1.beta2'
+    VERSION = '0.8.0.beta1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi-resources
 version: !ruby/object:Gem::Version
-  version: 0.7.1.beta2
+  version: 0.8.0.beta1
 platform: ruby
 authors:
 - Dan Gebhardt
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-31 00:00:00.000000000 Z
+date: 2016-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -172,6 +172,7 @@ files:
 - lib/jsonapi/paginator.rb
 - lib/jsonapi/processor.rb
 - lib/jsonapi/relationship.rb
+- lib/jsonapi/relationship_builder.rb
 - lib/jsonapi/request_parser.rb
 - lib/jsonapi/resource.rb
 - lib/jsonapi/resource_controller.rb