json_api_client 1.5.2 → 1.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 3b172a6b2cca062c34df683b1fcbea5a017420a5
-  data.tar.gz: 129f0173840bafb6982f191f07fa2f815cb5dce1
+SHA256:
+  metadata.gz: 50ee381b7fb9cdebf8538c162a5dab717e8e2e23fffdc293ef7738728f45f9c3
+  data.tar.gz: 1be6e62baf09fc3bc78c7c65a5a7b567b0c4a875d1e6bbe06411774ee34d059a
 SHA512:
-  metadata.gz: c80f324ed56f8de4575ce6feada1576c253f034bf23c6ef1cb0bce3233a49efc4719cfa740bea078134057cc740fde6f9a7cdf883cd5bfc2b2536a44984da0f9
-  data.tar.gz: 9b8a4f4842c6045772d77757781fb76c33e10704a82754749fb344ec9a4b77f155683d64c3646b6cd2a62457f2a19f2d118eb5028f4b2656188c35da8b2baee3
+  metadata.gz: 60b1b657a5b30630f03e461bc4d29f5c0127417c53d63da146059d7a4bfef97e294d48d3bea842811dc72366e18cca7b1ddb1f68a573d42f1571a30dc199a9f6
+  data.tar.gz: a99ff29dd85edb6e036538c61d9ae84359a62bd8464e4f9839c09e2d8c1859d30ee58182a962503b00134fcb20c473520157bbe52b0dba5819dfc70402054d4b

data/README.md

@@ -1,8 +1,8 @@
-# JsonApiClient [![Build Status](https://travis-ci.org/chingor13/json_api_client.png)](https://travis-ci.org/chingor13/json_api_client) [![Code Climate](https://codeclimate.com/github/chingor13/json_api_client.png)](https://codeclimate.com/github/chingor13/json_api_client) [![Code Coverage](https://codeclimate.com/github/chingor13/json_api_client/coverage.png)](https://codeclimate.com/github/chingor13/json_api_client)
+# JsonApiClient [![Build Status](https://travis-ci.org/JsonApiClient/json_api_client.png?branch=master)](https://travis-ci.org/JsonApiClient/json_api_client) [![Code Climate](https://codeclimate.com/github/JsonApiClient/json_api_client.png)](https://codeclimate.com/github/JsonApiClient/json_api_client) [![Code Coverage](https://codeclimate.com/github/JsonApiClient/json_api_client/coverage.png)](https://codeclimate.com/github/JsonApiClient/json_api_client)
 
 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
 
@@ -39,14 +39,29 @@ MyApi::Article.where(author_id: 1).all
 MyApi::Person.where(name: "foo").order(created_at: :desc).includes(:preferences, :cars).all
 
 u = MyApi::Person.new(first_name: "bar", last_name: "foo")
+u.new_record?
+# => true
 u.save
 
+u.new_record?
+# => false
+
 u = MyApi::Person.find(1).first
 u.update_attributes(
   a: "b",
   c: "d"
 )
 
