jsonapi-resources 0.5.9 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f421adb3d1c9d4ac14ec14de18bffb8e03233b8f
-  data.tar.gz: 738efbc31c5bd1d1d1a7dc1c3bd83c7f9163e6ae
+  metadata.gz: 6f1f659549f6b8804be7a7bed6ca3a359a37fc5e
+  data.tar.gz: 3703986e36f362f348ce463d4977b268171d8f0b
 SHA512:
-  metadata.gz: 16c6f58ddc71ba0f97489b7ff725ff41905f43b1329a23b60004f250567180ff385d87d822dd4c4197ec13b9f7bfad6ee20062335dd558328ce6e78e5bb182c0
-  data.tar.gz: f1263437a5904619e8f11ff34f6bf7f701ad9f48bb1b272a6790ec45fcffb361121cfe5f0d66f8332f8283aa16b2b7e68e003895919f4f5e7e1998315e1512b0
+  metadata.gz: 7b368231330b4c2a21bcfde117c7c4797a16c3bf145e20525b6fcdff429fde0a276e2b9b95b0e265dee890f37b4862529e7780f4caef90886d99ea36a4877af5
+  data.tar.gz: 4518564dceb728f5a594dd93c9fcf22de5051ad6397a4282513ad8f8f7d27c7bae355cae3bc8a9fd593fc11bdfdb91885f878a17a809d0150d1ef4daa4a7a174

data/.travis.yml

@@ -1,9 +1,8 @@
 language: ruby
 sudo: false
 env:
-  - "RAILS_VERSION=4.0"
-  - "RAILS_VERSION=4.1"
-  - "RAILS_VERSION=4.2"
+  - "RAILS_VERSION=4.1.0"
+  - "RAILS_VERSION=4.2.0"
 rvm:
   - 2.0
   - 2.1

data/README.md

@@ -1,5 +1,7 @@
 # JSONAPI::Resources [![Build Status](https://secure.travis-ci.org/cerebris/jsonapi-resources.png?branch=master)](http://travis-ci.org/cerebris/jsonapi-resources) [![Code Climate](https://codeclimate.com/github/cerebris/jsonapi-resources/badges/gpa.svg)](https://codeclimate.com/github/cerebris/jsonapi-resources)
 
