Track the real HTTP reason of ApiErrors

Author: stokarenko

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- [#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

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
 
@@ -474,6 +474,14 @@ 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.
@@ -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
@@ -680,4 +688,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/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])

test/unit/errors_test.rb

@@ -22,13 +22,42 @@ def test_timeout_errors
     end
   end
 
-  def test_500_errors
+  def test_internal_server_error_with_plain_text_response
     stub_request(:get, "http://example.com/users")
       .to_return(headers: {content_type: "text/plain"}, status: 500, body: "something went wrong")
 
-    assert_raises JsonApiClient::Errors::ServerError do
-      User.all
-    end
+    exception = assert_raises(JsonApiClient::Errors::InternalServerError) { User.all }
+    assert_equal '500 Internal Server Error', exception.message
+  end
+
+  def test_internal_server_error_with_json_api_response
+    stub_request(:get, "http://example.com/users").to_return(
+      headers: {content_type: "application/vnd.api+json"},
+      status: 500,
+      body: {errors: [{title: "Some special error"}]}.to_json
+    )
+
+    exception = assert_raises(JsonApiClient::Errors::InternalServerError) { User.all }
+    assert_equal '500 Internal Server Error (Some special error)', exception.message
+  end
+
+  def test_500_errors_with_plain_text_response
+    stub_request(:get, "http://example.com/users")
+      .to_return(headers: {content_type: "text/plain"}, status: 503, body: "service unavailable")
+
+    exception = assert_raises(JsonApiClient::Errors::ServerError) { User.all }
+    assert_equal '503 Service Unavailable', exception.message
+  end
+
+  def test_500_errors_with_with_json_api_response
+    stub_request(:get, "http://example.com/users").to_return(
+      headers: {content_type: "application/vnd.api+json"},
+      status: 503,
+      body: {errors: [{title: "Timeout error"}]}.to_json
+    )
+
+    exception = assert_raises(JsonApiClient::Errors::ServerError) { User.all }
+    assert_equal '503 Service Unavailable (Timeout error)', exception.message
   end
 
   def test_not_found

test/unit/status_test.rb

@@ -11,7 +11,7 @@ def test_server_responding_with_status_meta
         }
       }.to_json)
 
-    assert_raises JsonApiClient::Errors::ServerError do
+    assert_raises JsonApiClient::Errors::InternalServerError do
       User.find(1)
     end
   end
@@ -24,7 +24,7 @@ def test_server_responding_with_http_status
       status: 500,
       body: "something irrelevant")
 
-    assert_raises JsonApiClient::Errors::ServerError do
+    assert_raises JsonApiClient::Errors::InternalServerError do
       User.find(1)
     end
   end