+u.persisted?
+# => true
+
+u.destroy
+
+u.destroyed?
+# => true
+u.persisted?
+# => false
+
 u = MyApi::Person.create(
   a: "b",
   c: "d"
@@ -142,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
@@ -158,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
@@ -196,6 +237,23 @@ results = Article.includes(:author, :comments => :author).find(1)
 
 # should not have to make additional requests to the server
 authors = results.map(&:author)
+
+# makes POST request to /articles?include=author,comments.author
+article = Article.new(title: 'New one').request_includes(:author, :comments => :author)
+article.save
+
+# makes PATCH request to /articles/1?include=author,comments.author
+article = Article.find(1)
+article.title = 'Changed'
+article.request_includes(:author, :comments => :author)
+article.save
+
+# request includes will be cleared if response is successful
+# to avoid this `keep_request_params` class attribute can be used
+Article.keep_request_params = true
+
+# to clear request_includes use
+article.reset_request_includes!
 ```
 
 ## Sparse Fieldsets
@@ -217,6 +275,24 @@ article.created_at
 # or you can use fieldsets from multiple resources
 # makes request to /articles?fields[articles]=title,body&fields[comments]=tag
 article = Article.select("title", "body",{comments: 'tag'}).first
+
+# makes POST request to /articles?fields[articles]=title,body&fields[comments]=tag
+article = Article.new(title: 'New one').request_select(:title, :body, comments: 'tag')
+article.save
+
+# makes PATCH request to /articles/1?fields[articles]=title,body&fields[comments]=tag
+article = Article.find(1)
+article.title = 'Changed'
+article.request_select(:title, :body, comments: 'tag')
+article.save
+
+# request fields will be cleared if response is successful
+# to avoid this `keep_request_params` class attribute can be used
+Article.keep_request_params = true
+
+# to clear request fields use
+article.reset_request_select!(:comments) # to clear for comments
+article.reset_request_select! # to clear for all fields
 ```
 
 ## Sorting
@@ -246,6 +322,10 @@ articles = Article.page(2).per(30).to_a
 
 # also makes request to /articles?page=2&per_page=30
 articles = Article.paginate(page: 2, per_page: 30).to_a
+
+# keep in mind that page number can be nil - in that case default number will be applied
+# also makes request to /articles?page=1&per_page=30
+articles = Article.paginate(page: nil, per_page: 30).to_a
 ```
 
 *Note: The mapping of pagination parameters is done by the `query_builder` which is [customizable](#custom-paginator).*
@@ -360,7 +440,7 @@ class NullConnection
   def initialize(*args)
   end
 
-  def run(request_method, path, params = {}, headers = {})
+  def run(request_method, path, params: nil, headers: {}, body: nil)
   end
 
   def use(*args); end
@@ -394,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.
@@ -451,16 +577,16 @@ 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 = "page[number]"
-JsonApiClient::Paginating::Paginator.per_page_param = "page[size]"
+JsonApiClient::Paginating::Paginator.page_param = "number"
+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
@@ -473,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
 
@@ -502,7 +658,48 @@ 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:
+
+* a description about what's broken or what the desired functionality is
+* a test illustrating the bug or new feature
+* the code to fix the bug
+
+Ideally, the PR has 2 commits - the first showing the failed test and the second with the fix - although this is not
+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)

data/lib/json_api_client/associations/base_association.rb

@@ -21,6 +21,13 @@ module JsonApiClient
       def from_result_set(result_set)
         result_set.to_a
       end
+
+      def load_records(data)
+        data.map do |d|
+          record_class = Utils.compute_type(klass, klass.key_formatter.unformat(d["type"]).classify)
+          record_class.load id: d["id"]
+        end
+      end
     end
   end
 end

data/lib/json_api_client/associations/belongs_to.rb

@@ -1,19 +1,19 @@
 module JsonApiClient
   module Associations
     module BelongsTo
-      extend ActiveSupport::Concern
+      class Association < BaseAssociation
+        include Helpers::URI
+
+        attr_reader :param
 
-      module ClassMethods
-        def belongs_to(attr_name, options = {})
-          # self.associations = self.associations + [HasOne::Association.new(attr_name, self, options)]
-          self.associations += [BelongsTo::Association.new(attr_name, self, options)]
+        def initialize(attr_name, klass, options = {})
+          super
+          @param = options.fetch(:param, :"#{attr_name}_id").to_sym
+          @shallow_path = options.fetch(:shallow_path, false)
         end
-      end
 
-      class Association < BaseAssociation
-        include Helpers::URI
-        def param
-          :"#{attr_name}_id"
+        def shallow_path?
+          @shallow_path
         end
 
         def to_prefix_path(formatter)
@@ -21,6 +21,7 @@ module JsonApiClient
         end
 
         def set_prefix_path(attrs, formatter)
+          return if shallow_path? && !attrs[param]
           attrs[param] = encode_part(attrs[param]) if attrs.key?(param)
           to_prefix_path(formatter) % attrs
         end

data/lib/json_api_client/associations/has_many.rb

@@ -1,14 +1,6 @@
 module JsonApiClient
   module Associations
     module HasMany
-      extend ActiveSupport::Concern
-
-      module ClassMethods
-        def has_many(attr_name, options = {})
-          self.associations = self.associations + [HasMany::Association.new(attr_name, self, options)]
-        end
-      end
-
       class Association < BaseAssociation
       end
     end

data/lib/json_api_client/associations/has_one.rb

@@ -1,19 +1,16 @@
 module JsonApiClient
   module Associations
     module HasOne
-      extend ActiveSupport::Concern
-
-      module ClassMethods
-        def has_one(attr_name, options = {})
-          self.associations += [HasOne::Association.new(attr_name, self, options)]
-        end
-      end
-
       class Association < BaseAssociation
         def from_result_set(result_set)
           result_set.first
         end
+
+        def load_records(data)
+          record_class = Utils.compute_type(klass, klass.key_formatter.unformat(data["type"]).classify)
+          record_class.load id: data["id"]
+        end
       end
     end
   end
-end
+end

data/lib/json_api_client/connection.rb

@@ -7,11 +7,14 @@ module JsonApiClient
       site = options.fetch(:site)
       connection_options = options.slice(:proxy, :ssl, :request, :headers, :params)
       adapter_options = Array(options.fetch(:adapter, Faraday.default_adapter))
+      status_middleware_options = {}
+      status_middleware_options[:custom_handlers] = options[:status_handlers] if options[:status_handlers].present?
       @faraday = Faraday.new(site, connection_options) do |builder|
         builder.request :json
         builder.use Middleware::JsonRequest
-        builder.use Middleware::Status
+        builder.use Middleware::Status, status_middleware_options
         builder.use Middleware::ParseJson
+        builder.use ::FaradayMiddleware::Gzip
         builder.adapter(*adapter_options)
       end
       yield(self) if block_given?
@@ -28,8 +31,10 @@ module JsonApiClient
       faraday.builder.delete(middleware)
     end
 
-    def run(request_method, path, params = {}, headers = {})
-      faraday.send(request_method, path, params, headers)
+    def run(request_method, path, params: nil, headers: {}, body: nil)
+      faraday.run_request(request_method, path, body, headers) do |request|
+        request.params.update(params) if params
+      end
     end
 
   end

data/lib/json_api_client/error_collector.rb

@@ -33,18 +33,27 @@ module JsonApiClient
       end
 
       def source_parameter
-        source.fetch(:parameter) do
-          source[:pointer] ?
-            source[:pointer].split("/").last :
-            nil
-        end
+        source[:parameter]
       end
 
       def source_pointer
-        source.fetch(:pointer) do
-          source[:parameter] ?
-            "/data/attributes/#{source[:parameter]}" :
-            nil
+        source[:pointer]
+      end
+
+      def error_key
+        if source_pointer && source_pointer != "/data"
+          source_pointer.split("/").last
+        else
+          "base"
+        end
+      end
+
+      def error_msg
+        msg = title || detail || "invalid"
+        if source_parameter
+          "#{source_parameter} #{msg}"
+        else
+          msg
         end
       end
 
@@ -74,7 +83,7 @@ module JsonApiClient
 
     def [](source)
       map do |error|
-        error.source_parameter == source
+        error.error_key == source
       end
     end
 

data/lib/json_api_client/errors.rb

@@ -1,44 +1,103 @@
+require 'rack'
+
 module JsonApiClient
   module Errors
     class ApiError < StandardError
       attr_reader :env
-      def initialize(env)
+
+      def initialize(env, msg = nil)
         @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
 
     class ClientError < ApiError
     end
 
+    class ResourceImmutableError < StandardError
+      def initialize(msg = 'Resource immutable')
+        super msg
+      end
+    end
+
     class AccessDenied < ClientError
     end
 
     class NotAuthorized < ClientError
     end
 
+    class NotFound < ClientError
+      attr_reader :uri
+      def initialize(env_or_uri, msg = nil)
+        env = nil
+
+        if env_or_uri.kind_of?(Faraday::Env)
+          env = env_or_uri
+          @uri = env[:url]
+        else
+          @uri = env_or_uri
+        end
+
+        msg ||= "Resource not found: #{uri.to_s}"
+        super env, msg
+      end
+    end
+
+    class RequestTimeout < ClientError
+    end
+
+    class Conflict < ClientError
+      def initialize(env, msg = 'Resource already exists')
+        super env, msg
+      end
+    end
+
+    class TooManyRequests < ClientError
+    end
+
     class ConnectionError < ApiError
     end
 
     class ServerError < ApiError
-      def message
-        "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
 
-    class Conflict < ServerError
-      def message
-        "Resource already exists"
-      end
+    class InternalServerError < ServerError
     end
 
-    class NotFound < ServerError
-      attr_reader :uri
-      def initialize(uri)
-        @uri = uri
-      end
-      def message
-        "Couldn't find resource at: #{uri.to_s}"
-      end
+    class BadGateway < ServerError
+    end
+
+    class ServiceUnavailable < ServerError
+    end
+
+    class GatewayTimeout < ServerError
     end
 
     class UnexpectedStatus < ServerError
@@ -46,11 +105,21 @@ module JsonApiClient
       def initialize(code, uri)
         @code = code
         @uri = uri
+
+        msg = "Unexpected response status: #{code} from: #{uri.to_s}"
+        super nil, msg
+      end
+    end
+
+    class RecordNotSaved < ServerError
+      attr_reader :record
+
+      def initialize(message = nil, record = nil)
+        @record = record
       end
       def message
-        "Unexpected response status: #{code} from: #{uri.to_s}"
+        "Record not saved"
       end
     end
-
   end
 end