reamaze_api 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8d2efff7cf528f03bb9740c5760e8b550fba79b6
-  data.tar.gz: 49e9d0787266a1f1cb8c4cba2461cae3b87ea87e
+  metadata.gz: e555a6235c5bb2d36d98fb4b6ab19fe9947d0575
+  data.tar.gz: 4e067a44af81e4f4ff901c3c802c66506404cb15
 SHA512:
-  metadata.gz: c0b921866ccc2c8410b24ac760d2631794628d77a25e450cbbb206bedf1e8d82050dbe8cdd36669e6452868cd6e0da5af35c6f4e7ed3c11ff95d0b6e312e43f3
-  data.tar.gz: 9cc19b0ab9219fd2b2ff3aa41a6657bcb9b88b12bba63432d457d3370ecd5e76cd1c70ebbf24d185efee71671316ac388cbba98de09bde30350d1956f391973d
+  metadata.gz: ee7e1e594e3e532087ba366f69edaf8a057deef34b5ac8a3caadd6be4c6d8c2dd18584b28d5462ef4424d6b8eaaa7f102ee168e0ad139aeafb7aec77e19a3385
+  data.tar.gz: 67174ce5cad75fa3cb818eda68dcc66d9e3bab7997b40690f1476dad9d6bad86ca9f0f775071bf10146d89ea45aae63cb5e9802953f425c5f9c5915e9bd51671

data/README.md

@@ -93,6 +93,35 @@ end
 
 [Faraday]: https://github.com/lostisland/faraday
 