+[![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)
+
 `JSONAPI::Resources`, or "JR", provides a framework for developing a server that complies with the
 [JSON API](http://jsonapi.org/) specification.
 
@@ -29,6 +31,7 @@ backed by ActiveRecord models or by custom objects.
     * [Namespaces] (#namespaces)
     * [Error Codes] (#error-codes)
     * [Handling Exceptions] (#handling-exceptions)
+    * [Action Callbacks] (#action-callbacks)
   * [Serializer] (#serializer)
 * [Configuration] (#configuration)
 * [Contributing] (#contributing)
@@ -150,7 +153,7 @@ class AuthorResource < JSONAPI::Resource
   has_many :posts
 
   def fetchable_fields
-    if (context.current_user.guest)
+    if (context[:current_user].guest)
       super - [:email]
     else
       super
@@ -225,6 +228,41 @@ end
 The system will lookup a value formatter named `DateWithTimezoneValueFormatter` and will use this when serializing and
 updating the attribute. See the [Value Formatters](#value-formatters) section for more details.
 
+##### Flattening a Rails relationship
+
+It is possible to flatten Rails relationships into attributes by using getters and setters. This can become handy if a relation needs to be created alongside the creation of the main object which can be the case if there is a bi-directional presence validation. For example:
+
+```ruby
+# Given Models
+class Person < ActiveRecord::Base
+  has_many :spoken_languages
+  validates :name, :email, :spoken_languages, presence: true
+end
+
+class SpokenLanguage < ActiveRecord::Base
+  belongs_to :person, inverse_of: :spoken_languages
+  validates :person, :language_code, presence: true
+end
+
+# Resource with getters and setter
+class PersonResource < JSONAPI::Resource
+  attributes :name, :email, :spoken_languages
+
+  # Getter
+  def spoken_languages
+    @model.spoken_languages.pluck(:language_code)
+  end
+
+  # Setter (because spoken_languages needed for creation)
+  def spoken_languages=(new_spoken_language_codes)
+    @model.spoken_languages.destroy_all
+    new_spoken_language_codes.each do |new_lang_code|
+      @model.spoken_languages.build(language_code: new_lang_code)
+    end
+  end
+end
+```
+
 #### Primary Key
 
 Resources are always represented using a key of `id`. The resource will interrogate the model to find the primary key.
@@ -445,25 +483,27 @@ class PostResource < JSONAPI::Resource
 
   def self.records(options = {})
     context = options[:context]
-    context.current_user.posts
+    context[:current_user].posts
   end
 end
 ```
 
-When you create a relationship, a method is created to fetch record(s) for that relationship. This method calls
-`records_for(relationship_name)` by default.
+When you create a relationship, a method is created to fetch record(s) for that relationship, using the relation name
+for the relationship.
 
 ```ruby
 class PostResource < JSONAPI::Resource
   has_one :author
   has_many :comments
 
-  # def record_for_author(options = {})
-  #   records_for("author", options)
+  # def record_for_author
+  #   relation_name = relationship.relation_name(context: @context)
+  #   records_for(relation_name)
   # end
 
-  # def records_for_comments(options = {})
-  #   records_for("comments", options)
+  # def records_for_comments
+  #   relation_name = relationship.relation_name(context: @context)
+  #   records_for(relation_name)
   # end
 end
 
@@ -474,11 +514,11 @@ section for additional details on raising errors.
 
 ```ruby
 class BaseResource < JSONAPI::Resource
-  def records_for(relationship_name, options={})
+  def records_for(relation_name)
     context = options[:context]
-    records = model.public_send(relationship_name)
+    records = model.public_send(relation_name)
 
-    unless context.current_user.can_view?(records)
+    unless context[:current_user].can_view?(records)
       raise NotAuthorizedError
     end
 
@@ -567,10 +607,10 @@ class AuthorResource < JSONAPI::Resource
 
   def self.find(filters, options = {})
     context = options[:context]
-    authors = context.current_user.find_authors(filters)
+    authors = context[:current_user].find_authors(filters)
 
     return authors.map do |author|
-      self.new(author)
+      self.new(author, context)
     end
   end
 end
@@ -626,7 +666,7 @@ The default paginator, which will be used for all resources, is set using `JSONA
 
 ```ruby
 JSONAPI.configure do |config|
-  # built in paginators are :none, :offset, :cursor, :paged
+  # built in paginators are :none, :offset, :paged
   config.default_paginator = :offset
 
   config.default_page_size = 10
@@ -709,8 +749,6 @@ Will get you the following payload by default:
 }
 ```
 
-You can also pass an `include` option to [Serializer#serialize_to_hash](#include) if you want to define this inline.
-
 #### Callbacks
 
 `ActiveSupport::Callbacks` is used to provide callback functionality, so the behavior is very similar to what you may be
@@ -781,6 +819,7 @@ To return the total record count of a find operation in the meta data of a find
 OperationsProcessor. For example:
 
 ```ruby
+# lib/jsonapi/counting_active_record_operations_processor.rb
 class CountingActiveRecordOperationsProcessor < ActiveRecordOperationsProcessor
   after_find_operation do
     @operation_meta[:total_records] = @operation.record_count
@@ -792,6 +831,8 @@ Set the configuration option `operations_processor` to use the new `CountingActi
 specifying the snake cased name of the class (without the `OperationsProcessor`).
 
 ```ruby
+require 'jsonapi/counting_active_record_operations_processor'
+
 JSONAPI.configure do |config|
   config.operations_processor = :counting_active_record
 end
@@ -840,6 +881,8 @@ class PeopleController < ApplicationController
 end
 ```
 
+> __Note__: This gem [uses the filter chain to set up the request](https://github.com/cerebris/jsonapi-resources/issues/458#issuecomment-143297055). In some instances, variables that are set in the filter chain (such as `current_user`) may not be set at the right time. If this happens (i.e. `current_user` is `nil` in `context` but it's set properly everywhere else), you may want to have your authentication occur earlier in the filter chain, using `prepend_before_action` instead of `before_action`.
+
 ##### ActsAsResourceController
 
 `JSONAPI::Resources` also provides a module, `JSONAPI::ActsAsResourceController`. You can include this module to
@@ -994,12 +1037,12 @@ end
 
 By default, all exceptions raised downstream from a resource controller will be caught, logged, and a ```500 Internal Server Error``` will be rendered. Exceptions can be whitelisted in the config to pass through the handler and be caught manually, or you can pass a callback from a resource controller to insert logic into the rescue block without interrupting the control flow. This can be particularly useful for additional logging or monitoring without the added work of rendering responses.
 
-Pass a block, refer to controller class methods, or both. Note that methods must be defined as class methods on a controller and accept one parameter, which is passed the exception object that was rescued. 
+Pass a block, refer to controller class methods, or both. Note that methods must be defined as class methods on a controller and accept one parameter, which is passed the exception object that was rescued.
 
 ```ruby
   class ApplicationController < JSONAPI::ResourceController
 
-    on_server_error :first_callback 
+    on_server_error :first_callback
 
     #or
 
@@ -1014,6 +1057,26 @@ Pass a block, refer to controller class methods, or both. Note that methods must
 
 ```
 
+#### Action Callbacks
+
+##### ensure_correct_media_type
+
+By default, when controllers extend functionalities from `jsonapi-resources`, the `ActsAsResourceController#ensure_correct_media_type`
+method will be triggered before `create`, `update`, `create_relationship` and `update_relationship` actions. This method is reponsible
+for checking if client's request corresponds to the correct media type required by [JSON API](http://jsonapi.org/format/#content-negotiation-clients): `application/vnd.api+json`.
+
+In case you need to check the media type for custom actions, just make sure to call the method in your controller's `before_action`:
+
+```ruby
+class UsersController < JSONAPI::ResourceController
+  before_action :ensure_correct_media_type, only: [:auth]
+
+  def auth
+    # some crazy auth code goes here
+  end
+end
+```
+
 ### Serializer
 
 The `ResourceSerializer` can be used to serialize a resource into JSON API compliant JSON. `ResourceSerializer` must be
@@ -1022,7 +1085,7 @@ The `ResourceSerializer` can be used to serialize a resource into JSON API compl
 
 ```ruby
 post = Post.find(1)
-JSONAPI::ResourceSerializer.new(PostResource).serialize_to_hash(PostResource.new(post))
+JSONAPI::ResourceSerializer.new(PostResource).serialize_to_hash(PostResource.new(post, nil))
 ```
 
 This returns results like this:
@@ -1075,9 +1138,9 @@ This returns results like this:
 }
 ```
 
-#### serialize_to_hash method options
+#### Serializer options
 
-The `serialize_to_hash` method also takes some optional parameters:
+The `ResourceSerializer` can be initialized with some optional parameters:
 
 ##### `include`
 
@@ -1107,13 +1170,9 @@ JSONAPI::ResourceSerializer.new(PostResource, include: include_resources,
     tags: [:name],
     comments: [:body, :post]
   }
-).serialize_to_hash(PostResource.new(post))
+).serialize_to_hash(PostResource.new(post, nil))
 ```
 
-##### `context`
-
-Context data can be provided to the serializer, which passes it to each resource as it is inspected.
-
 #### Routing
 
 JR has a couple of helper methods available to assist you with setting up routes.
@@ -1283,18 +1342,23 @@ phone_number_contact GET    /phone-numbers/:phone_number_id/contact(.:format) co
 
 #### Formatting
 
-JR by default uses some simple rules to format an attribute for serialization. Strings and Integers are output to JSON
+JR by default uses some simple rules to format (and unformat) an attribute for (de-)serialization. Strings and Integers are output to JSON
 as is, and all other values have `.to_s` applied to them. This outputs something in all cases, but it is certainly not
 correct for every situation.
 
-If you want to change the way an attribute is serialized you have a couple of ways. The simplest method is to create a
-getter method on the resource which overrides the attribute and apply the formatting there. For example:
+If you want to change the way an attribute is (de-)serialized you have a couple of ways. The simplest method is to create a
+getter (and setter) method on the resource which overrides the attribute and apply the (un-)formatting there. For example:
 
 ```ruby
 class PersonResource < JSONAPI::Resource
-  attributes :name, :email
-  attribute :last_login_time
+  attributes :name, :email, :last_login_time
 
+  # Setter example
+  def email=(new_email)
+    @model.email = new_email.downcase
+  end
+
+  # Getter example
   def last_login_time
     @model.last_login_time.in_time_zone(@context[:current_user].time_zone).to_s
   end
@@ -1312,8 +1376,10 @@ handled for an attribute. The `format` can be set per attribute as it is declare
 
 ```ruby
 class PersonResource < JSONAPI::Resource
-  attributes :name, :email
+  attributes :name, :email, :spoken_languages
   attribute :last_login_time, format: :date_with_utc_timezone
+
+  # Getter/Setter for spoken_languages ...
 end
 ```
 
@@ -1431,6 +1497,9 @@ JR has a few configuration options. Some have already been mentioned above. To s
 initializer and add the options you wish to set. All options have defaults, so you only need to set the options that
 are different. The default options are shown below.
 
+If using custom classes (such as the CountingActiveRecordOperationsProcessor, or a CustomPaginator),
+be sure to require them at the top of the initializer before usage.
+
 ```ruby
 JSONAPI.configure do |config|
   #:underscored_key, :camelized_key, :dasherized_key, or custom

data/jsonapi-resources.gemspec

@@ -23,7 +23,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'minitest'
   spec.add_development_dependency 'minitest-spec-rails'
-  spec.add_development_dependency 'minitest-reporters'
   spec.add_development_dependency 'simplecov'
   spec.add_development_dependency 'pry'
   spec.add_dependency 'rails', '>= 4.0'

data/lib/jsonapi/acts_as_resource_controller.rb

@@ -5,9 +5,9 @@ module JSONAPI
     extend ActiveSupport::Concern
 
     included do
-      before_filter :ensure_correct_media_type, only: [:create, :update, :create_relationship, :update_relationship]
-      append_before_filter :setup_request
-      after_filter :setup_response
+      before_action :ensure_correct_media_type, only: [:create, :update, :create_relationship, :update_relationship]
+      append_before_action :setup_request
+      after_action :setup_response
     end
 
     def index
@@ -187,22 +187,22 @@ module JSONAPI
       @request.server_error_callbacks = callbacks || []
     end
 
-    # Pass in a methods or a block to be run when an exception is 
+    # Pass in a methods or a block to be run when an exception is
     # caught that is not a JSONAPI::Exceptions::Error
-    # Useful for additional logging or notification configuration that 
+    # Useful for additional logging or notification configuration that
     # would normally depend on rails catching and rendering an exception.
     # Ignores whitelist exceptions from config
 
-    class_methods do 
+    module ClassMethods
       def on_server_error(*args, &callback_block)
         callbacks = []
 
-        if callback_block 
+        if callback_block
           callbacks << callback_block
         end
 
         method_callbacks = args.map do |method|
-          ->(error) do 
+          ->(error) do
             if self.respond_to? method
               send(method, error)
             else
@@ -211,7 +211,7 @@ module JSONAPI
           end
         end.compact
         callbacks += method_callbacks
-        append_before_filter { add_error_callbacks(callbacks) }
+        append_before_action { add_error_callbacks(callbacks) }
       end
     end
   end

data/lib/jsonapi/link_builder.rb

@@ -81,7 +81,7 @@ module JSONAPI
       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"
+      [base_path_name, end_path_name, "path"].reject(&:blank?).join("_")
     end
 
     def engine_resource_url(source)

data/lib/jsonapi/operation.rb

@@ -150,7 +150,7 @@ module JSONAPI
     end
 
     def record_count
-      @_record_count ||= records.count
+      @_record_count ||= records.count(:all)
     end
 
     def source_resource

data/lib/jsonapi/request.rb

@@ -92,15 +92,11 @@ module JSONAPI
     end
 
     def setup_create_relationship_action(params)
-      parse_add_relationship_operation(params.require(:data),
-                                      params.require(:relationship),
-                                      params.require(@resource_klass._as_parent_key))
+      parse_modify_relationship_action(params, :add)
     end
 
     def setup_update_relationship_action(params)
-      parse_update_relationship_operation(params.fetch(:data),
-                                         params.require(:relationship),
-                                         params.require(@resource_klass._as_parent_key))
+      parse_modify_relationship_action(params, :update)
     end
 
     def setup_update_action(params)
@@ -114,7 +110,28 @@ module JSONAPI
     end
 
     def setup_destroy_relationship_action(params)
-      parse_remove_relationship_operation(params)
+      parse_modify_relationship_action(params, :remove)
+    end
+
+    def parse_modify_relationship_action(params, modification_type)
+      relationship_type = params.require(:relationship)
+      parent_key = params.require(@resource_klass._as_parent_key)
+      relationship = @resource_klass._relationship(relationship_type)
+
+      # Removals of to-one relationships are done implicitly and require no specification of data
+      data_required = !(modification_type == :remove && relationship.is_a?(JSONAPI::Relationship::ToOne))
+
+      if data_required
+        data = params.fetch(:data)
+        object_params = { relationships: { format_key(relationship.name) => { data: data } } }
+        verified_params = parse_params(object_params, updatable_fields)
+
+        parse_arguments = [verified_params, relationship, parent_key]
+      else
+        parse_arguments = [params, relationship, parent_key]
+      end
+
+      send(:"parse_#{modification_type}_relationship_operation", *parse_arguments)
     end
 
     def initialize_source(params)
@@ -159,8 +176,7 @@ module JSONAPI
           @errors.concat(e.errors)
         end
 
-        if type_resource.nil? || !(@resource_klass._type == underscored_type ||
-          @resource_klass._has_relationship?(underscored_type))
+        if type_resource.nil?
           @errors.concat(JSONAPI::Exceptions::InvalidResource.new(type).errors)
         else
           unless values.nil?
@@ -548,66 +564,47 @@ module JSONAPI
     end
     # :nocov:
 
-    def parse_add_relationship_operation(data, relationship_type, parent_key)
-      relationship = resource_klass._relationship(relationship_type)
-
+    def parse_add_relationship_operation(verified_params, relationship, parent_key)
       if relationship.is_a?(JSONAPI::Relationship::ToMany)
-        object_params = { relationships: { format_key(relationship.name) => { data: data } } }
-        verified_param_set = parse_params(object_params, updatable_fields)
-
         @operations.push JSONAPI::CreateToManyRelationshipOperation.new(
           resource_klass,
           context: @context,
           resource_id: parent_key,
-          relationship_type: relationship_type,
-          data: verified_param_set[:to_many].values[0]
+          relationship_type: relationship.name,
+          data: verified_params[:to_many].values[0]
         )
       end
     end
 
-    def parse_update_relationship_operation(data, relationship_type, parent_key)
-      relationship = resource_klass._relationship(relationship_type)
+    def parse_update_relationship_operation(verified_params, relationship, parent_key)
+      operation_args = [resource_klass].push(
+        context: @context,
+        resource_id: parent_key,
+        relationship_type: relationship.name
+      )
+
       if relationship.is_a?(JSONAPI::Relationship::ToOne)
         if relationship.polymorphic?
-          object_params = { relationships: { format_key(relationship.name) => { data: data } } }
-          verified_param_set = parse_params(object_params, updatable_fields)
-
-          @operations.push JSONAPI::ReplacePolymorphicToOneRelationshipOperation.new(
-                             resource_klass,
-                             context: @context,
-                             resource_id: parent_key,
-                             relationship_type: relationship_type,
-                             key_value: verified_param_set[:to_one].values[0][:id],
-                             key_type: verified_param_set[:to_one].values[0][:type]
-                           )
+          operation_args[1].merge!(
+            key_value: verified_params[:to_one].values[0][:id],
+            key_type: verified_params[:to_one].values[0][:type]
+          )
+
+          operation_klass = JSONAPI::ReplacePolymorphicToOneRelationshipOperation
         else
-          object_params = { relationships: { format_key(relationship.name) => { data: data } } }
-          verified_param_set = parse_params(object_params, updatable_fields)
-
-          @operations.push JSONAPI::ReplaceToOneRelationshipOperation.new(
-                             resource_klass,
-                             context: @context,
-                             resource_id: parent_key,
-                             relationship_type: relationship_type,
-                             key_value: verified_param_set[:to_one].values[0]
-                           )
+          operation_args[1].merge!(key_value: verified_params[:to_one].values[0])
+          operation_klass = JSONAPI::ReplaceToOneRelationshipOperation
         end
       elsif relationship.is_a?(JSONAPI::Relationship::ToMany)
         unless relationship.acts_as_set
           fail JSONAPI::Exceptions::ToManySetReplacementForbidden.new
         end
 
-        object_params = { relationships: { format_key(relationship.name) => { data: data } } }
-        verified_param_set = parse_params(object_params, updatable_fields)
-
-        @operations.push JSONAPI::ReplaceToManyRelationshipOperation.new(
-                           resource_klass,
-                           context: @context,
-                           resource_id: parent_key,
-                           relationship_type: relationship_type,
-                           data: verified_param_set[:to_many].values[0]
-                         )
+        operation_args[1].merge!(data: verified_params[:to_many].values[0])
+        operation_klass = JSONAPI::ReplaceToManyRelationshipOperation
       end
+
+      @operations.push(operation_klass.send(:new, *operation_args))
     end
 
     def parse_single_replace_operation(data, keys, id_key_presence_check_required: true)
@@ -665,29 +662,25 @@ module JSONAPI
       @errors.concat(e.errors)
     end
 
-    def parse_remove_relationship_operation(params)
-      relationship_type = params[:relationship]
-
-      parent_key = params[resource_klass._as_parent_key]
+    def parse_remove_relationship_operation(params, relationship, parent_key)
+      operation_base_args = [resource_klass].push(
+        context: @context,
+        resource_id: parent_key,
+        relationship_type: relationship.name
+      )
 
-      relationship = resource_klass._relationship(relationship_type)
       if relationship.is_a?(JSONAPI::Relationship::ToMany)
-        keys = parse_key_array(params[:keys])
+        keys = params[:to_many].values[0]
         keys.each do |key|
+          operation_args = operation_base_args.dup
+          operation_args[1] = operation_args[1].merge(associated_key: key)
           @operations.push JSONAPI::RemoveToManyRelationshipOperation.new(
-            resource_klass,
-            context: @context,
-            resource_id: parent_key,
-            relationship_type: relationship_type,
-            associated_key: key
+            *operation_args
           )
         end
       else
         @operations.push JSONAPI::RemoveToOneRelationshipOperation.new(
-          resource_klass,
-          context: @context,
-          resource_id: parent_key,
-          relationship_type: relationship_type
+          *operation_base_args
         )
       end
     end