Merge branch 'master' into update-changelog-after-1-10

Author: gaorlov

.gitignore

@@ -24,3 +24,10 @@ Gemfile.lock
 *.gemfile.lock
 
 /coverage
+
+# IntellJ/RubyMine
+*.iml
+.idea/
+
+# asdf config
+.tool-versions

CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## 1.13.0
+
+- [#348](https://github.com/JsonApiClient/json_api_client/pull/348) - add NestedParamPaginator to address inconsistency in handling of pagination query string params (issue [#347](https://github.com/JsonApiClient/json_api_client/issues/347)).
+
+## 1.12.2
+
+- [#350](https://github.com/JsonApiClient/json_api_client/pull/350) - fix resource including with blank `relationships` response data
+
+## 1.12.1
+
+- [#349](https://github.com/JsonApiClient/json_api_client/pull/349) - fix resource including for STI objects
+
+## 1.12.0
+
+- [#345](https://github.com/JsonApiClient/json_api_client/pull/345) - track the real HTTP reason of ApiErrors
+
+## 1.11.0
+
+- [#344](https://github.com/JsonApiClient/json_api_client/pull/344) - introduce safe singular resource fetching with `raise_on_blank_find_param` resource setting
+
 ## 1.10.0
 
 - [#335](https://github.com/JsonApiClient/json_api_client/pull/335) - access to assigned relationship
@@ -31,7 +51,7 @@
   * fix relationships passing to `new` and `create` methods
   * fix false positive tests on create
   * refactor tests on create/update to prevent false same positive tests in future
-  
+
 - [#315](https://github.com/JsonApiClient/json_api_client/pull/315) - add shallow_path feature to belongs_to
  * add `shallow_path` options to belongs_to to use model w/ and w/o nesting in parent resource
 

README.md

@@ -2,7 +2,7 @@
 
 This gem is meant to help you build an API client for interacting with REST APIs as laid out by [http://jsonapi.org](http://jsonapi.org). It attempts to give you a query building framework that is easy to understand (it is similar to ActiveRecord scopes).
 
-*Note: master is currently tracking the 1.0.0 specification. If you're looking for the older code, see [0.x branch](https://github.com/chingor13/json_api_client/tree/0.x)*
+*Note: master is currently tracking the 1.0.0 specification. If you're looking for the older code, see [0.x branch](https://github.com/JsonApiClient/json_api_client/tree/0.x)*
 
 ## Usage
 
@@ -52,14 +52,14 @@ u.update_attributes(
   c: "d"
 )
 
-u.persisted? 
+u.persisted?
 # => true
 
 u.destroy
 
-u.destroyed? 
+u.destroyed?
 # => true
-u.persisted? 
+u.persisted?
 # => false
 
 u = MyApi::Person.create(
@@ -164,7 +164,7 @@ module MyApi
   class Account < JsonApiClient::Resource
     belongs_to :user
   end
-  
+
   class Customer < JsonApiClient::Resource
       belongs_to :user, shallow_path: true
     end
@@ -474,9 +474,17 @@ module MyApi
 end
 ```
 
+##### Server errors handling
+
+Non-success API response will cause the specific `JsonApiClient::Errors::SomeException` raised, depends on responded HTTP status.
+Please refer to [JsonApiClient::Middleware::Status#handle_status](https://github.com/JsonApiClient/json_api_client/blob/master/lib/json_api_client/middleware/status.rb)
+method for concrete status-to-exception mapping used out of the box.
+
+JsonApiClient will try determine is failed API response JsonApi-compatible, if so - JsonApi error messages will be parsed from response body, and tracked as a part of particular exception message. In additional, `JsonApiClient::Errors::ServerError` exception will keep the actual HTTP status and message within its message.
+
 ##### Custom status handler
 
-You can change handling of response status using `connection_options`. For example you can override 400 status handling. 
+You can change handling of response status using `connection_options`. For example you can override 400 status handling.
 By default it raises `JsonApiClient::Errors::ClientError` but you can skip exception if you want to process errors from the server.
 You need to provide a `proc` which should call `throw(:handled)` default handler for this status should be skipped.
 ```ruby
@@ -569,7 +577,7 @@ end
 
 You can customize how your resources find pagination information from the response.
 
-If the [existing paginator](https://github.com/chingor13/json_api_client/blob/master/lib/json_api_client/paginating/paginator.rb) fits your requirements but you don't use the default `page` and `per_page` params for pagination, you can customise the param keys as follows:
+If the [existing paginator](https://github.com/JsonApiClient/json_api_client/blob/master/lib/json_api_client/paginating/paginator.rb) fits your requirements but you don't use the default `page` and `per_page` params for pagination, you can customise the param keys as follows:
 
 ```ruby
 JsonApiClient::Paginating::Paginator.page_param = "number"
@@ -578,7 +586,7 @@ JsonApiClient::Paginating::Paginator.per_page_param = "size"
 
 Please note that this is a global configuration, so library authors should create a custom paginator that inherits `JsonApiClient::Paginating::Paginator` and configure the custom paginator to avoid modifying global config.
 
-If the [existing paginator](https://github.com/chingor13/json_api_client/blob/master/lib/json_api_client/paginating/paginator.rb) does not fit your needs, you can create a custom paginator:
+If the [existing paginator](https://github.com/JsonApiClient/json_api_client/blob/master/lib/json_api_client/paginating/paginator.rb) does not fit your needs, you can create a custom paginator:
 
 ```ruby
 class MyPaginator
@@ -591,6 +599,20 @@ class MyApi::Base < JsonApiClient::Resource
 end
 ```
 
+### NestedParamPaginator
+
+The default `JsonApiClient::Paginating::Paginator` is not strict about how it handles the param keys ([#347](https://github.com/JsonApiClient/json_api_client/issues/347)). There is a second paginator that more rigorously adheres to the JSON:API pagination recommendation style of `page[page]=1&page[per_page]=10`.
+
+If this second style suits your needs better, it is available as a class override:
+
+```ruby
+class Order < JsonApiClient::Resource
+  self.paginator = JsonApiClient::Paginating::NestedParamPaginator
+end
+```
+
+You can also extend `NestedParamPaginator` in your custom paginators or assign the `page_param` or `per_page_param` as with the default version above.
+
 ### Custom type
 
 If your model must be named differently from classified type of resource you can easily customize it.
@@ -636,6 +658,37 @@ end
 
 ```
 
+### Safe singular resource fetching
+
+That is a bit curios, but `json_api_client` returns an array from `.find` method, always.
+The history of this fact was discussed [here](https://github.com/JsonApiClient/json_api_client/issues/75)
+
+So, when we searching for a single resource by primary key, we typically write the things like
+
+```ruby
+admin = User.find(id).first
+```
+
+The next thing which we need to notice - `json_api_client` will just interpolate the incoming `.find` param to the end of API URL, just like that:
+
+> http://somehost/api/v1/users/{id}
+
+What will happen if we pass the blank id (nil or empty string) to the `.find` method then?.. Yeah, `json_api_client` will try to call the INDEX API endpoint instead of SHOW one:
+
+> http://somehost/api/v1/users/
+
+Lets sum all together - in case if `id` comes blank (from CGI for instance), we can silently receive the `admin` variable equal to some existing resource, with all the consequences.
+
+Even worse, `admin` variable can equal to *random* resource, depends on ordering applied by INDEX endpoint.
+
+If you prefer to get `JsonApiClient::Errors::NotFound` raised, please define in your base Resource class:
+
+```ruby
+class Resource < JsonApiClient::Resource
+  self.raise_on_blank_find_param = true
+end
+```
+
 ## Contributing
 
 Contributions are welcome! Please fork this repo and send a pull request. Your pull request should have:
@@ -649,4 +702,4 @@ required. The commits will be squashed into master once accepted.
 
 ## Changelog
 
-See [changelog](https://github.com/chingor13/json_api_client/blob/master/CHANGELOG.md)
+See [changelog](https://github.com/JsonApiClient/json_api_client/blob/master/CHANGELOG.md)

json_api_client.gemspec

@@ -16,8 +16,9 @@ Gem::Specification.new do |s|
   s.add_dependency "faraday_middleware", '~> 0.9'
   s.add_dependency "addressable", '~> 2.2'
   s.add_dependency "activemodel", '>= 3.2.0'
+  s.add_dependency "rack", '>= 0.2'
 
-  s.add_development_dependency "webmock"
+  s.add_development_dependency "webmock", '~> 3.5.1'
   s.add_development_dependency "mocha"
 
   s.license = "MIT"

lib/json_api_client/errors.rb

@@ -1,10 +1,31 @@
+require 'rack'
+
 module JsonApiClient
   module Errors
     class ApiError < StandardError
       attr_reader :env
+
       def initialize(env, msg = nil)
-        super msg
         @env = env
+        # Try to fetch json_api errors from response
+        msg = track_json_api_errors(msg)
+
+        super msg
+      end
+
+      private
+
+      # Try to fetch json_api errors from response
+      def track_json_api_errors(msg)
+        return msg unless env.try(:body).kind_of?(Hash) || env.body.key?('errors')
+
+        errors_msg = env.body['errors'].map { |e| e['title'] }.compact.join('; ').presence
+        return msg unless errors_msg
+
+        msg.nil? ? errors_msg : "#{msg} (#{errors_msg})"
+        # Just to be sure that it is back compatible
+      rescue StandardError
+        msg
       end
     end
 
@@ -21,7 +42,13 @@ class ConnectionError < ApiError
     end
 
     class ServerError < ApiError
-      def initialize(env, msg = 'Internal server error')
+      def initialize(env, msg = nil)
+        msg ||= begin
+          status = env.status
+          message = ::Rack::Utils::HTTP_STATUS_CODES[status]
+          "#{status} #{message}"
+        end
+
         super env, msg
       end
     end
@@ -36,20 +63,23 @@ class NotFound < ServerError
       attr_reader :uri
       def initialize(uri)
         @uri = uri
-      end
-      def message
-        "Couldn't find resource at: #{uri.to_s}"
+
+        msg = "Couldn't find resource at: #{uri.to_s}"
+        super nil, msg
       end
     end
 
+    class InternalServerError < ServerError
+    end
+
     class UnexpectedStatus < ServerError
       attr_reader :code, :uri
       def initialize(code, uri)
         @code = code
         @uri = uri
-      end
-      def message
-        "Unexpected response status: #{code} from: #{uri.to_s}"
+
+        msg = "Unexpected response status: #{code} from: #{uri.to_s}"
+        super nil, msg
       end
     end
   end

lib/json_api_client/included_data.rb

@@ -4,20 +4,30 @@ class IncludedData
 
     def initialize(result_set, data)
       record_class = result_set.record_class
-      included_set = data.map do |datum|
-        type = datum["type"]
+      grouped_data = data.group_by{|datum| datum["type"]}
+      grouped_included_set = grouped_data.each_with_object({}) do |(type, records), h|
         klass = Utils.compute_type(record_class, record_class.key_formatter.unformat(type).singularize.classify)
-        params = klass.parser.parameters_from_resource(datum)
-        resource = klass.load(params)
-        resource.last_result_set = result_set
-        resource
+        h[type] = records.map do |record|
+          params = klass.parser.parameters_from_resource(record)
+          klass.load(params).tap do |resource|
+            resource.last_result_set = result_set
+          end
+        end
       end
 
-      included_set.concat(result_set) if record_class.search_included_in_result_set
-      @data = included_set.group_by(&:type).inject({}) do |h, (type, resources)|
-        h[type] = resources.index_by(&:id)
-        h
+      if record_class.search_included_in_result_set
+        # deep_merge overrides the nested Arrays o_O
+        # {a: [1,2]}.deep_merge(a: [3,4]) # => {a: [3,4]}
+        grouped_included_set.merge!(result_set.group_by(&:type)) do |_, resources1, resources2|
+          resources1 + resources2
+        end
       end
+
+      grouped_included_set.each do |type, resources|
+        grouped_included_set[type] = resources.index_by(&:id)
+      end
+
+      @data = grouped_included_set
     end
 
     def data_for(method_name, definition)

lib/json_api_client/middleware/status.rb

@@ -44,7 +44,9 @@ def handle_status(code, env)
           # Allow to proceed as resource errors will be populated
         when 400..499
           raise Errors::ClientError, env
-        when 500..599
+        when 500
+          raise Errors::InternalServerError, env
+        when 501..599
           raise Errors::ServerError, env
         else
           raise Errors::UnexpectedStatus.new(code, env[:url])

lib/json_api_client/paginating.rb

@@ -1,5 +1,6 @@
 module JsonApiClient
   module Paginating
     autoload :Paginator, 'json_api_client/paginating/paginator'
+    autoload :NestedParamPaginator, 'json_api_client/paginating/nested_param_paginator'
   end
-end
+end