Merge pull request JsonApiClient#4 from residently/update-to-latest-upstream

Update to latest upstream

Author: timparkerdev

.gitignore

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

.travis.yml

@@ -3,6 +3,8 @@ rvm:
   - 2.2.6
   - 2.3.3
   - 2.4.1
+  - 2.5.1
+  - 2.6.0
 env:
   global:
     - CODECLIMATE_REPO_TOKEN=396d4263adb6febf1e6e9b0c0e176fbde35e1a116a3c1ecf8dd4f9384e41979b
@@ -12,9 +14,15 @@ gemfile:
   - gemfiles/4.1.gemfile
   - gemfiles/4.2.gemfile
   - gemfiles/5.0.gemfile
+  - gemfiles/5.2.3.gemfile
+  - gemfiles/6.0.gemfile
 matrix:
   fast_finish: true
   exclude:
+    - rvm: 2.2.6
+      gemfile: gemfiles/6.0.gemfile
+    - rvm: 2.3.3
+      gemfile: gemfiles/6.0.gemfile
     - rvm: 2.4.1
       gemfile: gemfiles/3.2.gemfile
     - rvm: 2.4.1
@@ -23,7 +31,23 @@ matrix:
       gemfile: gemfiles/4.1.gemfile
     - rvm: 2.4.1
       gemfile: gemfiles/4.2.gemfile
+    - rvm: 2.4.1
+      gemfile: gemfiles/6.0.gemfile
+    - rvm: 2.5.1
+      gemfile: gemfiles/3.2.gemfile
+    - rvm: 2.5.1
+      gemfile: gemfiles/4.0.gemfile
+    - rvm: 2.5.1
+      gemfile: gemfiles/4.1.gemfile
+    - rvm: 2.5.1
+      gemfile: gemfiles/4.2.gemfile
+    - rvm: 2.6.0
+      gemfile: gemfiles/4.0.gemfile
+    - rvm: 2.6.0
+      gemfile: gemfiles/4.1.gemfile
+    - rvm: 2.6.0
+      gemfile: gemfiles/4.2.gemfile
 # We need to install latest version of bundler, because one in travis
 # image is too old to recognize platform => :mri_22 in Gemfile.
 before_install:
-  - gem install bundler
+  - gem install bundler || gem install bundler -v 1.17.3

CHANGELOG.md

@@ -2,6 +2,81 @@
 
 ## Unreleased
 