+### API Errors
+
+By default, ReamazeAPI returns an error Hash for any API response with status
+400-599. For example, the API returns a 404 if you provide an invalid brand
+name:
+
+```ruby
+client = ReamazeAPI.new brand: "invalid"
+client.articles.all
+# {
+#     :success => false,
+#       :error => "ReamazeAPI::NotFound",
+#     :message => "GET https://invalid.reamaze.com/api/v1/articles: 404"
+# }
+```
+
+If you would rather raise exceptions:
+
+```ruby
+ReamazeAPI.config do |c|
+  c.exceptions = true
+end
+
+client = ReamazeAPI.new brand: "invalid"
+client.articles.all # raises
+# ReamazeAPI::NotFound: GET https://invalid.reamaze.com/api/v1/articles: 404
+#   ...backtrace
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then,

data/lib/reamaze_api/client.rb

@@ -3,20 +3,23 @@ require "uri"
 
 module ReamazeAPI
   class Client
-    # Reamaze's API doesn't always return JSON. If there's an error parsing
-    # the response as JSON, just return the raw body.
-    class Middleware < FaradayMiddleware::ParseJson
-      define_parser do |body|
-        begin
-          JSON.parse(body) unless body.strip.empty?
-        rescue JSON::ParserError
-          body
+    # Raises a ReamazeAPI::Error for any HTTP response code 400-599.
+    class RaiseErrorMiddleware < Faraday::Response::Middleware
+      private
+
+      # Private: Raises a ReamazeAPI::Error for any HTTP response code
+      # 400-599.
+      #
+      # response - HTTP response (Faraday::Env)
+      #
+      # Returns nothing.
+      def on_complete(response)
+        if error = ReamazeAPI::Error.from_response(response)
+          raise error
         end
       end
     end
 
-    Faraday::Response.register_middleware reamaze_api: lambda { Middleware }
-
     # Public: HTTP methods used by the API
     #
     # Returns an Array.
@@ -47,6 +50,7 @@ module ReamazeAPI
       @http = Faraday.new(url: @url, ssl: { verify: true }) do |builder|
         builder.request    :json
         builder.response   :json
+        builder.use        RaiseErrorMiddleware
         builder.adapter    Faraday.default_adapter
         builder.basic_auth login, token
 
@@ -98,6 +102,9 @@ module ReamazeAPI
     # path:   API path (without `/api/v1` prefix, eg: "/messages")
     # params: Hash of parameters to send with the request (default: {})
     #
+    # Raises a ReamazeAPI::Error for any HTTP response code 400-599 unless
+    # `ReamazeAPI.config.exceptions` is false.
+    #
     # Returns a Hash.
     def commit(method:, path:, params: {})
       path = "#{@url.path}#{path}"
@@ -105,7 +112,9 @@ module ReamazeAPI
       response = @http.run_request(method, path, params, {})
 
       Utils.symbolize_hash(success: response.success?, payload: response.body)
-    rescue => e
+    rescue ReamazeAPI::Error => e
+      raise if ReamazeAPI.config.exceptions
+
       Utils.error_hash(e)
     end
 

data/lib/reamaze_api/error.rb

@@ -0,0 +1,73 @@
+module ReamazeAPI
+  # Encapsulates HTTP errors that may be returned by the Reamaze API. All API
+  # errors inherit from this class.
+  class Error < StandardError
+    # Public: Create an exception from the given response.
+    #
+    # response - HTTP response (Faraday::Env)
+    #
+    # Returns a ReamazeAPI::Error or nil.
+    def self.from_response(response)
+      if klass = case response[:status].to_i
+                 when 403
+                   ReamazeAPI::Forbidden
+                 when 404
+                   ReamazeAPI::NotFound
+                 when 422
+                   ReamazeAPI::UnprocessableEntity
+                 when 429
+                   ReamazeAPI::TooManyRequests
+                 when 400..499
+                   ReamazeAPI::ClientError
+                 when 500..599
+                   ReamazeAPI::ServerError
+                 end
+
+        klass.new(response)
+      end
+    end
+
+    # Public: Initialize a new ReamazeAPI::Error instance.
+    #
+    # response - HTTP response (Faraday::Env)
+    #
+    # Returns nothing.
+    def initialize(response = nil)
+      @response = response
+      super(build_message)
+    end
+
+    private
+
+    # Private: Error message to be displayed.
+    #
+    # Returns a String or nil.
+    def build_message
+      return if @response.nil?
+
+      message  = "#{@response[:method].to_s.upcase} "
+      message << "#{@response[:url]}: "
+      message << "#{@response[:status]}"
+      message << "\n\nBODY: #{@response[:body].inspect}" if @response[:body]
+      message
+    end
+  end
+
+  # Raised on HTTP 400-499
+  class ClientError < Error; end
+
+  # Raised on HTTP 403 (bad username/password)
+  class Forbidden < ClientError; end
+
+  # Raised on HTTP 404 (eg: bad brand or API URL)
+  class NotFound < ClientError; end
+
+  # Raised on HTTP 422 (eg: missing params in a POST)
+  class UnprocessableEntity < ClientError; end
+
+  # Raised on HTTP 429 (API rate limit exceeded)
+  class TooManyRequests < ClientError; end
+
+  # Raised on HTTP 500-599 (error on the Reamaze API server itself)
+  class ServerError < Error; end
+end

data/lib/reamaze_api/version.rb

@@ -1,3 +1,3 @@
 module ReamazeAPI
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/reamaze_api.rb

@@ -1,5 +1,6 @@
 require "reamaze_api/version"
 require "reamaze_api/utils"
+require "reamaze_api/error"
 require "reamaze_api/client"
 require "reamaze_api/resource"
 require "reamaze_api/article"
@@ -10,7 +11,7 @@ require "reamaze_api/message"
 
 module ReamazeAPI
   # Public: Configuration class
-  Config = Struct.new(:brand, :login, :token)
+  Config = Struct.new(:brand, :login, :token, :exceptions)
 
   # Public: Optional default configuration used to authenticate with the
   # Reamaze API.
@@ -41,7 +42,11 @@ module ReamazeAPI
   #
   # Returns a ReamazeAPI::Client instance.
   def self.new(**credentials, &block)
-    params = config.to_h.select { |_, value| value }.merge(credentials)
+    params = {
+      brand: credentials.fetch(:brand) { config.brand },
+      login: credentials.fetch(:login) { config.login },
+      token: credentials.fetch(:token) { config.token },
+    }
 
     Client.new(**params, &block)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reamaze_api
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Joshua Priddle
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-06-22 00:00:00.000000000 Z
+date: 2016-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -114,6 +114,7 @@ files:
 - lib/reamaze_api/client.rb
 - lib/reamaze_api/contact.rb
 - lib/reamaze_api/conversation.rb
+- lib/reamaze_api/error.rb
 - lib/reamaze_api/message.rb
 - lib/reamaze_api/resource.rb
 - lib/reamaze_api/utils.rb