+## 1.16.1
+
+- [#361](https://github.com/JsonApiClient/json_api_client/pull/361) - Call super from inherited method so that it will execute parent classes' implementations
+
+## 1.16.0
+
+- [#359](https://github.com/JsonApiClient/json_api_client/pull/359) - Support gzip content encoding
+
+## 1.15.0
+
+- [#346](https://github.com/JsonApiClient/json_api_client/pull/346) - add the option to have immutable resources
+- [#357](https://github.com/JsonApiClient/json_api_client/pull/357) - fix missing constant formatter
+
+## 1.14.1
+
+- [#353](https://github.com/JsonApiClient/json_api_client/pull/353) - fix to support deserializing resources with relationships without those related resources being included in the response (issue [#352](https://github.com/JsonApiClient/json_api_client/issues/352)).
+
+## 1.14.0
+
+- [#338](https://github.com/JsonApiClient/json_api_client/pull/338) - implement hash and eql? for builder class
+- [#351](https://github.com/JsonApiClient/json_api_client/pull/351) - Remove rudimental `last_result_set` relationship from serializer
+
+## 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
+
+## 1.9.0
+
+- [#328](https://github.com/JsonApiClient/json_api_client/pull/328) - allow custom type for models
+
+- [#326](https://github.com/JsonApiClient/json_api_client/pull/326) - correct changes after initialize resource
+  * remove type from changes on initialize
+  * ensure that query builder doesn't propagate query values to resource attributes via #build method
+
+- [#324](https://github.com/JsonApiClient/json_api_client/pull/324) - add possibility to override status handling
+  * add status_handlers to JsonApiClient::Resource.connection_options
+
+- [#330](https://github.com/JsonApiClient/json_api_client/pull/330) - deletion use overridden primary key
+
+## 1.8.0
+
+- [#316](https://github.com/JsonApiClient/json_api_client/pull/316) - Allow custom error messages
+
+- [#305](https://github.com/JsonApiClient/json_api_client/pull/305) - optional search relationship data in result set
+
+## 1.7.0
+
+- [#320](https://github.com/JsonApiClient/json_api_client/pull/320) - fix passing relationships on create
+  * 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
+
 ## v1.6.4
 - [#314](https://github.com/JsonApiClient/json_api_client/pull/314) - Mimic ActiveRecord behavior when destroying a resource:
   * Add `destroyed?` method

Gemfile

@@ -11,5 +11,5 @@ gem 'addressable', '~> 2.2'
 gem "codeclimate-test-reporter", group: :test, require: nil
 
 group :development, :test do
-  gem 'byebug', platforms: [:mri_20, :mri_21, :mri_22]
+  gem 'byebug', '~> 10.0', platforms: [:mri_20, :mri_21, :mri_22]
 end

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(
@@ -157,13 +157,17 @@ articles.links.related
 
 You can force nested resource paths for your models by using a `belongs_to` association.
 
-**Note: Using belongs_to is only necessary for setting a nested path.**
+**Note: Using belongs_to is only necessary for setting a nested path unless you provide `shallow_path: true` option.**
 
 ```ruby
 module MyApi
   class Account < JsonApiClient::Resource
     belongs_to :user
   end
+
+  class Customer < JsonApiClient::Resource
+    belongs_to :user, shallow_path: true
+  end
 end
 
 # try to find without the nested parameter
@@ -173,6 +177,28 @@ MyApi::Account.find(1)
 # makes request to /users/2/accounts/1
 MyApi::Account.where(user_id: 2).find(1)
 # => returns ResultSet
+
+# makes request to /customers/1
+MyApi::Customer.find(1)
+# => returns ResultSet
+
+# makes request to /users/2/customers/1
+MyApi::Customer.where(user_id: 2).find(1)
+# => returns ResultSet
+```
+
+you can also override param name for `belongs_to` association
+
+```ruby
+module MyApi
+  class Account < JsonApiClient::Resource
+    belongs_to :user, param: :customer_id
+  end
+end
+
+# makes request to /users/2/accounts/1
+MyApi::Account.where(customer_id: 2).find(1)
+# => returns ResultSet
 ```
 
 ## Custom Methods
@@ -448,6 +474,52 @@ 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.
+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
+class ApiBadRequestHandler
+  def self.call(_env)
+    # do not raise exception
+  end
+end
+
+class CustomUnauthorizedError < StandardError
+  attr_reader :env
+
+  def initialize(env)
+    @env = env
+    super('not authorized')
+  end
+end
+
+MyApi::Base.connection_options[:status_handlers] = {
+    400 => ApiBadRequestHandler,
+    401 => ->(env) { raise CustomUnauthorizedError, env }
+}
+
+module MyApi
+  class User < Base
+    # will use the customized status_handlers
+  end
+end
+
+user = MyApi::User.create(name: 'foo')
+# server responds with { errors: [ { detail: 'bad request' } ] }
+user.errors.messages # { base: ['bad request'] }
+# on 401 it will raise CustomUnauthorizedError instead of JsonApiClient::Errors::NotAuthorized
+```
+
 ##### Specifying an HTTP Proxy
 
 All resources have a class method ```connection_options``` used to pass options to the JsonApiClient::Connection initializer.
@@ -505,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"
@@ -514,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
@@ -527,6 +599,36 @@ 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.
+It will work both for defined and not defined relationships
+
+```ruby
+class MyApi::Base < JsonApiClient::Resource
+  resolve_custom_type 'document--files', 'File'
+end
+
+class MyApi::File < MyApi::Base
+  def self.resource_name
+    'document--files'
+  end
+end
+```
 
 ### Type Casting
 
@@ -556,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:
@@ -569,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)

gemfiles/5.2.3.gemfile

@@ -0,0 +1,15 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake"
+gem "appraisal"
+gem "activesupport", "~> 5.2.3"
+gem "addressable", "~> 2.2"
+gem "codeclimate-test-reporter", :group => :test, :require => nil
+
+group :development, :test do
+  gem "byebug", :platforms => [:mri_20, :mri_21, :mri_22]
+end
+
+gemspec :path => "../"